Giters

stakahama / aprl-kpp-gp

Code to add gas/particle partitioning to the output of KPP; accompanies manuscript http://dx.doi.org/10.5194/acp-16-8729-2016

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

APRL KPP G/P module DOI

This program generates a gas-phase chemical kinetic model using the Kinetic Pre-Processor (KPP) [1][2] with the Master Chemical Mechanism (MCM) [3], and adds dynamic gas/particle (G/P) partitioning with vapor pressure estimation from the SIMPOL.1 group contribution model [4]. Further details are provided by Ruggeri et al. [5].

  1. http://dx.doi.org/10.5194/acp-6-187-2006
  2. https://github.com/barronh/kpp
  3. http://mcm.leeds.ac.uk/MCM
  4. http://dx.doi.org/10.5194/acp-8-2773-2008
  5. http://dx.doi.org/10.5194/acp-16-8729-2016

This program is released under the GNU Public License v3.0 (LICENSE_GPLv3.txt). If used, please include a citation to our manuscript:

Ruggeri, G., Bernhard, F. A., Henderson, B. H., and Takahama, S.: Model–measurement comparison of functional group abundance in α-pinene and 1,3,5-trimethylbenzene secondary organic aerosol formation, Atmos. Chem. Phys., 16, 8729-8747, doi:10.5194/acp-16-8729-2016, 2016.

Main features:

  • Vapor pressure estimates from MCM species and functional groups defined in APRL-SSP (https://github.com/stakahama/aprl-ssp). [Python]
  • Gas-phase simulation code generated by KPP is modified to implement dynamic partitioning via operator splitting. [Python/Fortran]
  • Generates 1) original gas-phase only and 2) gas-phase with G/P partitioning module to run with same inputs.

User inputs

Directory structure

The user should provide compound-specific information and initial conditions (e.g., in "compounds/") and simulations parameters (e.g., in "simulations/"). "photolysisfiles/" are provided and the appropriate "photolysis.txt" should be copied into the run subdirectory. Using the same name for the top level directory (e.g., "apinene_1") for the compounds and simulation directories may be helpful.

compounds/

  • apinene_1/
    • {ROOT}.kpp
    • mcm_{ROOT}_mass.txt
  • apinene_2/
    • {ROOT}.kpp
    • mcm_{ROOT}_mass.txt

simulations/

  • apinene_1/
    • run_001/
      • (for gas,total) photolysis.txt
      • (for gas,total) [optional] input_time.txt
      • (for gas,total) [optional] input_temp.txt
      • (for gas,total) [optional] cgas_init.def
      • (for total) input_partitioning.txt
      • (for total) [optional] molefrac_init.txt
    • run_002/
      • (for gas,total) photolysis.txt
      • (for gas,total) [optional] input_time.txt
      • (for gas,total) [optional] input_temp.txt
      • (for gas,total) [optional] cgas_init.def
      • (for total) input_partitioning.txt
      • (for total) [optional] molefrac_init.txt
  • apinene_2/ (same structure as above)

photolysisfiles/

  • original/
    • photolysis.txt
  • dark/
    • photolysis.txt
  • constantlight/
    • photolysis.txt

Note that the user will provide "cgas_init.def"; a corresponding "cgas_init.txt" file to be read by the Fortran program will be generated by "exec_dual.py" described below.

The main objective is to build a program for a fixed mechanism (set of chemical reactions, species) to simulate over a range of temperatures, concentrations, and timesteps. After generating the gas and total (gas+aerosol) simulation models ("exec_gas/{ROOT}.exe" or "exec_total/{ROOT}.exe" in each simulation subdirectory), parameters can be changed through input files for various simulations ("run_{DDD}/"). Note that runs using "input_temp.txt" and "cgas_init.txt" are untested and should be against a reference simulation.

File descriptions

Mechanism information:

  • {ROOT}.def: combines organic and inorganic kpp files; specifies initial concentrations, temperature, and time parameters
  • {ROOT}.kpp: generated from MCM web
  • mcm_{ROOT}_mass.txt: table of masses and SMILES strings (downloaded as mcm_subset_mass.txt)

