Revision of the manual

.github/workflows/ci.yml

@@ -9,16 +9,17 @@
 #
 # -----------------------------------------------------------------------------
 
-# Workflow for continuous integration (CI) of AtChem2,
-# using Github Actions and Codecov
+# Workflow for the continuous integration (CI) of AtChem2, using
+# Github Actions and Codecov
 #
 # Acknowledgements: J. Allsopp
-# ----------------------------------------------------- #
+# -------------------------------------------------------------------- #
 name: AtChem2 CI
 
 # ------------------------------ EVENTS ------------------------------ #
 # Controls when the workflow is activated
 on:
+
   # Triggers when a pull request is created or updated (only on the
   # master branch)
   pull_request:
@@ -27,58 +28,64 @@ on:
   # Triggers when a push is made to the master branch (either by
   # merging a pull request, or by direct commit)
   push:
-    branches:
-      - master
+    branches: [ master ]
 
   # Run manually from the Actions tab
   workflow_dispatch:
 
 # ------------------------------ JOBS ------------------------------ #
-# This workflow contains a single job called `testing`, which compiles
-# the AtChem2 model, runs the Testsuite, and checks the Testsuite code
-# coverage using Codecov
+# This workflow contains a single job called `ci_testing` which
+# compiles the AtChem2 model, runs the Testsuite, and checks the code
+# coverage using Codecov (https://app.codecov.io/gh/AtChem/AtChem2)
 jobs:
-  testing:
-    # The job runs on both linux (ubuntu) and macos runner images,
-    # with three versions of gnu fortran -- the runner images are
-    # described here: https://github.com/actions/runner-images
+  ci_testing:
+    # The job runs on two versions of linux (ubuntu) and macos runner
+    # images, with three versions of gnu fortran -- the runner images
+    # are described here: https://github.com/actions/runner-images
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-22.04, macos-12]
-        fortran: [9, 10, 11]
-        exclude: #TODO: fortran9 does not work on macos12
-        - os: macos-12
-          fortran: 9
+        os: [ubuntu-20.04, ubuntu-22.04] #, macos-12, macos-13]
+        fortran: [10, 11, 12]
+        exclude: # gfortran-11, gfortran-12 not available for ubuntu-20.04
+        - os: ubuntu-20.04
+          fortran: 11
+        - os: ubuntu-20.04
+          fortran: 12
       fail-fast: false
 
     # -------------------------------------------------------------
-    # Sequence of tasks to be executed as part of the `testing` job:
-    # 1. checkout the repository
-    # 2. install gfortran, AtChem2 dependencies
-    # 3. compile AtChem2
-    # 4. run all tests (indent, style, unit, model)
-    # 5. recompile AtChem2, run unit and model tests for Codecov
+    # Sequence of tasks to be executed as part of the `ci_testing` job:
+    # 1. Checkout the repository
+    # 2. Install gfortran, AtChem2 dependencies
+    # 3. Compile AtChem2
+    # 4. Run the Testsuite with default settings
+    # 5. Recompile AtChem2, run unit and model tests for Codecov
     steps:
 
       # -------------------------------------------------------------
       # (1) Checkout the repository under $GITHUB_WORKSPACE
-      - uses: actions/checkout@v4
+      - name: Checkout repo
+        uses: actions/checkout@v4 # https://github.com/marketplace/actions/checkout
         with:
           fetch-depth: 2
 
       # -------------------------------------------------------------
       # (2) Install gfortran, if not supplied with the runner image,
-      # and the AtChem2 dependencies (CVODE, openlibm, numdiff, FRUIT)
+      # and the AtChem2 dependencies: CVODE, openlibm, numdiff, FRUIT
+
+      # gfortran on ubuntu
+      # - name: Install gfortran-11 (ubuntu-20.04)
+      #   if: matrix.os == 'ubuntu-20.04' && matrix.fortran == 11
+      #   run: sudo apt-get install gfortran-11
 
-      # gfortran on macos-11
-      - name: Install gfortran-9 (macos-11)
-        if: matrix.os == 'macos-11' && matrix.fortran == 9
+      # gfortran on macos
+      - name: Install gfortran-10 (macos-12)
+        if: matrix.os == 'macos-12' && (matrix.fortran == 10) # || matrix.fortran == 11)
         run: brew install gcc@${{ matrix.fortran }}
 
-      # gfortran on macos-12
-      - name: Install gfortran-9 and gfortran-10 (macos-12)
-        if: matrix.os == 'macos-12' && (matrix.fortran == 9 || matrix.fortran == 10)
+      - name: Install gfortran-10 and gfortran-11 (macos-13)
+        if: matrix.os == 'macos-13' && (matrix.fortran == 10 || matrix.fortran == 11)
         run: brew install gcc@${{ matrix.fortran }}
 
       # AtChem2 dependencies
@@ -97,13 +104,13 @@ jobs:
       # -------------------------------------------------------------
       # (3) Compile AtChem2 using the standard compilation flags
       - name: Build AtChem2
