AtChem 2
AtChem2 is a modelling tool for atmospheric chemistry. It is primarily designed to use the Master Chemical Mechanism (MCM), but it can be used with any general set of chemical reactions. The MCM is a near-explicit chemical mechanism which describes the gas-phase oxidation of volatile organic compounds (VOC) in the lower atmosphere. The latest stable version of AtChem2 can be downloaded from the AtChem2 GitHub.
This documentation will take you through getting a copy of the AtChem2 source code, setting up the environment for AtChem2 use, building a model, and submitting a model run to Viking’s job scheduler, in batch mode.
Setting up the environment
To work with AtChem2 you will need to load the following modules on Viking:
$ module load GCC/11.2.0 # Fortran compilter
$ module load SUNDIALS/2.7.0-foss-2021b # Solving suite
$ module load OpenLibm/0.8.1-GCC-11.2.0 # Maths library
$ module load Python/3.9.6-GCCcore-11.2.0 # A Python interpreter
Next, clone a copy of the AtChem2 source code and move into the directory
$ git clone https://github.com/AtChem/AtChem2.git atchem2
$ cd atchem2
Building a model
The ‘Installation, Setup, and Execution’ section of the AtChem2 README describes the process of building a model, which will be paraphrased here.
Make a copy of the AtChem2 Makefile template - this will be used by the model build script to compile the model (if you’re interested in learning more about what a Makefile is, have a look at the GNU docs):
$ cp tools/install/Makefile.skel ./Makefile
Open the Makefile in a text editor (if you’re not sure how to do this, see this tutorial), and change the values of CVODELIBDIR and OPENLIBMDIR to correspond with the Viking module environment, i.e:
CVODELIBDIR = cvode/lib
OPENLIBMDIR = openlibm-0.4.1
becomes:
CVODELIBDIR = /opt/apps/eb/software/SUNDIALS/2.7.0-foss-2021b/lib
OPENLIBMDIR = /opt/apps/eb/software/OpenLibm/0.8.1-GCC-11.2.0/lib
Run the AtChem2 build script, giving it the location of a FACSIMILE format mechanism with which to build your model (for this example, we are using the test mechanism supplied with AtChem2):
$ ./build/build_atchem2.sh model/mechanism.fac
You will see some text describing what this process is doing, as well as some compiler warnings - don’t worry about these! If this process completes successfully, you should now have an AtChem2 executable file in the current directory.
Test that the mechanism test model built correctly by running it:
$ ./atchem2
If the model runs successfully, you should see a ‘final statistics’ statement in the output that looks like the following:
------------------
Final statistics
------------------
No. steps = 603 No. f-s = 699 No. J-s = 1003 No. LU-s = 100
No. nonlinear iterations = 696
No. nonlinear convergence failures = 0
No. error test failures = 28
Runtime = 0
Deallocating memory.
Model outputs are saved in the model/output directory:
$ ls model/output
environmentVariables.output finalModelState.output lossRates.output photolysisRates.output productionRates.output speciesConcentrations.output
errors.output jacobian.output mainSolverParameters.output photolysisRatesParameters.output reactionRates
At this point, you can build and run AtChem2 models, and are ready to start using your own mechanisms and configuring the model parameters for your simulations. Please refer to the AtChem2 wiki or the AtChem2 User Manual for comprehensive information about how to work with AtChem2.
Running models
An example Slurm batch script is shown below for the test mechanism used above. This requests a single core and 100MB of RAM and will run for a maximum of 2 minutes. If you are using the same mechanism file for multiple model runs you can build the model on the login node outside of the job rather than rebuilding it for each submission.
#!/usr/bin/env bash
#SBATCH --job-name=atchem2_mech_test
#SBATCH --mail-user=USERNAME@york.ac.uk
#SBATCH --mail-type=ALL
#SBATCH --output=atchem2_mech_test.log
#SBATCH --account=VIKING-PROJECT-ACCOUNT-CODE
#SBATCH --partition=nodes
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=1
#SBATCH --mem-per-cpu=100MB
#SBATCH --time=00:02:00
cd ${SLURM_SUBMIT_DIR} || exit
module load GCC/11.2.0
module load SUNDIALS/2.7.0-foss-2021b
module load OpenLibm/0.8.1-GCC-11.2.0
module load Python/3.9.6-GCCcore-11.2.0
./build/build_atchem2.sh model/mechanism.fac
./atchem2