Simulations:

  • photolysis.txt: input for kpp_constants.f90

  • input_time.txt: time in units of seconds. Note that when partitioning is turned on, the operators are coupled as S1(DT)oS2(DT) so 2*DT is a full timestep for gas-phase chemistry + partitioning.

      {TSTART}
  {DURATION}
  {DT}

  • input_temp.txt: temperature and conversion factor (ppb to molec/cm^3) (untested)

      {TEMP}
  {CFACTOR}

  • cgas_init.def: initial gas-phase concentrations (in ppb) in equation form as you would write in the .def file

      {COMPOUND1} = {PPB1}
  {COMPOUND2} = {PPB2}
  ...

where COMPOUND1, COMPOUND2 are names of species. There will be a corresponding file generated by the program called cgas_init.txt, and this will be the file read in by the Fortran program (uses species indices rather than species names).

  • input_partitioning.txt: M0 is the initial aerosol concentration in micrograms per cubic meter; PARTITIONING_MODE is 0 for no partitioning, 1 for instantaneous (equilibrium) partitioning, and 2 for dynamic partitioning using LSODE; ABSORPTIVE_MODE is whether/when to turn on absorptive partitioning (see below); INTEGRATORCHECK determines whether additional diagnostics are run (0=off, 1=on); MINCONC is the value (in ppb) at which minimum concentrations in gas and aerosol phases are maintained; MF is a DLSODE option which controls the integration (10=Nonstiff, no Jacobian required; 21=User-supplies Jacobian-generating function (default); 22=Jacobian is internally generated). MINCONC=0 and MF=22 is recommended. NCONC is the fixed number concentration [m^-3] of particles and DIAM_SEED is the seed diameter [m] (enter 0.E0 if no seed).

      {M0}
  {PARTITIONING_MODE}
  {ABSORPTIVE_MODE}
  {INTEGRATORCHECK}
  {MINCONC}
  {MF}
  {NCONC}
  {DIAM_SEED}

ABSORPTIVE_MODE options:

  • 0: begin absorptive partitioning immediately.
  • 1: begin absorptive partitioning when COA > 0 (does not use information about COA,init).
  • 2: begin absorptive partitioning when COA > COA,init

