SAPRC-99 Mechanism Files and Associated Programs and Examples

Documentation Prepared June 10, 2000
Files Last Updated September 25, 2001
Page Last Updated March 30, 2010

William P. L. Carter
Research Chemist
Air Pollution Research Center, and
College of Engineering, Center for Environmental Research and Technology
University of California, Riverside, CA 92621

Phone: (951) 781-5797
Fax: (951) 781-5790
e-mail: carter@cert.ucr.edu
home page: https://intra.cert.ucr.edu/~carter

Please Note:
The SAPRC-99 mechanism has been superceded by the SAPRC-07 mechanism, available at /~carter/SAPRC. This page and the files linked to it are retained for information purposes, but much of the information below is out of date. If you need current information, please to to the current SAPRC mechanism page, referenced above. Please contact me if you need information or files about the SAPRC-99 mechanism that are not available here.

Contents


Summary

This distribution contains files and programs implementing the SAPRC-99 gas-phase atmospheric chemical mechanisms for use in airshed models for predicting the effects of VOC and NOx emissions on tropospheric ozone and other measures of air quality. The detailed mechanism, its evaluation against chamber data, and ozone reactivity scales calculated using it are documented in detail by Carter (2000a) A condensed, fixed-parameter version of the mechanism is also available Carter (2000b), and files implementing this version are also included.

