Questions regarding the use of ISAM module in CMAQ

CMAQ-ISAM
1

Dear all,

I am currently learning how to use the ISAM module in CMAQ. Although I have gone through the GitHub documentation, I still have some questions that I hope you could help me with. I would appreciate it.

  1. IOAPI

According to the requirements, I need to provide GRIDMASK.nc (ISAM_REGIONS file) from IOAPI. However, since I am not familiar with IOAPI, I would like to know if there are any convenient methods to create the GRIDMASK file, perhaps using Python? As of now, I can only modify variable names and values based on the GRIDCRO2D file generated by MCIP, which is quite limited.

  1. isam_control.txt

In order to use ISAM, apart from enabling the relevant code in run_cctm.csh, certain settings must be added to specific documents such as setting TAG NAME, REGION(S), and EMIS STREAM(S) in the isam_control.txt file. I understand that TAG NAME can be user-defined within three characters, while the latter two should be set to the variable names included in GRIDMASK.nc and the label of different emission sources in run_cctm.csh. My question is, what is the maximum number of TAG NAMEs that can be added in one simulation? For instance, if I want to trace five regions and six emission sources simultaneously, I will need to add 30 sets of TAGs. Will it affect the simulation performance to some extent?

  1. EmissCtrl.nml

Furthermore, adjustments need to be made to ‘&RegionsRegistry’ content in EmissCtrl.nml. I noticed in the nml file that

For example, to refer to file “CMAQ_REGIONS” with path “/home/user/data/cmaq/cmaq_region_file.nc” the specification in the CMAQ runscript would look like: SETENV CMAQ_REGIONS /home/user/data/cmaq/cmaq_region_file.nc
Note that an unlimited number of files can be used here, but each must contain a path for reference in the runscript.

Does this mean that multiple File Labels can be set simultaneously or does it refer to SETENV CMAQ_REGIONS /home/user/data/cmaq/cmaq_region_file.nc? If it refers to the latter, how can I set multiple files in the SETENV CMAQ_REGIONS code?

Regarding the ‘Variable on File’ in ‘&RegionsRegistry’ of EmissCtrl.nml, typically, I use ‘ALL’. However, if there are other variables in my GRIDMASK.nc besides the defined regions (but not mentioned and not used in the isam_control.txt), will it have any impact?

Thank you for taking the time to address my questions.
2023-04-30T16:00:00Z

2

Hello Evan,

thanks for your interest in using the CMAQ ISAM option.

  1. For your first question, you might find the following threads useful as they discuss different approaches for creating an ISAM_REGIONS and potential pitfalls doing so when using non-I/O API tools:
    Could not open ISAM_REGIONS
    CMAQ v5.3.3 DESID region option (mask_file)
    What’s the maskdata’s format?

  2. The only software limit on the number of TAG NAMEs I am aware of is the I/O API MXVARS3 setting discussed in Chapter 3 of the User’s Guide. In the standard I/O API installation, this parameter is set to 2048 whereas in the “large” version, it is set to 16,384. Since the number of variables written out by ISAM is the product of the TAG NAMEs and the number of tracked species associated with the desired TAG CLASSes (I think about 60 for the OZONE TAG CLASS), this will impose some practical limit on the number of TAG NAMES especially when not using the “large” I/O API version, but 20 - 30 TAG NAMES should not yet push this limit unless many TAG CLASSes are defined. Aside from the software limit, you may possibly have hardware / memory limits, but that depends on your architecture and domain size.

But yes, the more TAG NAMEs you define, the slower the model will run, so there is definitely an impact on performance and, of course, output file sizes. On our system, a configuration with about 20 tags ran about 15 times slower than the base model without ISAM, so it still saved time comparing to running 20 individual brute-force zero out simulations for each tag. Your setup likely would yield different performance numbers, and at some point adding more tags likely would push you up against some practical limits on simulation times and file sizes, but there isn’t any general guidance on how many tags might be too much.

  1. I believe you could define multiple files in your run script, e.g.
    setenv CMAQ_REGIONS_01 /home/user/data/region_file_01.nc
    setenv CMAQ_REGIONS_02 /home/user/data/region_file_02.nc

and then reference both of them in the ‘&RegionsRegistry’ section like this

 !        Region Label   | File_Label  | Variable on File
          'EVERYWHERE'  ,'N/A'        ,'N/A',

          'ALL'         ,'CMAQ_REGIONS_01' ,'ALL',
          'ALL'         ,'CMAQ_REGIONS_02','ALL',

The only thing I think would be important is to make sure that there is no duplication of variables across the different files (though I’ve never tried this and could be wrong about that)

Having “extra” variables in these files (i.e. variables not mentioned and not used in isam_control.txt) and using the ‘ALL’ keyword to make them available to CMAQ should not cause a problem.

2 Likes
3

Thank you for your detailed and informative response ~ !