Mechanism Converter to SSH-aerosol v2.0

This program converts given atmospheric chemical mechanisms from MCM (FACSIMILE) or GECKO format to the SSH-aerosol v2.0 format. The code is adapted from the GENOA algorithm (v2.0).

Scripts

The program includes:

• python scripts:

  1. converter.py: The main script for conversion.
  2. parameter.py: All user-defined parameters are stored in this script.
  3. utils.py: Contains utility functions used in the conversion process.
  4. data_stream.py: Handles reading and writing data from/to files.
  5. kinetic_rate_to_ssh.py: Converts kinetic rates from MCM or GECKO formats to SSH-aerosol v2.0 format.
  6. module.py: Defines the classes for species and reactions in the mechanism.
  7. smiles.py: Calculates molecular properties based on SMILES strings.

• data/ folder: contains the data files required for the conversion process.

• examples/ folder:

  1. inputs/: contains example input mechanisms for testing the conversion script.
  2. scripts/: contains example parameter files for testing the conversion script. To use the example parameters, copy the files to the main directory and rename them to parameter.py.
  3. example_output: contains example output mechanisms in SSH-aerosol v2.0 format generated by the example scripts.
  4. outputs/: it is an empty folder that will contain the output mechanisms generated by the conversion script.

Installation of Dependencies: OpenBabel and UManSysProp

To install required OpenBabel, you can use conda:

```
  conda install -c conda-forge openbabel
```

To install UManSysProp, you can download it from its GitHub repository:

```
  git clone git@github.com:loftytopping/UManSysProp_public.git
```

Then, give the path to the UManSysProp folder in the `converter.py` script as variable `path_to_umansysprop`.

Usage

Step 1: To convert a mechanism, the user must specify the following parameters in the parameter.py script:

1. output_dir: Path to the output directory.
2. chem_id: Identifier for the output mechanism.
3. reaction_file: Path to the file containing the mechanism.
4. reaction_type: Type of the reaction mechanism (e.g., FACSMILE for MCM, GECKO, SSH`).

For conversion of MCM and SSH mechanisms, the user must also specify:

1. species_file: Path to the file containing the species information.
2. species_type: Type of the species information (e.g., MCM, GECKO, SSH).

To include aerosol properties, the user can specify:

1. soap_file: Path to the file containing the SOAP decomposition information. This file is generated by running SSH-aerosol with the aerosol species list [name].aer.1st.
2. vptype: Type of saturation vapor pressure computation (e.g., simpol).
3. psat_nvoc: Set aerosols to non-volatile if Psat < psat_nvoc in atm.
4. psat_svoc: Set aerosols to volatile if Psat > psat_svoc in atm.

Please check the example parameter files in the examples/scripts folder for more details.

Step 2: After setting the parameters, run the converter.py script to convert the mechanism to SSH-aerosol v2.0 format:

```
  python converter.py
```

The output mechanism will be saved in the specified output directory with the given identifier.

The script will generate the following output files in the specified output directory:

1. [chem_id].species: Species list file that can be directly used in the SSH-aerosol simulations.
2. [chem_id].reactions: Reaction list file that can be directly used in the SSH-aerosol simulations.
3. [chem_id].aer.1st: Aerosol species list file that contains SMILES structures, where the aerosol species are disconnected to their precursors (Precursors for ogranic aerosols are not specified). This file is used to generate the SOAP output information required to further convert this mechanism with functional group decomposition.
4. [chem_id].aer: Aerosol species list file that contains SMILES structures, where the aerosol species are connected to their precursors. This file can be used to obtain the SOAP output information along with the generated species file, and also to run the SSH-aerosol simulations with SMILES structures.
5. [chem_id].aer.vec: Aerosol species list file that contains functional group decomposition information. This file can be used to run the SSH-aerosol simulations.
6. [chem_id].mol: Molecular properties file that contains the molecular properties of all the species in the mechanism. Togehter with the reaction file, this file can be used in the converter and GENOA to import a mechanism in the SSH-aerosol format.

See the example output files in the examples/output folder for more details.

Please check the converted mechanisms before using them in SSH-aerosol. Some manual modifications may be required to ensure the mechanism is correctly converted. For example, kinetic rate constants that can not be converted will be set to !!! in the output reaction file. The user should manually update these values.

Step 3: To run the SSH-aerosol model with the converted mechanism, the user may neet specify the following parameters in the SSH-aerosol namelist:

1. species_list_file: Make sure the species list file is consistent with the initial and constant concentration files used in the namelist.
2. aerosol_species_list_file: Make sure the aerosol concentrations are consistent with the aerosol species list file used in the namelist. For the fist time running converted mechanism, please use [name].aer.1st file to generate the soap output information required to convert a mechansim with functional group decomposition.
3. reaction_list_file: If the mechanism is converted from GECKO, please also provide the corresponding photolysis_file in the namelist.
4. RO2_list_file: It is an optional file that only needs to be specified if the mechanism contains RO2-RO2 reactions (tag_RO2 > 0 in the namelist).

Note that this may change depending on the version of SSH-aerosol. Please refer to the SSH-aerosol documentation for more information.

Examples:

Three example mechanisms are provided in the examples/inputs folder:

• API2_GECKO-A: A two-generation degradation scheme for a-pinene from the GECKO-A generator.
• API_MCM: The degradation scheme for a-pinene from the MCM mechanism.
• ISOP_MCM: The degradation scheme for isoprene from the MCM mechanism.

Those mechanism files can be used to test the converter via the exmaple parameter files in the examples/scripts folder. To use the example parameters, copy the files to the main directory and rename them to parameter.py. Then, run the converter.py script to convert the mechanisms to SSH-aerosol v2.0 format. The output mechanisms will be saved in the examples/output folder.