Start version 1.3-dev (#445)

* New version number * Improve formatting * Minor updates to the manual
AtChem · Apr 2, 2021 · 37503ae · 37503ae
1 parent 9c06d09
commit 37503ae
Show file tree

Hide file tree

Showing 28 changed files with 99 additions and 70 deletions.
diff --git a/doc/AtChem2-Manual.pdf b/doc/AtChem2-Manual.pdf
diff --git a/doc/latex/AtChem2-Manual.tex b/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.1}\\[2\baselineskip]  % Title
+    {\Huge\bfseries AtChem2\\[0.5\baselineskip] v1.3-dev}\\[2\baselineskip]  % Title
     {\LARGE\textit{User Manual}}\\[4\baselineskip]  % Subtitle
     {\Large\textsc{R. Sommariva\\S. Cox}}  % Author(s)
     \vspace{0.5\textheight}\\

diff --git a/doc/latex/Development.tex b/doc/latex/Development.tex
@@ -63,7 +63,7 @@ \section{Test Suite} \label{sec:test-suite}
 the codebase ($>$90\%) and a wide range of common configurations.
 
 There are four types of tests, which can be executed from the
-\maindir\ using the \verb|make| command (note that the
+\maindir\ using the command \verb|make| (note that the
 \hyperref[subsec:optional-dependencies]{optional dependencies} need to
 be installed):
 

diff --git a/doc/latex/Execution.tex b/doc/latex/Execution.tex
@@ -110,7 +110,7 @@ \subsubsection{Chemical species}
 \subsubsection{Photolysis rates}
 
 Any photolysis rate in the chemical mechanism can be constrained. The
-photolysis rates are identified as \verb|J<i>|, where \texttt{i} is
+photolysis rates are identified as \texttt{J<i>}, where \texttt{i} is
 the ID number assigned by the MCM to each photolysis reaction
 (Sect.~\ref{sec:photolysis-rates}). To constrain a photolysis rate add
 its name to \texttt{photolysisConstrained.config} and create a file
@@ -122,11 +122,11 @@ \subsection{Constraint files} \label{subsec:constraint-files}
 
 The files with the constraint data are text files with two columns and
 no header: the first column is the time in seconds from midnight of
-the start date (Sect.~\ref{sec:model-parameters}), the second column
-is the value of the variable in the appropriate unit. For the chemical
-species the unit is molecule cm$^{-3}$ and for the photolysis rates
-the unit is s$^{-1}$; for the units of the environment variables, see
-Sect.~\ref{sec:environment-variables}. For example:
+the start date (in UTC, Sect.~\ref{sec:model-parameters}), the second
+column is the value of the variable in the appropriate unit. For the
+chemical species the unit is molecule cm$^{-3}$ and for the photolysis
+rates the unit is s$^{-1}$; for the units of the environment
+variables, see Sect.~\ref{sec:environment-variables}. For example:
 
 \begin{verbatim}
 -900   73.21
@@ -147,7 +147,8 @@ \subsection{Constraint files} \label{subsec:constraint-files}
 allow correct interpolation of the variables at the beginning of the
 model run. This is because the model constraints \emph{must cover} the
 same amount of time, or preferably more, as the intended model runtime
-(Sect.~\ref{subsec:interpolation}).
+to avoid interpolation errors -- see Sect.~\ref{subsec:interpolation}
+for details.
 
 For example: if the model starts at 41400 seconds (day 1 at 11:30) and
 stops at 225900 seconds (day 3 at 14:45), then the first and the last
@@ -186,20 +187,41 @@ \subsection{Interpolation} \label{subsec:interpolation}
 each of the constrained species.
 
 As mentioned in Sect.~\ref{subsec:constraint-files}, the model start
-and stop time \emph{must be} within the time interval of the
-constrained data to avoid interpolation errors or model crashes. If
-data is not supplied for the entire runtime interval, the final value
-of the constrained variable will be used for all times
+and stop times \emph{must be} within the time interval of all the
+constrained data to avoid interpolation errors or model crashes.
+
+\begin{verbatim}
+                  start            stop
+model run           |----------------|
+constraint 1    |---------------------------|
+constraint 2       |------------------|
+constraint 3     |-----------------------|
+\end{verbatim}
+
+If constrained data are not supplied for the entire runtime interval,
+the final value of the constrained variable will be used for all times
 \emph{before the first} data point and \emph{after the last} data
-point. If this situation occurs, a warning is printed to the terminal
-for all data evaluations outside of the supplied time
-interval~\footnote{This behaviour is likely to change in future
-  versions of AtChem2, at least to avoid the situation where the last
-  value is used for all times before the first data point (see issue
-  \href{https://github.com/AtChem/AtChem2/issues/294}{\#294}).}. In any
-case, and to avoid errors, it is good practice to always provide
-constraint data that include a short period before the start time and
-a short period after the stop time.
+point. When this situation occurs, a warning is printed to the
+terminal for all data evaluations outside of the supplied time
+interval:
+
+\begin{verbatim}
+ error in piecewise linear interpolation
+  4.3205895E+05 720  3.0000000E+04
+ error in piecewise linear interpolation
+  4.3205895E+05 720  0.0000000E+00
+\end{verbatim}
+
+Changing the \textbf{model start time} and/or the \textbf{number of steps}
+in the \texttt{model.parameters} file (Sect.~\ref{sec:model-parameters})
+is usually enough to solve the problem~\footnote{This behaviour is
+  likely to change in future versions of AtChem2, at least to avoid
+  the situation where the last value is used for all times before the
+  first data point (see issue
+  \href{https://github.com/AtChem/AtChem2/issues/294}{\#294}).}.
+In any case, and to avoid errors, it is good practice to always
+provide constraint data that include a short period before the start
+time and a short period after the stop time.
 
 % -------------------------------------------------------------------- %
 \section{Build} \label{sec:build}
@@ -298,7 +320,7 @@ \section{Build} \label{sec:build}
 which case the model needs to be recompiled. If the \texttt{.fac} file
 has also been changed, the \texttt{build\_atchem2.sh} script must be
 used; otherwise -- if only the Fortran code has been changed --
-executing the \verb|make| command from the \maindir\ is enough to
+executing the command \verb|make| from the \maindir\ is enough to
 recompile the model.
 
 % -------------------------------------------------------------------- %

diff --git a/doc/latex/Installation.tex b/doc/latex/Installation.tex
@@ -27,7 +27,7 @@ \section{Requirements} \label{sec:requirements}
 \item Python~\footnote{All Python scripts used in AtChem2 work equally
   with Python v2 and v3. Support for Python v2 will be removed in
   future versions of AtChem2.}
-\item make and cmake
+\item make, cmake
 \item Ruby (optional)
 \end{itemize}
 
@@ -38,7 +38,7 @@ \section{Requirements} \label{sec:requirements}
 AtChem2 has the following dependencies:
 
 \begin{itemize}
-\item BLAS and LAPACK
+\item BLAS, LAPACK
 \item CVODE
 \item openlibm
 \item numdiff (optional)
@@ -58,15 +58,19 @@ \section{Download} \label{sec:download}
 be obtained in two ways:
 
 \begin{itemize}
-\item with \textbf{git}:
+\item with \textbf{git} (This method will download the development
+  version and it is recommended if you want to contribute to the model
+  development):
   \begin{enumerate}
   \item Open the terminal. Move to the directory where you want to
     install AtChem2.
-  \item Execute \verb|git clone https://github.com/AtChem/AtChem2.git|
-    (if using HTTPS) or \verb|git clone [email protected]:AtChem/AtChem2.git|
-    (if using SSH). This method will download the development version
-    and it is recommended if you want to contribute to the model
-    development.
+  \item Execute:
+    \begin{itemize}
+      \item if using HTTPS:\\
+        \verb|git clone https://github.com/AtChem/AtChem2.git|
+      \item if using SSH:\\
+        \verb|git clone [email protected]:AtChem/AtChem2.git|
+    \end{itemize}
   \end{enumerate}
 \item with the \textbf{archive file}:
   \begin{enumerate}
@@ -362,11 +366,12 @@ \section{Model Structure} \label{sec:model-structure}
 
 \begin{table}[htb]
   \centering \scriptsize
-  \caption{Directory structure of AtChem2. ``Original'' refers to version 1.0 and earlier
-    (including AtChem-online); ``New'' refers to version 1.1 and later.}
+  \caption{Directory structure of AtChem2.\\
+    $(\dag)$ Not present in AtChem-online\\
+    $(\ddag)$ Called \texttt{travis/} in versions 1.1.* and 1.2.*}
   \label{tab:atchem-dirs}
   \begin{tabular}{llp{3.7cm}}
-    Original & New & Description\\
+    Version 1.0 and earlier & Version 1.1 and later & Description\\
     \hline
     --                               & \texttt{build/}                         & scripts to build the model.\\
     \hline
@@ -392,15 +397,16 @@ \section{Model Structure} \label{sec:model-structure}
     \hline
     \texttt{tools/}                  & \texttt{tools/}                         & various scripts and plotting tools.\\
     \hline
-    \texttt{travis/}                 & \texttt{travis/}                        & scripts and files for the Test Suite.\\
+    \texttt{travis/}~$(\dag)$        & \texttt{test/}~$(\ddag)$                & scripts and files for the Test Suite.\\
   \end{tabular}
 \end{table}
 
 In AtChem2 version 1.1 (and later versions) the directories
 \texttt{build/}, \texttt{mcm/}, \texttt{obj/} and \texttt{src/}
 contain the build scripts, the MCM data files, the files generated by
-the compiler, the source code; the directory \texttt{travis/} contains
-the files and the scripts necessary to run the
+the compiler, the source code; the directory
+\texttt{test/}~\footnote{Called \texttt{travis/} in version 1.2 and
+  earlier.} contains the files and the scripts necessary to run the
 \hyperref[sec:test-suite]{Test Suite}.
 
 For the majority of the users, the most important directories are

diff --git a/doc/latex/Setup.tex b/doc/latex/Setup.tex
@@ -281,8 +281,9 @@ \subsection{The build process} \label{subsec:build-process}
   radical (from \texttt{mechanism.species}), the second column is the
   name of the peroxy radical as a Fortran comment:
   \begin{verbatim}
-  ! Note that this file is automatically generated by build/mech_converter.py --
-    Any manual edits to this file will be overwritten when calling build/mech_converter.py
+  ! Note that this file is automatically generated by
+    build/mech_converter.py -- Any manual edits to this file
+    will be overwritten when calling build/mech_converter.py
   23 !CH3O2
   26 !C2H5O2
   28 !IC3H7O2
@@ -341,8 +342,7 @@ \section{Model Parameters} \label{sec:model-parameters}
   \emph{N.B.}: when one or more variables are constrained, the time
   interval between the model start time and the model stop time
   \emph{must be} equal to or less than the time interval of the
-  constrained data -- see Sect.~\ref{subsec:constraint-files} and
-  Sect.~\ref{subsec:interpolation} for details.
+  constrained data -- see Sect.~\ref{subsec:interpolation} for details.
 \item \textbf{jacobian output step size}. Frequency (in seconds) of
   the model output of the Jacobian matrix. If this parameter is set to
   \texttt{0} (default option), the Jacobian matrix is not output.
@@ -497,9 +497,9 @@ \subsection{BLHEIGHT} \label{subsec:blheight}
 
 Boundary Layer Height. It is required only if the model includes
 non-chemical processes, such as emission or deposition of chemical
-species. The unit is usually centimetre or metre, depending on how
-these processes are parametrized in the chemical mechanism -- go to
-Sect.~\ref{subsec:facsimile-format} for details.
+species. The unit is usually centimetre (cm) or metre (m), depending
+on how these processes are parametrized in the chemical mechanism --
+go to Sect.~\ref{subsec:facsimile-format} for details.
 
 \begin{itemize}
 \item fixed value
@@ -512,8 +512,9 @@ \subsection{BLHEIGHT} \label{subsec:blheight}
 \subsection{ASA} \label{subsec:asa}
 
 Aerosol Surface Area. It is required only if the model includes
-heterogeneous chemical reactions. The unit is area (cm$^2$,
-$\mu$m$^2$ or nm$^2$) per cm$^3$.
+heterogeneous chemical reactions. The unit is area (cm$^2$, $\mu$m$^2$
+or nm$^2$) per cm$^3$, depending on how these reactions are
+implemented in the chemical mechanism.
 
 \begin{itemize}
 \item fixed value
@@ -599,7 +600,7 @@ \section{Photolysis Rates} \label{sec:photolysis-rates}
 The photolysis rates are the rate coefficients of the photolysis
 reactions, and are identified in FACSIMILE
 \hyperref[subsec:facsimile-format]{format} with the notation
-\verb|J<i>| -- where \texttt{i} is the ID number assigned by the MCM
+\texttt{J<i>} -- where \texttt{i} is the ID number assigned by the MCM
 to each photolysis reaction (or to a group of photolysis
 reactions). AtChem2 implements the MCM parametrization
 (Sect.~\ref{subsec:calculated-photolysis-rates}) to calculate the

diff --git a/src/atchem2.f90 b/src/atchem2.f90
@@ -150,7 +150,7 @@ end subroutine FCVFUN
   rout(:) = -1.0_DP
   rpar(:) = -1.0_DP
 
-  write (*, '(A)') 'AtChem2 v1.2.1'
+  write (*, '(A)') 'AtChem2 v1.3-dev'
   write (*,*)
   write (*, '(A)') '-------------'
   write (*, '(A)') ' Directories'

diff --git a/test/tests/firstorder/firstorder.out.cmp b/test/tests/firstorder/firstorder.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/test/tests/secondorder/secondorder.out.cmp b/test/tests/secondorder/secondorder.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/test/tests/short/short.out.cmp b/test/tests/short/short.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/test/tests/short_dense/short_dense.out.cmp b/test/tests/short_dense/short_dense.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/test/tests/short_end_of_day/short_end_of_day.out.cmp b/test/tests/short_end_of_day/short_end_of_day.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/test/tests/short_ext1/short_ext1.out.cmp b/test/tests/short_ext1/short_ext1.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/test/tests/short_ext2/short_ext2.out.cmp b/test/tests/short_ext2/short_ext2.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/test/tests/short_ext3/short_ext3.out.cmp b/test/tests/short_ext3/short_ext3.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/test/tests/short_ext4/short_ext4.out.cmp b/test/tests/short_ext4/short_ext4.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/test/tests/short_no_pre/short_no_pre.out.cmp b/test/tests/short_no_pre/short_no_pre.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/test/tests/spec_no_env_yes1/spec_no_env_yes1.out.cmp b/test/tests/spec_no_env_yes1/spec_no_env_yes1.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/test/tests/spec_no_env_yes2/spec_no_env_yes2.out.cmp b/test/tests/spec_no_env_yes2/spec_no_env_yes2.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/test/tests/spec_yes_env_no/spec_yes_env_no.out.cmp b/test/tests/spec_yes_env_no/spec_yes_env_no.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/test/tests/spec_yes_env_no_with_jfac/spec_yes_env_no_with_jfac.out.cmp b/test/tests/spec_yes_env_no_with_jfac/spec_yes_env_no_with_jfac.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/test/tests/spec_yes_env_no_with_jfac_fail1/spec_yes_env_no_with_jfac_fail1.out.cmp b/test/tests/spec_yes_env_no_with_jfac_fail1/spec_yes_env_no_with_jfac_fail1.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/test/tests/spec_yes_env_no_with_jfac_fixed/spec_yes_env_no_with_jfac_fixed.out.cmp b/test/tests/spec_yes_env_no_with_jfac_fixed/spec_yes_env_no_with_jfac_fixed.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/test/tests/spec_yes_env_no_with_photo/spec_yes_env_no_with_photo.out.cmp b/test/tests/spec_yes_env_no_with_photo/spec_yes_env_no_with_photo.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/test/tests/spec_yes_env_yes/spec_yes_env_yes.out.cmp b/test/tests/spec_yes_env_yes/spec_yes_env_yes.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/test/tests/spec_yes_plus_fixed_env_no/spec_yes_plus_fixed_env_no.out.cmp b/test/tests/spec_yes_plus_fixed_env_no/spec_yes_plus_fixed_env_no.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/test/tests/static/static.out.cmp b/test/tests/static/static.out.cmp
@@ -1,4 +1,4 @@
-AtChem2 v1.2.1
+AtChem2 v1.3-dev
 
 -------------
  Directories

diff --git a/tools/version.sh b/tools/version.sh
@@ -14,8 +14,8 @@
 #
 # N.B.: the script MUST be run from the main directory of AtChem2.
 
-VERS_OLD="v1.3-dev"
-VERS_NEW="v1.2.1"
+VERS_OLD="v1.2.1"
+VERS_NEW="v1.3-dev"
 
 find ./ -type f ! -name "version.sh" -print | xargs perl -pi -e "s/$VERS_OLD/$VERS_NEW/g"