AtChem2

AtChem2 is a modelling tool for atmospheric chemistry. It is primarily designed to use the Master Chemical Mechanism (MCM, https://mcm.york.ac.uk/MCM), a near-explicit chemical mechanism which describes the gas-phase oxidation of volatile organic compounds (VOC) in the lower atmosphere. AtChem2 can also be used with other chemical mechanisms, as well as any general set of chemical reactions, provided they are in the correct format.

AtChem2 is open source, under the MIT license.

Please see the file CITATION.md for information on how to cite the model in publications.

Directory structure

• build/ contains the Python and shell scripts to build the AtChem2 model.
• doc/ contains the AtChem2 user manual, with its LaTeX source files and figures, and the poster presented at the 2018 ACM conference.
• docker/ contains Docker-related scripts and files.
• mcm/ contains the MCM data files, with minimal chemical mechanisms in FACSIMILE (.fac) and KPP (.kpp) formats.
• model/ is the default directory for the chemical mechanism, model configuration, constraints and output. It also contains an example chemical mechanism in FACSIMILE format. There can be several such directories (with different names).
• obj/ contains the module/object files generated by the Fortran compiler.
• src/ contains the Fortran source files.
• tests/ contains the Testsuite scripts, files, and logs.
• tools/ contains scripts to install AtChem2 and its dependencies, plotting tools in various programming languages, and other utilities.

Install

AtChem2 compiles and runs both on Unix/Linux and macOS systems: it implements a continuous integration development workflow and an extensive Testsuite, in order to ensure reliable and reproducible results. A working knowledge of the unix shell is required to install and use AtChem2.

AtChem2 requires a Fortran compiler (GNU gfortran or Intel ifort), the CVODE (part of SUNDIALS) and openlibm libraries, make, and Python. Compilation of CVODE also requires cmake and gcc. Optionally, numdiff, FRUIT, and Ruby (v3.0) are required to run the Testsuite.

The latest stable version of AtChem2 can be downloaded from the Releases page, and is associated with a doi number for referencing in publications.

After installing the required dependencies using the scripts in the tools/install/ directory, copy the file tools/install/Makefile.skel to the Main Directory and rename it Makefile. Set the variables CVODELIBDIR, OPENLIBMDIR and FRUITDIR in the Makefile to the full paths of CVODE, openlibm and (if installed) FRUIT.

Alternatively, and optionally, AtChem2 can be run as a Docker container. Currently the containerized version is available only for AtChem2 v1.2.2, thanks to the Uni York group.

Build & Run

To build the AtChem2 model -- using the example chemical mechanism and default settings -- execute the following command from the Main Directory:

./build/build_atchem2.sh ./model/mechanism.fac

The build script converts the chemical mechanism from the FACSIMILE format (mechanism_test.fac) to a Fortran-compatible format, and generates the pre-compiled shared library mechanism.so in the model/configuration/ directory. After the build process is completed, an executable file called atchem2 is created in the Main Directory.

Set the model parameters, the initial conditions, and the required outputs by editing the files in the model/configuration/ directory. If needed, ensure that the constrained data files are in the relevant subdirectory in model/constraints/. To run the model with the default configuration, execute the command:

./atchem2

The executable accepts several command line arguments to customize the location of the configuration, input and output directories, and of the shared library. More information on AtChem2, with detailed instructions on its installation, configuration and use can be found in the manual (doc/AtChem2-Manual.pdf) and in the GMD paper (see the file CITATION.md).

The AtChem2 wiki contains a summary of the instructions to install, compile, run, and contribute to the development of AtChem2, together with additional information, and a list of known issues with the suggested solutions or workarounds.

Python tools designed to help users run AtChem2 box-models and analyze their output are available at the associated repository: AtChem-tools.