Version 122 (#496)

* Set version number to 1.2.2

* Error handling for install scripts

* Compile updated manual

* Format yml file

* Update changelog file

.github/workflows/ci.yml

@@ -11,7 +11,8 @@
 
 name: AtChem2-CI
 
-# Controls when the action will run.
+# ------------------------------ EVENTS ------------------------------ #
+# Controls when the action will run
 on:
   # Triggers the workflow on push or pull request events but only for the master branch
   pull_request:
@@ -25,31 +26,33 @@ on:
     branches:
       - master
 
-# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+# ------------------------------ JOBS ------------------------------ #
+# A workflow run consists of one or more jobs that can run sequentially or in parallel
 jobs:
-  # This workflow contains a single job called "build"
+  # This workflow contains a single job called `build`
   build:
-    # The type of runner that the job will run on - we use a matrix to run on two OSs
-    # runner images are described here: https://github.com/actions/runner-images
+    # Type of runner that the job will run on - we use a matrix to run on two OSs
+    # Runner images are described here: https://github.com/actions/runner-images
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
         os: [ubuntu-22.04, macos-11, macos-12]
         fortran: [9, 10, 11]
-        exclude:
+        exclude: #TODO: fortran9 does not work on macos12
         - os: macos-12
           fortran: 9
       fail-fast: false
 
+    # -------------------------------------------------------------
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
-      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      # Checkout the repository under $GITHUB_WORKSPACE, so the job can access it
       - uses: actions/checkout@v3
         with:
           fetch-depth: 2
 
       # -------------------------------------------------------------
-      # Install gfortran - if not supplied on this OS image
+      # Install gfortran - if not supplied on the OS image
       # macOS-11 only
       - name: Install gfortran-9 on macOS-11
         if: matrix.os == 'macos-11' && matrix.fortran == 9
@@ -93,7 +96,7 @@ jobs:
         run: |
           cp tools/install/Makefile.skel Makefile
           ./build/build_atchem2.sh ./model/mechanism.fac
-          if [ $RUNNER_OS != 'Linux' ] ; then
+          if [ $RUNNER_OS != "Linux" ] ; then
             install_name_tool -change libopenlibm.4.dylib $PWD/openlibm-0.8.1/libopenlibm.4.dylib atchem2 ;
             install_name_tool -change @rpath/libsundials_cvode.2.dylib $PWD/cvode/lib/libsundials_cvode.dylib atchem2 ;
             install_name_tool -change @rpath/libsundials_fnvecserial.2.dylib $PWD/cvode/lib/libsundials_fnvecserial.dylib atchem2 ;
@@ -111,8 +114,8 @@ jobs:
         run: |
           # Run Atchem2
           ./atchem2
-          # Upload 'build' coverage to codecov
-          if [[ "$RUNNER_OS" == "Linux" ]]; then sudo ln -f -s /usr/bin/gcov-${{ matrix.fortran }} /usr/bin/gcov ; bash <(curl -s https://codecov.io/bash) -F build ; fi
+          # Upload `build` coverage to codecov
+          if [[ $RUNNER_OS == "Linux" ]]; then sudo ln -f -s /usr/bin/gcov-${{ matrix.fortran }} /usr/bin/gcov ; bash <(curl -s https://codecov.io/bash) -F build ; fi
 
       # -------------------------------------------------------------
       - name: Run tests
@@ -123,9 +126,9 @@ jobs:
           # Run unit tests
           export PATH=$PATH:$PWD/numdiff/bin
           make unittests
-          # Upload 'unittests' coverage to codecov
-          if [[ "$RUNNER_OS" == "Linux" ]]; then sudo ln -f -s /usr/bin/gcov-${{ matrix.fortran }} /usr/bin/gcov ; bash <(curl -s https://codecov.io/bash) -F unittests ; fi
+          # Upload `unittests` coverage to codecov
+          if [[ $RUNNER_OS == "Linux" ]]; then sudo ln -f -s /usr/bin/gcov-${{ matrix.fortran }} /usr/bin/gcov ; bash <(curl -s https://codecov.io/bash) -F unittests ; fi
           make clean
-          # Run full build tests - this will upload 'tests' coverage to codecov for each test
+          # Run full build tests - this will upload `tests` coverage to codecov for each test
           make oldtests
-          #make modeltests
+          #make modeltests #TODO: modeltests are temporarily deactivated (pass on linux, fail on macos)

CHANGELOG.md

@@ -1,96 +1,102 @@
 # AtChem2 - CHANGELOG
 
-## post v1.2.1
+## v1.2.2 (May 2023)
 
-- move implementation of continuous integration from Travis CI to GitHub Actions
-- remove unit testing from CodeCov
-- optimisation of gfortran compiler
-- error handling for RO2 sum in `build/mech_converter.py`
-- disable (provisionally) support for LAPACK and BLAS
-- fix bug in input and output of constant photolysis rates
-- update the scripts in the `tools/` directory and the `.gitignore` files
-- move and rename the example mechanism `mcm/mechanism_test.fac` to `model/mechanism.fac`.
-- update the manual and the `*.md` files
-- improving logging and reporting of the Test Suite
-- new version of the Test Suite (work in progress...)
+- 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)
+- 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`
+- fix bug in the input and output of constant photolysis rates
+- add missing comments and tidy several fortran source files
+- fix error handling for the RO2 sum in `build/mech_converter.py`
+- update and tidy the `.py` and `.sh` scripts in the `tools/` directory
+- update `.gitignore` files, and remove the extension from the `LICENSE` file (per convention)
+- move and rename the example chemical mechanism file (`mcm/mechanism_test.fac`) to `model/mechanism.fac`
+- move and rename the script to generate the user manual (`doc/make_pdf.sh`) to `tools/make_manual_pdf.sh`
+- rename the versioning script `version.sh` to `update_version_number.sh`
+- 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)
 
-- new environment variable `ASA` (aerosol surface area)
-- fix bug in the C-binding for `gfortran` version 9 and above
-- remove tabs from the configuration files
-- update the Travis configuration file
+- add a new environment variable: `ASA` (aerosol surface area)
+- fix a bug in the C-binding for `gfortran` version 9 and above
+- remove tabs from all configuration files
+- update the configuration file for TravisCI
 - tidy the comments and printout messages of various source files
-- update the manual
+- update the user manual
 
 ## 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 to the `build/` directory
+- streamline the build procedure, rename and tidy the build scripts, and move them to the `build/` directory
 - implement the pre-compilation of the chemical mechanism into a shared library (`mechanism.so`)
-- implement the dilution mechanism and redefine the `DILUTE` environment variable
+- implement the dilution mechanism, and redefine the `DILUTE` environment variable accordingly
 - convert the documentation to LaTeX format
-- rewrite the user manual (`doc/AtChem2-Manual.pdf`) and reorganize the [wiki pages](https://github.com/AtChem/AtChem2/wiki)
-- add the poster presented at the ACM 2018 conference (`doc/AtChem_poster_ACM2018.pdf`)
-- change the reference in `CITATION.md` to the GMD paper (https://www.geosci-model-dev.net/13/169/2020/)
+- rewrite the user manual (`doc/AtChem2-Manual.pdf`), and reorganize the wiki pages
+- include the poster presented at the ACM 2018 conference (`doc/AtChem_poster_ACM2018.pdf`)
+- change the reference in `CITATION.md` to the [GMD paper](https://www.geosci-model-dev.net/13/169/2020/)
 - fix the header of `photolysisConstant.config` and remove the `initialConditionsSetting.output` file
 - fix a bug in `mech_converter.py` affecting chemical reactions with no reactants
-- change all Python scripts to be independent of the Python version
+- ensure that all Python scripts are independent of the Python version
 - rename plotting script `plot-atchem2.py` to `plot-atchem2-numpy.py`
 - new Python plotting script `plot-atchem2-pandas.py` (uses `pandas` instead of `numpy`)
 - improve the documentation of the behaviour and unit tests
-- remove the behaviour test `full`
+- remove the behaviour test `full` (fails with the new dilution mechanism)
 - new script to set the version of AtChem2 before a release (`tools/version.sh`)
-- minor improvements to the install procedure
-- move the example chemical mechanism file to the `mcm`/ directory, and add a minimal .fac file (`mechanism_skel.fac`)
+- minor improvements to the installation procedure
+- move the example chemical mechanism file (`tools/mechanism_test.fac`) and add a minimal `.fac` file (`mechanism_skel.fac`) to the `mcm`/ directory
 - tidy and improve comments in various source files and scripts
-- minor fixes and updates
+- various minor fixes and updates
 
 ## v1.1.1 (January 2019)
 
 - add `doc/` directory containing the documentation in markdown format
 - add `CONTRIBUTING.md` file
-- fix the header of `lossRates.output` and `productionRates.output`
-- change name of environment variable `ROOFOPEN` to `ROOF`
+- fix the headers of `lossRates.output` and `productionRates.output`
+- change the name of the environment variable `ROOFOPEN` to `ROOF`
 
 ## v1.1 (November 2018)
 
 - implement a new directory structure
-- rename some configuration and output files
 - add `CHANGELOG.md` and `CITATION.md` files
 - simplify the installation procedure and remove `makefile.local`
 - restructure the handling and calculation of photolysis rates
 - fix the calculations of sun declination and solar zenith angle
 - improve handling of dates and numerical precision
-- check calculation of reaction rates and improve format of `instantaneousRates` files (now called `reactionRates`)
+- rename some configuration and output files
+- check calculation of reaction rates and improve the format of `instantaneousRates/*` files (now called `reactionRates/*`)
 - merge `outputLossRates.config` and `outputProductionRates.config` into `outputRates.config`
 - fix the output of `lossRates.output` and `productionRates.output`
 - implement code coverage testing with [Codecov](https://codecov.io/)
 - implement a unit testing framework (new requirements: **Ruby**, **FRUIT**)
 - add unit tests for atmosphere, configuration, date and solar functions
-- add exact solution tests
+- add exact solution behaviour tests
 - improve running and reporting of the testsuite
-- rework mechanism conversion procedure and Python scripts
+- rework the mechanism conversion procedure, and the related Python scripts
 - add plotting tools in R, Python, Matlab, gnuplot
-- extend the documentation on the [wiki](https://github.com/AtChem/AtChem2/wiki)
+- extend the documentation on the wiki
 - fix several minor bugs
 
 ## v1.0 (July 2017)
 
-- create a code repository on [github.com](https://github.com/)
+- create a code repository and organization on [github.com](https://github.com/AtChem/)
 - adopt the [MIT open source license](https://opensource.org/licenses/MIT)
-- upgrade to **CVODE** version 2.9
+- upgrade to **CVODE v2.9**
 - remove the web interface and all the code related to [AtChem-online web service](https://atchem.leeds.ac.uk/)
-- standardize the codebase to Fortran95, use a consistent modular structure for the source code
+- standardize the codebase to Fortran95, and use a consistent modular structure for the source code
 - adopt coding style guidelines and standardize the naming of variables, subroutines, source files
-- improve formatting of output files, screen output and error reporting
+- improve the formatting of output files, screen output, and error reporting
 - improve code comments and create a [wiki](https://github.com/AtChem/AtChem2/wiki) for the documentation
-- tidy and speed up the Python and shell scripts
-- create a user-friendly command line interface to install, compile and run the model
-- verify that the model compiles with both **gfortran** and **Intel** compilers
-- verify that the model runs on Linux/Unix and macOS machines
+- tidy up and improve the Python and shell scripts
+- create a user-friendly command-line interface to install, compile and run the model
+- verify that the model compiles with both **GNU gfortran** and **Intel ifort** compilers
+- verify that the model runs on both Linux/Unix and macOS machines
 - implement continuous integration with [TravisCI](https://travis-ci.org/) and develop a range of test scenarios (new dependency: **numdiff**)
 - improve the model stability and numerical accuracy (new dependency: **openlibm**)
-- correct the calculations of solar angles, water vapour concentration and of the sum of organic peroxy radicals (`RO2`)
-- remove air number density (`M`) as environment variable
+- correct the calculations of solar angles, water vapour concentration and peroxy radicals summation (`RO2`)
+- remove air number density (`M`) as environment variable (now calculated in module `atmosphereFunctions`)
 - fix several minor bugs

README.md

@@ -1,6 +1,7 @@
 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)
 =======
 
+
 **AtChem2** is a modelling tool for atmospheric chemistry. It is primarily designed to use the **Master Chemical Mechanism** (MCM, http://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 _open source_, under the [MIT license](https://opensource.org/licenses/MIT).

doc/latex/AtChem2-Manual.tex

@@ -51,7 +51,7 @@
   \hspace{0.05\textwidth}
   % Box for the title page text
   \parbox[b]{0.75\textwidth}{
-    {\Huge\bfseries AtChem2\\[0.5\baselineskip] v1.3-dev}\\[2\baselineskip]  % Title
+    {\Huge\bfseries AtChem2\\[0.5\baselineskip] v1.2.2}\\[2\baselineskip]  % Title
     {\LARGE\textit{User Manual}}\\[4\baselineskip]  % Subtitle
     {\Large\textsc{R. Sommariva\\S. Cox}}  % Author(s)
     \vspace{0.5\textheight}\\

src/atchem2.f90

@@ -150,7 +150,7 @@ end subroutine FCVFUN
   rout(:) = -1.0_DP
   rpar(:) = -1.0_DP
 
-  write (*, '(A)') 'AtChem2 v1.3-dev'
+  write (*, '(A)') 'AtChem2 v1.2.2'
   write (*,*)
   write (*, '(A)') '-------------'
   write (*, '(A)') ' Directories'

tests/model_tests/env_model_1/env_model_1.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/model_tests/env_model_2/env_model_2.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/model_tests/env_model_3/env_model_3.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/model_tests/env_model_4/env_model_4.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/model_tests/firstorder/firstorder.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/model_tests/secondorder/secondorder.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/model_tests/static/static.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/tests/short/short.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/tests/short_dense/short_dense.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/tests/short_end_of_day/short_end_of_day.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/tests/short_ext1/short_ext1.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/tests/short_ext2/short_ext2.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/tests/short_ext3/short_ext3.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/tests/short_ext4/short_ext4.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/tests/short_no_pre/short_no_pre.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/tests/spec_no_env_yes1/spec_no_env_yes1.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/tests/spec_no_env_yes2/spec_no_env_yes2.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/tests/spec_yes_env_no/spec_yes_env_no.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/tests/spec_yes_env_no_with_jfac/spec_yes_env_no_with_jfac.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/tests/spec_yes_env_no_with_jfac_fail1/spec_yes_env_no_with_jfac_fail1.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/tests/spec_yes_env_no_with_jfac_fixed/spec_yes_env_no_with_jfac_fixed.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/tests/spec_yes_env_no_with_photo/spec_yes_env_no_with_photo.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories

tests/tests/spec_yes_env_yes/spec_yes_env_yes.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.3-dev
+AtChem2 v1.2.2
 
 -------------
  Directories