-        # Set $FORT_VERSION for use with the `Makefile`, called from
-        # the `build_atchem2.sh` script
+        # Set $FORT_VERSION for use with the `Makefile`, which is
+        # called by the `build_atchem2.sh` script
         env:
           FORT_VERSION: ${{ matrix.fortran }}
         run: |
           cp tools/install/Makefile.skel Makefile
-          ./build/build_atchem2.sh ./model/mechanism.fac
+          ./build/build_atchem2.sh ./model/mechanism.fac ./model/configuration/ ./mcm/
 
           # macos only
           if [ $RUNNER_OS != "Linux" ] ; then
@@ -114,8 +121,8 @@ jobs:
           fi
 
       # -------------------------------------------------------------
-      # (4) Run all tests: indent, style, unit, model
-
+      # (4) Run the Testsuite using the standard compilation flags and
+      # default settings: indent, style, unit, model tests
       - name: Indent and Style tests
         run: |
           make indenttest
@@ -129,26 +136,27 @@ jobs:
           export PATH=$PATH:$PWD/numdiff/bin
           make unittests
           make oldtests    # NB: oldtests will eventually be merged into modeltests
-          #make modeltests  # NB: modeltests are temporarily deactivated (pass on linux, fail on macos)
+          #make modeltests  # TODO: temporarily deactivated (pass on linux, fail on macos)
 
       # -------------------------------------------------------------
-      # (5) Recompile AtChem2 using the code coverage flags, then
-      # upload the gcov files to Codecov
-
+      # (5) Recompile AtChem2 using the code coverage compilation
+      # flags, then upload the gcov files to Codecov
       - name: Unit and Model tests (x Codecov)
-        if: matrix.os == 'ubuntu-22.04' && matrix.fortran == 11
+        if: matrix.os == 'ubuntu-22.04' && matrix.fortran == 12
         # Set $FORT_VERSION for use with the `Makefile`
         env:
           FORT_VERSION: ${{ matrix.fortran }}
         run: |
           export PATH=$PATH:$PWD/numdiff/bin
           make clean
+          # unit tests
           make unittests CCOV=true
