\documentclass[11pt]{article}

\usepackage[letterpaper,margin=0.75in]{geometry}
\usepackage{parskip}
\usepackage{enumerate}
\usepackage{alltt}
\usepackage[T1]{fontenc}

\begin{document}

\newcommand{\mech}{\textless mech\textgreater}

\begin{center}

\ \\[8cm]

{\LARGE BOXMOX extensions to KPP} \\[1cm]
Christoph Knote (christoph.knote@lmu.de)\\
Meteorological Institute, LMU Munich, Germany
\\[1cm]
Version 1.8a\\
09/2019

% version   name  comment
% 0.9       CK    initial release
% 1.2       CK    update to match multimox
% 1.3       CK    new Namelist method of setting time etc., changed to
%                 ReadStencil method
% 1.4       CK    added MCM v3.3 mechanism, cleanup
% 1.5       CK    added simplified tooling, new mechanisms
% 1.6       CK    ability to create adjoint mechanism using the
%                  prepare_BOXMOX_mechanism command
% 1.6.1     CK    bugfix release
% 1.7       CK    revamped mixing process options, included simple aerosol as
%                 surface density area and radius
% 1.8a      CK    implemented NOx fixing
\end{center}

\thispagestyle{empty}

\newpage

\tableofcontents

\newpage

\section*{Version history}

\subsection*{1.8a}
\textit{not released yet}

New features

\begin{itemize}
  \item Implemented NO$_x$ fixing method for steady state calculations
\end{itemize}

\subsection*{1.7}
\textit{released December 2017}

New features

\begin{itemize}
  \item Method to include heteorogeneous reactions on aerosol
  \item Revamped mixing options (by constant K, volume, or tracer concentration)
  \item Simplified photoysis rates labeling
  \item New and renamed namelist options ({\tt lverbose}, {\tt iturb})
  \item Restructured and updated documentation
\end{itemize}

Minor updates

\begin{itemize}
  \item New command {\tt list\_BOXMOX\_mechanisms}
  \item {\tt new\_BOXMOX\_experiment} now copies default namelist to work
  directory
\end{itemize}

Internal changes

\begin{itemize}
  \item Code cleanup
  \item \emph{setup} file removed
  \item Creation of \emph{VERSION} file to indicate BOXMOX version used for
  simulation
\end{itemize}

\subsection*{1.6}
\textit{released February 2017}

New features

\begin{itemize}
  \item Ability to create adjoint mechanism using
  {\tt prepare\_BOXMOX\_mechanism}
\end{itemize}

\subsection*{1.5}
\textit{released December 2016}

New features

\begin{itemize}
  \item Simplified tooling and use scripts
  \item Bug fix in MOZART-4 mechanism
\end{itemize}

\subsection*{1.4}
\textit{released September 2016}

New features

\begin{itemize}
  \item MCM v3.3, as well as several other mechanisms used in
  Knote et al., Atm. Env., 2015, are included
  \item Preparations to use adjoint models
\end{itemize}

\subsection*{1.3}
\textit{released November 2015}

New features

\begin{itemize}
  \item Namelist input (runtime definitions, verbosity)
  \item Example cases for an urban plume, PBL diurnal cycle, and a chamber
  experiment (\emph{boxmox/data} subdirectory)
  \item Diagnostic messages: notify user of unusable species in input files
\end{itemize}

Internal changes

\begin{itemize}
  \item Code refactoring
  \item Preparations for using MCM in BOXMOX
\end{itemize}

\subsection*{1.2}
\textit{released July 2015}

Initial public release

\newpage

\section{The BOXMOX extension}

A bunch of code that makes it possible to use KPP mechanisms in a box model
fashion with the ability to read in parameters from simple text files.

\subsection{Essentials of KPP}

The Kinetic Preprocessor (KPP; Sandu and Sander, 2006) is a code generator
that creates a numerical solver for a set of predefined (chemical) differential
equations in a number of programming languages (Fortran, Matlab, C).

\subsection{Essentials of BOXMOX}

While KPP is already a box model, it is missing a ``wrapper'' that allows
convenient input of initial and boundary conditions as well as environmental
parameters, and it lacks processes typically associated with box model
simulations of atmospheric chemistry. This is what the BOXMOX extensions
provide.

Through a set of text files the user provides input for initial conditions, as
well as for (time-varying) photolysis rates, environmental parameters, turbulent
mixing, emissions and deposition.

