Prepare release v1.2 (#422)

* Remove unnecessary .gitignore files

* Move fix_indent.py and fix_style.py to tools/

* Fix indent and style scripts

* Update citation and readme files

* Remove unused printout message

* Update manual

* Update manual 2

* Update .md files

* Update version number

* Update changelog file

* Add footnote to manual

* Minor edits

CHANGELOG.md

@@ -1,5 +1,28 @@
 # AtChem2 - CHANGELOG
 
+## 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
+- implement the pre-compilation of the chemical mechanism into a shared library (`mechanism.so`)
+- implement the dilution mechanism and redefine the `DILUTE` environment variable
+- 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/)
+- 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
+- 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`
+- 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`)
+- tidy and improve comments of various source files and scripts
+- minor fixes and updates
+
 ## v1.1.1 (January 2019)
 
 - add `doc/` directory containing the documentation in markdown format

CITATION.md

@@ -1,17 +1,21 @@
-To reference **AtChem2** in publications, please cite:
+To reference **AtChem2** in publications, please cite the following paper:
 
 
-Sommariva, R.; Cox, S.; Martin, C.; Boronska, K.; Young, J.; Jimack, P.; Pilling, M. J.; Bloss, W. J.; Monks, P. S., Rickard, A. R.: *AtChem, an open source box-model for the Master Chemical Mechanism*, Atmospheric Chemical Mechanisms Conference, 5-7 December, UC-Davis, CA, USA (2018).
+R. Sommariva, S. Cox, C. Martin, K. Boronska, J. Young, P. K. Jimack, M. J. Pilling, V. N. Matthaios, B. S. Nelson, M. J. Newland, M. Panagi, W. J. Bloss, P. S. Monks, and A. R. Rickard.  
+**AtChem (version 1), an open-source box model for the Master Chemical Mechanism**.  
+_Geoscientific Model Development_, 13, 1, 169--183, 2020.
+doi: [10.5194/gmd-13-169-2020](https://doi.org/10.5194/gmd-13-169-2020).
 
 
-@conference{sommariva_acm2018,  
-author    = {Sommariva, R. and Cox, S. and Martin, C. and Boronska, K. and Young, J. and Jimack, P. and Pilling, M. J. and Bloss, W. J. and Monks, P. S. and Rickard, A. R.},  
-title     = {{AtChem}, an open source box-model for the {Master Chemical Mechanism}},  
-booktitle = {Atmospheric Chemical Mechanisms Conference},  
-date      = {5-7 December},  
-year      = {2018},  
-location  = {UC-Davis, CA, USA}  
+@article{sommariva_2020,  
+author  = {Sommariva, R. and Cox, S. and Martin, C. and Boro{\'n}ska, K. and Young, J. and
+           Jimack, P. K. and Pilling, M. J. and Matthaios, V. N. and Nelson, B. S. and
+           Newland, M. J. and Panagi, M. and Bloss, W. J. and Monks, P. S. and Rickard, A. R.},  
+title   = {{AtChem} (version 1), an open-source box model for the {Master Chemical Mechanism}},  
+journal = {Geoscientific Model Development},  
+year    = 2020,  
+volume  = 13,  
+number  = 1,  
+pages   = {169--183},  
+doi     = {10.5194/gmd-13-169-2020},  
 }
-
-
-A copy of the poster, which was presented at the [Atmospheric Chemical Mechanisms Conference 2018](https://acm.aqrc.ucdavis.edu/), can be found in the `doc/` directory.

CONTRIBUTING.md

@@ -1 +1 @@
-For instructions on how to contribute to the development of **AtChem2**, please refer to chapter 5 of the manual (in the `doc/` directory) and to the related [wiki page](https://github.com/AtChem/AtChem2/wiki/How-to-contribute).
+For instructions on how to contribute to the development of **AtChem2**, please refer to the user manual (`doc/AtChem2-Manual.pdf`) and to the related [wiki page](https://github.com/AtChem/AtChem2/wiki/How-to-contribute).

README.md

@@ -2,7 +2,7 @@ AtChem2  [![Build Status](https://travis-ci.org/AtChem/AtChem2.svg?branch=master
 =======
 
 
-**AtChem2** is an atmospheric chemistry box-model, primarily designed for use with the **Master Chemical Mechanism (MCM)**, a near-explicit chemical mechanism which describes the gas-phase oxidation of volatile organic compounds (VOC) in the lower atmosphere. The MCM can be found at http://mcm.york.ac.uk/ (previously at http://mcm.leeds.ac.uk/). The latest stable release of AtChem2 can be downloaded [here](https://github.com/AtChem/AtChem2/releases).
+**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 MCM is available at http://mcm.leeds.ac.uk/. The latest stable version of AtChem2 can be [downloaded here](https://github.com/AtChem/AtChem2/releases).
 
 AtChem2 is _open source_, under the [MIT license](https://opensource.org/licenses/MIT).
 
@@ -13,29 +13,29 @@ Directory structure
 -------------------
 
 - `build/` contains the Python and shell scripts used to compile AtChem2.
-- `doc/` contains the AtChem2 manual, with the LaTeX source files, and the poster presented at the [ACM 2018 conference](https://acm.aqrc.ucdavis.edu/).
-- `mcm/` contains data files related to specific versions of the MCM and an example chemical mechanism.
+- `doc/` contains the AtChem2 user manual, with the LaTeX source files, and the poster presented at the [ACM 2018 conference](https://acm.aqrc.ucdavis.edu/).
+- `mcm/` contains data files related to specific versions of the MCM and an example chemical mechanism (in FACSIMILE format).
 - `model/` contains the the chemical mechanism, and the model configuration, constraints and output.
-- `obj/` contains the files generated by the Fortran compiler.contains Python and shell scripts to install and compile AtChem2
+- `obj/` contains the files generated by the Fortran compiler.
 - `src/` contains the Fortran source files.
 - `tools/` contains shell scripts to install AtChem2 and its dependencies, plotting scripts in various languages, and other utilities.
-- `travis/` contains the _test suite_ scripts and files.
+- `travis/` contains the Test Suite scripts and files.
 
 
 Installation, Setup and Execution
 ---------------------------------
 
-AtChem2 requires a Fortran compiler (GNU `gfortran` or Intel `ifort`), the **CVODE** library (part of the [SUNDIALS suite](https://computing.llnl.gov/projects/sundials)), **openlibm** and **Python**. Compilation of CVODE also requires **cmake**, and the Fortran libraries **BLAS** and **LAPACK**. Optionally, **numdiff**, **FRUIT**, and **Ruby** are required to run the _test suite_.
+AtChem2 requires a Fortran compiler (GNU `gfortran` or Intel `ifort`), the **CVODE** library (part of [SUNDIALS](https://computing.llnl.gov/projects/sundials)), **openlibm** and **Python**. Compilation of CVODE also requires **cmake**, and the Fortran libraries **BLAS** and **LAPACK**. Optionally, **numdiff**, **FRUIT**, and **Ruby** are required to run the Test Suite.
 
-AtChem2 compiles and runs on Unix/Linux and macOS systems. From the main directory, copy and rename the file `tools/install/Makefile.skel` to `./Makefile`. Edit `./Makefile` to set the variables `CVODELIB`, `OPENLIBMDIR` and `FRUITDIR` to the paths of CVODE, openlibm and (if installed) FRUIT. A working knowledge of the unix shell is required to install and use AtChem2.
+AtChem2 compiles and runs on Unix/Linux and macOS systems. From the _Main Directory_, copy and rename the file `tools/install/Makefile.skel` to `./Makefile`. Edit `./Makefile` to set the variables `CVODELIB`, `OPENLIBMDIR` and `FRUITDIR` to the paths of CVODE, openlibm and (if installed) FRUIT. A working knowledge of the **unix shell** is required to install and use AtChem2.
 
-From the main directory, execute:
+From the _Main Directory_, execute the command:
 ```
-./build/build_atchem2.sh mcm/mechanism_test.fac model/configuration/ mcm/
+./build/build_atchem2.sh mcm/mechanism_test.fac
 ```
-to compile AtChem2 using the example chemical mechanism (in FACSIMILE format) and a default model configuration. The build script converts the chemical mechanism from the FACSIMILE format (`.fac`) to a Fortran compatible format and generates the shared library `mechanism.so` and other related files in the `model/configuration/` directory. At completion of the build process an executable file called `atchem2` is created in the main directory.
+to compile AtChem2 using the example chemical mechanism and the default model configuration. The build script converts the chemical mechanism from the FACSIMILE format (`.fac`) to a Fortran compatible format, and generates the shared library `mechanism.so` and other related files in the `model/configuration/` directory. At completion of the build process, an executable file called `atchem2` is created in the _Main Directory_.
 
-Set the initial conditions, the required outputs and the other model parameters by editing the files in the `model/configuration/` directory. If required, copy the constraints files into the relevant directory in `model/constraints/`. To run the model, execute:
+Set the initial conditions, the required outputs and the other model parameters by editing the files in the `model/configuration/` directory. If required, copy the constraint files to the relevant subdirectory in `model/constraints/`. To run the model, execute the command:
 ```./atchem2```
 
-The build script and the `atchem2` executable accept several command line arguments to customize the location of the configuration, input and output directories, and of the shared library. More information on AtChem2, and detailed instructions on its installation, configuration and use can be found in the manual (`doc/AtChem2-Manual.pdf`). A summary of the main commands and additional information is available on the [AtChem2 wiki](https://github.com/AtChem/AtChem2/wiki).
+The build script and the `atchem2` executable accept several command line arguments to customize the location of the configuration, input and output directories, and of the shared library. More information on AtChem2, and detailed instructions on its installation, configuration and use can be found in the manual (`doc/AtChem2-Manual.pdf`). A summary of the main commands, and additional information, is available on the [AtChem2 wiki](https://github.com/AtChem/AtChem2/wiki).

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.2-dev}\\[2\baselineskip]  % Title
+    {\Huge\bfseries AtChem2\\[0.5\baselineskip] v1.2}\\[2\baselineskip]  % Title
     {\LARGE\textit{User Manual}}\\[4\baselineskip]  % Subtitle
     {\Large\textsc{R. Sommariva\\S. Cox}}  % Author(s)
     \vspace{0.5\textheight}\\

doc/latex/Development.tex

@@ -191,16 +191,16 @@ \subsection{Adding new behaviour tests} \label{subsec:adding-new-behaviour-tests
 |  |  |- model.parameters
 |  |  |- outputSpecies.config
 |  |  |- outputRates.config
-|  |  |- photolysisConstant.config (*)
-|  |  |- photolysisConstrained.config (*)
+|  |  |- photolysisConstant.config    [*]
+|  |  |- photolysisConstrained.config [*]
 |  |  |- solver.parameters
-|  |  |- speciesConstrained.config (*)
-|  |  |- speciesConstant.config (*)
+|  |  |- speciesConstrained.config    [*]
+|  |  |- speciesConstant.config       [*]
 |  |  |- initialConcentrations.config
-|  |- constraints
-|     |- environment/ (**)
-|     |- photolysis/ (**)
-|     |- species/ (**)
+|  |- constraints     [**]
+|     |- environment/ [**]
+|     |- photolysis/  [**]
+|     |- species/     [**]
 |- output
 |  |- reactionRates/
 |  |- concentration.output.cmp
@@ -217,19 +217,12 @@ \subsection{Adding new behaviour tests} \label{subsec:adding-new-behaviour-tests
 |- $TESTNAME.out.cmp
 \end{verbatim}
 
-The files marked with \texttt{(*)} and the directories marked with
-\texttt{(**)} are optional -- depending on the configuration used in
-the test. If present, the directories marked with \texttt{(**)} should
+The files marked with \texttt{[*]} and the directories marked with
+\texttt{[**]} are optional -- depending on the configuration used in
+the test. If present, the directories marked with \texttt{[**]} should
 contain the relevant constraint files, according to the corresponding
-configuration files in \texttt{model/configuration/}. In addition,
-these directories should contain a \texttt{.gitignore} file with the
-following content:
-\begin{verbatim}
-# Ignore nothing in this directory
-
-# Except this file
-!.gitignore
-\end{verbatim}
+configuration files in \texttt{model/configuration/} (see
+Sect.~\ref{sec:constraints} for details).
 
 The file \texttt{\$TESTNAME.out.cmp} should contain the exact copy of
 the expected terminal printout. Each behaviour test is briefly
@@ -254,12 +247,12 @@ \section{Style Guide} \label{sec:style-guide}
   at the indentation level of each line of code.
 \end{itemize}
 
-These scripts are in the \texttt{build/} directory and can be invoked
+These scripts are in the \texttt{tools/} directory and can be invoked
 from the \maindir\ with the following commands:
 
 \begin{verbatim}
-python build/fix_style.py src/filename.f90
-python build/fix_indent.py src/filename.f90
+python tools/fix_style.py src/filename.f90
+python tools/fix_indent.py src/filename.f90
 \end{verbatim}
 
 It is important to keep in mind that these scripts are \emph{not

doc/latex/Installation.tex

@@ -419,9 +419,11 @@ \subsection{The \texttt{doc/} and \texttt{tools/} directories} \label{subsec:doc
 Conference \citep{sommariva_2018} is also included
 (\texttt{AtChem\_poster\_ACM2018.pdf}).
 
-The \texttt{tools/} directory contains an auxiliary script
-(\texttt{version.sh}, used to update the version number of the model
-in each \hyperref[ch:development]{development cycle}) and the
+The \texttt{tools/} directory contains the script
+(\texttt{version.sh}, used to update the version number of AtChem2 in
+each \hyperref[ch:development]{development cycle}), two scripts to
+check and correct the Fortran code (\texttt{fix\_style.py} and
+\texttt{fix\_indent.py}, see Sect.~\ref{sec:style-guide}), and the
 following subdirectories:
 
 \begin{itemize}

doc/latex/Setup.tex

@@ -513,9 +513,16 @@ \subsection{DILUTE} \label{subsec:dilute}
 fixed value, the chemical mechanism is automatically modified during
 the \hyperref[subsec:build-process]{build process}: for each species
 in the chemical mechanism, a loss ``reaction'' is added to the
-mechanism with a ``rate coefficient'' equal to the dilution rate. For
-example, the following ``reactions'' are added to the ``Tropospheric
-O3-NOx cycle'' mechanism shown in Sect.~\ref{subsec:facsimile-format}:
+mechanism with a ``rate coefficient'' equal to the dilution
+rate~\footnote{The behaviour of \texttt{DILUTE} was changed with the
+  release of version 1.2 (May 2020). In previous versions of AtChem2,
+  the user had to manually add to the chemical mechanism a
+  ``reaction'' using \texttt{DILUTE} for each species for which
+  dilution was required; in addition, \texttt{DILUTE} could be
+  constrained. The new approach makes the use of \texttt{DILUTE} both
+  more intuitive and more accurate.}. For example, the following
+``reactions'' are added to the ``Tropospheric O3-NOx cycle'' mechanism
+shown in Sect.~\ref{subsec:facsimile-format}:
 
 \begin{verbatim}
 % DILUTE : NO2 = ;

src/atchem2.f90

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

travis/run_indent_test.sh

@@ -19,7 +19,7 @@ RESULTS_FILE=travis/tests/testsuite.log
 echo "Running indent script on:"
 for file in src/*.f90 ; do
   echo $file
-  python ./build/fix_indent.py $file $file.cmp &>/dev/null
+  python ./tools/fix_indent.py $file $file.cmp &>/dev/null
   this_indent_file_failures=$(diff -q $file $file.cmp)
   exitcode=$?
   rm $file.cmp

travis/run_style_test.sh

@@ -19,7 +19,7 @@ RESULTS_FILE=travis/tests/testsuite.log
 echo "Running style script on:"
 for file in src/*.f90 ; do
   echo $file
-  python ./build/fix_style.py $file $file.cmp &>/dev/null
+  python ./tools/fix_style.py $file $file.cmp &>/dev/null
   this_style_file_failures=$(diff -q $file $file.cmp)
   exitcode=$?
   rm $file.cmp

travis/run_tests.sh

@@ -208,28 +208,10 @@ done
 if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then bash <(curl -s https://codecov.io/bash) -F tests ; fi
 
 # After all tests are run, exit with a FAIL if $fail_counter>0, otherwise PASS.
-if [[ "$style_test_passed" -gt 0 ]]; then
-  echo "Style test       FAILED"
-else
-  echo "Style test       PASSED"
-fi
-if [[ "$indent_test_passed" -gt 0 ]]; then
-  echo "Indent test      FAILED"
-else
-  echo "Indent test      PASSED"
-fi
 if [[ "$fail_counter" -gt 0 ]]; then
   echo "Tests            FAILED"
   echo "$fail_counter/$test_counter tests FAILED"
 else
   echo "Tests            PASSED"
   echo "  ($test_counter/$test_counter tests PASSED)"
 fi
-if [[ "$style_test_passed" -gt 0 ]] || [[ "$indent_test_passed" -gt 0 ]] || [[ "$fail_counter" -gt 0 ]]; then
-  echo "Testsuite FAILED"
-  echo "The diff is in $RESULTS_FILE"
-  exit 1
-else
-  echo "Testsuite PASSED"
-  exit 0
-fi ;

travis/tests/.gitignore

@@ -1,14 +1,14 @@
-# Ignore output files from test runs
+# Ignore output/log files and mechanism files of the test runs
 *.output
 *.out
 */output/reactionRates/*
-*/model/configuration/mechanism.prod
-*/model/configuration/mechanism.reac
-*/model/configuration/mechanism.ro2
-*/model/configuration/mechanism.species
-*/model/configuration/mechanism.f90
-*/model/configuration/mechanism.o
-*/model/configuration/mechanism.so
+mechanism.prod
+mechanism.reac
+mechanism.ro2
+mechanism.species
+mechanism.f90
+mechanism.o
+mechanism.so
 testsuite.log
 
 # Except configuration and reference files

travis/tests/firstorder/firstorder.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.2-dev
+AtChem2 v1.2
 
 -------------
  Directories

travis/tests/secondorder/secondorder.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.2-dev
+AtChem2 v1.2
 
 -------------
  Directories

travis/tests/short/short.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.2-dev
+AtChem2 v1.2
 
 -------------
  Directories

travis/tests/short_dense/short_dense.out.cmp

@@ -1,4 +1,4 @@
-AtChem2 v1.2-dev
+AtChem2 v1.2
 
 -------------
  Directories