Add support for kpp format (#497)

* Set up to support KPP formats

* Tidy build py scripts

* Rename some variables for clarity

* Remove logfile printout

* Reset version number to dev status

* Tidy mech_converter.py script

* Cosmetic changes to sh scripts

* Check python scripts with pylint

* Skeleton convert_kpp.py and other small fixes

* Functional conversion script

* Amend mcm/ and .fac info

* Tidy comments py scripts

* Links for the badges

* Call kpp cpnversion script from mech_converter

* Set path of the kpp file

* Model test for the KPP conversion

* cmp files for the new model tests

* Remove extra fac file

* Fix compilation of model in kpp test

* Upload coverage only if tests are run

* Compile manual

.github/workflows/ci.yml

@@ -148,6 +148,7 @@ jobs:
  make modeltests CCOV=true # Run only the new model Testsuite
 
  - name: Upload coverage reports to Codecov
+ if: matrix.os == 'ubuntu-22.04' && matrix.fortran == 11
  uses: codecov/codecov-action@v3
  with:
  gcov: true

CHANGELOG.md

@@ -1,11 +1,23 @@
-# AtChem2 - CHANGELOG
+AtChem2 - CHANGELOG
+===================
 
-## v1.2.2 (May 2023)
+
+post v1.2.2
+-----------
+
+- new implementation of the Testsuite code coverage using Codecov
+- restructure the `ci.yml` file and streamline the continuous integration process
+- update the `Makefile` and move the instructions for the Testsuite to a secondary makefile
+- support for chemical mechanisms in KPP format (as generated by the MCM website)
+
+
+v1.2.2 (May 2023)
+-----------------
 
 - move implementation of continuous integration from TravisCI to [GitHub Actions](https://docs.github.com/en/actions)
-- improve reporting of the testsuite results by using logfiles
-- begin implementation of the new testsuite ("behaviour tests" now referred to as "old tests")
-- remove unit testing from CodeCov (coverage reporting is broken)
+- improve reporting of the Testsuite results by using logfiles
+- begin implementation of the new Testsuite ("behaviour tests" now referred to as "model tests")
+- remove unit testing from Codecov (coverage reporting is broken)
 - disable (provisionally) CVODE support for LAPACK and BLAS
 - upgrade the install scripts to **openlibm v0.8.1** and **numdiff v5.9.0**, and add error handling
 - in the `Makefile`, add optimisation flag for `gfortran` and compilation flags for `ifort`
@@ -20,7 +32,9 @@
 - update the `*.md` files, and add _Buy Me a Coffee_ button to the `README.md` file
 - several updates to the user manual (including new MCM website at Uni. York) and other minor fixes
 
-## v1.2.1 (January 2021)
+
+v1.2.1 (January 2021)
+---------------------
 
 - add a new environment variable: `ASA` (aerosol surface area)
 - fix a bug in the C-binding for `gfortran` version 9 and above
@@ -29,7 +43,9 @@
 - tidy the comments and printout messages of various source files
 - update the user manual
 
-## v1.2 (May 2020)
+
+v1.2 (May 2020)
+---------------
 
 - implement argument parser and named arguments for the `atchem2` executable
 - streamline the build procedure, rename and tidy the build scripts, and move them to the `build/` directory
@@ -52,14 +68,18 @@
 - tidy and improve comments in various source files and scripts
 - various minor fixes and updates
 
-## v1.1.1 (January 2019)
 
-- add `doc/` directory containing the documentation in markdown format
+v1.1.1 (January 2019)
+---------------------
+
+- create the directory `doc/`, containing the documentation in markdown format
 - add `CONTRIBUTING.md` file
 - fix the headers of `lossRates.output` and `productionRates.output`
 - change the name of the environment variable `ROOFOPEN` to `ROOF`
 
-## v1.1 (November 2018)
+
+v1.1 (November 2018)
+--------------------
 
 - implement a new directory structure
 - add `CHANGELOG.md` and `CITATION.md` files
@@ -75,13 +95,15 @@
 - implement a unit testing framework (new requirements: **Ruby**, **FRUIT**)
 - add unit tests for atmosphere, configuration, date and solar functions
 - add exact solution behaviour tests
-- improve running and reporting of the testsuite
+- improve running and reporting of the Testsuite
 - rework the mechanism conversion procedure, and the related Python scripts
 - add plotting tools in R, Python, Matlab, gnuplot
 - extend the documentation on the wiki
 - fix several minor bugs
 
-## v1.0 (July 2017)
+
+v1.0 (July 2017)
+----------------
 
 - create a code repository and organization on [github.com](https://github.com/AtChem/)
 - adopt the [MIT open source license](https://opensource.org/licenses/MIT)

README.md

@@ -1,8 +1,8 @@
-AtChem2 ![license](https://img.shields.io/github/license/AtChem/AtChem2?color=blue) ![release](https://img.shields.io/github/v/release/AtChem/AtChem2?color=blue) ![AtChem2-CI](https://github.com/AtChem/AtChem2/workflows/AtChem2-CI/badge.svg) [![codecov](https://codecov.io/gh/AtChem/AtChem2/graph/badge.svg?token=b6GTNgTXqJ)](https://codecov.io/gh/AtChem/AtChem2)
+AtChem2 [![license](https://img.shields.io/github/license/AtChem/AtChem2?color=blue)](https://github.com/AtChem/AtChem2/blob/master/LICENSE) [![release](https://img.shields.io/github/v/release/AtChem/AtChem2?color=blue)](https://github.com/AtChem/AtChem2/releases) [![AtChem2 CI](https://github.com/AtChem/AtChem2/actions/workflows/ci.yml/badge.svg)](https://github.com/AtChem/AtChem2/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/AtChem/AtChem2/graph/badge.svg)](https://codecov.io/gh/AtChem/AtChem2)
 =======
 
 
-**AtChem2** is a modelling tool for atmospheric chemistry. It is primarily designed to use the **Master Chemical Mechanism** (MCM, http:https://mcm.york.ac.uk/), but it can be used with any general set of chemical reactions as long as they are provided in the correct format. The MCM is a near-explicit chemical mechanism which describes the gas-phase oxidation of volatile organic compounds (VOC) in the lower atmosphere.
+**AtChem2** is a modelling tool for atmospheric chemistry. It is primarily designed to use the **Master Chemical Mechanism** (MCM, https:https://mcm.york.ac.uk/MCM), but it can be used with any general set of chemical reactions as long as they are provided in the correct format. The MCM is a near-explicit chemical mechanism which describes the gas-phase oxidation of volatile organic compounds (VOC) in the lower atmosphere.
 
 AtChem2 is _open source_, under the [MIT license](https://opensource.org/licenses/MIT).
 
@@ -20,16 +20,16 @@ Directory structure
 - `model/` contains an example directory structure for the chemical mechanism, model configuration, constraints, output, and an example chemical mechanism (in FACSIMILE format). There can be several such directories (with different names).
 - `obj/` contains the files generated by the Fortran compiler.
 - `src/` contains the Fortran source files.
-- `tests/` contains the Test Suite scripts and files.
+- `tests/` contains the Testsuite scripts and files.
 - `tools/` contains shell scripts to install AtChem2 and its dependencies, plotting scripts in various languages, and other utilities.
 
 
 Installation, Setup and Execution
 ---------------------------------
 
-AtChem2 requires a **Fortran** compiler (GNU `gfortran` or Intel `ifort`), the **CVODE** (part of [SUNDIALS](https://computing.llnl.gov/projects/sundials)) and **openlibm** libraries, **make**, and **Python**. Compilation of CVODE also requires **cmake**. Optionally, **numdiff**, **FRUIT**, and **Ruby** are required to run the Test Suite. AtChem2 compiles and runs on Unix/Linux and macOS systems. 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](https://computing.llnl.gov/projects/sundials)) and **openlibm** libraries, **make**, and **Python**. Compilation of CVODE also requires **cmake**. Optionally, **numdiff**, **FRUIT**, and **Ruby** are required to run the Testsuite. AtChem2 compiles and runs on Unix/Linux and macOS systems. A working knowledge of the **unix shell** is required to install and use AtChem2.
 
-The latest stable version of AtChem2 can be downloaded from the [Releases page](https://github.com/AtChem/AtChem2/releases). 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 `CVODELIB`, `OPENLIBMDIR` and `FRUITDIR` in `Makefile` to the paths of CVODE, openlibm and (if installed) FRUIT. To compile the model using the example chemical mechanism, execute the command:
+The latest stable version of AtChem2 can be downloaded from the [Releases page](https://github.com/AtChem/AtChem2/releases). 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 `Makefile` to the paths of CVODE, openlibm and (if installed) FRUIT. To compile the model using the example chemical mechanism, execute the command:
 
 ```
 ./build/build_atchem2.sh ./model/mechanism.fac

build/build_atchem2.sh

@@ -10,29 +10,31 @@
 #
 # -----------------------------------------------------------------------------
 
+# -----------------------------------------------------------------------------
 # Script to process the mechanism file (*.fac) and convert it to the
 # correct format for AtChem2.
 #
-# N.B.: the script MUST be run from the base directory of AtChem2.
-#
 # $1 is the location of the chemical mechanism file in FACSIMILE
-# format. This argument is NOT optional, and there is no
-# default.
+# format. Argument $1 is NOT optional, and there is no default.
 #
 # $2 is the directory for the chemical mechanism in Fortran format:
 # - mechanism.species
 # - mechanism.reac
 # - mechanism.prod
 # - mechanism.ro2
 # - mechanism.f90
-# By default, it is ./model/configuration/
+# By default, argument $2 is: ./model/configuration/
 #
 # $3 is the directory of the MCM data files:
 # - list of organic peroxy radicals (RO2)
 # - parameters to calculate photolysis rates
-# By default, it is ./mcm/
+# By default, argument $3 is: ./mcm/
+#
+# Usage:
+# ./build/build_atchem2.sh /path/to/mechanism/file
+# ./build/build_atchem2.sh /path/to/mechanism/file /path/to/mechanism/directory
+# -----------------------------------------------------------------------------
 
-set -e
 echo ""
 echo "* facsimile mechanism file:" $1
 echo "* fortran mechanism directory [ default = ./model/configuration/ ]:" $2
@@ -54,7 +56,7 @@ else
 fi
 
 echo ""
-echo "make base executable"
+echo "make atchem2 executable"
 make
 
 exit 0