Included in this distribution are several programs that can be used to implement these mechanisms for model calculations. Executables are included that run on PC-compatible systems, and FORTRAN source code for these programs are included so they can be modified or compiled for use on other systems. The programs include all those necessary to calculate ozone reactivity scales for VOCs using this mechanism and the scenarios and methods of Carter (1994). These programs and files can be used to duplicate the reactivity data given by Carter (2000a), or can be used in conjunction with the mechanism generation system at /~carter/mechgen.htm to calculate ozone reactivities for VOCs whose structures you specify (provided those structures can be handled by this system (see Carter, 2000a). Also included are programs to conduct simulations of environmental chamber experiments using the mechanism, and programs needed to derive parameters in the mechanism that depend on the mixture of compounds being represented. Although these programs are unfortunately not comprehensively documented, several batch files showing examples of their use are included to illustrate their use. These are discussed further below.

The tables below list the distributed files and programs, indicating the directory structure into which they should be installed. he files must be in this directory structure relative to each other for the examples files and the batch files that compile and link the programs to work. This structure shown schematically on Figure 1.

The purposes of the files in these directories are as follows:

Figure 1. Directory structure for installed files
                +- Mech   --- SAPRC99 -- Models3
                |
                +- Example--- char
(root for       |
 distribution) -+- React  -+- cmpfiles
                |          +- inpfiles
                |          +- SAPRC99* -+- clcfiles*
                |                       +- rctfiles*
                +- Pgms
                |          +- subs **
                +- Source -+- champgms **
                |          +… etc. **
                +- Lib ***
* These subdirectories are not on the distribution, but are created when the "Lumpall" batch file is run to initialize for reactivity calculations.
** Only needed if you want to modify any of the programs.
*** Only needed if you want to modify the mechanism or any of the programs.

 

Installation Instructions

The installation should be done in a DOS window, preferably under Windows 3.1, 95 or 98. I have found that some of the executables cause the computer to crash when run in pure DOS mode on some machines, and that although the installation is successful and the programs run in a Windows NT 4.0 DOS box, every so often the programs fail to run for no apparent reason. They have not been tested under Windows 2000 or other operating systems. (Note added 3/2010: These programs run under Windows 2000, as originally distributed, but F77L/EM won't run under Windows 2000 with the latest security updates and will not run under XP or later systems. None of the programs run under Vista. Check the current SAPRC mechanism files distribution for the latest available program files.)
 

  1. At a minimum the file MODEL.ZIP, INSTALL.BAT and PKUNZIP.EXE should be downloaded, and all put in the same (temporary) directory.

  2.  
  3. Create a directory on a disk with at least 40 MB free that will serve as the "root" subdirectory for the distribution. All files will be installed in a subdirectory structure below this as shown in Figure 1.

  4.  
  5. Give the command "A:\tmp/INSTALL a:\tmp d:\root", where "A:\tmp" should be replaced by the designation of the disk and directory where you copied MODEL.ZIP, INSTALL.BAT, AND PKUNZIP.EXE, and "D:\root" should be replaced by the designation of the disk and directory that you created in the previous step. Note that the directory D:/root must already exist; the install batch file doesn’t create it. If the above instructions were followed properly, the files should be extracted and be in the directory structure shown in Figure 1. The files installed in the root directory are listed in Table 1, and the other tables list the files installed in the various subdirectories.

  6.  
  7. If you do not have a license for Lahey F77L/EM or its current equivalent, then delete all the files that were installed in the LIB subdirectory. You will be able to run the examples and do chamber and reactivity calculations using the installed executable files, but you will not be able to modify the mechanism or any of the programs. If you do not intend to modify any of the programs, you can also delete the files in the subdirectories to SOURCE, though you will need to keep SOURCE/INT3.LIB if you want to modify any of the mechanisms.

  8.  
  9. After it installs the files, the INSTALL.BAT procedure will test to see if your DOS window has sufficient environment space for the example batch files and other procedures to run. If it does, you will get a message saying so. If it doesn’t, look at FIXENV.TXT to see how this can be addressed for various operating systems. This should not be a problem for properly configured Windows 95 or higher systems.

  10.  
  11. INSTALL.BAT also creates a file called NEWENV.BAT that sets the environment variables that are needed to run the examples and compile the programs and mechanisms. Note that unless you edit NEWENV.BAT as indicated in comments to that file, running it will over-write your path so other programs you may not use will no longer work in this DOS window. NEWENV.BAT called when you run any of the example batch files, and also if you open the window using WIN95DOS.PIF. Otherwise, you will need to run this manually in order for the programs to work.

  12.  
  13. Run EXAMPLE.BAT to run the examples and test the installation. It will fail if the environment space is inadequate or files are missing or not installed properly. If it succeeds it will run EXAMPLE\EXAMPLE1.BAT and create the files SIMPLE.CSV and DTC707A.CSV in the EXAMPLE directory and pause. Then it will run some reactivity calculations for AIRLMPBS, create the file REACTEX.CSV in the REACT subdirectory, and show reactivity results for MIBK. See the comments in those batch files for the programs they run and the output they produce. Note that your path will be over-written after you run EXAMPLE.BAT, so you may not be able to use this DOS window for other programs.
Table 1. Downloaded files and Files in the root directory used for installation, documentation, and testing.
 
  Files that must be downloaded and placed in a temporary directory. See the Installation Instructions for details.
INSTALL.BAT Used to install the files in the appropriate location. This is copied to the root directory during the installation process.
PKUNZIP.EXE Used by INSTALL.BAT to uncompress the files for installation. This is copied to the root directory during the installation process.
MODEL.ZIP The ZIP archive file with all the files in the distribution. This large file is not copied to the root directory, and can be deleted if the installation is successful.

Root Directory. See the Installation Instructions for details.
NEWENV.BAT Used to set the path and environment variables as needed to run the distributed programs. Created by INSTALL.BAT.
TESTENV.BAT Used to determine if the DOS box used to run the programs has adequate environment space.
FIXENV.TXT Information on how to deal with inadequate environment space if this is indicated by TESTENV.BAT.
README.TXT Basic information about the files and installation procedure.
SAPRC99.htm This document in HTML format
EXAMPLE.BAT Example calculations and installation tests.

 

Mechanism Files

The files implementing SAPRC99 mechanism are listed in Table 2. The major set of mechanism files is in the MECH\SAPRC99 directory; these are sufficient for implementing the detailed or "adjustable parameter" version for reactivity calculations, ambient air, or chamber simulations. These files are used for the simulations in the example calculations in the EXAMPLE and REACT directories in this distribution. They can also be adapted for use with other airshed model software that presently can support use of the adjustable parameter versions of earlier versions of the SAPRC mechanism (e.g., SAPRC90 or SAPRC97), though some modifications to the software and the files may be needed.

It is not necessary to run any programs in the MECH\SAPRC99 directory to prepare the mechanisms to run the example calculations discussed below. However, as indicated on Table 2, several batch files are available for this purpose, which would need to be run if the mechanism were modified.

Files needed to implement the fixed parameter version of the mechanism that was developed for implementation into Models-3 and other modeling systems that cannot handle variable parameter mechanisms are in the MECH\SAPRC99\MODELS3 directory, and are listed on Table 3. The fixed parameter version is documented by Carter (2000b). This directory also contains the batch files to run example calculations that are discussed by Carter (2000b); as indicated on Table 3. Note that the files that are used by both the fixed parameter version and the full version are in the MECH\SAPRC99 directory; the MODELS3 subdirectory only contains the files that are specific to this version. This is somewhat different than the arrangement of the files as documented by Carter (2000b). A simpler distribution that contains only the MODELS3 files as discussed by Carter (2000b) is available at /~carter/SAPRC99/s99mod3.htm

The files currently available for implementing this mechanism in the UAM-FCM software of (Kumar et al, 1995) are listed in Table 4. As indicated above, the implementation of this version of the mechanism into this system is not yet complete, though most of files needed for this purpose are in the "Mech/SAPRC99" directory. (Note added 3/2010: This is not currently supported.)

For some applications and software implementations, it is desirable to represent all the VOCs explicitly, rather than using the lumped model species of the "fixed parameter" versions of mechanism, or having to use the special software and input processing required for the variable parameter version. The "Mech\DMSRXN" directory contains files giving the reactions of all the detailed model species that can be represented separately in the SAPRC-99 mechanism. These files are listed on Table 5. These can be used if desired to represent these species explicitly without having to use the parameter lumping programs, or could be used for implementing explicit versions of this mechanism.
 
 

Table 2. Files implementing the SAPRC-99 Mechanism in the "Mech\SAPRC99" directory.
 
File Description
  Directory = \MECH\SAPRC99
This contains the files implementing the SAPRC-99 mechanism for reactivity and chamber simulations, and for ambient simulations using the "variable parameter" version of the mechanism.
RCTPREP.BAT Batch file to compile all mechanism-specific model simulation programs needed for reactivity calculations. (Not needed unless mechanisms are modified)
KZSPREP.BAT Batch file to produce photolysis rates for sets of actinic fluxes that may be used for reactivity simulations. (Not needed unless photolysis files are changed or reactivity calculations are desired for a new set of actinic fluxes. Called by RCTPREP.BAT
MODELING.PRM Parameter file giving file locations and options for running model preparation and other programs in this directory.
PHF.LIS List of all photolysis files. Used by programs called by KZSPREP.BAT.
  Input files used to prepare mechanism-specific model simulation programs. (See RCTPREP.BAT).
AIRLMPBS.PRP Main input file used to prepare mechanism-specific program used for base case reactivity calculations.
AIRLMPG.PRP Main input file used to prepare mechanism-specific program used for added single VOC reactivity calculations.
AIRLMPMX.PRP Main input file used to prepare mechanism-specific program used for added test mixture reactivity calculations.
CHAMCALC.PRP Main input file used to prepare mechanism-specific program used for chamber simulations and other static calculations. This program should be used when the VOC input data are processed using CHAMLUMP.LPC
SAPRC99P.PRP Main input file used to prepare the mechanism-specific program recommended for use when representing complex ROG - NOx mixtures in airshed calculations. This program should be used when the VOC input data are processed using PARMLUMP.LPC.
BASEMECH.RXN Input file giving the reactions in the base mechanisms (reactions of the inorganic and common organic products). Used by CHAMCALC.PRP
SAPRC99F.RXN Input file giving the reactions in the "fixed parameter" mechanism used to represent the base ROG - NOx mixture used in the reactivity calculations. Used by the AIRLMP* models.
SAPRC99P.RXN Input file giving the reactions in the "variable parameter" mechanism recommended for use in airshed model simulations for representing complex ROG - NOx mixtures. Used by SAPRC99.PRP.
WALLS.RXN Input file giving the wall reactions that should be used when simulating chamber experiments. Used by all the PRP files.
BASETEST.RXN Input file giving special reactions used in base case reactivity simulations, that are needed by the software that processes and tabulates the reactivity results. Used by AIRLMPBS.PRP
ALKARO1.RXN Input files giving generalized reactions for VOCs that react only with OH radicals. Used by AIRLMPMX.PRP
ALKARO*.RXN
LMPGEN1.RXN Input files giving generalized reactions for any VOC. Used by all of the PRP files.
LMPGEN*.RXN
LMPPRD1.RXN Input files giving generalized reactions for any VOC product species. Used by CHAMCALC.PRP and AIRLMPG.PRP
LMPPRD*.RXN
*.PHF Input files used to specify absorption cross sections and quantum yields for photolysis reactions. Used for mechanism simulation program preparation and also by the programs called by KZSPREP.BAT. These include ACETONE, ACROLEIN, BACL_ADJ, BZCHO, C2CHO, CCHO_R, COOH, GLY_ABS, GLY_R, H2O2, HCHO_M, HCHO_R, HNO3, HO2NO2, HONO-NO, HONO-NO2, IC3ONO2, KETONE, MGLY_ABS, MGLY_ADJ, NO2, NO3NO, NO3NO2, O3O1D, and O3O3P.PHF.
*.EXE Output files produced by the mechanism simulation preparation program.

*.EXE are the executable files. 
*.MOD are the mechanism specific data files that must be read when the corresponding executable program is run. 
*.PRO are the output listing files. They are not needed to run the simulations.

*.MOD
AIRLMPBS.PRO
AIRLMPG.PRO
AIRLMPMX.PRO
CHAMCALC.PRO
SAPRC99P.PRO
  Input files used when "Lumping" or processing single VOCs or VOC mixtures for simulations using the variable parameter versions of the mechanism.
DMS.PRM Listing of all the detailed VOC model species, giving parameters such as molecular weight, carbon number, kOH, and description of each. Used by most "lumping" programs.
ARBEMIT.PRM Specification of the California ARB "ChemCode" emissions classes in terms of detailed VOC model species. Used by EMITOCMP.EXE when processing CARB emissions data for model simulations. Not to be used when processing EPA emissions data.
EPAEMIT.PRM Specification of EPA’s "Saroad" emissions classes in terms of detailed VOC model species. Used by EMITOCMP.EXE when processing EPA emissions data for model simulations. Note that the 6-digit numbers in many cases refer to different chemicals than those in ARB emissions databases.
  Lumping control files that determine how individual VOCs or complex mixtures are represented in model simulations. In general, each .LPC file prepares VOC data for a particular mechanism simulation program for a particular purpose.
CHAMLUMP.LPC Used when preparing input for conducting chamber or static simulations using CHAMCALC.EXE. Specified in CHAMCALC.PRM in the EXAMPLE directory.
PARMLUMP.LPC Used when processing emissions or preparing input for ambient air simulations using the "adjustable parameter" version of the condensed mechanism. Rate constant units are cm3 molec-1 s-1 for use with preparing reactions or airshed model software requiring rate constants to be in those units.
AIRCALC.LPC Same as PARMLUMP.LPC except the units for the rate constants are in ppm-1 min-1, as is required for use with the example programs and calculations.
EMITLUMP.LPC Used when processing emissions or preparing input for ambient air simulations using the "fixed parameter" version of the condensed mechanism. See Carter (2000b).
BASELUMP.LPC Used to prepare base case ROG mixtures for reactivity simulations. Used by LUMPALL.BAT in the REACT directory. Specified by BASEHC.PRM in the REACT directory.
TESTLUMP.LPC Used to prepare the input file used to specify input for reactivity simulations for individual VOCs. Used by LUMPALL.BAT in the REACT directory in preparing REACT\TESTHC.INS from MECH\SAPRC99\TESTHC.INP.
TMIXLUMP.LPC Used to prepare the input file used to specify input for reactivity simulations for mixtures. Used by LUMPALL.BAT in the REACT directory.
REACT.LPC Used by DMSRCT.EXE when summarizing reactivity data, i.e., when preparing the .RCT files in REACT\RCTFILES using the data in the reactivity simulation output files in REACT\CLCFILES. See the example batch files in the REACT directory. Specified in MODELING.PRM in the REACT directory in preparing REACT\TESTHC.INS from MECH\SAPRC99\TESTMIX.INP.
  Mechanistic parameter files referenced by the various .LPC files. Separate files are used for separate groups of compounds, with different groups determined by (a) whether the files were produced by the mechanism generation system or prepared manually (for assigned or parameterized mechanisms), and (b) how the various VOCs are to be lumped as specified by the LPC files.
ALKOTH.GNA Mechanistic parameter files that were produced by the mechanism generation system. ALKOTH is for those VOCs that react only with OH, Alkenes is for alkenes and other VOCs that react with other species but do not photolyze, ALDES is for aldehydes, KETONES is for ketones, ACROLS is for acroleins and other species that photolyze using acrolein’s absorption cross sections, EXXATES is for the components of "iso-acetate" mixtures, ACETYLS is for acetylenes when used in their simulations where their O3 reactions are represented, and ACETYL-OH is for acetylenes when lumped with species that react only with OH, as is appropriate when representing them in complex mixtures. The file EXPLVOCS.GNA contains the parameters for ethene and isoprene, which is needed in when using versions of the mechanism where they are not represented explicitly.
ALKENES.GNA
ALDES.GNA
KETONES.GNA
ACROLS.GNA
EXXATES.GNA
ACETYLS.GNA
ACTYL-OH.GNA
EXPLVOCS.GNA
TERPENES.GNA Mechanism parameter files that were produced manually for for assigned or parameterized mechanism species. TERPENES is used for terpenes, ASNALKE for other species that react with O3 and/or NO3, AROMATIC is used for aromatic hydrocarbons, ASNARO is used for other compounds lumped with aromatics, and ASNOTH is used for species that react only with OH, and includes the "placeholder" mechanisms for amines and halogenated compounds.
ASNALKE.GNA
AROMATIC.GNA
ASNARO.GNA
ASNOTH.GNA
LUMPMOLE.LPM This contains the "lumped molecule" assignments used in the current version of the mechanism.
OLDNAMES.LPM This gives the translation from obsolete model species names to names that have assignments in this version of the mechanism. It probably can be removed (but the LPC files would need to be edited to remove reference to it).
MIXES.LPM This specifies the composition (.CMP) files that are associated with model species that are mixtures. Used when processing emissions data that have emissions classes referring to mixtures.
EMITLUMP.LPM This gives the "lumped molecule" assignments that are used when processing complex mixtures for representation using the "fixed parameter" version of the mechanism. All the species specified here have better representations using the adjustable parameter versions of the mechanisms, but there is no other means to represent them in the fixed parameter version.
*.CMP Files specifying compositions of the model species that are mixtures. Referenced by MIXES.LPM. these are ARBROG, D95, ISOPARM, MS-A, MS-B, MS-C, MS-D, OC10ACET, OC12ACET, OC13ACET, OC6-ACET, OC7-ACET, OC8-ACET, and OC9-ACET.CMP.
  Other miscellaneous files used in the reactivity calculations.
EXPLKOH.PRM Gives the OH rate constants or other information needed to estimate kinetic reactivities of explicit model species. Used by REACTCAL.EXE when deriving how much compound to add when calculating its reactivity.
TESTHC.INP Gives the test compounds that are used in the reactivity simulations, including individual VOCs and "pure mechanism" species. Used as input when REACT/LUMPALL.BAT creates REACT/SAPRC99/TESTHC.INS with the input for the reactivity calculations. TESTHC.INP has the input for individual species, and TESTMIX.INP has the input for mixtures.
TESTMIX.INP
ALLDMS.BAT This is a batch file that can be used to calculate reactivities of all detailed model species that have mechanisms assigned to them. This should be called within the REACT directory, with the parameter being the scenario name. See the example batch files in the REACT directory for examples of its use.
PETERSON.JZS Input and output files for deriving photolysis rates as a function of zenith angle for various sets of actinic fluxes. The .JZS files have the actinic fluxes as a function of zenith angle, the .KZS files are the corresponding photolysis rates for those zenith angles, and the .FZS files are parameters of functions fit to the photolysis data that are used as input to the simulation programs when calculating reactivities. The .KZS and .FZS files are output by programs called by KZSPREP.BAT, using the .JZS and PHF files as input. The actinic flux files include "PETERSON.JZS" has the actinic fluxes from Peterson (1976), and "STDZA640.JZS" which are actinic fluxes calculated by Jeffries (personal communication) for 640 meters. Note that the KZS files can be used to verify photolysis rate implementations using other software.
STDZA640.JZS
PETERSON.KZS
STDZA640.KZS
PETERSON.FZS
STDZA640.FZS
STD640.FZS This is the .FZS file that is used when calculating photolysis rates in the reactivity simulations. It is set equal to STDZA640.FZS by KZSPREP.BAT.
ALLDMS.LIS Listing of all detailed model species. Can be used as input to the REACTTAB program to produce a tabulation of reactivity data for all VOC species. See REACT/AVGCOND.BAT for an example of its use.
  Assignment Files that are used by GNATORXN.EXE, GNATOMEC.EXE, RXPTORXN.EXE and RXPTOMEC.EXE when deriving reaction (.RXN or .MEC) files from parameter files.
GENHV.PRM Gives the photolysis files that are associated with the two-letter codes used in .GNA files for photolysis reactions. 
MODSPE.PRM Gives the product model species name that is associated with each two-letter code used in .GNA files.

Table 3. Files implementing the fixed parameter version of the SAPRC-99 Mechanism for Models-3 and other models that cannot support adjustable parameter mechanisms.
  Directory = \MECH\SAPRC99\MODELS3
Files for implementing the SAPRC-99 mechanism into Models-3 or other models requiring use of the fixed-parameter version. See Carter (2000b) for documentation of these files and examples. Note that a number of the files needed for implementing this version are in the MECH\SAPRC99 directory, not in this directory as indicated by Carter (2000b).
SAPRC99F.MEC Mechanism input file in Models-3 format for the fixed parameter condensed mechanism, with the mechanistic parameter for anthropogenic emissions derived using the mixture in ARBROG.CMP, which is the base ROG mixture used in the reactivity simulations (i.e., based on air quality data)
PHOTDATA.ZIP Compressed file containing photolysis absorption cross section and quantum yield files in Models-3 format. One .PHD file for each .photolysis reaction in the mechanism that has distinct absorption cross sections and quantum yields. PKUNZIP can extract these files.
EMITGRP.DAT Assignments of emissions group to lumped model species for use in emissions processing. See comments in file for format of data.
MODELING.PRM Default file locations for programs. In this case, gives the location of the composition files and the mechanism files used in the example calculations. Note that this indicates that some of the files are in the subdirectory below this, so if it is desired to have all the files needed by the examples in one directory, copy the files indicated there to this directory, and edit MODELING.PRM accordingly.
  Input files for Mechanism Test Simulations
MD3TEST.PRP Preparation program input file used to prepare the fixed parameter mechanism for the mechanism implementation test simulations. (It does not need to be prepared because the output files are also included.)
MD3TEST.EXE Executable simulation program to run test simulations using SAPRC software. Produced by SAPRC mechanism preparation program using MD3TEST.PRP.
MD3TEST.MOD Data file needed by MD3TEST.EXT to run test simulations. Produced by SAPRC mechanism preparation program using MD3TEST.PRP.
MD3TEST1.INT Simulation input file for Static multi-day simulation. Anthropogenic VOCs.
MD3TEST2.INT Static multi-day simulation. Anthropogenic VOCs. Low NOx.
MD3TEST3.INT Continuous emissions multi-day simulation, anthropogenic VOCs.
MD3TEST4.INT Continuous emissions multi-day simulation, biogenic VOCs.
MD3TEST5.INT Same simulation conditions as MD3TEST1, except for T=320K, rather than T=300K.
  Output files for mechanism test simulations.
MD3TEST1.CSV Results of the corresponding simulation using MD3TEST*.INT as input. These can be compared with output files using different software with the input as specified in the above .INT files.
MD3TEST2.CSV
MD3TEST3.CSV
MD3TEST4.CSV
MD3TEST5.CSV
  Emissions Processing and Mechanism Lumping Examples
LUMPCOMP.BAT Example batch file to derive the reactions of the ALKn, AROn, and OLEn model species to best represent the composition of the distribution of detailed model species in the file BASEROG.CMP The output file produced is LUMPCOMP.MEC. The reactions in that file can be used to replace the reactions of these species that are in the SAPRC99F.MEC file, as appropriate for the model application. The composition of BASEROG.CMP in this example is the same as that used to derive the lumped model species reactions in the default mechanism, so the reactions in of these species in LUMPCOMP.MEC should be the same as those in SAPRC99F.MEC. However, BASEROG.CMP can be replaced or edited as appropriate to represent different compositions.
LUMPEMIT.BAT Example batch file to derive the reactions of the ALKn, AROn, and OLEn model species to best represent the composition of the emissions profile given in the file EPAEMIT.EMI. The output file produced is LUMPEMIT.MEC. This can be used to replace the reactions of these species that are in the SAPRC99F.MEC file, if it is desired to use a mechanism optimized to represent this emissions inventory rather than a composition based on air quality data. The reactions of these species will be different than those in SAPRC99F.MEC.
LUMPTERP.BAT Example batch file to derive the reactions of TRP1 in the lumped mechanism, given the compistion of terpenes in the TERPENES.CMP file. The output file produced is LUMPTERP.MEC. This can be used to replace the reactions of TRP1 in the SAPRC99F.MEC file for model applications where the biogenic inventory suggests it is appropriate to use a different terpene composition than employed to derive these reactions in the current mechanism. This example just produces the same TRP1 mechanism as in SAPRC99F.MEC, but the file TERPENES.CMP can be edited as appropriate to represent a different terpene distribution.
  Input files for Emissions Processing and Lumping Examples
BASEROG.CMP Composition of ambient VOCs based on analyses of ambient air data used to derive the mechanisms of the ALKn, AROn, AND OLEn model species in SAPRC99F.MEC. Given in terms of mole emissions of SAPRC-99 detailed model species. Same as ARBROG.CMP, but can be replaced or edited as desired to represent different compositions.
EPAEMIT.EMI Emissions profile derived by EPA to represent regional model input for Models-3. Given as mass emissions for EPA SAROAD classes. This can be replaced or edited as desired to represent different emissions inputs.
TERPENES.CMP Composition of mixture used to represent biogenic terpenes. Used to derive TRP1 mechanism in the lumped mechanism. This can be replaced or edited as desired to represent different biogenic inventories.
  Output files for Emissions Processing and Lumping Examples
BASEROG.RXP Mechanistic parameters of lumped model species corresponding to the mixture of VOCs in BASEROG.CMP. Produced by CMPTORXP using BASEROG.CMP and EMITLUMP.LPC as input. Should be the same as LUMPCOMP.RXP produced by LUMPCOMP.BAT.
BASEROG.MEC Reactions of lumped model species corresponding to the mixture of VOCs in BASEROG.CMP. Produced by RXPTOMEC using BASEROG.RXP as input. Should be the same as the file LUMPCOMP.MEC produced by LUMPCOMP.BAT.
EPAEMIT.CMP EPA emissions profile in terms of detailed model species. Produced by EMITOCMP using EPAEMIT.EMI and EPAEMIT.PRM as input. Should be the same as the file LUMPEMIT.CMP produced by LUMPEMIT.BAT.
EPAEMIT.RXP Mechanistic parameters of lumped model species corresponding to the EPA (1999b) emissions profile. Produced by CMPTORXP using EPAEMIT.CMP and EMITLUMP.LPC as input. Should be the same as the file LUMPEMIT.RXP produced by LUMPEMIT.BAT.
EPAEMIT.MEC Reactions of lumped model species corresponding to the EPA emissions profile. Produced by RXPTOMEC using EPAEMIT.RXP as input. Should be the same as the file LUMPEMIT.MEC produced by LUMPEMIT.BAT.
TERPENES.RXP Mechanistic parameters of the lumped model species corresponding to the mixture of terpenes in TERPENES.CMP. Produced by CMPTORXP using TERPENES.CMP and PARMLUMP.LPC as input. Should be the same as LUMPTERP.RXP produced by LUMPTERP.BAT.
TERPENES.MEC Reactions of the TRP1 model species corresponding to the mixture of terpenes in TERPENES.CMP. Produced by RXPTOMEC using TERPENES.RXP as input. Should be the same as the file LUMPTERP.MEC produced by LUMPTERP.BAT.

 

Table 4. Files needed to implement the mechanism in the UAM-FCM system of Kumar et al (1995). (This set of files is presently incomplete)
 
  Directory = \MECH\SAPRC99\FCM

Files specific for the UAM-FCM implementation of the SAPRC-99 mechanism. (This is presently incomplete)

FCMCHANG.BAT Batch file to change the names of the model species in the .RXN files needed by UAM-FCM so they are compatible with the UAM software. Unfortunately, this does not work on large files, and SAPRC99P.RXN had to be split in two for this to work for it.
SAPRC99P.RXN Same as MECH\SAPRC99\SAPRC99P.RXN except the names have been changed using FCMCHANG.BAT.
SAPRC99P.PRP Same as MECH\SAPRC99\SAPRC99P.PRP except the names have been changed using FCMCHANG.BAT.
SAPRC99P.PRO 

SAPRC99P.MOD 

SAPRC99P.EXE

Output files from preparing the FCM version of the SAPRC99P mechanism for implementation testing.
SAPRC99P.LPC Same as AIRCALC.LPC in the MECH\SAPRC99 directory, except that it uses the FCM-compatible names as indicated in FCMCHANG.BAT. Uses the .GNA and .LPM in the MECH\SAPRC99 directory.

 
 

Table 5. Explicit reaction files for all the VOC model species that are represented in the mechanism.
 
  Directory = \MECH\SAPRC99\DMSRXN
This contains the reactions of all the detailed model species that can be represented separately in the SAPRC-99 mechanism. These can be used if desired to represent these species explicitly without having to use the parameter lumping programs.
MAKERXN.BAT Batch file to produce the reaction files in both the .RXN and .MEC files from the associated mechanistic parameter (.GNA) files (see below). Needs to be run only if the mechanistic parameter files are modified.
*.RXN Reactions of the detailed model species in either SAPRC (.RXN) or Models-3 (.MEC) format. One file for each .GNA file in the mechanism (see above).
*.MEC

 

Example Calculations

A number of example calculations are included with this distribution to illustrate the use of these programs. These batch files, and the input files they use, can be modified as desired for specific applications of interest, or used as a basis for showing how the programs are used. Most of these batch files that are intended to be called directly by the user have comments describing what is being done in the various steps involved in the procedures.

Two sets of examples are included in this distribution. Those in the directory EXAMPLE are used to illustrate some simple calculations and lumping procedures, and those in the directory REACT are used to illustrate reactivity calculations. In both cases, the environment must be set as discussed above in the installation instructions. This can be done by running the NEWENV.BAT procedure in the root directory or, for Windows 95 or 98 systems, by using WIN95DOS.PIF to open the DOS window to run the programs. The default directory must be the EXAMPLE or REACT directory, as applicable.

The files in the EXAMPLE directory are listed on Table 6, and the specific example calculations there are are discussed below. The reactivity examples are discussed in the following section.

EXAMPLE 1

EXAMPLE1.BAT shows examples of two model simulations, one with a simple static system and the other of an indoor chamber experiment. The output files are model simulation listing output (.OUT) files produced directly by the simulation program, and .CSV files containing the calculated concentration-time in a comma-separated-value format that can be read by spreadsheet programs. Intermediate output files are also produced, as discussed in the comments in the batch file.

Both these calculations use the variable-parameter version of the mechanism, where the individual VOCs not represented in the base mechanism are represented using adjustable parameter model species. The initial concentrations of these species must be specified with in the group of records defined by the .LUMP command in the input (.INP) file, and the program LUMPINT is called by INTRUN to derive the parameters that correspond to these species.

The input file for the first calculation run by EXAMPLE1.BAT is SIMPLE.INP. This is a simple static simulation of a propene + n-butane - NOx system. This can be modified as desired to simulate other systems. Note that the photolysis rates are calculated using spectral distribution data in the EXAMPLE\CHAR subdirectory (see Table 6).

The input file for the second calculation run by EXAMPLE1.BAT is DTC707A.INP, an example of an input file for simulating an environmental chamber experiment in the UCR chamber data base as described by Carter et al (1995). This can be thus be used as an example of how to simulate experiments in that data base using this mechanism. The DTC707A.INP file is the model simulation file produced by the RCHADINP program (Carter et al, 1995) for the full surrogate - NOx experiment DTC-707A.

EXAMPLE 2

EXAMPLE2.BAT gives examples of simulations of a simple system using the adjustable parameter version of the mechanism. These simulations can also be used for testing implementations of the mechanism using different software. For that reason, the output files produced by this example are also included; they are over-written if EXAMPLE2.BAT is run.

The model simulation input file used in this example is AIRTEST.INP. It is similar to the implementation test files included with the Models-3 distribution (Carter, 2000b), except that this uses the variable parameter version of the mechanism. To aid in implementation testing, the calculation is a static simulation with no dilution and with constant light intensity, and all the photolysis rates are input explicitly. (See the files for the Models-3 implementation, as discussed by (Carter, 2000b), to test the implementation of the photolysis rate calculation procedures.)

The VOC mixture used in the AIRTEST simulation used by EXAMPLE2.BAT is total emissions profile from a California Air Resources Board data set from the SCAQS episode. The model simulation program that reads AIRTEST.INP expects the data to be in terms of moles of SAPRC-99 detailed VOC model species per mole carbon of total VOCs.

To illustrate emissions lumping procedure, this example assumes that the emissions profile input data are given in terms of mass ARB ChemCode classes, that are specified as 6-digit numbers similar to, but not always exactly the same, as the EPA’s SAROAD classes. Therefore, before the simulation using AIRTEST.INP can be conducted, this emissions profile is converted into a profile giving moles of SAPRC-99 detailed model species using the EMITOCMP program. The emissions input data in this example is in the file ARBTEST.EMI, and the output file produced by EMITOCMP in this example is AIRTEST.CMP. Note that it uses the file MECH\SAPRC99\ARBEMIT.PRM to determine the relationship between the ChemCode classes and SAPRC detailed model species. If EPA emissions data are to be processed in this way, the file MECH\SAPRC99\EPAEMIT.PRM must be used instead.

Once the VOC input data are converted into the necessary format, the example simulation is run, using a procedure similar to those used in EXAMPLE1.BAT. The output file with the concentration-time data is AIRTEST.CSV. These data can be compared with results of calculations using other software and implementations, using AIRTEST.INP to determine the reaction conditions and either ARBTEST.EMI or AIRTEST.CMP to determine the VOC input.
 

Table 6. Files used in the example chamber simulation calculations.
 
  Directory = \EXAMPLE
EXAMPLE1.BAT Does example calculations of two model simulations, one with a simple static system using input in SIMPLE.INP and the other of an indoor chamber experiment, using input in DTC707A.INP. The output files are model simulation listing output (SINPLE.OUT or DTC707A.OUT) files produced directly by the simulation program, and the corresponding .CSV files containing the calculated concentration-time in a comma-separated-value format that can be read by spreadsheet programs. Intermediate output files are also produced, as discussed in the comments in the batch file.
SIMPLE.INP Input file for the simple static simulation.
DTC707A.INP Input file for an example of a chamber experiment in the UCR chamber data base as described by Carter et al (1995). This file is produced by the programs and files supplied with that data base.
CHAMCALC.PRM The parameter file indicating which model simulation programs and lumping control files to use when doing the calculations in EXAMPLE1.BAT. Also gives the locations of other files needed by the programs, such as the spectral distribution files in the CHAR subdirectory.

EXAMPLE2.BAT

Does example calculations converting an emissions profile in terms of mass emissions of ARB ChemCode species to molar emissions of SAPRC detailed model species, and does a simple static simulation using the VOC composition in this profile. This can be used to test implementations of the adjustable parameter version of the SAPRC mechanism into different airshed model software systems.

AIRTEST.INP
EXAMPLE2 input files
The input file for the simple static simulation used by EXAMPLE2.BAT. All the photolysis rates are given explicitly, and there is no dilution. The light intensity is constant for 12 hours, then dark for 12 hours, then constant at the initial values, to test simulations for both light and dark conditions. The VOC input data are expected to be in the file AIRTEST.CMP.
ARBTEST.EMI The input file used by EXAMPLE2.BAT that gives an emissions profile in terms of mass emissions of ARB ChemCode classes. These are specified by 6-digit number similar to, but not exactly the same as, the EPA’s SAROAD classes. The assignment of these classes in terms of SAPRC-99 detailed model species is in the file MECH\SAPRC99\ARBEMIT.PRM.
AIRCALC.PRM The parameter file used for model simulations using the adjustable parameter version of the SAPRC-99 mechanism, with VOC input lumped in a way appropriate for ambient simulations. This is used to indicate which model simulation program and lumping control file to use in the calculations used by EXAMPLE2.BAT. Also gives locations of files used. See comments in the file.
FCMCALC.PRM Same as AIRCALC.PRM except uses simulation program and lumping control file in MECH\SAPRC99\FCM subdirectory. Running the AIRTEST simulation in EXAMPLE2.BAT using this instead of AIRCALC (in the INTRUN AIRTEST AIRCALC command) should give the same result, except for the different species names.

AIRTEST.CMP
EXAMPLE2 output files
The output file produced by EXAMPLE2.BAT giving the VOC profile specified in ARBTEST.EMI in terms of moles of SAPRC-99 detailed model species. This is referred to in AIRTEST.INP as the source of the VOC composition data.
AIRTEST.CSV The concentration-time profiles produced by running the calculation with AIRTEST.INP and ARBTEST.EMI in EXAMPLE2.BAT, in spreadsheet-compatible comma-separated-value format.
  Directory = \EXAMPLE\CHAR
Contains files used to run the calculations in EXAMPLE1.BAT
DTC-18.CHR The chamber characterization parameter specification needed to run the example chamber simulation for run DTC707A. This is part of the UCR chamber data base described by Carter et al (1995).
ITCUSE.SDR The spectral distribution needed to run the example chamber simulation for run DTC707A. This is the spectral distribution recommended for modeling chamber experiments using blacklights, and is part of the UCR chamber data base described by Carter et al (1995).
Z0.SDR The spectral distribution needed to run the "SIMPLE" example calculation. This represents the spectral distribution of direct overhead sunlight as given by Peterson (1976).

 

Reactivity Example Calculations

The files to conduct reactivity simulations using the procedures and scenarios described by Carter (1994), but with this version of the mechanism are in the REACT directory. Several example calculations are included to illustrate how to use these programs to duplicate the reactivity data given by Carter (2000a), or to calculate reactivities for other VOCs in conjunction with the SAPRC99 mechanism generation system. The files in this directory are listed in Table 7.

The REACTEX.BAT batch file runs several example reactivity simulations, which are described in more detail in the comments in the files. Before it runs the simulations, it makes sure the necessary preparation steps have been taken, which involves compiling the mechanisms if needed (which shouldn't be required), creating the subdirectories for the calculations, and running LUMPALL.BAT to prepare the VOC input data for the base case mixtures and the individual VOCs whose reactivities are to be calculated. Then it runs the base case simulation for the "averaged conditions" scenario, and reactivity simulations for several VOCs. It then uses DMSRCT to calculate the reactivity scale, and REACTTAB to produce a summary of the reactivity results in a comma-separated value file REACTEX.CSV.

REACTEX.BAT also runs an example of a reactivity calculation using the output of the mechanism generation system, in the file TESTVOC.DAT, with methyl isobutyl ketone as the example VOC. The reactivity results are summarize to the screen. Methods for accessing the mechanism generation system through the internet to produce these files for any selected VOC that can be processed by this system are discussed in the following section.

Several other batch files are also included in this distribution to give examples of different types of reactivity calculations. The AVGCOND.BAT batch file shows how the reactivity scales can be calculated for the averaged conditions adjusted NOx MIR, MOIR, and EBIR scenarios. Similar procedures can be used for calculating these scales for any of the individual 39 EKMA scenarios. See comments in AVGCOND.BAT for details. See Table 7 for a summary of these files and what they are used for.
 

Table 7. Files used for reactivity calculations in the "React" directory and its subdirectories.
 
  Directory = \REACT
REACTEX.BAT Runs several example reactivity simulations, using the "averaged conditions base case scenario. Runs LUMPALL.BAT if needed to initialize for reactivity calculations with this mechanism, runs the base case and several example reactivity calculations, produces the reactivity scale for these VOCs, and produces a summary of the results in REACTEX.CSV. Also runs an example of a reactivity calculation using the output of the mechanism generation system, in the file TESTVOC.DAT, with methyl isobutyl ketone as the example VOC. 
AVGCOND.BAT Prepares the base case adjusted NOx scenarios based on the "averaged conditions" base case scenario, and runs some example reactivity calculations using them. Does initialization calculations (such as running LUMPALL and the base case simulation for the base case "averaged conditions" scenario) if needed. Runs MROPT2.EXE to determine the MIR, MOIR, and EBIR points and runs the base case and several added VOC simulations for those scenarios. Produces a summary of the results and outputs that in AVGCOND.CSV.
LUMPALL.BAT  This is used to initialize for reactivity calculations by processing all the mechanism-dependent files that are needed. First it creates all the subdirectories that are needed for the mechanism-specific processed files and the output files, i.e., REACT\SAPRC99 and its subdirectories. 
RCTALL.BAT This is used to prepare all the reactivity scales for all the scenarios, including the individual scenario and multi-scenario scales. Only useful after REACTCAL has been called for all the scenarios and VOCs. Useful for showing how the multi-scenario scales are created. The comments in the file also indicate the codes used for the various types of reactivity scales.
SCENARIO.PRM Used to specify the conditions of the base case scenarios, such as the input file to use, NOx and VOC levels, and other parameters used in the reactivity simulations that may depend on the scenario. See comments in file. Read by REACTCAL.EXE when running the simulations for the base case condition. After that, the data are read from the .BAS file when doing the calculations for the added VOCs.
MODELING.PRM Contains the parameters, specifications, and file locations used when running the reactivity calculation programs for this mechanism. See comments in the file.
BASEHC.PRM  Gives the lumping control file and other parameters used when the CMPTOLMO.EXE program called by LUMPALL.BAT creates the input file for the base ROG mixture.
TESTVOC.DAT  This is an example of a mechanism generation output file that is used by REACTEX.BAT to show how reactivity calculations can be run using mechanism generation output. This example contains the parameters for methyl isobutyl ketone.
EPASCN*.LIS, etc. Contains a list of the individual base case (BS), MIR (MR), MOIR (MO) and EBIR (NL) scenarios. Used by RCTALL.BAT when creating the multi-scenario scales.
REACTTAB.TXT  A text file giving a very out-of-date documentation of the reactivity scales and the REACTTAB and RENORCMP programs. Although out of date, it is useful in describing the capabilities of those programs. The part about the REACTTAB options specified in the interactive or command line versions were updated to reflect the current version, but other parts of the discussion may not accurately describe the current version.
  Directory = \REACT\CMPFILES
*.CMP Files giving compositions for all mixtures whose reactivities are calculated. These include ALOFT, ARBMIX1, ARBMIX1N, ARBROG, CNG-TLEV, D95, E85-TLEV, ISOPARM, LPG-TLEV, M85-TLEV, MS-A, MS-B, MS-C, MS-D, OC10ACET, OC12ACET, OC13ACET, OC6-ACET, OC7-ACET, OC8-ACET, OC9-ACET, PH2-LEV, PH2-TLEV, RFA-LEV, and RFA-TLEV.CMP. See DMS.PRM for descriptions of these mixtures.
  Directory = \REACT\INPFILES
Contains input files for scenarios used in the reactivity calculations.
AVGEPA.INP The input file giving the conditions of the "Averaged conditions" scenario of Carter (1994).
*1.INP The input files giving the conditions of each of the 39 city-specific base case scenarios of Carter (1994).
PETERSON.JZS Gives the actinic flux data of Peterson (1976) that can be used for calculating photolysis rates. 
STDZA640.JZS Gives the actinic flux data that are used for calculating the photolysis rates for the scenarios of Carter (1994). Used as input to the programs called by MECH\SAPRC99\KZSPREP.BAT when calculating photolysis rates for the mechansm.
  Directory \REACT\SAPRC99
This directory and its subdirectories and the files listed below are not on the distribution, but are created when the mechanism-specific files are initialized using LUMPALL.BAT.

The REACT\SAPRC99 directory contains the mechanism-specific input files needed for the calculations. Its subdirectories contain the output files, as described below.

ARBMIX1.RXP Input file specifying the composition of the base ROG surrogate in terms of model species and mixture-dependent parameters. Created by LUMPALL.BAT
ALOFT.LMO The composition of the aloft ROG mixture used in the scenarios, in terms of lumped model species. Parameters are not given for the variable-parameter model species because the parameters used for the aloft mixtures are the same as those used by the ground-level emissions, which are in ARBMIX1.RXP. Created by LUMPALL.BAT
TESTHC.INS The mechanistic parameters and other input needed to conduce reactivity simulations for all VOCs in the mechanism. Created by LUMPALL.BAT
  Directory REACT/SAPRC99/CLCFILES
This contains output files giving reactivity results for individual scenarios that are output by REACTCAL.
*.BAS Information about the input and results of the base case simulations. Created by REACTCAL.EXE when running a simulation for a base case scenario. MROPT2.EXE also outputs the NOx levels corresponding to MIR, MOIR, EBIR points and other data when it is run. These files are then used as input whenever REACTCAL is subsequently run for that scenario. One such file for each scenario.
*.CLC The maximum ozone and amounts reacted data for the individual VOCs for the individual scenarios. Contains all the data needed to calculate "ozone yield" reactivities. One such file for each scenario.
*.CLD More detailed reactivity results for the individual scenarios, giving the hourly ozone and other data that are needed to calculate "integrated ozone" reactivities and reactivities relative to other species, as indicated by the "MAXCAL" parameter in MODELING.PRM One such file for each scenario.
  Directory REACT/SAPRC99/RCTFILES
This contains output files giving reactivity scales for the individual scenarios that are output by DMSRCT.EXE Also contains the multi-scenario reactivity scales produced by RCTAVG.EXE, etc.
*.RCT The various reactivity scales, one for each scenario or multi-scenario scale.

 

Use of the Reactivity Programs with the Mechanism Generation System

As indicated above, these programs can be used to calculate incremental reactivities for VOCs whose parameters were derived using the SAPRC99 mechanism generation system, which is accessible over the Internet. REACTEX.BAT shows an example of how this can be done given the parameter file produced for a VOC. This section briefly describes how to do this for any VOC that can be processed by this system.

Before any reactivity calculations can be conducted for any VOC, the base case simulation must be run for that scenario. REACTEX.BAT does the base case simulation for the "averaged conditions" base case scenario, but other scenarios may be of greater interest. Of particular interest in the context of California regulations is the MIR scale, which can be approximated by conducting simulations using the "averaged conditions" MIR scenario, called the AVBARBBS scenario. The "averaged conditions" MOIR and EBIR scenarios, called AVGARBMO and AVGARBNL, respectively, are also of interest, since they approximate the MOIR and EBIR scales, respectively (see Carter, 1994, for a discussion of these scales). AVGCOND.BAT can be run to create these scenarios. Once it is run, it does not need to be re-run when other reactivity calculations for these scales are required, unless the mechanism for the base case conditions or the scenario is modified.

Once AVGCOND.BAT is run, one can calculate the reactivities for any VOC using the following commands, where "parmfile" is the file giving the parameters for the VOC that is produced by the mechanism generation system as discussed below.
 

Type of Averaged Conditions Scale
Command
High NOx (MIR)   REACTCAL AVGARBMR F=parmfile
NOx most favorable for O3 (MOIR)   REACTCAL AVGARBMO F=parmfile
Relatively low NOx where NOx and VOC controls are equally beneficial   REACTCAL AVGARBNL F=parmfile

To test this using the parameters for methyl isobutyl ketone in the TESTVOC.DAT file supplied with the distribution, use "TESTVOC.DAT" in place of "parmfile", above. The reactivity results will be output to the user. For the AVGARBMR scenario, the output is

Incremetal reactivity data for MIBK     CH3-CH(CH3)-CH2-CO-CH3
    4.4192 Gm O3 / Gm VOC (MWt= 100.16)
    9.2215 Mol O3 / Mol VOC
    1.5369 Mol O3 / Mol C VOC (nC=  6.)
   10.612  Mol O3 / Mol VOC reacted (mechanistic reactivity)
    0.8689 Fraction reacted (kinetic reactivity)
Reactivity calculation done for AVGARBMR MIBK
For the MOIR and EBIR scenarios, the gm O3/ gm VOC reactivity results using TESTVOC.DAT are 1.8484 and 1.2316, respectively.

To run the calculations in this way for other VOCs, it is necessary to access the mechanism generation system to create the parameter file. This can be done as follows:

  1. Note added 3/2010: The current version of the mechanism generation system is currently not available because of firewall limiations at CE-CERT. Please contact me if there is an interest in making this available.

  2.  
  3. Once at the "gateway" page, find the login form with spaces with the account name and password, and a control bar called "Access Mechanism Generation System". If you do not have an account, just click on that control bar with the default "anonymous" user name and blank password space. The only advantage of having an account is to have a separate space to create your reactants, and having the capability of getting the parameter files emailed to you. Contact Bill Carter at carter@cert.ucr.edu if you want an account.

  4.  
  5. If the system is available, you should see a page with a title "Web Enabled Mechanism Reaction Chamber" with a number with a form with a control labeled "Create reactant" and a form space labeled "Structure". Enter the structure of the VOC in the space and click on the "create reactant" button. For information on what structures can be defined and the format the system expects, click on the "help on create" link, or see Carter (2000a) for details.

  6.  
  7. If the create reactant process is successful, the page will be changed to include the reactant you created under "currently selected reactants". Click on the structure of the VOC you created.

  8.  
  9. You will see a screen with information on the reactant, and a table with various "processing methods". Click on the method "Generate full mechanism using SAPRC-99B Lumping", at the bottom. (If you have an account, you'll also have the option of having the results emailed to you.)

  10.  
  11. The program will then generate the mechanism and output a screen showing the parameters and other output. If the molecule is large it may take a while, but for most molecules less than C12 it should finish before the web browser times out. If the results aren't emailed to you, you'll need to save this screen to a file. In Explorer or Netscape use the File | Save menu to save the page, giving the file name and directory you want to use. This will be the parmfile referred to in the REACTCAL scenaro F=parmfile command. If the results are emailed to you, you will get the file in your email (without the HTML code), and you can save that email message with the name and location you want for parmfile.

  12.  
  13. If you want to process other VOCs, go to the bottom of the page and press "reload main menu", or go to the top of the page to display the form where you can enter new VOCs. You can press "clear above reactants" if you want to remove the display for the last one, but it is not necessary.
  14. Go through steps 3-6 above for the next VOC, being sure to save it to a different file name in step 6.

  15.  
  16. Go to the DOS window with the REACT directory the local directory and the environment set using NEWENV.BAT in the root directory, and run the REACTCAL scenarioid F=parmfile commands as indicated above for each of the VOCs you created. The results will be output to your screen.
Please note that in the future the mechanism generation system may generate mechanisms for an updated version of the SAPRC-99 mechanism should such be developed. The messages on the gateway page or produced by the mechanism generation system should indicate when that is the case, how one can get updated programs and files, and whether it is an option to generate parameters that are compatible with this version of the mechanism. However, this is not the case at the present time.

Summary of Distributed Programs

 A brief summary of the purposes of the various distributed programs is given in Table 8, along with the other executable programs and batch files included in the PGMS directory. Examples of the use of most of these programs are in the various example batch files in the EXAMPLE or REACT directories, as discussed above. Additional documentation might be available in the source files for those programs, in the subdirectories to SOURCE. Unfortunately, most of these programs are not documented beyond that.
 

Table 8. Executable programs and batch files in the "Pgms" directory.
 
  Directory = \PGMS
  Utliity Programs (source not available)
RUN386.EXE Required to run F77L/EM programs. Must be on the path or many of the executable files in this distribution will not run.
CHANGE.COM Shareware utility that can be used to change text in ASCII files. Use: CHANGE filename "old text" "new text". Case-sensitive. Used by some of the batch files.
PKUNZIP.EXE Shareware utility used to extract "ZIP" files, as used by the installation batch file. Note that this is an old version that does not support long file names.
  Programs used for Mechanism Preparation (Source included except as indicated)
PRP.EXE Main program that controls the mechanism preparation process. First calls PREP.EXE to read the PRP file and prepare the mechanism data (MOD) file and the mechanism-specific subroutine source file, then calls INTCL3.BAT to compile and link the mechanism-specific executable.
PREP.EXE Prepares the mechanism-specific data and source file from the mechanism input (PRP) file as indicated above.
INTCL3.BAT Compiles and links the mechanism-specific subroutine to produce the mechanism-specific executable (EXE) file.
JZTOKZ.EXE Used by MECH\SAPRC99\KZSPREP.BAT to compute photolysis rates for ambient simulations. Inputs list of photolysis (PHF) files and a actinic flux data (JZS) file and outputs KZS files giving photolysis rates at the zenith angles in the JZS file.
KZSFIT.EXE Used by MECH\SAPRC99\KZSPREP.BAT to derive photolysis rate input for mechanism simulation program for ambient simulations. Takes KZS files output by JZTOKZ.EXE and products FZS files that give parameters for calculating the photolysis rates as continuous functions of the zenith angle.
  Programs used for model simulations (in conjunction with the mechanism-specific EXE file in the MECH subdirectory) and related utilities.
INT.EXE Does the simulation using the conditions specified in a given .INT file using the mechanism indicated either in the MODEL= input in the .INT file or the DFLMOD= input in MODELING.PRM or the parameter file. 

Use: INT intfile parmfile, where "intfile" is the name of the .INT file with the input conditions, and "parmfile" is optional and is the name of a .PRM file that is used to read the parameters such as the location of the mechanism files and other input files that are different from those in MODELING.PRM

INTRUN.EXE Does a simulation after first calling LUMPINT.EXE to lump detailed model species into lumped model species used in the mechanism based on lumping control information in a lumping control file. Use is similar to INT.EXE except the input is an .INP file that may contain .LUMP records listing detailed model species to be lumped. The mechanism and lumping control file are specified in the "parmfile" input or MODELING.PRM. See EXAMPLE\EXAMPLE1.BAT for examples of its use.
TMP2CDT.EXE This is needed to save results of calculations in useable .CDT binary files because of a bug in F77L/EM concerning binary files. Must be compiled using F77L. Called by the mechanism-specific simulation program. If a different compiler is used for the mechanism simulation program besides F77L/EM, PRNTC.FOR and and STOREC.FOR in SOURCE/INT can be replaced by the versions in SOURCE/INT/NOF77LEM.ZIP, and this program will not be needed.
DO3NO.EXE Called by INTRUN.EXE to create ([O3]-[NO]) and D([O3]-[NO]) channels from O3 and NO data. Useful for some mechanism evaluation applications.
CDT2CSV.EXE Used to create a spreadsheet-readable .CSV file from the binary .CDT files produced when running the simulation programs with the SAVE option in the .INT or .INP file. Use: CDT2CSV calcno csvfile, where "calcno" is the calculation number (or 0 for last calculation, -1 for 2nd to last, etc.) and "csvfile" is the CSV file name. See EXAMPLE\EXAMPLE1.BAT for an example of its use. Note that it is not necessary to use this to produce .CSV files if the SAVE CSV option is used in the .INT or .INP file.
  VOC Lumping programs and utilities
LUMPINT.EXE Used to do VOC lumping for model simulations for preparation for chamber, static, or reactivity simulations. Use LUMPINT inputfile outputfile parmfile, where "parmfile" is the LPC file to control the lumping or a parameter (.PRM) file indicating which LPC and mechanism files to use. Lumps VOC names specified after .LUMP records and produces lumped species parameters and concentrations corresponding to them that can be input into model-specific executable programs that are compatible with the specifications in the .LPC file. Called by INTRUN.EXE and REACT\LUMPALL.BAT.
CMPTORXP.EXE Used to compute lumped model species parameters corresponding to the distribution of detailed VOC model species given in a composition (.CMP) file. Use: CMPTORXP cmpfile rxpfile parmfile, where "cmpfile" is a .CMP input file with detailed model species concentrations or relative levels in molar units, "rxpfile" is a the output .RXP file with the corresponding levels of the lumped model species and the parameters for the model species with composition-adjusted parameters, and "parmfile" is the parameter (.PRM) file that specifies which .LPC file to use. See the batch files in MECH\SAPRC99\MODELS3 for examples of its use.
CMPTOLMO.EXE Similar to CMPTORXP.EXE except the output file is a .LMO file that contains only the lumped model species levels and not the mechanistic parameters. Used by REACT/LUMPALL.BAT to compute the levels of the aloft VOCs in terms of lumped model species whose parameters were derived to represent the ground-level VOCs.
EMITOCMP.EXE Used to produce "composition" (.CMP) files giving VOC distributions or emissions in terms of moles of detailed model species, using .EMI files giving emissions in terms of mass emissions of 5-digit SAROAD classes or ChemCodes generally used in emissions inventories. Use: EMITOCMP "emifile" "cmpfile" "assignment file", where the "assignment file" can be either MECH\SAPRC99\ARBEMIT.PRM or MECH\SAPRC99\EPAEMIT.PRM, depending on which emissions inventory is being processed. Note that the 5-digit SAROAD or ChemCode classes used by the California ARB and the U.S. EPA are different for some VOCs, so the appropriate parameter file must be used. See EXAMPLE\EXAMPLE2.BAT and MECH\SAPRC99\MODELS3\LUMPEMIT.BAT
  Programs and associated utilities used for reactivity calculations.
REACTCAL.EXE Conducts a reactivity simulation for a given scenario for a given VOC or the base case. See REACT\REACTEX.BAT and REACT\AVGCOND.BAT for examples of its use. Results are summarized in the scenario’s .CLC and CLD files in the CLCFILES subdirectory for the mechanism. If a base case simulation is conducted, also puts the base results in the .BAS file in the CLCFILES subdirectory. The data in the .BAS file is used to determine the conditions in the added VOC calculations for that scenario, among other purposes. The data i the .CLC and CLD files have various results of the added VOC runs. Calls the mechanism-specific simulation program appropriate for the type of reactivity calculation as indicated in MODELING.PRM.
MROPT2.EXE Used to find the MIR, MOIR and EBIR NOx levels for a scenario. Results are output in the .BAS file for the scenario. See REACT\REACTEX.BAT and REACT\AVGCOND.BAT for examples of its use. This information can then be used by REACTCAL when creating base case simulations for these adjusted NOx scales, as shown in the example batch files.
DMSRCT.EXE Used to compute the reactivity scales for a given scenario given the calculation data in the CLC and/or CLD files created by REACTCAL The results are output in the .RCT files in the RCTFILES directory for the mechanism. Thes data in the RCT files can also include reactivities for species assumed to have the same per-mole reactivities of other species (i.e., represented using the "lumped molecule" approach) whose reactivities were calculated. This is controlled by the REACT.LPC file as indicated by the RCTLPC= input in MODELING.PRM. See REACT\REACTEX.BAT and REACT\AVGCOND.BAT for examples of its use. As indicated there, depending on the options selected it can be used to produce either ozone yield, maximum 8-hour average, or integrated ozone reactivity scales.
RCTAVG.EXE Used to create multi-scenario average reactivity scales such derived by averaging incremental reactivities from multiple scenarios. Input is a list of RCT files and the output is a RCT file giving the aggregated reactivity scale. Use: RCTAVG lisfile rctfile, where "lisfile" is a file with the list of the scenarios to be aggregated, and "rctfile" is the output aggregated reactivity scale .RCT file. See REACT/RCTALL.BAT for examples of its use. Used to create the MIR, MOIR, and EBIR scales for the SAPRC-99 mechanism.
RCTAGG.EXE Used to create "aggregate" reactivity scales such "average ratio" or "least squares error" scales discussed by Carter (1994). Input is a list of RCT files and the output is a RCT file giving the aggregated reactivity scale. Use: RCTAGG lisfile rctfile standardVOC, where "lisfile" is a file with the list of the scenarios to be aggregated, "rctfile" is the output aggregated reactivity scale .RCT file, and "standardVOC is optional and is used only if relative reactivity scales are desired. See REACT/RCTALL.BAT for examples of its use.
RCTAGGKM.EXE Similar to RCTAVG except derives scales by separately averaging the kinetic and mechanistic reactivities, as used when deriving the MIR, MOIR, and EBIR scales given by Carter (1994). It is no longer used for this purpose, but is included in this distribution for those who wish to duplicate the earlier method.
REACTTAB.EXE Used to produce output reactivity tabulations in .CSV and other formats. See examples of its use in REACT\REACTEX.BAT and REACT\AVGCOND.BAT, and see REACT\REACTTAB.TXT for the draft documentation of an early version of this program. Runs in batch or interactive mode. Uses the .RCT files produced by DMSRCT.EXE, RCTAVG.EXE, etc. as inputs for the reactivity data for the scenarios specified in the input files or by the user.
  Miscellaneous mechanism utilities
GNATOMEC.EXE Produces reaction files for model species given the mechanistic parameters for the species in .GNA files. GNATORXN.EXE outputs the reactions in the format used by the SAPRC PREP program, and GNATOMEC.EXE outputs them in the format used by the Models-3 mechanism compiler. Used to produce the .RXN and .MEC files in the MECH\SAPRC99\DMSRXN directory. Useful for implementing explicit mechanisms for the VOCs into models, without having to use the lumping programs to represent them.
GNATORXN.EXE
RXPTOMEC.EXE Produces reaction files for lumped model species representing mixtures of VOCs given the .RXP files giving the parameters for the lumped model species. Output is in the SAPRC .RXN format or the MODELS-3 .MEC format depending on which program is used. See the batch files in MECH\SAPRC99\MODELS3 for examples of their use.
RXPTORXN.EXE
  Miscellaneous composition file utility.
RENORCMP.EXE Utility to normalize and convert composition (.CMP) files giving concentrations or relative levels of detailed VOC model species. See REACT/REACTTAB.TXT for documentation. Mainly used to normalize such files to give 1 ppmC total VOC, which is its default operation. Use: RENORCMP cmpfile, where the "cmpfile" is the input .CMP file that is to be replaced by the normalized version.

 

Editing and Compiling Programs

It is not necessary to compile any of the programs for use on PC systems because all the executables are included in the distribution in the PGMS directory. But if you wish to re-compile them using F77L or F77L/EM, the necessary batch files to do this are in the SOURCE directory or its subdirectories. The files TESTFTN.BAT and TESTFTN3.BAT can be used to test whether you can compile programs using F77L or F77L/EM, respectively. If they fail, it is probably because you don’t have their files in the LIB directory, or the LIB directory is not on the path. If they work, the file BLDALL.BAT will create the libraries and compile all the programs in the subdirectories. It does this by calling the BLDALL.BAT file that is in each subdirectory. See those files to see what they do. Note that SOURCE/SUBS/BLDALL.BAT creates the library SUBS.LIB that contains the subroutines used by most of the programs, and that SOURCE/INT/BLDALL.BAT creates the library INT3.LIB that is needed whenever a mechanism is prepared. Most of the programs listed on Table 8 can be re-compiled in this way, except those obtained from other sources.

Table 9 lists the files in the SOURCE subdirectory and indicates where the source files for the programs can be found. A summary description for most these source files has not yet been prepared, but in most cases this can be inferred by looking at the files or their names. Note that the BLDAL.BAT file in the SOURCE directory will compile all the programs or build all the libraries, and the BLDALL.BAT file in each subdirectory compiles the programs or libraries in that directory,
 
 

Table 9. Program source files and compilation and linking batch files in the "Source" directory and its subdirectories.
 
  Directory = \SOURCE
BLDALL.BAT  This can be used to re-compile all the programs and libraries in the distribution. It is not necessary to run this unless they are changed. Requires F77L and F77L/EM to be installed and on the path. This works by calling the BLDALL.BAT file in all the subdirectories.
TESTFTN.BAT This can be used to test whether F77L is properly installed and on the path.
TESTFTN3.BAT This can be used to test whether F77L/EM is properly installed and on the path.
SUBS.LIB This is the library of utility subroutines used by most of the program, compiled using F77L. Created using SOURCE\SUBS\BLDALL.BAT.
SUBS3.LIB This is the library of utility subroutines used by most of the program, compiled using F77L/EM. Created using SOURCE\SUBS\BLDALL.BAT.
INT3.LIB This is the library of subroutines for the mechanism-specific simulation program that do not depend on the mechanism. This is used by INTCL3.BAT (called by PRP.EXE) when preparing a mechanism.
  Directory = \SOURCE\SUBS
This contains the source code for the various utility subroutines used by many of the programs.
ADDSUB.BAT Compiles a subroutine with F77L and adds it to SUBS.LIB
ADDSUB3.BAT Compiles a subroutine with F77L/EM and adds it to SUBS3.LIB
BLDALL.BAT Compiles all the subroutines using both F77L and F77L/EM and creates SUBS.LIB and SUBS3.LIB.
COMPSUB.BAT Compiles a subroutine with F77L and replaces it in SUBS.LIB
COMPSUB3.BAT Compiles a subroutine with F77L/EM and replaces it in SUBS3.LIB
SUBSBLD.BAT Compiles all the subroutines using both F77L creates SUBS.LIB.
SUBSBLD3.BAT  Compiles all the subroutines using both F77L/EM creates SUBS3.LIB.
*.FOR  The source files for the subroutines.
  Directory = \SOURCE\PREP
This contains the source code for the PRP and PREP programs.
BLDALL.BAT Compiles and links PRP.EXE and PREP.EXE
PREPCOMP.BAT Compiles PREP
PREPLINK.BAT Links PREP
PREP.FOR Source for main PREP module.
PSPECS.FOR Specifications for commons and parameters for all PREP modules.
PRP.FOR PRP source
*.FOR PREP subroutines.
  Directory = \SOURCE\INTUTIL
This contains the source code for the INT, CDT2CSV, JZTOKZ, DO3NO, KZSFIT, CDT2CSV and DO3NO programs.
BLDALL.BAT Compiles and links PRP.EXE and PREP.EXE, whose sources are in this directory.
CDT2CSV.FOR Source files for the various programs.
DELCDT.FOR
DO3NO.FOR
INT.FOR
JZTOKZ.FOR
KZSFIT.FOR
OPTSPC.FOR Specifications for optimization variables used by KZSFIT.FOR.
  Directory = \SOURCE\INT
This contains the source code for all the mechanism-independent subroutines used in the mechanism-dependent model simulation program, that are used to produce INT3.LIB. It also contains the source code for TMP2CDT (see below)
BLDALL.BAT Compiles all modules and adds them to INT3.LIB, and compiles TMP2CDT.
ADDSUB.BAT Compiles a subroutine and adds it to INT3.LIB
COMPSUB.BAT Compiles a subroutine and replaces it in INT3.LIB
INTBLD.BAT Compiles all modules and adds them to INT3.LIB.
INTMAIN.FOR Main module for the simulation program.
MAINSPC.FOR Specifications for the parameters and common variable arrays used by INTMAIN and most of the subroutines.
*.FOR  
TMP2CDT.FOR This is needed to save results of calculations in useable .CDT binary files because of a bug in F77L/EM concerning binary files. Must be compiled using F77L. Called by the mechanism-specific simulation program. If a different compiler is used for the mechanism simulation program besides F77L/EM, PRNTC.FOR and and STOREC.FOR in SOURCE/INT can be replaced by the versions in SOURCE/INT/NOF77LEM.ZIP, and this program will not be needed.
NOF77LEM.ZIP A compressed file containing versions of the PRNTC and STOREC subroutines that don't use TMP2CDT to re-format the unformatted output files. Replace the STOREC.FOR and PRNTC.FOR files in this distribution with these if this program is to be used with a different compiler than F77L/EM.
  Directory = \SOURCE\LMPPGMS
Contains the source code for the various lumping programs, except for LUMPINT. These include CMPTOLMO, CMPTORXP, DMSRCT, EMITOCMP, GNATOMEC, GNATORXN, RXPTOMEC, and RXPTORXN.
BLDALL.BAT Compiles and links all the programs.
CMPOLNK3.BAT Batch files to compile and link specific programs. Used by BLDALL.BAT.
CMPRLNK3.BAT
COMPSUB3.BAT
DMSRLNK3.BAT
EMICLNK3.BAT
CMPTOLMO.FOR Source code for main modules for the individual programs. Most call subroutines whose sources are in LMPSUBS.
 
 
 
 
 
 
 
 
 
 
 
 

 

CMPTORXP.FOR
DMSRCT.FOR
EMITOCMP.FOR
GNATOMEC.FOR
GNATORXN.FOR
RXPTOMEC.FOR
RXPTORXN.FOR
LUMPSPEC.FOR Specifications for common parameters, variables, and arrays used by these programs.
SARSPEC.FOR Specifications for common parameters, variables, and arrays used by the programs that process emissions data.
  Directory = \SOURCE\LMPSUBS
*.FOR Various subroutines used by the programs in LMPPGMS and also by LUMPINT.
  Directory = \SOURCE\LUMPINT
Contains source code for the LUMPINT program. Note that this program also uses some subroutines in LMPSUBS.
BLDALL.BAT Compiles and links LUMPINT.
COMPSUB3.BAT Batch files used by BLDALL.

 

LILINK3.BAT
LUMPINT.FOR Source for main LUMPINT module.
LUMPSPEC.FOR Specifications for common parameters, variables, and arrays used by LUMPINT.
SARSPEC.FOR Specifications for common parameters, variables, and arrays used when processing emissions data.
ILMPSB.FOR Subroutine that is specific to LUMPINT.
  Directory = \SOURCE\REACTCAL
Contains the source for REACTCAL and MROPT2, programs used in reactivity calculations.
BLDALL.BAT Compiles and links REACTCAL and MROPT2.
RCBLD3.BAT Compiles and links REACTCAL.
REACTCAL.FOR Main module for REACTCAL
SCENSPEC.FOR Specifications of arrays and parameters concerning the scenarios.
*.FOR Various REACTCAL subroutines.
MROPT2.FOR Source for MROPT2 program.
  Directory = \SOURCE\CMPREACT
Contains source files for REACTTAB, RENORCMP and various programs for preparing multi-scenario reactivity scales (RCTAVG, RCTAVG, RCTAGGKM).
BLDALL.BAT Compiles and links all programs.
RAKMLNK3.BAT Batch files to compile or link various programs. Called by BLDALL.BAT.
RALINK3.BAT
RAVLINK3.BAT
RTBLD.BAT
RTLINK3.BAT
REACTTAB.FOR Main modules for the various programs.
RENORCMP.FOR
RCTAGG.FOR
RCTAGGKM.FOR
RCTAVG.FOR
LDDMS.FOR Subroutines used by various programs.
LDRCT.FOR
  Directory = \SOURCE\CHAMPGMS
Contains source for the INTRUN program.
BLDALL.BAT Compiles and links INTRUN
INTRUN.FOR INTRUN source.
  Directory = \LIB
Contains programs and files needed to compile and link using F77L and F77L/EM. See installation discussion above. (These do not work reliably on Windows-2000 or newer systems.)

 

Additional Information

Additional information concerning the latest version of the SAPRC mechanism and its associated documentation is available at /~carter/reactdat.htm. See also William P.L. Carter's home page at https://intra.cert.ucr.edu/~carter for a summary of his research, links to his downloadable documents and reports, and links to sites with other information of potential interest or relevance.

If you continue to use this software and files into the future, you should check /~carter/SAPRC99.htm or the links indicated above to see if an updated version of the mechanism is available, or if any corrections or updates are made to these distributed files.

Please contact William P. L. Carter at the address, phone number or email address given above if you have questions, comments, or for other information, or if you want to be notified if errors are found or updates are available.. Comments on problems and suggestions for improvements are welcome, though there may be a delay in responding to questions that may be difficult to answer. Please be persistent if you get no response in a timely manner to email inquiries. Also let
 
 

References

Carter (2000a): "Documentation of the SAPRC-99 Chemical Mechanism for VOC Reactivity Assessment," Draft report to the California Air Resources Board, Contracts 92-329 and 95-308, May 8, available at /~carter/absts.htm#saprc99).

Carter, (2000b): "Implementation of the SAPRC-99 Chemical Mechanism into the Models-3 Framework," Report to the United States Environmental Protection Agency, January 29. Available at /~carter/absts.htm#s99mod3).

Carter (1994): "Development of Ozone Reactivity Scales for Volatile Organic Compounds," J. Air & Waste Manage. Assoc., 44, 881-899. 1994, See /~carter/absts.htm#reactpap

Carter, W. P. L., D. Luo, I. L. Malkina, and D. Fitz (1995d): "The University of California, Riverside Environmental Chamber Data Base for Evaluating Oxidant Mechanism. Indoor Chamber Experiments through 1993," Report submitted to the U. S. Environmental Protection Agency, EPA/AREAL, Research Triangle Park, NC., March 20. See /~carter/absts.htm#databas and /~carter/chdata/.

Kumar, N., F. W. Lurmann, and W. P. L. Carter (1995), "Development of the Flexible Chemical Mechanism Version of the Urban Airshed Model," Report to California Air Resources Board, Agreement no. 93-716. Document No. STI-94470-1508-FR, Sonoma Technology, Inc. Santa Rosa, CA, August.

Peterson, J. T. (1976): "Calculated Actinic Fluxes (290 - 700 nm) for Air Pollution Photochemistry Applications", EPA-600/4-76-025, June.


[Top of This Page] [To Carter Home Page]

Current version of page written by William P. L. Carter September 25, 2001
Bad Links repaired and update notes added March 30, 2010