Output of such a simulation are text files containing time series of the
concentrations of all species in the mechanism, as well as all rate constants
and the Jacobian.

BOXMOX was already used in a multi-mechanism comparison within the AQMEII Phase
2 project (Knote et al., 2015), please use this citation when referring to
BOXMOX. A data assimilation toy model ('BEATBOX') has been built using BOXMOX in
Knote et al. (2017).

\subsection{References}

Knote,~C., Barr{\'e},~J., and Eckl,~M.: \textbf{BEATBOX: Background Error
Analysis Testbed with Box Models}. {\em Geoscientific Model Development
Discussions}, in review, doi:10.5194/gmd-2017-188, 2017.

Knote,~C., Tuccella,~P., Curci,~G., Emmons,~L., Orlando,~J., Madronich,~S.,
Bar{\'o},~R., Jim{\'e}nez-Guerrero,~P., Luecken,~D., Hogrefe,~C., Forkel,~R.,
Werhahn,~J., Hirtl,~M., P{\'e}rez,~J.-L., San~Jos{\'e},~R., Giordano,~L.,
Brunner,~D., Yahya,~K., and Zhang,~Y.: \textbf{Influence of the choice of
gas-phase mechanism on predictions of key gaseous pollutants during the AQMEII phase-2
intercomparison}. {\em Atmospheric Environment}, 115:553--568,
doi:10.1016/j.atmosenv.2014.11.066, 2015.

Sandu,~A., and Sander,~R.: \textbf{Technical note: Simulating chemical systems
in {Fortran90} and {Matlab} with the {Kinetic PreProcessor KPP-2.1}}. {\em
Atmospheric Chemistry and Physics}, 6(1):187--195,
doi:10.5194/acp-6-187-2006, 2006.

\newpage

\section{Installation}

\emph{BOXMOX is a Linux program, we assume you are working on a reasonably
recent Linux distribution.}

You should have received or downloaded the \emph{install\_BOXMOX.bash} shell
script. The script is written in {\tt bash}, a shell that is installed on most
*nix machines, but might not be your default. Do not worry. Open the script in
your favorite text editor and adapt the user section to your machine. You need
to set

\begin{itemize}
  \item absolute path to the location you want BOXMOX to be
  \item C compiler (usually {\tt gcc} or {\tt cc})
  \item C compile flags (if any)
  \item absolute path to the FLEX binary (test with {\tt which flex})
  \item absolute path to the FLEX library (libfl.a, try {\tt type -a libfl.a})
\end{itemize}

Save the file. Now execute it:

\begin{verbatim}
me@mymachine> bash install_BOXMOX.bash

BOXMOX extension to KPP (1.7)

Output directory: /glade/u/home/knote/testy
C compiler:       gcc
C compiler flags: -O
FLEX binary:      /usr/bin/flex
FLEX library:     /usr/lib64/libfl.a

Downloading BOXMOX
Downloading KPP
Unpacking KPP
Patching KPP
Compiling KPP
Tex'ing BOXMOX readme (boxmox/README.pdf)

 --- YOU ARE GOOD TO GO ---

Remember to set the following env. variables and
add them to your .bashrc. to remember them permanently:

export KPP_HOME=/glade/u/home/knote/boxmox
export PATH=$KPP_HOME/bin:$PATH

me@mymachine>
\end{verbatim}

Once you see the message ``YOU ARE GOOD TO GO'', everything should have worked
out fine. Remember to set your environment variables (required) by copying the
two lines starting with {\tt export} and pasting in the terminal, or by adding
them to your \emph{.bashrc} / \emph{.profile} files in your home directory (new
login required to make it work). Contact me if you run into problems
installing BOXMOX.

\newpage

\section{Preparing a BOXMOX simulation}

\emph{This section assumes you have sucessfully installed BOXMOX, and
intend to use a KPP mechanism description that has already been adapted for use with
BOXMOX. Several such adapted mechanisms were installed with BOXMOX, please refer
to section \ref{sec:adaptmechs} on how to adapt other mechanisms.}

\subsection{Utility programs}

Several commands have been installed with BOXMOX that make preparing box model
simulations easy:

\subsubsection{{\tt list\_BOXMOX\_mechanisms}}

Lists mechanisms ready for simulation, or (with {\tt -a} switch) all mechanisms
available including the ones not yet prepared.

\subsubsection{{\tt prepare\_BOXMOX\_mechanism}}

To use a chemical mechanism in BOXMOX, you need to prepare (compile) it first.
This has to be done only once for each mechanism. To prepare a mechanism, just
call {\tt prepare\_BOXMOX\_mechanism}:

\begin{verbatim}
me@mymachine> prepare_BOXMOX_mechanism MOZART_4
All necessary files and programs found.
Running KPP.
'Make'ing the model.
Successfully created MOZART_4.
me@mymachine>
\end{verbatim}

This creates a box model executable for the chosen mechanism (in this case,
MOZART-4) which you can now use for your experiments. The executables can be
found in \emph{\$KPP\_HOME/boxmox/compiled\_mechs/\mech}.

\subsubsection{{\tt new\_BOXMOX\_experiment}}

To make a box model simulation, you would copy the box model executable
created in the last step into a newly created directory (and execute it). This
is what the command {\tt new\_BOXMOX\_experiment} is for:

\begin{verbatim}
me@mymachine> new_BOXMOX_experiment MOZART_4 new_experiment_folder
me@mymachine> ls new_experiment_folder/
BOXMOX.nml	MOZART_4.exe	VERSION
me@mymachine>
\end{verbatim}

\subsubsection{{\tt new\_BOXMOX\_experiment\_from\_example} (alternatively)}

A couple of ready-to-run experiments are distributed with BOXMOX, which can
serve as starting point for further experiments.
{\tt new\_BOXMOX\_experiment\_from\_example} creates a new experiment based on
these examples.

\begin{verbatim}
me@mymachine> new_BOXMOX_experiment_from_example chamber_experiment new_experiment_folder
me@mymachine> ls new_experiment_folder/
BOXMOX.nml		InitialConditions.csv	PhotolysisRates.csv	VERSION
Environment.csv		MOZART_4.exe		README			plot.R
me@mymachine>
\end{verbatim}

\subsection{Setting up a BOXMOX namelist}
\label{nml}

Parameters like runtime and verbosity can be controlled using a Namelist, a
simple text file that resides in the same directory as the BOXMOX executable. It
is a standard FORTRAN namelist, has to have the name \emph{BOXMOX.nml}, and can
contain the following variables:

{\tt TSTART} is the start time of the run in seconds.

{\tt TEND} is the end time of the run in seconds.

{\tt DT} is the time step in seconds.

{\tt lverbose} triggers (a lot) of additional screen output from a
BOXMOX simulation.

{\tt iturb} defines the type of (turbulent) mixing.

{\tt lfix\_nox} defines whether total NO$_x$ should be fixed to its initial
values.

A typical \emph{BOXMOX.nml} file looks like this:

\begin{alltt}
\input{../case_studies/BOXMOX.nml}
\end{alltt}


\subsection{Input file format}
\label{txt:fileformat}

All input files described above are simple (ASCII) text files that need to be
found in the same directory where the compiled mechanism (\emph{\mech .exe}) is
executed. Their format needs to be readable through FORTRAN list-directed
formatting. Exports from Excel as ``.csv'' (character separated values) as well
as fixed-width formats should work. The general formatting rules are:

\begin{itemize}
\item values are separated by blanks or a comma
\item values cannot contain blanks
\item UNIX line endings (LF)
\end{itemize}

If an input file does not exist, BOXMOX will notify the user and
continue. This is equal to not considering the process the file is associated
with.

The file format convention is as follows:

\begin{verbatim}
I
I
I
(A) (A+) A+
(F) (F+) F+
\end{verbatim}

with {\tt I} integer, {\tt A} string, {\tt F} a real variable.
{\tt (...)} indicates optional values, and {\tt ...+} indicates
possibility to have multiple values.

\textbf{line 1:} number of variables

\textbf{line 2:} number of ancillary variables (e.g. Kturb)

\textbf{line 3:} units of time in file

\textbf{line 4:} names of (time, ancillary and main) variables

\textbf{line 5 ff:} values

In case values provided are time-dependent (\textbf{line 3} is not 0), the first
column (in \textbf{lines 4} and \textbf{5 ff}) must contain the time. In case
the values do not depend on time, the time column must not exist. Ancillary
variables are to be provided in columns before the main variables.

An example, time-dependent \emph{PhotolysisRates.csv} file without ancillary
variables could look like this (note that fixed-width is not necessary,
comma-separated works as well):

\begin{verbatim}
3
0
2
        time          o2        o31d        o33p
  0.0000E+00  0.0000E+00  0.0000E+00  0.0000E+00
  1.0000E+00  0.0000E+00  0.0000E+00  0.0000E+00
  2.0000E+00  0.0000E+00  0.0000E+00  0.0000E+00
  3.0000E+00  0.0000E+00  0.0000E+00  0.0000E+00
  4.0000E+00  0.0000E+00  5.4040E-08  7.8720E-05
  5.0000E+00  0.0000E+00  1.0490E-06  3.2440E-04
  6.0000E+00  0.0000E+00  5.5420E-06  4.2150E-04
[... more ...]
\end{verbatim}

\subsubsection{Units of time}

In \textbf{line 3}, input files define the type of time dependence the values
have:

{\tt 0}: without time dependency, one line of values expected

{\tt 1}: seconds since simulation start

{\tt 2}: hour of day for an idealized diurnal cycle

\subsubsection{Variable names}

In \textbf{line 4}, variable names (labels) have to be defined. Different sets
are used:

\emph{PhotolysisRates.csv}: labels have to match the name used in the KPP
rate constant (see \ref{sec:photrates}).

\emph{Environment.csv}: the variables described in \ref{sec:env} are
available.

all other input files: labels have to match whatever species names you used in
the KPP mechanism definition (\emph{\mech .spc} file).

The name of the time variable can be freely chosen, we suggest ``{\tt time}''.

\subsubsection{Variable units}

The underlying KPP can work with whatever units the rate constants are defined
in. In BOXMOX we assume molecules cm$^{-3}$ for concentrations, and cm$^3$
molecules$^{-1}$ s$^{-1}$ for rate constants. This constraint is made to ensure
that the model is consistent with input values for the boundary layer height and
emissions. Input values of concentrations are given in parts per million per
volume (ppmv). The other potential input variables are to be provided in the
following units:

\begin{itemize}
  \item concentrations: parts per million per volume (ppmv)
  \item emissions: molecules cm$^{-2}$ s$^{-1}$
  \item Eddy diffusivity: m$^3$ s${-1}$
  \item volume: m$^3$
  \item planetary boundary layer height: m
  \item temperature: K
  \item deposition velocities: cm $s^{-1}$
  \item photolysis rates: $s^{-1}$
\end{itemize}

\newpage

\section{Running a simulation}

Once you have created a new experiment, adapted the namelist, added / adapted
the input files needed for the processes you want to include, you can then run
the box model:

\begin{verbatim}
me@mymachine>cd <path to experiment>
me@mymachine>./<mech>.exe

 ------------------------------------------------------------
 BOXMOX (1.7) driver
 ------------------------------------------------------------

 BOXMOX configuration file BOXMOX.nml found.

              TSTART         0.000
                TEND      3600.000
                  DT        10.000

            lverbose           F

               iturb           0

 ------------------------------------------------------------

  * Environment.csv
      useable:TEMP,PRES

  * InitialConditions.csv
      useable:CH2O,C2H6,CH4,H2O,CO,NO,NO2,O3,HNO3,SO2,NH3,PAN,H2O2,CH3OOH,CH3COOH,
[...]
      unknown: CO2,HCOOH,NROG,NOASN,XYLENES,ALKNIT,MBO,BENZENE,APIN,BPIN,LIMON,
[...]

  * Environment.csv
      useable:TEMP,PRES

  * PhotolysisRates.csv
      known:1_c4h9ono2,2_c4h9ono2,acrolein,biacet,c2cho,c2h5cho,c2h5ono2,
[...]

  10.0%. T=0.350E+03
[...]
 100.0%. T=0.360E+04

 ------------------------------------------------------------
 BOXMOX successfully completed.
 ------------------------------------------------------------

me@mymachine>
\end{verbatim}

That is it.

\section{Results and output}

The model run creates a number of output files, all of them simple text files:

\begin{itemize}
  \item \emph{\mech .conc} - the concentration matrix

In the first line the names of each column are given, then follows beginning at
line two a data matrix with one more columns than your .spc file has species
(first column is time in hours), and one row per time
step.

  \item \emph{\mech .rates} - the rate constant matrix

The number of rate constants (nrates) in your mechanism in the first line,
followed by nrates lines with the name of each reaction, followed by a data
matrix with one more columns than your mechanism has rate constants (first
column is time in hours), and one row per time step.

  \item \emph{\mech .jacobian} - the Jacobian (dx / dy) matrix

  \item \emph{\mech .hessian} - the Hessian (d$^2$x / (dy dz)) matrix,
if {\tt HESSIAN} is set to ON in \emph{\mech .kpp}

\end{itemize}

\newpage

\section{Processes and their representation in BOXMOX}

The following section describes the processes that are added to a KPP box model
by the BOXMOX extensions. Each process is connected to an input file, and their
file names are mentioned in each section. Omission of an input file is equal to
ignoring the associated process.

\subsection{Environmental parameters}
\label{sec:env}

Environmental parameters define properties of the box and is characteristics.
These are provided through file \emph{Environment.csv}.

Available variables are:
\begin{itemize}
  \item {\tt TEMP}: temperature in Kelvin
  \item {\tt PRES}: pressure in Pa
  \item {\tt VOL}:  box volume in m$^{3}$
  \item ({\tt PBLH}: planetary boundary layer height in m)
\end{itemize}

The variable {\tt PBLH} is an alternative to describe a change in the vertical
extent (hence, the volume) of the box.

When temperature and pressure are provided as time-dependent variables, this
will cause assumed air density to vary accordingly. Values provided in any input
file that require conversion using density (e.g., initial concentrations,
background values) will be converted using the time-varying air density
accordingly.

\subsection{Initial conditions}

Values for initial conditions of all species used in the mechanism can be
provided through the file \emph{InitialConditions.csv}. All species not defined
in \emph{InitialConditions.csv} are set to a tiny, positive value for numerical
stability (variable {\tt ALL\_SPEC} in \emph{boxmox/wrapper}).

\subsection{Photolysis rates}
\label{sec:photrates}

Photolysis rates can either be provided in the .eqn file as fixed values or
values that depend on the KPP variable SUN (see KPP documentation).

Additionally, photolysis rates can be provided through the file
\emph{PhotolysisRates.csv}. In this case, use {\tt J(``label'')} as reaction
rate function, with {\tt label} corresponding to a column in the file
\emph{PhotolysisRates.csv}.

Example:

In the .eqn file of your mechanism you add the following photolysis rates:

\begin{verbatim}
[...]
A + B = C : J("AB");
C + D = E : J("CD_ch1");
C + D = F : J("CD_ch2");
[...]
\end{verbatim}

Then the corresponding contents of \emph{PhotolysisRates.csv} would be:

\begin{verbatim}
3
0
0
AB CD_ch1 CD_ch2
1e-3 5e-4 2e-4
\end{verbatim}

\subsection{Heterogeneous surface reactions}

A combination of input file and rate constant variable allows to consider
heterogeneous reactions that depend on aerosol. The variables {\tt AER\_SAD}
(aerosol surface area in m$^3$ m$^{-2}$) and {\tt AER\_R} (aerosol effective
radius in m) are provided for rate constants in the \emph{\mech .spc} file.
Their values can be set by creating a new input file \emph{Aerosol.csv}, for
which labels {\tt SAD} and {\tt R} are known. The BOXMOX example het\_chem and
the mechanism HETCHEM shows how to use this feature.

\subsection{Turbulent mixing}

The box can exchange with its surroundings via mixing (due to turbulent
motions), a process also referred to as dilution or en-/detrainment. The
convective term ($\vec{v} \nabla c$) of the continuity equation for the
concentration of a substance $c$

\begin{equation}
\frac{\partial c}{\partial t} + \vec{v} \nabla c = 0
\end{equation}

is simplified to an exchange between the box and a background
concentration $c_{bg}$, scaled by a coefficient:

\begin{equation}
K_{turb} ( c - c_{bg} ) := \vec{v} \nabla c
\end{equation}

The coefficient $K_{turb}$ is equal to the Eddy diffusivity, or turbulent
diffusion coefficient, if only turbulent exchange is considered. The new
concentration of $c$ at the end of time step $\Delta t$ is then calculated as

\begin{equation}
c(t=t_0 + \Delta t) = c(t=t_0) + K_{turb} ( c(t=t_0) - c_{bg}(t=t_0) )
\end{equation}

Three different options are implemented to describe $K_{turb}$, and thereby
mixing. They are specified using the namelist variable {\tt iturb} and through
the provision of background concentrations (and {\tt Kturb}) in
\emph{Background.csv}.

\subsubsection{Specified $K_{turb}$ (iturb=1)}

Using values for the eddy diffusivity $K_{turb}$ specified as
ancillary variable {\tt Kturb} in \emph{Background.csv}.

\subsubsection{Box volume changes (iturb=2)}

Using the changes in the volume of the box as defined through the {\tt VOL}
variable in \emph{Environment.csv}. Increases in box volume are matched by
mixing assuming the change in box volume is due to the influx of background
air, decreases in box volume are ignored.

Hint: simulating \emph{top de-/entrainment} due to a time-varying planetary
boundary layer height is a special case of mixing due to volume changes of a
box with a constant horizontal extent.

\subsubsection{Following a tracer concentration (iturb=3)}

Using the change in concentration of a tracer known to the chemical mechanism.
The model attempts to match the box concentration of a species (tracer) with the
tracer concentrations specified as ancillary variable in \emph{Background.csv}
through mixing with the background.

\subsection{Emissions}

For all species emission fluxes can be provided in \emph{Emissions.csv}. It is
assumed that these mix instantaneously within the box. Realistic emission fluxes
(e.g. from 3-D models) require a realistic mixing volume, hence it is only
reasonable to provide emissions in combination with a realistic {\tt PBLH} /
{\tt VOL} setting in \emph{Environment.csv}. Details on how to set up a correct
input file can be found in section \ref{txt:fileformat}.

\subsection{Deposition}

A first-order loss process, analogous to ``dry deposition'', can be included.
Values are provided as deposition velocities $v_{dep,i}$ for a species $i$. The
change in concentration $C_i$ over time t is calculated as

\begin{equation}
\frac{\partial C}{\partial t} = -v_{dep,i} \cdot C_i(t=t_0) / dz
\end{equation}

with $dz$ the vertical extent of the box ({\tt PBLH}). Values for deposition
are provided through file \emph{Deposition.csv}. Also for deposition, a
realistic value for the boundary layer height {\tt PBLH} should be set.

\newpage

\section{Adding and modifying mechanisms}
\label{sec:adaptmechs}

Making a BOXMOX simulation itself consists of only one step - running the BOXMOX
executable in a directory in which you provided all input files you needed.
Change/add/remove input files as you like and simply re-run the executable to
make a new simulation. Output files will be overwritten.

It might, however, be of interest to make changes to the underlying mechanism,
or even create a new mechanism. In the following it is shown how to modify an
existing mechanism and even create a new one.

\subsection{Modifying an existing mechanism}
\label{sec:modmech}

The set of equations, species and further definitions for an existing mechanism
\mech{} can be found in your KPP/BOXMOX installation directory:

\begin{verbatim}
${KPP_HOME}/models/<mech>.(eqn|spc|def)
\end{verbatim}

The KPP definitions (integration scheme, creation of Jacobian, \ldots) for a
mechanism are in:

\begin{verbatim}
${KPP_HOME}/examples/<mech>.kpp
\end{verbatim}

To make changes to this mechanism, edit the files as needed, and then recreate
the mechanism for use in BOXMOX using {\tt prepare\_BOXMOX\_mechanism -f \mech}.
Note usage of the {\tt -f} flag to force recreation of the mechanism even though
it has already been prepared. You can then make simulations with the new
mechanism as it has been described above.

\subsection{Adding new mechanism}

To add a new KPP mechanism for use in BOXMOX, you need to create the files
mentioned in the previous subsection (\ref{sec:modmech}). It might be the
easiest to use one of the simple existing mechanisms as blueprint. BOXMOX
mechanisms are KPP mechanisms (see KPP documentation) with slight adaptations to
make them useable in BOXMOX:

\subsubsection{Edit the \emph{\${KPP\_HOME}/examples/\mech .kpp} file}

Make sure the following variables are set:

\begin{verbatim}
#MODEL <mech>
#LANGUAGE Fortran90
#DOUBLE ON
#INTEGRATOR rosenbrock
#DRIVER ../boxmox/boxmox
#JACOBIAN SPARSE_LU_ROW
#HESSIAN OFF
\end{verbatim}

Additional lines might exist, and can be used with BOXMOX unchanged most of
time. To get the Hessian matrix (e.g. for adjoint runs), set {\tt HESSIAN} to
'ON'.

\subsubsection{Edit the \emph{\${KPP\_HOME}/models/\mech .def} file}

The following has to be included in the .def file, at the top of the file
before any {\tt \#INCLUDE} directives:

\begin{verbatim}
#include ../boxmox/wrapper

#LOOKATALL
\end{verbatim}

\subsubsection{Preparing the new mechanism}

Once you created the 4 files (\emph{\${KPP\_HOME}/examples/\mech .kpp},
\emph{\${KPP\_HOME}/models/\mech .(def|spc|eqn)}) you can prepare the mechanism
with {\tt prepare\_BOXMOX\_mechanism \mech}.

\end{document}
