Skip to content

Commit

Permalink
Edit setup and installation sections
Browse files Browse the repository at this point in the history
  • Loading branch information
@rs028
rs028 committed Oct 3, 2019
1 parent 7b83f40 commit 1bcba15
Show file tree
Hide file tree
Showing 3 changed files with 63 additions and 85 deletions.
5 changes: 3 additions & 2 deletions doc/latex/AtChem2-Manual.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,9 @@
\frenchspacing

% shortcuts
\newcommand{\maindir}{\texttt{Main Directory}}
\newcommand{\depdir}{\texttt{Dependency Directory}}
\newcommand{\maindir}{\texttt{\em Main Directory}}
\newcommand{\depdir}{\texttt{\em Dependency Directory}}
\newcommand{\sharedir}{\texttt{\em Shared Library Directory}}

% -------------------- DOCUMENT -------------------- %
\begin{document}
Expand Down
35 changes: 17 additions & 18 deletions doc/latex/Installation.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -338,19 +338,19 @@ \section{Model Structure} \label{sec:model-structure}
the new directory structure and, for reference, the original one.

\begin{table}[htb]
\centering \footnotesize
\centering \scriptsize
\caption{Directory structure of AtChem2. ``Original'' refers to version 1.0 and earlier;
``New'' refers to version 1.1 and later.} \label{tab:atchem-structure}
\begin{tabular}{llp{3cm}}
\begin{tabular}{llp{3.7cm}}
Original & New & Description\\
\hline
-- & \texttt{build/} & scripts to compile the model.\\
-- & \texttt{build/} & scripts to build the model.\\
\hline
-- & \texttt{doc/} & user manual and other documentation.\\
\hline
-- & \texttt{mcm/} & MCM data files and example chemical mechanism.\\
\hline
\texttt{modelConfiguration/} & \texttt{model/configuration/} & model and solver configuration files.\\
\texttt{modelConfiguration/} & \texttt{model/configuration/} & chemical mechanism, shared library, model and solver configuration files.\\
\hline
\texttt{speciesConstraints/} & \texttt{model/constraints/species/} & model constraints: chemical species.\\
\hline
Expand All @@ -360,7 +360,7 @@ \section{Model Structure} \label{sec:model-structure}
\hline
\texttt{modelOutput/} & \texttt{model/output/} & model output: chemical species, photolysis rates, environment variables, diagnostic variables.\\
\hline
\texttt{instantaneousRates/} & \texttt{model/output/reactionRates/} & model output: reaction rates of every reaction.\\
\texttt{instantaneousRates/} & \texttt{model/output/reactionRates/} & model output: reaction rates for every reaction of the chemical mechanism.\\
\hline
\texttt{obj/} & \texttt{obj/} & files generated by the Fortran compiler.\\
\hline
Expand Down Expand Up @@ -428,13 +428,13 @@ \subsection{The doc/ and tools/ directories} \label{subsec:doc-tools-directories
To run a plotting script, open the terminal and execute one of the
following commands from the \maindir:

\begin{verbatim}
gnuplot -c tools/plot/plot-atchem2.gp model/output/
octave tools/plot/plot-atchem2.m model/output/
python2 tools/plot/plot-atchem2_v2.py model/output/
python3 tools/plot/plot-atchem2_v3.py model/output/
Rscript --vanilla tools/plot/plot-atchem2.r model/output/
\end{verbatim}
\begin{itemize}
\item \verb|gnuplot -c tools/plot/plot-atchem2.gp model/output/|
\item \verb|octave tools/plot/plot-atchem2.m model/output/|
\item \verb|python2 tools/plot/plot-atchem2_v2.py model/output/|
\item \verb|python3 tools/plot/plot-atchem2_v3.py model/output/|
\item \verb|Rscript --vanilla tools/plot/plot-atchem2.r model/output/|
\end{itemize}

\subsection{The model/ directory} \label{subsec:model-directory}

Expand All @@ -448,12 +448,11 @@ \subsection{The model/ directory} \label{subsec:model-directory}
(see Sect.~\ref{subsec:build-process}).

The \texttt{model/} directory can be given any name and can be located
outside of the \maindir. Moreover, there can be multiple
\texttt{model/} directories (with different names) in the same
location. The paths to the required \texttt{model/} directory and/or
chemical mechanism file are given as an argument to the build script
and to the \texttt{atchem2} executable, as explained in
Sect.~\ref{sec:build}.
outside the \maindir. Moreover, there can be multiple \texttt{model/}
directories (with different names) in the same location. The paths to
the required \texttt{model/} directory and/or chemical mechanism file
are given as an argument to the build script and to the
\texttt{atchem2} executable, as explained in Sect.~\ref{sec:build}.

This approach gives the user the flexibility to run different versions
of the same model (in terms of configuration and/or chemical
Expand Down
108 changes: 43 additions & 65 deletions doc/latex/Setup.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,16 +14,16 @@ \chapter{Model Setup} \label{ch:setup}
% -------------------------------------------------------------------- %
\section{Chemical Mechanism} \label{sec:chemical-mechanism}

The \textbf{chemical mechanism} is the core element of an atmospheric
chemistry model. In AtChem2, the mechanism file is written in
FACSIMILE format and has the extension \texttt{.fac}. The FACSIMILE
format is used to describe chemical reactions in the commercial
The chemical mechanism is the core element of an atmospheric chemistry
model. In AtChem2, the mechanism file is written in FACSIMILE format
and has the extension \texttt{.fac}. The FACSIMILE format is used to
describe chemical reactions in the commercial
\href{https://www.mcpa-software.com/}{FACSIMILE Kinetic Modelling Software};
for historical reasons, the software and the format have been often
used in conjunction with the MCM. The
for historical reasons, the software and the format have been
often used in conjunction with the MCM. The
\href{https://mcm.leeds.ac.uk/MCM/extract.htt}{extraction tool} on the
MCM website can generate \texttt{.fac} files directly in FACSIMILE
format (see Sect.~\ref{subsec:mcm-extraction-tool}).
format (see Sect.~\ref{subsec:mcm-extraction}).

\subsection{FACSIMILE format} \label{subsec:facsimile-format}

Expand All @@ -47,7 +47,7 @@ \subsection{FACSIMILE format} \label{subsec:facsimile-format}
\end{verbatim}

The mechanism file is processed by a Python script (\texttt{mech\_converter.py}),
as explained in Sect.~\ref{subsec:build-process}. Note, that the Python script
as explained in Sect.~\ref{subsec:build-process}. Note that the Python script
expects the \texttt{.fac} file to have four sections:

\begin{itemize}
Expand Down Expand Up @@ -81,7 +81,7 @@ \subsection{FACSIMILE format} \label{subsec:facsimile-format}
the \texttt{mcm/} directory (\texttt{mechanism\_test.fac}) as an
example and for testing purposes.

\subsection{\cf{RO2} sum} \label{subsec:ro2-sum}
\subsection{The \cf{RO2} sum} \label{subsec:ro2-sum}

The sum of organic peroxy radicals (\cf{RO2}) is a key component of
the Master Chemical Mechanism: its purpose is to reduce the number of
Expand Down Expand Up @@ -122,7 +122,7 @@ \subsection{\cf{RO2} sum} \label{subsec:ro2-sum}
instructions on how to set up Atchem2 to use the previous versions of
the MCM can be found in the file \texttt{mcm/INFO.md}.

\subsection{MCM extraction tool} \label{subsec:mcm-extraction-tool}
\subsection{MCM extraction} \label{subsec:mcm-extraction}

The MCM website provides a convenient tool that can be used to
download the whole MCM (or subsets of it) in FACSIMILE
Expand All @@ -139,7 +139,8 @@ \subsection{MCM extraction tool} \label{subsec:mcm-extraction-tool}

\begin{verbatim}
[x] Include inorganic reactions?
[x] Include generic rate coefficients? FACSIMILE, FORTRAN and KPP formats only
[x] Include generic rate coefficients?
FACSIMILE, FORTRAN and KPP formats only
\end{verbatim}

Click on \emph{Extract} to download the generated \texttt{.fac} file
Expand All @@ -150,7 +151,7 @@ \subsection{MCM extraction tool} \label{subsec:mcm-extraction-tool}
delete, or change some chemical reactions) open the \texttt{.fac} file
with a text editor and edit the chemical mechanism as needed.

\subsection{Build process} \label{subsec:build-process}
\subsection{The build process} \label{subsec:build-process}

AtChem2 is built using the set of scripts in the \texttt{build/}
directory. Here, we only outline the build process; detailed
Expand All @@ -160,85 +161,62 @@ \subsection{Build process} \label{subsec:build-process}
The Python script \texttt{mech\_converter.py}, which is automatically
called by the \texttt{build\_atchem2.sh} script, converts the chemical
mechanism into a format that can be read by the Fortran code (see
Sect.~\ref{subsec:facsimile-format}). The Python script generates
seven files from the \texttt{.fac} file:
Sect.~\ref{subsec:facsimile-format}). The Python script generates a
number of files from the chemical mechanism (\texttt{.fac}) file:

\begin{itemize}
\item \textbf{mechanism.f90} contains the equations, in Fortran code,
to calculate the rate coefficients of each reaction. By default, it
is placed in \texttt{model/configuration/}.
\item \textbf{mechanism.so} is the compiled version of
\texttt{mechanism.f90}. By default, it is placed in
\texttt{model/configuration/}.
\item \textbf{mechanism.species} contains the list of chemical species
in the mechanism. By default, it is saved in
\texttt{model/configuration/}. The file has no header. The first
column is the \emph{ID number} of each species, the second column is
the name of the species:
\item \texttt{mechanism.f90} contains the equations, in Fortran code,
to calculate the rate coefficients of each reaction of the chemical
mechanism.
\item \texttt{mechanism.so} is the shared library, i.e. the
pre-compiled version of the chemical mechanism.
\item \texttt{mechanism.species} contains the list of chemical species
in the chemical mechanism. The file has no header. The first column
is the \emph{ID number} of the species, the second column is the
name of the species:
\begin{verbatim}
1 O
2 O3
3 NO
4 NO2
\end{verbatim}
\item \textbf{mechanism.reac} and \textbf{mechanism.prod} contain the
\end{verbatim}
\item \texttt{mechanism.reac} and \texttt{mechanism.prod} contain the
reactants and the products (respectively) in each reaction of the
mechanism. By default, it is saved in \texttt{model/configuration/}.
The files have a 1 line header with the number of species, the
number of reactions and the number of equations in the Generic Rate
Coefficients and Complex Reactions sections. The first column is the
chemical mechanism. The files have a 1 line header with the number
of species, the number of reactions and the number of equations in
the Generic Rate Coefficients and Complex Reactions sections (see
Sect.~\ref{subsec:facsimile-format}). The first column is the
\emph{ID number} of the reaction, the second column is the \emph{ID
number} of the species (from \texttt{mechanism.species}) which are
reactants/products in that reaction:
number} of the species which are reactants/products in that
reaction:
\begin{verbatim}
29 71 139 numberOfSpecies numberOfReactions numberOfGenericComplex
1 1
2 1
3 1
3 2
\end{verbatim}
\item \textbf{mechanism.ro2} contains the organic peroxy radicals
(RO2). By default, it is saved in \texttt{model/configuration/}. The
file has a comment line header (Fortran style). The first column is
the \emph{ID number} of the peroxy radical (from
\item \texttt{mechanism.ro2} contains the organic peroxy radicals
(RO2). The file has a comment line header in Fortran style. The
first column is the \emph{ID number} of the peroxy radical (from
\texttt{mechanism.species}), the second column is the name of the
peroxy radical as Fortran comment:
peroxy radical as a Fortran comment:
\begin{verbatim}
! Note that this file is generated by build/mech_converter.py
! based upon the file mcm/mechanism_test.fac. Any manual edits to
! based upon the file mcm/mechanism_test.fac Any manual edits to
! this file will be overwritten when calling build/mech_converter.py
23 !CH3O2
26 !C2H5O2
28 !IC3H7O2
29 !NC3H7O2
\end{verbatim}
\end{verbatim}
\end{itemize}

The locations of the files generated during the build process can be
modified by changing the second and the third argument of the script
\texttt{build/build\_atchem2.sh}. For more information and detailed
instructions go to: \hyperref[ch:execution]{Model Execution}.

\subsection{Example mechanism file} \label{subsec:example-mechanism-file}

\begin{verbatim}
* ------------------------------------------------------------------- *;
* SIMPLE CHEMICAL MECHANISM *;
* Chemical mechanism for ethanol - from MCM v3.3.1 *;
* ------------------------------------------------------------------- *;
*;
* Generic Rate Coefficients ;
*;
* Complex reactions ;
*;
* Peroxy radicals. ;
RO2 = HOCH2CH2O2 ;
*;
* Reaction definitions. ;
% 3.0D-12*EXP(20/TEMP)*0.05 : C2H5OH + OH = C2H5O ;
% 3.0D-12*EXP(20/TEMP)*0.9 : C2H5OH + OH = CH3CHO + HO2 ;
% 3.0D-12*EXP(20/TEMP)*0.05 : C2H5OH + OH = HOCH2CH2O2 ;
\end{verbatim}
The directory containing the files generated by the build script is
the \sharedir\ and, by default, it is \texttt{model/configuration/}:
the location of the \sharedir\ can be changed using the second
argument of the build script, as explained in more detail in
Sect.~\ref{sec:build} (see also Sect.~\ref{subsec:model-directory}).

% -------------------------------------------------------------------- %
\section{Model Parameters} \label{sec:model-parameters}
Expand Down

0 comments on commit 1bcba15

Please sign in to comment.