Merge PR #92 'MCM' into dev

This merge brings PR #92 (MCM, by @RolfSander) into the KPP 3.1.0
development stream.

This adds a minimal example for the Master Chemical Mechanism
(MCM) minimal example, plus a C-I test.

Signed-off-by: Bob Yantosca <[email protected]>

.ci-pipelines/Dockerfile

@@ -31,6 +31,9 @@ ENV KPP_FLEX_LIB_DIR=/lib/x86_64-linux-gnu
 RUN sed -i 's/#define MAX_EQN .*/#define MAX_EQN 1023/g' /kpp/src/gdata.h \
     && sed -i 's/#define MAX_SPECIES .*/#define MAX_SPECIES 1023/g' /kpp/src/gdata.h
 
+# Disable MCM test
+RUN sed -i 's/DO_MCM=1/DO_MCM=0/g' /kpp/.ci-pipelines/ci-common-defs.sh
+
 # Build KPP executable and ensure testing scripts are executable
 RUN cd /kpp/src/ && make
 RUN chmod +x /kpp/.ci-pipelines/ci-common-defs.sh

.ci-pipelines/ci-cleanup-script.sh

@@ -17,6 +17,7 @@ cwd=$(pwd -P)
 for this_test in ${GENERAL_TESTS}; do
     clean_ci_test_folder "${this_test}" "${cwd}"
 done
+clean_ci_test_folder "${MCM_TEST}" "${cwd}"
 
 # Remove any log files used to store C-I test results
 cd $cwd

.ci-pipelines/ci-common-defs.sh

@@ -32,6 +32,10 @@ F90_small_strato
 # Testing if #MINVERSION works
 MINVERSION_TEST="X_minver"
 
+# Testing if the Master Chemical Mechanism test works
+DO_MCM=1
+MCM_TEST="mcm"
+
 #=======================================================================
 # Functions
 #=======================================================================