Note that for the "extra solvent" simulation, set ABSORPTIVE_MODE to 0 and do not provide a molefrac_init.txt file.

  • molefrac_init.txt: IND is the organic compound index and a0 is the initial mole fraction; the first line is a label (for "harvest_parms.py") preceded by #

      {#COMMENT}
  {IND1} {a0(1)}
  {IND2} {a0(2)}

This input file is best generated by a a script (~/git/projects/aprl-kpp-gp/postprocess/a0_initialize.R). If molefrac_init.txt is not provded and ABSORPTIVE_MODE is 0 in input_partitioning.txt -> "extra solvent" mode; ABSORPTIVE_MODE is 1 in input_partitioning.txt -> "infinite sink" assumption (only until COA > COA,init, which generally occurs in the first time step).

Instructions

There are four main executable python scripts. The first should be run in the compound/ folder, and the rest in the simulations/ folder.

  • search_struct.py: generates SIMPOL and FTIR group tables; also property tables
  • build_dual.py: construct MCM/KPP executables for gas and aerosol simulations
  • execute_dual.py: run executables for a given folder of input parameters ("runpath")
  • harvest_parms.py: harvest parameters from one or more runpath folders

Add aprl-kpp-gp/ to the list of paths in which executable are searched:

$ export PATH=~/git/projects/aprl-kpp-gp:$PATH

Calculate group abundances for each compound

Run in compounds directory (e.g., "compounds/apinene_1").

This uses aprl-structsearch. Note that according to the instructions for aprl-structsearch, you should add the path of this program to the PATH environmental variable also:

$ export PATH=~/git/projects/aprl-structsearch:$PATH

I have created a script, search_struct.py, in aprl-kpp-gp to facilitate generation of SIMPOL and FTIR groups, and also the vapor pressures at 298.15K and 358.15K (60 degrees C) using the aprl-structsearch program.

Command:

$ search_struct.py {ROOT} {PROGPATH}

Arguments:

  • ROOT: label for KPP
  • [optional] PROGPATH: path to aprl-structsearch if not on executable path

Example usage:

$ search_struct.py apinene

Outputs (in working directory):

  • {ROOT}_FTIRGroups.csv: table of abundances, compounds x groups
  • {ROOT}_SIMPOLGroups.csv: table of abundances, compounds x groups
  • {ROOT}_props_298.csv: vapor pressures and enthalpies of vaporization at 298.15K
  • {ROOT}_props_358.csv: vapor pressures and enthalpies of vaporization at 358.15K

Build executables for gas-phase only ("gas") and gas+aerosol ("total") simulations

Run in simulation directory (e.g., "simulations/apinene_1/").

Command:

$ build_dual.py {ROOT} {CPATH} {--skipbuild} {--onlygas} {--onlytotal}

Arguments:

  • ROOT: label for KPP
  • CPATH: path to compounds directory
  • [optional] --skipbuild: will not run kpp again but only use output of kpp (in "kppbuild/") to generate "exec_gas/" and "exec_total/". Default is to build.
  • [optional] --onlygas: will not run kpp again but only use output of kpp (in "kppbuild/") to generate "exec_gas/". Default is to generate "exec_total".
  • [optional] --onlytotal: will not run kpp again but only use output of kpp (in "kppbuild/") to generate "exec_total/". Default is to generate "exec_total".

Example usage:

$ build_dual.py apinene ../../compounds/apinene_1

Outputs (in working directory):

  • contents of {CPATH} are copied here
  • kppbuild/: kpp output
  • exec_gas/: executable for gas-phase simultions
  • exec_total/: executable for total-phase simulations

Execute gas-phase and gas+aerosol simulations

Run in simulation directory (e.g., "simulations/apinene_1/").

Command:

$ exec_dual.py {ROOT} {RUNPATH} {MODE}

Arguments:

  • ROOT: label for KPP
  • RUNPATH: name of input folder
  • [optional] MODE: one of "gas,total", "gas", or "total" (without quotes). Default is "gas,total"

Example usage:

$ exec_dual.py apinene run_varyvoc_001

Outputs (in run directories):

  • runpath/gas/{ROOT}.dat
  • runpath/gas/{ROOT}_formatted.csv
  • runpath/total/{ROOT}.dat
  • runpath/total/{ROOT}_formatted.csv
  • runpath/total/{ROOT}_aer.dat
  • runpath/total/{ROOT}_aer_formatted.csv

Note that "exec_dual.py" will also create a "cgas_init.txt" file in the run directory for the Fortran program to read; each time the script is executed, "cgas_init.txt" will be overwritten by the translated contents of the user-provided "cgas_init.def".

Build executables for gas-phase only ("gas") and gas+aerosol ("total") simulations

Run in simulation directory (e.g., "simulations/apinene_1/").

Command:

$ harvest_parms.py {ROOT} {RUNPATH}

Arguments:

  • ROOT: label for KPP
  • [optional] RUNPATH: zero or more paths. if omitted, all paths beginning with "run_" will be harvested

Example usage:

$ harvest_parms.py apinene

Outputs (in working directory):

  • parameter_table.csv

[optional] Generate molefrac_init.txt file.

Command:

$ ~/git/projects/aprl-kpp-gp/postprocess/a0_initialize.R {ROOT} {TYPE} {RUNPATH}

Arguments:

  • ROOT: label for KPP
  • TYPE can be one of:
    • purecomponent
    • equalcomponent
    • initialequilibrium
    • gasphasecomp
    • recycledseed
  • RUNPATH: name of input folder

Note that ABSORPTIVE_MODE in input_partitioning.txt, in addition to the TYPE argument, will also affect the partitioning. For "infinitesink" or "extrasolvent", a0_initialize.R does not need to be invoked (see explanation for molefrac_init.txt).

Example usage:

$ ~/git/projects/aprl-kpp-gp/postprocess/a0_initialize.R apinene purecomponent run_001

Full example

$ export MYPATH=/path/to/MCM/new # change to desired path

$ cd $MYPATH
$ cd compounds/apinene_1
$ search_struct.py apinene

$ cd $MYPATH
$ cd simulations/apinene_1
$ build_dual.py apinene ../../compounds/apinene_1
-> note that simulations/apinene_1/ has been populated (e.g., with kppbuild/, exec_gas/, exec_total/)

$ cd $MYPATH
$ mkdir simulations/apinene_1/run_001
$ cp -p photolysisfiles/dark/photolysis.txt simulations/apinene_1/run_001/
-> also add other input files (e.g., run a0\_initialize.R)

$ exec_dual.py apinene run_001
-> check in run_001/gas/ and run_001/total/ for outputs files

$ harvest_parms.py apinene
-> look at parameter_table.csv

About

Code to add gas/particle partitioning to the output of KPP; accompanies manuscript http://dx.doi.org/10.5194/acp-16-8729-2016

License:GNU General Public License v3.0

Languages

Language:Fortran 94.9%Language:Python 4.8%Language:R 0.3%