-          mv tests/unit_tests/*.gc* ./  # Needed to deal with gcc11 changing the way it handles gcda and gcna files
-          make modeltests CCOV=true     # Run only the new model Testsuite
+          mv tests/unit_tests/*.gc* ./  # for gcc>=11 handling of *.gcda, *.gcna files
+          # model tests
+          make modeltests CCOV=true     # run only the new Testsuite
 
-      - name: Upload coverage reports to Codecov
-        if: matrix.os == 'ubuntu-22.04' && matrix.fortran == 11
-        uses: codecov/codecov-action@v3
+      - name: Upload coverage reports to Codecov # TODO: update codecov action
+        if: matrix.os == 'ubuntu-22.04' && matrix.fortran == 12
+        uses: codecov/codecov-action@v3 # https://github.com/marketplace/actions/codecov
         with:
           gcov: true

.github/workflows/tex.yml

@@ -0,0 +1,88 @@
+# -----------------------------------------------------------------------------
+#
+# Copyright (c) 2017 Sam Cox, Roberto Sommariva
+#
+# This file is part of the AtChem2 software package.
+#
+# This file is covered by the MIT license which can be found in the file
+# LICENSE.md at the top level of the AtChem2 distribution.
+#
+# -----------------------------------------------------------------------------
+
+# Workflow to generate automatically the pdf file of the AtChem2 manual
+# -------------------------------------------------------------------- #
+name: AtChem2 PDF
+
+# ------------------------------ EVENTS ------------------------------ #
+# Controls when the workflow is activated
+on:
+
+  # Triggers when a pull request is created or updated (only on the
+  # master branch)
+  pull_request:
+    branches: [ master ]
+    paths:
+      - './doc/latex/*.tex'
+      - './doc/figures/*.svg'
+
+  # Triggers when a push is made to the master branch (either by
+  # merging a pull request, or by direct commit)
+  push:
+    branches: [ master ]
+
+# ------------------------------ JOBS ------------------------------ #
+# This workflow contains a single job called `pdf_manual` which sets
+# up a full TeXLive environment, compiles the latex source files, and
+# generates the pdf file of the manual
+jobs:
+  pdf_manual:
+    # The job runs on the latest version of linux (ubuntu)
+    runs-on: ubuntu-latest
+
+    steps:
+
+      # -------------------------------------------------------------
+      # 1. Checkout the repository from the branch associated with the
+      # current Pull Request
+      - name: Checkout repo
+        uses: actions/checkout@v4 # https://github.com/marketplace/actions/checkout
+        with:
+          fetch-depth: 2
+          ref: ${{ github.ref }}
+
+      # - name: Check Token Permissions
+      #   run: |
+      #     echo "Token Permissions: $(curl -sSL -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" https://api.github.com/repos/AtChem/AtChem2 | jq .permissions)"
+
+      # -------------------------------------------------------------
+      # 2. Setup TeXLive and Inkscape (v1.x), then run the script to
+      # generate the pdf file of the manual
+      - name: Setup TexLive and compile the manual
+        uses: xu-cheng/texlive-action@v2 # https://github.com/marketplace/actions/github-action-with-texlive
+        with:
+          scheme: full
+          run: |
+            # install inkscape
+            apk add inkscape
+            # run script to generate the pdf file
+            ./tools/make_manual_pdf.sh
+
+      - name: Upload pdf file as artifact
+        uses: actions/upload-artifact@v4 # https://github.com/marketplace/actions/upload-a-build-artifact
+        with:
+          name: AtChem2-Manual.pdf
+          path: doc/AtChem2-Manual.pdf
+
+      # -------------------------------------------------------------
+      # 3.
+      - name: Configure git
+        run: |
+          git config --local user.name "github-actions[bot]"
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Commit and Push
+        run: |
+          git add doc/AtChem2-Manual.pdf
+          git status
+          #git commit -m "Update AtChem2-Manual.pdf"
+          #git push origin HEAD:${{ github.ref }}

build/mech_converter.py

@@ -278,9 +278,6 @@ def convert_to_fortran(input_file, mech_dir, mcm_vers):
     # Check that each of the RO2s from 'Peroxy radicals' are present
     # in the RO2 reference list from the MCM. If not, print a warning
     # at the top of mechanism.f90 for each errant species.
-    #
-    # TODO: This will break the expected format when mechanism.f90 is
-    #       replaced by a parsable format
     print('looping over inputted RO2s')
 
     with open(os.path.join(mech_dir, 'mechanism.f90'), 'w') as mech_rates_file:

doc/.gitignore

@@ -0,0 +1,8 @@
+# Ignore latex auxiliary files and png images in this directory
+figures/*.png
+latex/*.aux
+latex/*.bbl
+latex/*.blg
+latex/*.log
+latex/*.out
+latex/*.toc

doc/latex/AtChem2-Manual.tex

@@ -11,11 +11,12 @@
 
 % -------------------- PREAMBLE -------------------- %
 \documentclass[11pt,a4paper]{report}
-\usepackage{helvet,graphicx,hyperref,color}
+\usepackage{helvet,graphicx,hyperref}
 \usepackage{fancyhdr,caption,natbib}
-\usepackage[nottoc]{tocbibind}
+\usepackage[dvipsnames]{xcolor}
 \usepackage[version=3]{mhchem}
 
+% page style
 \pagestyle{fancy}
 \setlength{\headheight}{13.6pt}
 \rhead{\leftmark}
@@ -24,9 +25,15 @@
 \renewcommand{\bibname}{References}
 \frenchspacing
 
+% links
+\hypersetup{colorlinks=true,
+  linkcolor=BrickRed,
+  citecolor=ForestGreen,
+  urlcolor=NavyBlue}
+
 % shortcuts
 \newcommand{\maindir}{\texttt{\em Main Directory}}
-\newcommand{\depdir}{\texttt{\em Dependency Directory}}
+\newcommand{\depdir}{\texttt{\em Dependencies Directory}}
 \newcommand{\sharedir}{\texttt{\em Shared Library Directory}}
 
 \newcommand{\degc}{^\circ\mathrm{C}}
@@ -73,5 +80,7 @@
 
 \bibliographystyle{abbrvnat}
 \bibliography{References}
+\addcontentsline{toc}{chapter}{References}
 
 \end{document}
+%    rates output and reaction rates output can't be zero in config

doc/latex/Credits.tex

@@ -27,8 +27,10 @@ \section{Credits} \label{sec:credits}
 
 \begin{itemize}
 \item James Allsopp
+\item Will Drysdale
 \item Maarten Fabr{\'e}
 \item Alfred Mayhew
+\item Killian Murphy
 \item Beth Nelson
 \item Mike Newland
 \item Marios Panagi
@@ -63,7 +65,6 @@ \section{Acknowledgements} \label{sec:acknowledgements}
 \item Nahid Chowdhury
 \item Stuart Lacy
 \item Vasilis Matthaios
-\item Killian Murphy
 \item Paul Monks
 \item Jon Wakelin
 \item Rob Woodward-Massey
@@ -79,7 +80,7 @@ \section{Funding} \label{sec:funding}
 Funding has been provided, at different stages, by:
 
 \begin{itemize}
-\item Eurochamp project: \url{https://www.eurochamp.org}.
+\item EUROCHAMP project: \url{https://www.eurochamp.org}.
 \item Met Office: \url{https://www.metoffice.gov.uk}.
 \item National Centre for Atmospheric Science (NCAS):\\ \url{https://www.ncas.ac.uk}.
 \item Natural Environment Research Council (NERC):\\ \url{https://nerc.ukri.org}.