Figure 3 shows the input and output files and configuration options for ICON. A distinction is made between the options that are invoked at compilation versus those invoked at execution of the program. When compiling ICON, the user specifies a chemical mechanism to determine the gas-phase chemistry and aerosol mechanism for which to calculate chemical ICs. Setting the Mechanism variable in the ICON compile script configures the program to use a specific set of mechanism include files to build an executable. ICON executables are hard-wired to a specific mechanism configuration.
At execution the user provides a data file of chemical conditions that ICON will convert to ICs on a predefined model grid. Depending on how the user compiled the model, through the specification of the ModInpt variable, ICON will input either an ASCII vertical profile file (IC_PROFILE) or an existing CCTM concentration file (CTM_CONC_1). If the input file is not in the same chemical speciation as the simulation that the user is creating ICs for, it is necessary to specify a chemical conversion option by setting the ModMech variable at compilation. The default conversion profiles in ICON are set up to convert from RADM2 speciation to either CB-IV or SAPRC99 chemistry. It is possible to create a custom conversion file (MECH_CONV_FILE) and input this file to ICON by setting the ModMech variable to “user_defined” at compilation.
The horizontal grid and vertical layer structures for ICON are defined at execution through the input of a grid description (GRIDDESC) file and a meteorology cross-point 3-d (MET_CRO_3D) file, respectively. ICON interpolates between the input vertical layer structure and output layer structure if they are different.
Table 5.7. ICON input files
| File Name | Format | Description |
|---|---|---|
| IC_PROFILE | ASCII | Vertical chemical profiles from which to derive initial conditions; this file is created by the user |
| MECH_CONV_FILE | ASCII | Mapping factors for converting between chemical mechanisms; this file is created by the user |
| CTM_CONC_1 | GRDDED3 | Name and location of the CMAQ concentration file from which to derive initial conditions; this file is output from the CCTM |
| CTM_PING_1 | GRDDED3 | Name and location of the plume-in-grid concentration file for the coarse domain; this file is output from the CCTM; only used when ICON_PING is set to “Y” |
| PING_PDM_1 | GRDDED3 | Name and location of the plume-in-grid plume dynamics file for the coarse domain; this file output from the PDM; only used when ICON_PING is set to “Y” |
| MET_CRO_3D_CRS | GRDDED3 | Name and location of the course grid MET_CRO_3D file that is required for creating either plume-in-grid initial conditions or if the vertical grid structure changes between nested simulations; this file is output by MCIP |
| MET_CRO_3D_FIN | GRDDED3 | Name and location of the fine grid MET_CRO_3D file that is required if the vertical grid structure changes between nested simulations; this file is output by MCIP |
| GRIDDESC | ASCII | Horizontal grid description file for defining the model grid; this file is output by MCIP or can be created by the user |
| MET_CRO_3D | GRDDED3 | 3-D cross point meteorology file for defining the vertical layer structure of the model grid; this file is output by MCIP |
The configuration options listed here are set during compilation of the ICON executable. When these options are invoked they create a binary executable that is fixed to the specified configuration. To change these options it is necessary to recompile ICON and create a new executable.
- Opt:[default: verbose]
Defines the action to be taken by the program M3BLD when extracting source code from CVS and compiling an executable.
- compile_all: force compile, even if all the object files are current
- clean_up: remove all source files upon successful compilation
- no_compile: do everything except compile
- no_link: do everything except link
- one_step: compile and link in one step
- parse_only: checks configuration file syntax
- show_only: shows requested commands but does not execute them
- verbose: shows requested commands as they are executed
- MakeOpt:
Uncomment to build a Makefile to compile the executable
-
ModInpt:
Defines the format of the boundary conditions input files to be used by BCON.
- m3conc: input a CCTM CONC file; used for nested simulations or windows of a parent domain
- profile: input an ASCII vertical profiles file
-
ModMech:
Defines if the input boundary conditions data need to be converted from one chemical mechanism to another.
- mc_noop: do not perform any mechanism conversion; used when extracting boundary conditions from a CCTM CONC file for a nested simulation or when the input profiles are already formatted for the correct mechanism
- user_defined: input the file defined by the MECH_CONV_FILE variable; used for custom mechanism conversions
- radm2_to_cb4: convert the input boundary conditions profiles from RADM2 to CB-IV speciation
- radm2_to_saprc99: convert the input boundary conditions profiles from RADM2 to SAPRC99 speciation
-
Mechanism:
Specifies the gas-phase, aerosol, and aqueous phase chemical mechanisms to create boundary conditions for. The choices for the Mechanism variable are the mechanism directory names under the $M3MODEL/include/release directory. Examples include:
- cb4_ae3_aq: CB-IV gas-phase mechanism, 3rd generation CMAQ aerosol mechanism, aqueous/cloud chemistry
- cb4_ae4_aq: CB-IV gas-phase mechanism, 4th generation CMAQ aerosol mechanism, aqueous/cloud chemistry
- saprc99_ae4_aq: SAPRC99 gas phase mechanism, 4th generation CMAQ aerosol mechanism, aqueous/cloud chemistry
- saprc99_ae3: SAPRC99 gas phase mechanism and 3rd generation CMAQ aerosol mechanism
Section 3.3 provides an overview of how to install and compile the CMAQ programs for the tutorial simulation. Follow the steps outlined in Section 3.3 to compile new versions of ICON:
- If you have not already done so, build the CMAQ source code and compilation management program (M3BLD); this only needs to be done the first time you install CMAQ
- Install and compile the I/O API and netCDF libraries; if these are already available from a previous CMAQ compilation, configure the ICON build script to use the available libraries
- If you have not already done so, compile the STENEX library
- Configure the ICON build script for your application
- Invoke the build script to create an executable:
./bldit.icon.pgf
The environment variables listed here are invoked during execution of the program and are set in the ICON run script.
- EXEC: [default: ICON_${CFG}]
Executable to use for the simulation
- NPCOL_NPROW: [default: 1 1]
Domain decomposition for parallel mode; ICON is normally run in a single processor environment, so this setting should always be “1 1”.
- GRIDDESC: [default: ../GRIDDESC1]
Grid description file for setting the horizontal grid definition
- GRID_NAME:
Name of the grid definition contained in the GRIDDESC file that specifies the horizontal grid for the current application of the model
- LAYER_FILE:
Name and location of a MET_CRO_3D file for specifying the vertical layer structure for the current application of the model
- OUTDIR: [default: $M3DATA/icon]
Output data directory
- IC:
Sets the input file type. The setting of this variable determines how the input and output environment variables are set by the run script.
- profile: sets the output file name to include the tag “profile” in the name; uses the variable IC_PROFILE to point to an ASCII vertical profile file for input to ICON. Also optionally looks for the variable MECH_CONV_FILE to point to a user defined mechanism conversion file.
- m3conc: used for nested simulations, sets the output file name to include a start date in the name; uses the variable CTM_CONC_1 to point to a CCTM CONC file for input to ICON. Also looks for optional Plume-in-Grid inputs if the ICON_PING variable is set to “YES”.
- DATE:
Sets the Julian date to use for tagging the ICON output file for nested runs.
- SDATE:
Julian start date for extracting initial conditions from a CCTM CONC file for a nested simulation. If SDATE is not set, ICON will use the first hour of the CTM_CONC_1.
- STIME
Start time for extracting boundary conditions from a CCTM CONC file for a nested simulation. If SDATE is not set, ICON will use the first hour of the CTM_CONC_1.
Table 5.8. ICON output files
| File Name | Format | Description |
|---|---|---|
| INIT_CONC_1 | GRDDED3 | Gridded initial conditions data output on the model grid defined by GRID_NAME |
The default location of the ICON output files is the $M3DATA/icon directory, controlled by the OUTDIR variable in the run script. The default naming convention for all ICON output files uses the APPL and GRID_NAME environment variables in the file name. For initial conditions created from existing CCTM CONC files, the Julian date is also used in the file name through the DATE environment variable. All of the file naming variables for ICON outputs are set in the run script.