The program PROCAN creates a set of include files needed to instrument the CCTM to produce process analysis output. This program reads and interprets instructions from a command file and then generates three Fortran include files (.EXT) used by CCTM to produce the Process Analysis outputs that were requested in the commands. The process analysis commands themselves are formatted according to a simple set of rules and a free-form format. Nevertheless, each command has a special syntax that must be followed, and each command makes use of special keywords and/or operators that have specific meaning to PROCAN. The commands are of three major types: global commands, IPR commands, and IRR commands. The discussion begins first, however, with a description of some general rules for configuring PROCAN.
PROCAN configuration is implemented through the command file PACP_INFILE. The free-form format of the PROCAN command file is similar to that used by the general mechanism processor, CHEMECH. In general, white spaces are ignored and line wrap is allowed (i.e., commands can be continued on a subsequent line after a hard return). The free-form format also allows embedded comments and makes use of special symbols to indicate the type of input data. Special rules for naming species, entering labels, and specifying numerical values, such as stoichiometric coefficients and rate constant parameters, are also used. Each major component of the command file is discussed below:
- Comments. All lines that have an exclamation point in column 1 are treated as comment lines and are ignored by PROCAN. Any text enclosed in braces ({ }) or parentheses (( )) is also treated as comment and ignored by PROCAN.
- Species names. PROCAN recognizes two types of species names: model species and user-defined Process Analysis species. “Model species” refer to species names in the Species Tables [Provide link to a table of species names for each mechanism]. These names
must be spelled exactly as they appear in that table. The following special rules have been established for user-defined
species names.
- The Process Analysis species names must not contain any blanks and can be up to 16 characters long.
- The name must begin with an alphabetic character but may contain any alphanumeric character (i.e., “A-Z”, “a-z”., and “0-9”) or the characters “:” and “_” after the first position.
- The name is case sensitive. Thus, NO2 and no2 would represent two different species.
- A name can have embedded comments but cannot span two lines.
- Label names. For some of the IRR commands, reaction labels appearing in the chemical mechanism reaction list input file can be referenced. These labels would normally be spelled exactly as they appear in the chemical mechanism reaction list input file, except embedded comments and their delimiters should be omitted. However, any embedded blanks in those label names should be omitted, and the label name should contain no more that 16 non-blank characters.
- Numbers. Numerical inputs in the command file can be either integer (e.g., 5), floating point (e.g., 5.0), or exponential (e.g., 5.0E+00). With the exponential format, the “E” may be either upper or lowercase; a positive exponent will be assumed if the sign of the exponent is missing.
- Command Line Terminator. Input command lines are terminated by a semicolon.
This section describes the individual process analysis commands that are used to construct a PROCAN command file. In the description of these commands, the following conventions will be used. Bold type is used for PROCAN keywords and normal type for user supplied inputs. Alternative inputs are separated by vertical bars (|), and optional inputs are enclosed in braces ({}). The PROCAN commands fall into three general categories:
- Process Analysis Global Commands. These commands include general specifications that are applicable throughout the configuration. These specific commands are described in Table 5-1.
- Integrated Process Rate Commandhe same number of time steps as the concentration output file. Since the I/O API currently has a limit of 120 output variables on a file, multiple files will be output if this limit is exceeded. These commands are described in Table 5-2.
- Integrated Reaction Rate Commands. The commands are specific to the configuration of the integrated reaction rates. The same considerations for file size and memory usage detailed above should be considered when using these commands. These commands are described in Table 5-4.
Table 5.16. Process Analysis Global Commands
| Command | Description |
|---|---|
| OUTPUT_DOMAIN = {LOCOL[n1] + HICOL[n2] + LOROW[n3] + HIROW[n4] + LOLEV[n5] + HILEV[n6]}; | The OUTPUT_DOMAIN command provides the capability to limit the IPR and IRR output data to a portion of the modeling domain. The ni in brackets are numbers that define the bounds of the output domain relative to the number of columns, rows, and vertical levels in the modeling domain. Thus, for example, the value for n1 must be greater than or equal to one and less than or equal to the number of columns in the domain. If any one domain specifier is omitted, the corresponding end of the modeling domain is used as a default. If the command is omitted entirely, output is generated for the entire domain. |
| DEFINE FAMILY familyname = {c1*}species1 {+ {c2*}species2 + ...}; | The DEFINE FAMILY command is used to define a group of species as members of a family. The user specified “familyname” must be unique, and can be referenced in subsequent commands. The ci are numerical coefficients that default to one if not specified; “speciesi” represents the model species names. |
| ENDPA; | The ENDPA command signifies the end of the command input in the PACP command file. |
Table 5.17. Integrated Process Rate Output Command
| Command | Description |
|---|---|
| IPR_OUTPUT species|familyname|ALL = {pcode1 + pcode2 + ...}; | The IPR_OUTPUT command defines specific IPR outputs to be generated during a CMAQ CTM simulation. A model species name, family name, or the keyword ALL must follow the IRR_OUTPUT keyword. The keyword ALL refers to all model species. IPRs are generated for the selected species or family, and they are controlled by the specified values of pcodei, where pcodei corresponds to one of the process codes listed below. If no process codes are specified, IPRs will be generated for every science process (i.e., the first 12 codes shown in Table 5-3). The output variables that are generated are named either species_pcodei or familyname_pcodei. |
Table 5.18. IPR process codes
| Process Code | Definition |
|---|---|
| XADV | Advection in the E-W direction |
| YADV | Advection in the N-S direction |
| ZADV | Vertical advection |
| ADJC | Mass adjustment |
| HDIF | Horizontal diffusion |
| VDIF | Vertical diffusion |
| EMIS | Emissions |
| DDEP | Dry deposition |
| CHEM | Chemistry |
| AERO | Aerosols |
| CLDS | Cloud processes and aqueous chemistry |
| PING | Plume-in-grid |
| XYADV | Sum of XADV and YADV |
| XYZADV | Sum of XADV, YADV, ZADV |
| TOTADV | Sum of XADV, YADV, ZADV, and ADJC |
| TOTDIF | Sum of HDIF and VDIF |
| TOTTRAN | Sum of XADV, YADV, ZADV, ADJC, HDIF, and VDIF |
Table 5.19. Integrated Reaction Rate Output Commands
| Command | Description |
|---|---|
| IRR_TYPE = FULL|PARTIAL|NONE; | The IRR_TYPE command defines the type of IRR analysis. With the type set to FULL, IRRs for each individual reaction will be calculated and written to the IRR output file, and all other IRR commands will be ignored. IRR_TYPE set to PARTIAL indicates that the IRR commands following this command are to be processed to produce user-defined IRR outputs. Type set to NONE causes all IRR commands to be ignored and no IRR output to be generated. If the command is omitted, type PARTIAL is assumed. |
| DEFINE RXNSUM cyclename = species1; | The DEFINE CYCLE command is used to compute the net of all chemical production and loss of a species. Thus, this quantity is computed by summing the IRRs for all reactions in which a species is consumed, and then subtracting that sum from the sum of the IRRs for all reactions in which the species is produced. The “cyclename” is a user-defined name that must be unique, and can be referenced in subsequent IRR_OUTPUT commands. |
| DEFINE CYCLE sumname = {c1*}<rxlabl1> { ± {c2*} <rxlabl2> ± ...}; | The RXSUM command is used to compute a linear combination of the IRRs for individual reactions that can then be referenced in a subsequent IRR_OUTPUT command; “sumname” is user-defined and must be unique. The linear combination of IRRs is defined according to the expressions following the equal signs that specify which reactions's IRRs to sum. The “rxlabli” is the reaction label that is used in the generalized mechanism. The “ci” are optional numerical coefficients that default to one if not specified. |
| IRR_OUTPUT irrname = {c1*}op1|cyclname{qual1}| sumname{qual1}| <rxlabl1>{ ± {c2*}op2 | cyclname{qual2}| sumname{qual2}| <rxlabl2> + ...}; | The IRR_OUTPUT command defines a specific IRR output to be generated during a CMAQ simulation. It is constructed by specifying a linear combination of IRR operators, IRR global definitions, or IRRs for specified reactions. Each individual term in the combination must include either one of the five IRR operators described in Table M-14 (i.e., opi), a cycle name, a reaction sum name, or a reaction label enclosed in “greater than” and “less than” signs. The optional qualifiers (quali) for cyclename or reaction sum name can be either POSONLY or NEGONLY. With these qualifiers, the defined quantity is included as a term only when it is positive or negative, respectively. If the name is not qualified, the quantity is included regardless of sign. The numerical coefficients for each term (ci) are assumed to be one unless they are explicitly included. The irrname that is supplied by the user will be assigned as the variable name in the I/O API IRR output file. |
| DESCRIPTION = “description”; | The description command is provided to allow the user to specify a long description of the output variable that will be included on the I/O API IRR output name. If a description is not specified for an IRR_OUTPUT variable, the irrname (or short name) will be used in the output file. If the description command is used, it should be located immediately following the IRR_OUTPUT command to which it applies. |
| PROD [species1] {FROM[species2] {AND|OR [species3] }} | The PROD operator is used to compute the total production of a species by summing the IRRs of all reactions in which species1 appears as a product. The optional qualifiers FROM and/OR restrict the sum to include only those reactions in which species2 and/or species3 are reactants. The “speciesi” can be any gas-phase mechanism species or a family of gas-phase species; “species2” or “species3” may also be the keyword HV to restrict the selection to photolytic reactions. |
| NETP [species1] {FROM[species2] {AND|OR [species3] }} | The NETP operator is very similar to the production operator since it is used compute the production of a species. Whereas the PROD operator includes every reaction in which species1 occurs as a product, the NETP operator includes only those reactions in which the net production of species1 is greater than zero. Thus, if species1 or any member of the family species appears as both a reactant and a product with equal stoichiometry in a reaction, the PROD operator will include it, but the NETP operator will not. This operator is useful for getting the net production of a family, for example. |
| LOSS[species1] {AND|OR [species2] } | The LOSS operator is used to compute the total loss of a species by summing the IRRs of all reactions in which species1 appears as a reactant. The optional qualifier AND restricts the sum to include only those reactions in which both species1 and species2 are reactants. Similarly, the OR qualifier includes all reactions in which either “species1” or “species2” appears as a reactant, where “species1” or “species2” can be any gas-phase species in the mechanism, a family name that includes only gas-phase mechanism species, or the keyword HV to restrict the selection of reactions to those that are photolytic. |
| NETL[species1] {AND|OR [species2] } | The NETL operator is very similar to the loss operator since it is used to compute the loss of a species. However, it includes only those reactions in which there is a net loss of “species1” and/or “species2”. Thus, if species1 or any member of the family species appears as both a reactant and a product with equal stoichiometry in reaction, the NETL operator will not include it in summing the loss of that species, whereas the LOSS operator will include the IRR for that reaction. |
| NET[species1] | The NET operator is similar to the CYCLE definition since it gives the net of the production and the loss of a species for all reactions in which “species1” appears either as reactant or a product; “species1” may be any gas-phase, mechanism species or any family consisting wholly of gas-phase mechanism species. |
The environment variables listed here are invoked during execution of the program and are set in the PROCAN run script.
-
EXEC: [default: PACP_${CFG}]
Executable to use for the simulation
-
PACP_INFILE: [default: $M3DATA/procan/pacp.inp]
PROCAN control file for setting process analysis configuration