@@ -48,6 +52,7 @@ function run_ci_test() {
     # Arguments
     this_test=${1}     # Name of test
     return_dir=${2}    # Directory where we will return upon test completion
+    extra_cmds=${3}    # Extra commands to pass to compilation
 
     # Navigate to C-I test folder (or exit if error)
     test_path=$(get_ci_test_path "${this_test}")
@@ -63,7 +68,7 @@ function run_ci_test() {
     echo ""
     echo ">>>>>>>> Building the ${this_test} test executable <<<<<<<<<"
     echo ""
-    make -j -f Makefile_$this_test COMPILER=GFORTRAN
+    make -j -f Makefile_$this_test COMPILER=GFORTRAN ${extra_cmds}
     [[ $? -ne 0 ]] && exit 1
 
     echo ""

.ci-pipelines/ci-testing-script.sh

@@ -12,9 +12,16 @@ cwd=$(pwd -P)
 
 # Run C-I tests with various mechanism + integrator combinations
 for this_test in ${GENERAL_TESTS}; do
-    run_ci_test "${this_test}" "${cwd}"
+    run_ci_test "${this_test}" "${cwd}" ""
 done
 
+# Run the MCM test separately
+# NOTE: The MCM test cannot be run on Azure due to memory limitations,
+# so test the DO_MCM env var to see if we should run it.
+if [[ "x${DO_MCM}" == "x1" ]]; then
+  run_ci_test "${MCM_TEST}" "${cwd}" "EXTERNAL_RATES_F90=constants_mcm.f90"
+fi
+
 # Run a C-I test to see if the #MINVERSION command works as advertised
 run_minversion_ci_test "${MINVERSION_TEST}" "${cwd}"
 

.gitignore

@@ -64,3 +64,8 @@ docs/build/*
 
 # are there any *.dat files to exclude?
 *.dat
+
+# Other files/dirs to exclude
+*.pdf
+/examples/mcm/__pycache__
+

CHANGELOG.md

@@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased] - TBD
 ### Added
 - `#AUTOREDUCE` has been added to the list of KPP commands in the ReadTheDocs documentaton
+- Added `examples/mcm` folder with minimal example for the Master Chemical Mechanism
+- Added C-I test for MCM, based on the minimal example
 
 ### Removed
 - `TRANSPORT` and `TRANSPORTALL` input options; these were obsolete

ci-tests/mcm/constants_mcm.f90

@@ -0,0 +1 @@
+../../examples/mcm/constants_mcm.f90

ci-tests/mcm/driver_mcm.f90

@@ -0,0 +1 @@
+../../examples/mcm/driver_mcm.f90

ci-tests/mcm/mcm.kpp

@@ -0,0 +1 @@
+../../examples/mcm/mcm.kpp

ci-tests/mcm/mcm_isoprene.eqn

@@ -0,0 +1 @@
+../../examples/mcm/mcm_isoprene.eqn

docs/source/citations/09_acknowledgments.rst

@@ -27,7 +27,7 @@ to migrate from :program:`yacc` to :program:`bison`.
 
 We would also like to thank Lucas Estrada for his assistance in
 setting up the :ref:`ci-tests` on `Azure DevOps Pipelines
-<https://azure.microsoft.com/en-us/services/devops/pipelines/>`_. and
+<https://azure.microsoft.com/en-us/services/devops/pipelines/>`_ and
 for assistance with debugging.
 
 Shaddy Ahmed and Jennie Thomas helped us with the Matlab
@@ -36,4 +36,9 @@ output of KPP.
 We thank Domenico Taraborrelli for providing the
 rosenbrock_posdef_h211b_qssa solver.
 
+Stuart Lacy wrote an export function for the `Master Chemical Mechanism
+<https://mcm.york.ac.uk/MCM/export>`_. It creates KPP files that can be
+used out-of-the-box for the small model in the :file:`examples/mcm`
+directory.
+
 Parts of this user manual are based on :cite:t:`Damian-Iordache_1996`.

examples/mcm/README.md

@@ -0,0 +1,69 @@
+# MCM minimal example 
+
+By Rolf Sander
+
+The Master Chemical Mechanism (MCM) offers the export of a selected
+mechanism in KPP format. The downloaded files can be used out-of-the-box
+as input for the example model in this directory. Here, the isoprene
+degradation mechanism is used as an example.
+
+## Downloading a mechanism from the MCM web page
+
+1. Browse through the [MCM](https://mcm.york.ac.uk/MCM/browse) and
+   select a Subset of the mechanism.
+
+2. Go  to the [export page](https://mcm.york.ac.uk/MCM/export) and
+   choose KPP as the output format.
+
+3. Click on the `Download` button and rename the downloaded file to
+   `mcm_isoprene.eqn`.
+
+4. Download the auxiliary file
+   [constants_mcm.f90](https://mcm.york.ac.uk/MCM/export/kpp_constants).
+
+## Executing the MCM minimal example
+
+1. Ensure that KPP is
+   [installed](https://kpp.readthedocs.io/en/stable/getting_started/01_installation.html)
+   properly. The environment variable `$KPP_HOME` must be defined, and
+   the KPP executable `$KPP_HOME/bin/kpp` should be included in the
+   `$PATH`.
+
+2. Run KPP to generate Fortran90 solver files for the MCM minimal example:
+
+   ```console
+   $ kpp mcm.kpp
+   ```
+  
+3. Compile the KPP-generated source code to an executable:
+
+   ```console
+   $ gmake -f Makefile_mcm clean
+   $ gmake -f Makefile_mcm EXTERNAL_RATES_F90=constants_mcm.f90
+   ```
+   NOTE: On some systems, `gmake` may be installed as `make`.
+
+   ALSO NOTE: At present, only a single external F90 module file (with
+   rate constants and parameters for the MCM mechanism) can be specified
+   with the `EXTERNAL_RATES_F90` environment variable. To specify more
+   than one external file you will have to modify the `util/Makfile_f90`
+   and/or `util/Makfile_upper_F90` to add additional rules.
+
+4. Run the MCM minimal example executable:
+
+   ```console
+   $ ./mcm.exe
+   ```
+
+5. If Python 3 and matplotlib are available (e.g., installed in a
+   conda/mamba or a pip environment), plot the results with:
+   
+   ```console
+   $ python3 plot_data.py
+   ```
+   
+6. Remove all KPP-generated source code files and output files from the MCM minimal example once you no longer need them:
+
+   ```console
+   $ gmake -f Makefile_mcm distclean
+   ```