SAPRC-07 Chemical Mechanisms, Test Simulations, and Environmental Chamber Simulation Files

William P. L. Carter
College of Engineering Center for Environmental Research and Technology
University of California
Riverside, CA 92521
Email: carter@cert.ucr.edu

Page last updated: November 17, 2009
Files last updated: November 13, 2009

Please note: An error was found in the SAPRC-07 mechanisms concerning peroxy + acyl peroxy radical reactions that affect predictions under low NOx conditions. Predictions of ozone, and MIR reactivity scales, should not be affected (though this will be checked), but correcting the error has non-negligible effects on predictions of low NOx species such as H2O2 and has large effects on predictions of organic acids under low NOx conditions. I am in the process of correcting the mechanism and will make corrected documentation and files available as soon as possible. Plese email me if you are using the SAPRC-07 mechanism and want additional information and notification when corrected files are available. (Files dated before November 17, 2009 will not have been corrected.)
 

Summary

This distribution contains files documenting and implementing the current versions of the SAPRC-99 and SAPRC-07 gas-phase atmospheric chemical mechanisms and the files and programs necessary simulate the environmental chamber experiments used to evaluate the detailed mechanism, and to run the test calculations used to develop and evaluate the condensed SAPRC-07 mechanisms. (Files and programs to calculate the reactivity scales or simulate the reactivity scenarios are not included in this distribution, but can be prepared later if requested.) The distributed files are as follows:
SAPRC07.DOC and SAPRC07.PDF contain the report of Carter (2009a) documenting the development and evaluation of the detailed and the uncondensed, fixed-parameter SAPRC-07 mechanisms. The report is dated March 20, 2009 and includes updates the July, 2008 version to the report. The changes are described in Appendix E of the report.

SAPRC07.XLS contains large tables from the SAPRC-07 documentation report of Carter (2009a), including tables too large for the report itself. This includes listings of mechanisms for all the individual VOCs in the detailed mechanism, absorption cross-sections and quantum yields, reactivity scale tabulations, and other data. This file is dated March 17, 2009

CSAPRC07.DOC and CSAPRC07.PDF contain the report of Carter (2009b) describing the development and evaluation of the condensed mechanism. The date of the report is April 9, 2009

MECH.ZIP contains the files implementing the various versions of the SAPRC-07 mechanism. Files implementing the SAPRC-99 mechanism are also included. The archive was created from the files as of November 13, 2009.

PGMS.ZIP contains the SAPRC modeling programs needed to run the environmental chamber simulations and the test calculations. The archive was created from the files as of July 13, 2009.

TESTCALC.ZIP contains the files needed to run the static and multi-day dynamic test calculations discussed in the condensed mechanism documentation report of Carter (2007b). The archive was created from the files as of July 13, 2009.

CHAMCALC.ZIP contains the files necessary to use the distributed mechanisms and software to evaluate the mechanisms against the chamber data. The archive was created from the files as of November 12, 2009.

