\chapter{THE GRID COMMAND}
% !TEX root = hazy1.tex
\label{sec:CommandGrid}

The \cdCommand{grid} command varies some of the input parameters
to compute a grid of models.
It is actually a form of the \cdCommand{optimize} command and uses much
of the same code.
It was added by Ryan Porter and its first use was
described in \citet{Porter2006}.

When the code is
compiled with MPI support enabled (see Section~\ref{Hazy2-sec:ParallelMPI} of \Hazy~2),
the \cdCommand{grid} command will run
in parallel mode on any (distributed) MPI cluster.

If you want to calculate a grid of models, it is {\em mandatory} to use one of the
following commands
\begin{verbatim}
// non-MPI runs
cloudy.exe -r gridrun
// alternative
cloudy.exe -p gridrun

// MPI runs
mpirun -np <n> /path/to/cloudy.exe -r gridrun
// alternative
mpirun -np <n> /path/to/cloudy.exe -p gridrun
\end{verbatim}
This assumes that the input script is in the file \cdFilename{gridrun.in}. The
normal input and output redirection shown elsewhere will not work in this case
and \Cloudy\ will stop with an error message if you try to use it. The command
line switches are described in Section~\ref{Hazy2-sec:RunCommandLine} of
\Hazy~2. Using the \cdCommand{-r} or \cdCommand{-p} command line switches is
necessary because the code needs to know the name of the input script in order
to generate intermediate files with its name embedded. It is also necessary
for the correct functioning of the code in MPI mode.

\section{Grid start point, end point, increment [ linear ]}

Parameters for those commands with the \cdCommand{vary} keyword
(see Table \ref{tab:CommandWithVaryOption}
on page \pageref{tab:CommandWithVaryOption}) can be varied
within a grid.
Each
command with a \cdCommand{vary} option must be followed by a \cdCommand{grid} command.
The value
entered on the command with the \cdCommand{vary} option is
ignored but must be given
to satisfy the command parser.

The \cdCommand{grid} command line must have three numbers.
The first and second
are the start and end points of the range of variation.
The last number
is the value of the increment for each step.
The increment can be either positive or negative.
This behaves much the same
way as a \emph{do} loop in Fortran or a \emph{for} loop in C.
The \cdCommand{grid} command always changes variables from the start point
to the end point.
In other words, the start point must be less than the end point when
the increment is positive, while, when the increment is negative, the start
point must be larger than the end point. Note that the
grid points are calculated in random order, so it no longer
matters if you use a positive or negative increment\footnote{In versions
C10 and earlier of the code, the grid points were calculated in sequential
order (at least for non-MPI runs) so it made a difference then. The option of
choosing a negative increment is maintained for backward compatibility.}.
The following varies the
blackbody temperature over a range of $10^4$ to $10^6$~K with three points.
\begin{verbatim}
C the blackbody command with vary option, the 1e5 K is needed to
c get past the command parser, but is otherwise ignored
blackbody 1e5 K vary
c this varies the blackbody temperature from 1e6 to 1e4 K with -1 dex
c steps, so that 1e6K, 1e5K, and 1e4K will be computed
grid, range from 6 to 4 with -1 dex increments
\end{verbatim}
The following is a 2D grid in which both the ionization parameter and
metallicity are varied.
There will be five values of the ionization
parameter and three values of the metallicity computed.
\begin{verbatim}
ionization parameter -2 vary
grid range from 0 to -4 with -1 dex steps
metals 0 vary
grid range from -1 to 1 with 1 dex steps
\end{verbatim}

For nearly all commands, the quantity will be varied logarithmically (current
exceptions are the \cdCommand{illuminate}, \cdCommand{ratio alphox},
\cdCommand{dlaw}, and \cdCommand{fudge} commands). If the quantity is varied
logarithmically, the lower / upper limit and the step size also need to be
given as logarithms, as shown above. If the keyword \cdCommand{linear} is
included on the \cdCommand{grid} command, then these numbers will be
interpreted as linear quantities. As an example, the following will produce a
grid of models with a constant electron temperature of 5000, 10000, 15000, and
20000~K.
\begin{verbatim}
constant temperature 4 vary
grid range from 5000 to 20000 step 5000 linear
\end{verbatim}

For some commands the unit of the quantity will be implicitly changed by the
grid code. An example is the \cdCommand{radius} command. You can enter a
radius in parsec using the \cdCommand{parsec} keyword. However, the grid code
will always vary the radius in cm. In this case the lower / upper limit will
also need to be the (logarithm of) a radius in cm. There is currently no way
to overrule this. In general the lower / upper limit needs to have the exact
same units as are used on the command line that is generated by the grid,
\emph{not} the command line as originally typed by the user.

\section{Beware the grid command treatment of temperatures!!}
\label{sec:GridTemperatureGotcha}
%:GridTemperatureGotcha
The following will crash with an fpe
\begin{verbatim}
constant temperature 4 vary
grid range from 5000 to 20000 step 5000
\end{verbatim}
This is because of the rule stated above that the \cdCommand{grid} command
treats temperature ranges as logs unless the keyword
\cdCommand{linear} occurs.  

\section{Grid output options}
\label{sec:GridOutputOptions}

Several \cdCommand{save} output
options were developed to
retrieve information from \cdCommand{grid} runs.
The \cdCommand{save FITS} command
will generate FITS files for input into XSPEC (\citealp{Porter2006}).
The
\cdCommand{save grid} and \cdCommand{save line list} commands
save the grid points and emission-line intensities.

When computing a grid, the default is for save files to not overwrite
results of previous grid points (to not ``clobber'' themselves) and
to append the results to the save file instead.
Conversely, in optimizer runs the default
is for save files to overwrite one another since you
are usually not interested in output along the unpredictable convergence path.
That way you only get the save output from the fully converged model.

When you include the \cdCommand{separate} keyword on a \cdCommand{save}
command, the output of each grid point will be written to a separate file. See
Section~\ref{sec:save:separate} for further details.

In the output from \cdCommand{save} commands the default behavior is to put
separators consisting of hash marks in between the output from different
iterations (unless the \cdCommand{no hash} option is used). In grid runs this
behavior is slightly changed. There will be an additional separator at the
very end of the output, which will also have the additional text
``GRID\_DELIMIT'' appended, as well as the number of the grid point in the
format ``grid000000000''. This makes it easy to find back the output from a
specific grid point, as well as identify where there is output missing in case
some of the grid points have serious problems.

\section{Other grid options}

The \cdCommand{no vary} command can be used to ignore all
occurrences of the \cdCommand{grid} command and \cdCommand{vary}
option in an input stream.

The \cdCommand{repeat} option on the \cdCommand{grid} command
causes the expected number of grid
steps to be computed but the initial value of the variable is not
incremented.
This is mainly a debugging aid. 

\section{Notes on various commands}

\subsection{Constant temperature}
Section \ref{sec:GridTemperatureGotcha}
describes the rules governing how the temperature can
appear on the \cdCommand{constant temperature} command.