UNZIP.EXE is a freeware unzip program by Info-Zip (http://www.info-zip.org/) that can be used to extract the .ZIP files if the user does not already have such a program.

This distribution also includes files for the current version of the SAPRC07T mechanism that is being prepared for the EPA for use in CMAQ. This is a fixed-parameter version of the SAPRC-07 that includes explicit reactions of additional species. The version is current as of April 8, 2009. This version of the mechanism is still under development and is subject to change. Click here for additional information about specific SAPRC07T files.

Installation

Installing the files.

The programs are set up to run on PC's with Windows-type operating systems, and have been tested using Windows 98, 2000, and XP. However, the current distribution will not run on Windows Vista.

The files in all the .ZIP files are organized into a directory structure, and should be extracted in a way that preserves this structure. If the distributed programs are to be used with the files, they must be extracted with the subfolders in all .ZIP files sharing the same root folder. The directory structure for the distributed files is shown on Figure B-1, which also indicates the zip files.
The suggested installation procedure is to copy the .ZIP files to be used to the root directory where they are to be installed, along with the distributed UNZIP program. Then open a DOS window and go to that folder and run UNZIP for each of the files (e.g., UNZIP MECH; UNZIP PGMS, etc.), which will extract the files to the proper folders. The ZIP files are no then longer needed and can be deleted.

Running the Programs

The following discussion covers running the programs in PGMS.ZIP with the files in CHAMCALC.ZIP or TESTCALC.ZIP on a Windows-based PC system. The programs have been tested on Windows 98, 2000, and XP, but not Vista. If other operating systems are to be used then the programs must be re-compiled for those systems, and at least the F77L programs may need to be modified before they will compile.
The distributed programs must be run in a DOS box with the path and other environment variables pointing to the distributed files as needed. The easiest way to do this is to edit then run the NEWENV.BAT file that is installed in the root directory when PGMS.ZIP is extracted. This file contains the DOS commands to set up the environment as needed. But first it must be edited to change the line "SET TMPENV=" to point to the root directory where the files are distributed (without the trailing "\"). For example, if the files are extracted with the root directory C:\CARTER, e.g., the mechanisms are in C:\CARTER\MECH, that line in NEWENV.BAT should be changed to "SET TMPENV=C:\CARTER". (The distributed file points to a temporary folder on the Author's PC that is used to test the distribution.) Then each time the DOS box is opened to run the programs, the NEWENV.BAT must be executed to set up the programs. This can be done automatically by setting up the shortcut to open the DOS box with the desired environment, but the method depends on the Windows version that is used and is not discussed here.
The procedures to run the examples in the various distribution sets are discussed in conjunction with the descriptions of the distribution sets, below.

Distributed Files

Mechanism Files

The files and folders in MECH.ZIP, which implement versions of the SAPRC-99 and SAPRC-07 mechanisms are listed on Table B-1. These include files that can be used as the starting point for implementing the mechanisms into various modeling systems, as well as those used to implement the mechanisms on the software and calculations in this distribution. The minimum set of files needed to implement fixed-parameter SAPRC-07 in general modeling systems are either SAPRC07B.MEC or SAPRC07B.RXN, depending on the software used, the *.PHF files, and either SAPRC07L.LCC, CA-S07.CSV or S4-S07.CSV, depending on how the emitted or input VOCs are categorized. Likewise, the minimum set of files needed to implement CS07A are CS07A.MEC or .RXN, a subset of the .PHF files, and either CS07.LCC, CA-CS07.CSV, or S4-CS07.CSV. For CS07B the .MEC or .RXN files for that version are used, but the other files are the same as those for CS07A.
If the programs in PGMS.ZIP are installed then the mechanism input files can be edited and modified and the mechanisms used in the TESTCALC or CHAMCALC distribution can be modified. The modified mechanisms are compiled by running the PRP program and batch file on the corresponding .PRP file (e.g., "PRP CHAMLUMP"). This requires that the files in PGMS.ZIP be extracted and the DOS environment set as described above. Compiling the mechanism also requires the G77 compiler, which is included with PGMS.ZIP.
 

Program Files

The files and folders in PGMS.ZIP contain the SAPRC modeling programs needed to run the environmental chamber simulations and the test calculations. Source files for many of the FORTRAN programs are also included, some compiled using publicly-available G77 (G77 v.2.95 for MinGW32, available at http://www.geocities.com/Athens/Olympus/5564/g77.htm), and some compiled using an old version of F77L (4.1) that is no longer supported (see http://www.lahey.com). The executables necessary to compile the programs are also included, though the F77L compiler does not always work under Windows XP, and the F77L executables do not run under Vista. Since the executables for running all the programs on PC's with Windows systems are included (in the PGMS subfolder), it is not necessary to compile the programs unless they need to be modified, or unless another type of operating system is used. However, G77 must be installed if it is desired to modify the distributed mechanisms and use them to run the chamber or test calculation simulations, since changing the mechanism requires that the simulation program be re-compiled.
The files and programs in PGMS.ZIP are listed in Table B-2. The procedures for installing and running the distributed programs were described above in the Installation section.

Environmental Chamber Simulation Files

The files necessary to use the distributed mechanisms and software to evaluate the mechanisms against the chamber data are included in CHAMCALC.ZIP. The included files include input data for simulating the results of over 2400 chamber experiments using either the detailed SAPRC-99 or the detailed SAPRC-07 mechanisms, and measurement data for comparison with the results of the calculations. The experiments modeled are listed in the file Excel file MODELRUN.XLS which is included with the distribution. The files and folders included in this distribution are listed in Table B-3.
In order for these simulations to run, the files in MECH.ZIP and PGMS.ZIP must also be installed, and the DOS environment must be set up as described in the Installation section, above. The simulations are run in a DOS box in the CHAMCALC subfolder created in the installation. The file EXAMPLE.BAT runs the simulations. See the comments in EXAMPLE.BAT for a brief summary of the steps involved. Other programs are available to manage the results of these simulations, but a discussion of these is beyond the scope of the present documentation. More extensive documentation can be prepared later if there is sufficient interest.

Mechanism Comparison Calculation Files

Tiles needed to run the test calculations discussed in the condensed mechanism documentation report of Carter (2007b) that are summarized on Table 2 of that report are included in TESTCALC.ZIP. Note that the reactivity scenarios are not yet included, and when they are they would be in a separate ZIP file. These include input files for the test calculations and files needed to run the simulations for fixed parameter SAPRC-99 and uncondensed SAPRC-07, and for CS07A and CS07B. The files and folders included in this distribution are listed on Table B-4.
In order for these simulations to run, the files in MECH.ZIP and PGMS.ZIP must also be installed, and the DOS environment must be set up as described in the Installation section, above. The simulations are run in a DOS box in the TESTCALC subfolder created in the installation. The file EXAMPLE.BAT runs the simulations. See the comments in EXAMPLE.BAT for a brief summary of the steps involved. Other programs are available to manage the results of these simulations, and more extensive documentation can be prepared later if there is sufficient interest.
Figure B-1.  Directory structure for distributed files. All these directories
must share the same root directory for the example simulations to run.
[back to installation section]


Table B-1.  Files and folders in MECH.ZIP, which contain files implementing various versions of SAPRC mechanisms.
 
Folder
Files
Description
Root
README.TXT, 
README.DOC,
README.PDF
README.TXT contains a brief description of files in all distribution sets, README.DOC and .PDF contain this document Note: these files in included in all distribution sets, and should be the same on all sets of the same age. If they are not the same, the older versions should be overwritten with the most recent version.

MECHLIST.CSV,
MSCLIST.CSV,
SPEC4ASN.CSV		 These files contain assignments of model species for these and other mechanisms to chemical categories in the Speciate 4 emissions speciation profile database. MECHLIST.CSV contains the list of mechanisms for which assignments are output, MSCLIST.CSV gives the list of model species, and SPEC4ASN.CSV contains the assignments of model species to the Speciate 4 categories. The first column is the mechanism, the second is the Speciate 4 category number, the third is the model species and the fourth is the moles model species per mole compound (or per one total mole in the mixture) in the category.
MECH\SAPRC99
SAPRC-99 mechanism files
 
SAPRC99F.RXN
The "fixed parameter" version of SAPRC-99 mechanism in the SAPRC modeling programs format
 
Other *.RXN
Various modules of the SAPRC-99 detailed mechanism
 
*.PHF
Absorption cross sections and quantum yields for the photolysis reactions.
 
*.PRP, *.MOD, *.PRO, *.EXE
Mechanism preparation input (PRP) and output (MOD, PRO, EXE) files for the various versions of the SAPRC99 mechanism in the distribution that are used in the chamber simulations and example calculations using the software in PGMS.ZIP. Prepared mechanisms have .MOD, .PRO, and .EXE files of the same name. CHAM*.PRP are used for mechanisms for chamber simulations and TSTS99.PRP is used for the mechanism comparison test calculations.
 
CHAMLUMP.LPC
Lumping control file used when evaluating the detailed mechanism against chamber data
 
*.GNA, *.LPM
Parameter or assignment files for the detailed mechanism used by CHAMLUMP.LPC
 
CHAMS99L.LCC
Assignments of detailed model species to lumped model species used for the fixed parameter of SAPRC99 for chamber simulations.
 
STD640.FZS
Solar actinic fluxes as a function of zenith angle used for reactivity and test calculations (mechanism independent but expected to be in the mechanism folder)
MECH\SAPRC07
SAPRC-07 mechanism files
 
SAPRC07B.MEC, SAPRC07B.RXN
Uncondensed, fixed-parameter SAPRC-07 mechanism in CMAQ (MEC) or SAPRC (RXN) format

SAPRC07C.MEC,
SAPRC07C.RXN		 Same as above, but uses the explicit reactions for the peroxy radical operators. This has more reactions but is more compatible for some solver software systems, such as that using MEC files.
 
CS07A.MEC, CS07A.RXN
Condensed mechanism CS07A in CMAQ format in CMAQ (MEC) or SAPRC (RXN) format
 
CS07B.MEC, CS07B.RXN
Condensed mechanism CS07B in CMAQ format in CMAQ (MEC) or SAPRC (RXN) format
 
Other *.RXN
Various modules in the SAPRC-07 detailed mechanism
 
*.PHF
Absorption cross sections and quantum yields for the photolysis reactions. Same set used by all versions of the mechanism, though only a subset are used in the condensed versions.
 
*.PRP, *.MOD, *.PRO, *.EXE
Mechanism preparation input (PRP) and output (MOD, PRO, EXE) files for the various versions of the SAPRC07 SAPRC99 mechanism in the distribution that are used in the chamber simulations and example calculations using the software in PGMS.ZIP. Prepared mechanisms have .MOD, .PRO, and .EXE files of the same name. CHAM*.PRP are used for mechanisms for chamber simulations and TST*.PRP is used for the mechanism comparison test calculations for detailed (S07B) and condensed SAPRC07.
 
CHAMLUMP.LPC
Lumping control file used when evaluating the detailed mechanism against chamber data
 
*.GNA, *.LPM
Parameter or assignment files for the detailed mechanism used by CHAMLUMP.LPC
 
CHAMS07L.LCC
Assignments of detailed model species to lumped model species used for the fixed parameter of SAPRC07 for chamber simulations.
 
SAPRC07L.LCC
Assignments of detailed model species to lumped model species used for the fixed parameter of SAPRC07 for ambient and mechanism test simulations.
 
CS07.LCC
Assignments of detailed model species to lumped model species used for the condensed SAPRC07 mechanisms CS07A and CS07B.
 
STD640.FZS
Solar actinic fluxes as a function of zenith angle used for reactivity and test calculations (mechanism independent but expected to be in the mechanism folder)
 
CA-S07.CSV
Assignments of California CARB chemical categories used in emissions profiles to the SAPRC-07 mechanism (from EmitDB.xls)
 
CA-CS07.CSV
Assignments of California CARB chemical categories used in emissions profiles to the CS07 mechanism (from EmitDB.xls)
 
S4-S07.CSV
Assignments of Speciate 4 chemical categories used in emissions profiles to the SAPRC-07 mechanism (from EmitDB.xls)
 
S4-CS07.CSV
Assignments of Speciate 4 chemical categories used in emissions profiles to the CS07 mechanism (from EmitDB.xls)
MECH\SAPRC07T
SAPRC-07T mechanism files
 
S07TB.MEC,
S07TB.RXN
SAPRC-07T mechanism in CMAQ (MEC) or SAPRC (RXN) format using peroxy radical representation “B”. This is the representation used in the standard SAPRC mechanism as documented in the report to the CARB, but is not compatible for some model solver software systems. The MEC file has input that is not yet implemented in CMAQ.

S07TC.MEC,
S07TC.RXN		 Same as above, but uses the explicit reactions for the peroxy radical operators. This has more reactions but is more compatible for some solver software systems, such as that using MEC files.
 
*.PHF
Absorption cross sections and quantum yields for the photolysis reactions. Same set used by all versions of the mechanism, though only a subset are used in the condensed versions.
 
*.PRP, *.MOD, *.PRO, *.EXE
Mechanism preparation input (PRP) and output (MOD, PRO, EXE) files for test calculations using the two versions of the SAPRC07T mechanism. BASELMPB.* is used for version “B” and BASELMPC.* for version “C”. Prepared mechanisms have .MOD, .PRO, and .EXE files of the same name.
 
SAPRC07T.LCC
Assignments of detailed model species to lumped model species used for SAPRC07T for ambient and mechanism test simulations.
 
SAPRC07T.XLS
Excel file containing species and reactions in both versions of the mechanism.
 
S07TCHK.XLS
Excel file containing test calculation data for testing implementation of the mechanism.
 
S07TCHK*.INT
Simulation input file for testing the two versions of the mechanism and producing the outputs in S07TCHK.XLS. One for each version. To run, use (for example) “INT S07TCHKB”.
 
S07TCHK*.CSV
Output files produced by running the test calculations above, containing concentration-time results. These data are also in S07TCHK.XLS
 
S4-S07T.CSV
Assignments of Speciate 4 chemical categories used in emissions profiles to the SAPRC-07T mechanism (from EmitDB.xls)

[Back to mechanism files section]

Table B-2.  Files and folders in PGMS.ZIP, which contain the distributed executable and program source files.
 
Folder
Files and folders
Description
Root
README.TXT, 
README.DOC,
README.PDF
README.TXT contains a brief description of files in all distribution sets, README.DOC and .PDF contain this document Note: these files in included in all distribution sets, and should be the same on all sets of the same age. If they are not the same, the older versions should be overwritten with the most recent version.
 
NEWENV.BAT
Batch file to set DOS environment to execute and compile programs. Before using, it needs to be edited to change the "SET TMPENV=" line to refer to the full path name of the root directory where these files are installed.
PGMS
*.EXE, *.BAT
Executable and batch files needed to compile the mechanisms and run the model. This folder must be on the DOS path for the programs to run. The sources for some, but not all, of these executables are included with the distribution.
SOURCE
Various subfolders
Source files for programs that can be compiled using G77
 
BLDALL.BAT
Execute BLDALL in all the program subfolders to compile all the programs. Note: NEWENV.BAT needs to be edited and run first.
F77LSRC
Various subfolders (see Figure B-1)
Source files for programs that can be compiled using F77L. Note: This compiler may not work with Windows XP but the executables for all these programs are in PGMS and these should run under XP as long as path names are not too long.
 
BLDALL.BAT
Execute BLDALL in all the program subfolders to compile all the programs. Note: NEWENV.BAT needs to be edited and run first.
G77
Various
Binaries needed to compile using G77 and G77 documentation
F77L
Various
Binaries needed to compile using F77L. Strictly speaking a license from Lahey is required to use but as far as we know it is no longer supported.

[Back to program files section]


Table B-3.  Files in CHAMCALC.ZIP, containing files used to conduct the environmental
chamber simulations used in the SAPRC-07 mechanism evaluation (Carter, 2008a).
Folder
Files or folders
Description
Root
README.TXT, 
README.DOC,
README.PDF
README.TXT contains a brief description of files in all distribution sets, README.DOC and .PDF contain this document Note: these files in included in all distribution sets, and should be the same on all sets of the same age. If they are not the same, the older versions should be overwritten with the most recent version.
CHAMCALC
Folder where chamber simulation calculations are carried out
 
MODELRUN.XLS
Excel file containing list of all chamber runs modeled and related information.
 
SAPRC99.PRM
Parameter file for simulating runs using the detailed SAPRC99 mechanism
 
SAPRC07.PRM
Parameter file for simulating runs using the detailed SAPRC07 mechanism
 
MODELING.PRM
Default parameters and file locations for all simulations
 
EXAMPLE.BAT
Batch file to show example for simulating a test calculation with the two mechanisms. Requires files in PGMS.ZIP and MECH.ZIP
 
CLEANUP.BAT
Batch file to remove files created by example.bat and other simulations
CHAMCALC\INPFILES
Input files (RunID.INP) for simulations for all chamber experiments in the distribution. Runs are listed in MODELRUN.XLS
CHAMCALC\CMPFILES
Composition (.CMP) files for various mixtures used in certain complex mixture experiments.
CHAMCALC\CHAR
Input files with characterization data for chamber simulations.
 
LIGHT\*.SDR
Spectral distribution files
 
LIGHT\*.VSD, LIGHT\*.VSA
Files for time-varying spectral distributions for various outdoor chamber runs. *.VSD = binary files used as inputs; *.VSA = ASCII files showing data in binary files.
 
SAPRC99
Folder with characterization files for simulations using the SAPRC99 mechanism.
 
SAPRC07
Folder with characterization files for simulations using the SAPRC07 mechanism.
CHAMCALC\CHDFILES
Folder containing files with measurement data for all the chamber experiments modeled (RunID.GDT)
CHAMCALC\CDTFILES
Folder for calculation results (CALCnnnn.CDT) files. Initially empty, and files here deleted by CLEANUP.BAT

[Back to chamber simulation files section]


Table B-4.  Files in TESTCALC.ZIP, containing files used to run mechanism comparison
calculations associated with the SAPRC-07 condensed mechanisms documentation.
Folder
File(s)
Description
Root
README.TXT, README.PDF
README.TXT contains a brief description of files in all distribution sets, README.DOC and .PDF contain this document Note: these files in included in all distribution sets, and should be the same on all sets of the same age. If they are not the same, the older versions should be overwritten with the most recent version.
TESTCALC
Folder to run test calculations
 
SAPRC99.PRM
Parameters used to run test calculations with SAPRC-99 mechanism
 
SAPRC07.PRM
Parameters used to run test calculations with uncondensed, fixed-parameter SAPRC-07 mechanism
 
CS07A.PRM
Parameters used to run test calculations with CS07A mechanism
 
CS07A.PRM
Parameters used to run test calculations with CS07B mechanism
 
MODELING.PRM
Default parameters and file locations for all simulations
 
TESTCLCS.TXT
List of test calculations included and file names used for them
 
EXAMPLE.BAT
Batch file to show example for simulating a test calculation with all mechanisms. Requires files in PGMS.ZIP and MECH.ZIP
 
CLEANUP.BAT
Batch file to remove files created by example.bat and other simulations
TESTCALC\INPFILES
Input files used for test calculations.
 
*.INP
Input file for a particular test calculation. See TESTCLCS.TXT
 
Z0.SDR
Spectral distribution used for solar irradiation with Z=0.
 
ARBROG.CMP
Composition of base ROG mixture used for some test calculations.
TESTCALC\CDTFILES
Folder for calculation results (CALCnnnn.CDT) files. Initially empty, and files here deleted by CLEANUP.BAT

[Back to test calculation files section]

Related Links

  • SAPRC Mechanism main page: http://www.cert.ucr.edu/~carter/SAPRC/
  • Emissions Speciation Database main page: http://www.cert.ucr.edu/~carter//emitdb
  • W.P.L. Carter main page: http://www.cert.ucr.edu/~carter
    •   
    [top of page]