\chapter{CONTROLLING OUTPUT}
\label{sec:ControllingOutput}
% !TEX root = hazy1.tex

\section{Overview}

\Cloudy\ is capable of generating lots of output although its
default output is minimal.
Commands that control the output are described here.
Chapter~\ref{Hazy2-sec:output}
\cdSectionTitle{\refname{Hazy2-sec:output}} of Hazy 2
describes the meaning of the output.

\section{No buffering}

This command is described in Section~\ref{sec:no_buffering}.

\section{Normalize to ``O  3'' 5007 [scale factor = 100]}

The strength of an emission line in the standard output will be given
in intensity or luminosity units and as its intensity relative to a reference
line.  In the main printout each emission line has a label and wavelength,
followed by the energy radiated in the line, ending with the intensity
relative to a reference line.

Emission-line intensities are usually listed relative to the intensity
of H$\beta\ \lambda 4861$\AA, the default reference line.  By default the reference line
has an intensity of unity.  This command can change the reference line to
any of the other predicted lines and can change the relative intensity of
the reference line to another value.  The relative intensities of all lines
in the spectrum will be relative to the intensity of the line whose label
is within the double quotes and with wavelength given by the first number.
The label must be the four-character string that identifies the line in
the print out\footnote{The label was optional in versions 94 and before of the code, but
now is required due to the large number of lines, making unique wavelengths
unusual.}
and the wavelength must match the printed wavelength to
all four figures.
The wavelength units must appear if they are not
Angstroms.

The optional second number sets the relative intensity of the reference
line.
If it is equal to 100, as in this example, then all intensities will
be relative to a reference line intensity of 100.
The default is for an
intensity of unity.
The example given above will cause the relative
intensities to be expressed relative to an [O III] $\lambda$5007 intensity of 100.
The scale factor must be greater than zero.

The code works by finding the first line in the emission-line stack whose
wavelength and label matches the line on this command.
There is a possible
uniqueness problem since more than one line can have the same wavelength.
This is especially true for XUV or soft X-ray lines and for \htwo\ lines.

The following shows some examples of the \cdCommand{normalize} command:
\begin{verbatim}
// normalize to spectrum to Pa
normalize to "H  1" 1.875m

// normalize spectrum to the [OI] IR line on a scale where it is
 equal to 100 normalize to ``O  1'' 63.17m = 100
\end{verbatim}

\section{Plot [type, range]}

Plots of several predicted quantities can be made.\footnote{Today most plots are
generated by producing save output then
post-processing that output in other software.  The plot commands described
here still function but are likely to be removed in a future version of
the code.}  One of the keywords
described below must appear on the command line.  Up to 10 plots can be
generated.  The keyword \cdCommand{trace} will turn on a great deal of information
concerning the mechanics of generating the plot.

Publication-quality plots can be produced using the \cdCommand{save} commands
(described below) to produce a file that
can then be post-processed using other plotting software.

\section{Plot continuum [\_raw, trace, range]}

This plots the continuum.  This energy range can be changed by entering
the range key and the lower and upper limits.
This is described below.

The default is to plot both the incident continuum (in units of
$\nu f_\nu$)
(plotted as .'s) and the transmitted continuum (the o's).
If the option
\cdCommand{raw} is specified then the continuum in units actually used inside \Cloudy
($\pscm \ps \mathrm{cell}^{-1}$) will be plotted.
If the keyword
\cdCommand{photon} appears then the
units of the plotted continuum will be
photons cm$^{-2}\; \mathrm{s}^{-1}\; \mathrm{Ryd}^{-1}$.

\subsection{Plot continuum keywords}

It is possible to plot specific components of the continuum with the
following series of keywords.

\subsection{Plot diffuse continuum}

This plots the diffuse emission per unit volume within the last computed
zone.
This gives emission by gas and grains in the optically thin limit
and unity filling factor.

\subsection{Plot emitted continuum}

The net integrated continuum produced by the cloud is plotted.  This
is the sum of the continua emitted in the inward and outward directions
from the computed ionization structure and does not include the incident
continuum.

\subsection{Plot outward continuum}

The contents of the \cdVariable{outcon} and \cdVariable{flux}
arrays, multiplied by the local gas
opacity, are plotted to indicate sources of ionization and heating.

\subsection{Plot reflected continuum}

The continuum emitted from the illuminated face of the cloud is plotted.
This includes the back-scattered portion of the incident continuum along
with the diffuse continuum emitted from the cloud in the direction towards
the central object.  This is possible only for non-spherical (open)
geometries.

\section{Plot opacity [type, range]}

The opacity (total cross section per hydrogen atom) of the first and
last zones is plotted.  The full continuum predicted by the code, the range
\emm $\le h\nu < $\egamry , is plotted by default.  This is changed
by using the \cdCommand{range} option.

There are three optional keywords; \cdCommand{absorption},
\cdCommand{scattering}, and \cdCommand{total},
to change which opacity is plotted.  If none appear then the total opacity
is plotted.

\subsection{Plot range options}

The keyword \cdCommand{range} specifies the energy range of the
\cdCommand{opacity} and \cdCommand{continuum}
plots.  If one number occurs on the line then it is the lowest energy in
Rydbergs.  If the first number is zero then it is replace with the lowest
energy in the continuum, \emm .  The optional second number is
the highest energy shown on the plot.  If it is omitted or zero then the
high-energy limit of the code, presently \egamry , is used.  If either
number is negative then both are interpreted as the logs of the energies,
otherwise they are assumed to be the linear energy.  If the first number
is zero (i.e., interpreted as the lowest energy considered by the code)
then the second number is interpreted as the energy of the upper limit to
the plot and not its log.

The following give specific examples of the range option.
\begin{verbatim}
// plots the absorption opacity between 0.1 to 10 Ryd.
plot absorption opacity, range=.1 to 10 Ryd
//
// plot the opacity between 1 Ryd and
// the high energy limit of the code.
plot scattering opacity, range=1
//
// the range will be the full energy limit of the code
plot opacity
\end{verbatim}

\section{Plot \_map [Tmin=3e3 K, Tmax=2e4 K, linear, range]}

The keyword \cdCommand{\_map} (note the leading space)
says to do a plot of the heating
and cooling rates [erg cm$^{-3} \mathrm{s}^{-1}$]
as a function of temperature for the last
computed zone.
The \cdCommand{save map} command saves
this information in a file and is more useful.

\subsection{Plot map range options}

The high and low temperatures on the map are changed with the keyword
\cdCommand{range} and one or two optional numbers.  If no number appears then a
temperature range of 10~K to $10^9$~K is used.  If only one number appears
then only the lower temperature limit is changed.  If two numbers appear
then both lower and upper limits are changed.

If the first number is $\le 10$ then both numbers are interpreted as
logs of the temperature.
If the first number is $> 10$ then both are interpreted
as the temperature itself.
If the keyword \cdCommand{linear} appears then both numbers
are interpreted as the temperature itself no matter how large or small
they may be.

The number of points on the map is set with the \cdCommand{set nmaps} command.

\section{Print ages}

The code normally assumes that the system is old enough for microphysical
processes to have become time steady.  This tells the code to print all
of the timescales tracked by the code.
These are the same timescales
considered by the \cdCommand{age} command.
Normally only
the shortest timescale is printed at the end of the calculation.

If a physical process is not significant, for instance, the \htwo\ formation
timescale in a $10^6$~K gas,
the age is still computed but is set to a negative
number.
This retains the value while not including the process when the
important timescales are determined.

\section{Print arrays}

This prints the array elements that enter into solution
of the ionization balance.
By default it will print this information for
all elements.
If the keyword \cdCommand{only} appears then it will also look for the
name of an element and will only print the array
elements for that element.
\cdCommand{Print arrays only xxx} commands are additive.
If more than one appears then only the information for the
requested elements will be printed.
This is a debugging aid.

\section{Print citation}

\Cloudy\ is a research project that involves the creative efforts of many
people.  It should be cited as follows:  ``Calculations were performed with
version yy.mm.dd of \Cloudy, last described by Ferland et al. (yyyy).''
The numbers represent the release date and the citation is to a review paper.
The citation should mention the version of the code since some predictions
changes as the atomic data and treatment of physical processes improve.
Old versions of the code are never deleted from the web site so it is
possible to recover a version that produced a given result.

This command will print the current version number of the code and give
the full bibliographic citation for the review paper.

\section{Print constants}

The physical constants stored in the header file \cdFilename{physconst.h} will be
printed along with sizes of some variables.

\section{Print column densities [on; off]}

This controls whether the column densities of the various constituents
are printed.  The keywords are \cdCommand{\_ON\_} and \cdCommand{\_OFF}.  The default is to print the
column densities.

The column densities of several excited states within ground terms of
some species are printed as well.  The meaning of the labels for the excited
states column densities is given in the discussion of \cdTerm{cdColm} in Part 2 of
this document.

\section{Print coolants, zone 135}

This prints the coolants for the specified zone.
If no zone number or
0 appears on the line then the coolants for \emph{all} zones will be printed.
The total cooling and the fractional contribution of the strongest coolants
are printed.  For each coolant a label gives an indication of the
spectroscopic origin of the coolant and the following integer gives its
wavelength, with a 0 to indicate a continuum.  The last number of the group
is the fraction of the total cooling carried by that agent.

\section{Print continuum indices}
\label{sec:print:continuum}

The file created by the \cdCommand{save continuum} command
identifies a line that occurs within each continuum bin.
This can be used
to understand what lines contribute to the predicted spectrum.
The line
label is for the first line that was entered in a particular cell.
It is
not the strongest line and there may be many lines contributing to a
particular cell.
This command will print the line energy (Rydberg),
continuum array index, and the line's spectroscopic notation, for every
line that is included in the calculation.
The lines will be printed in
the order in which they are entered into the continuum.
The printout can
then be sorted by energy or array index to discover all lines that occur
within a particular cell.
This is a debugging aid.

There are two optional numbers which give the lower and upper limit to
the energy range (Rydbergs) to be printed.
All lines are printed if these
numbers do not appear then.

\section{Print departure coefficients}

LTE departure coefficients for levels within an element along the H-like
or He-like isoelectronic sequences will be printed.
The \cdCommand{print populations}
command controls printing individual level populations.

If the keyword \cdCommand{He-like} appears then an element on the helium-like
isoelectronic sequence will be printed.
Otherwise an element of the H-like
isoelectronic sequence is chosen.
The code will search for the name of
an element, and if it finds one, will print only that element.
If no
elements are recognized then departure coefficients for \hO\ (the H-like
sequence) or He$^0$ (the He-like) are printed.

\section{Print errors}

The code will always identify problems by either printing comments during
the calculation or warnings after the calculation is complete.
This says
to also print these warnings to \cdFilename{stderr}.
On many systems this output can
be redirected to the screen.
The \cdCommand{no buffering} command describes how to handle
\cdFilename{stderr} output.

\section{Print every 1000 [5 37 93]}

This will be replaced with the \cdCommand{print zone} command.

\section{Print heating}

The relative heating due to each stage of ionization or physical process
is printed.
This is the fraction of the total heating due to this particular
stage of ionization and is printed directly below the relative abundance
of that stage.

\section{Print populations  [H-like carbon, to level 45]}

Level populations are normally not printed for the atoms and ions of
the H-like or He-like isoelectronic sequences.
This will print them.
If
no numbers appear on the line then the first 15 levels will be printed.
Enter the highest level to print on the line as an integer if more are
desired.

If the keyword \cdCommand{He-like} appears then an element on the helium-like
isoelectronic sequence will be printed.
Otherwise an element of the H-like
isoelectronic sequence is chosen.
The code will search for the name of
an element, and if it finds one, will print that element and isoelectronic
sequence.
If none are recognized then populations for \hi\ are printed.

The departure coefficients are printed with the \cdCommand{print departure
coefficients} command.

\section{Print last}

Normally results for every iteration are printed as they are computed.
This command says to print only results for the last iteration.

\section{Print line options}

A large block of emission-line intensities is printed after the
calculation is complete.\footnote{In versions 87 and before, the code printed some relative line
intensities for each zone.  An extra line could be added with the \cdCommand{print
line} command.  This command, and that printout, no longer exists.  Use the
\cdCommand{save line intensities} command instead.} This controls details of that printout.

Some options change the layout of this information.
These include options
to print a single column, to sort the lines by wavelength or intensity,
or to print only the strongest lines, or those within a certain wavelength
range.

Other options indicate line-formation processes.
A great deal of
information about line formation and beaming is stored within the code but
not normally printed to save space.
The section of Part 2 of this document
\cdSectionTitle{The Emission Lines} gives more information.

Some spectra have so many lines that several different transitions may
appear to have the same wavelength.
This occurs to some extent for most
\htwo, \feii, and He-like spectra.
The \cdCommand{set line precision} command allows you to change the number of digits in
the printed line wavelength.
It may be necessary to increase the wavelength
precision if the default line wavelengths are ambiguous and more than one
transition appears with the same wavelength.

\subsection{Print line all}

All of the contributions to line formation, including collisions, pumping,
and heating, will be printed.

\subsection{Print line cell xx}

More than one line can occur within a continuum cell in the output
produced by the \cdCommand{save continuum} command.
This command will print the label for every line that falls into a particular
continuum cell.
The number of the cell, with the lowest energy cell being 1,
must appear.

\subsection{Print line collisions}

Collisions are often the dominant contributor to an optically thick
resonance line.
This adds an entry with the label \cdCommand{Coll}
followed by the wavelength and the collisional contribution.

\subsection{Print line column [linear]}

The main block of emission lines is normally printed with four lines
across the page.
This command says to print lines as a single column to
make it easier to enter into a spreadsheet.
The keyword \cdCommand{linear} will cause
the intensities to be printed as the linear flux in exponential format rather than as the log.

\subsection{Print line cumulative}
\label{sec:CommandPrintLineCumulative}

In a time-dependent simulation the main block of emission
lines give the emission for the current time step.
This command says to also print the time-integrated line emission,
referred to as the cumulative emission.
This ``spectrum'' is the total energy emitted in the lines,
with units $\ergpscm$.

\subsection{Print line faint -2 [\_off]}

\Cloudy\ will normally print the intensities of all emission lines with
intensities greater than $10^{-3}$ of the reference line,
which is usually H$\beta$.
This changes the limit to the relative intensity of the weakest line to
be printed.
The argument is either the log (if $\le 0$) or the linear (if
positive) intensity of the weakest line to print, relative to the reference line.
The \cdCommand{\_log} option will force interpretation as a log.
The reference
line is usually H$\beta$,
and can be changed with the \cdCommand{normalize} command.
In the case shown here, only lines with intensities
greater than 1\% of H$\beta$ will be printed.

If no numbers are entered, but the keyword \cdCommand{\_off} appears then all lines
are printed, even those with zero intensity.

\subsection{Print line flux at Earth}
\label{sec:line:flux:earth}

If the distance to an object is set with the
\cdCommand{distance} command and line luminosities are predicted
then this command says to print the observed
flux at the Earth rather than the line luminosity.
The units are ergs cm$^{-2}\mathrm{s}^{-1}$.
(No correction for interstellar extinction is included, of course).
Both the keywords \cdCommand{flux} and \cdCommand{Earth} must appear.
This command can be
combined with the \cdCommand{aperture}
command to simulate observing only part of
a spatially-resolved object.

\subsection{Print line heat}

Fluorescent excitation is included as a line formation process.
If a line is radiatively excited but then collisionally deexcited
it will heat rather than cool the gas.
This option prints the heating due to line
collisional de-excitation.
The entry will have the label \cdCommand{Heat} followed
by the wavelength.

\subsection{Print line H2 electronic}

By default only ro-vibrational lines within the ground electronic state
of \htwo\ are included in the emission-line printout when the
large \htwo\ molecule
is included with the \cdCommand{atom H2} command.
This command
tells the code to also print electronic transitions.

\subsection{Print line inward}

Optically-thick emission lines are not emitted isotropically.
The
``inward'' fraction of the line is the part that is emitted from the
illuminated face of the cloud into the direction towards the source of
ionizing radiation.
This will generally be greater than 50\% of the total
intensity if the line is optically thick.
This command prints this inward
fraction with the label ``Inwd'' followed by the wavelength.

The optical depth scale must be fully converged for the inward
intensity to be predicted.
Use the \cdCommand{iterate to convergence} to do this.

\subsection{Print line iso collapsed}
\label{sec:CommandPrintLineIsoCollapsed}

The model atoms for the iso-electronic sequences have both resolved and
collapsed levels.
Only predictions from the resolved levels are printed
by default.
This command will also print predictions from the collapsed
levels.
The model atoms do not a good representations of lines that come from the highest
collapsed level.
Only lines coming from the lowest $n-1$ levels are printed at the end of the calculation.

\subsection{Print line optical depths [\_off, faint]}

Mean line optical depths are not printed by default\footnote{Line center optical
depths were printed through version C10.  Mean line optical depths
are now reported.  Line center optical depths are 
$\sqrt{ \pi}$  times smaller than mean optical depths.}.
The option tells the
code to print them at the end of the iteration.
There are two optional
keywords.

If \cdCommand{\_off} appears then line mean optical depths will not be printed.  This is
useful if turned on in a previous iteration and no longer needed.

The keyword \cdCommand{faint} sets the smallest line mean optical depth to print.
The
default smallest mean line optical depth to print is 0.1.
The log of the limit
must be given.
Optical depths for all lines that mase are printed.

\subsection{Print line pump}

All lines include fluorescent excitation by the attenuated incident
continuum as a line formation process.
Continuum pumping will often be
the dominant formation mechanism for optically-thin high-excitation lines.
This option prints an estimate of the contribution to the total line
intensity from this process.
The entry will have the label ``Pump'' followed by the wavelength.

\subsection{Print line sort wavelength [range 3500A to 1.2m]}

The output spectrum to be sorted by wavelength rather than by
ion.\footnote{The \cdCommand{print sort} command existed but did not function between 1986
and 2001.  It became functional again with version 96 but was moved to become
an option on the \cdCommand{print line} command.}
It was originally added by Peter G. Martin.
If the \cdCommand{range} option appears
then two more numbers, the lower and upper bounds to the wavelength range,
must also appear.
Each number is interpreted as the wavelength in Angstroms
by default, but is interpreted as the wavelength in microns or centimeters
if the wavelength is immediately followed by a ``c'' or ``m.''
The two
wavelengths must be positive and in increasing wavelength order.

\subsection{Print line sort intensity}

The predicted emission lines will be sorted in order of decreasing
intensity.

\subsection{Print line sum}

This prints the sum of the intensities of an arbitrary set of emission
lines.
This can be useful for applications such as the \citet{Stoy1933} energy
balance method of determining stellar temperatures, which rely on the sum
of a set of observed line intensities relative to a recombination line (see also \citealp{Kaler1991} and section 5.10 of AGN3).
The sum is printed
as the last entry in the emission-line array as an entry with the label
``Stoy'' and a wavelength of~0.

Each emission line included in the sum is entered on its own line.  This
list begins on the line after the \cdCommand{print line sum} command and continues until
a line with \cdCommand{end} in the first three columns appears.
The line label must
occur as the first four characters on each line and the line wavelength
must appear as it does in the printout.
The default units of the wavelengths
are Angstroms and any other units must be specified.
The following gives
an example of its use.
\begin{verbatim}
print line sum
o  3 5007
totl 3727
o  1 6300
O  3  51.80m
S  3  18.67m
s  3 9532
end of lines
\end{verbatim}

Up to 30 lines can be entered into the sum.

\subsection{Print line surface brightness [arcsec]}
\label{sec:CommandPrintLineSurfaceBrightness}

By default the line intensities that are printed after the calculation
is complete is given as $L$ [erg~s$^{-1}$] for the luminosity case and
$4\pi J$[erg cm$^{-2} \mathrm{s}^{-1}$] for the intensity case.
This command will change these
intensities into surface brightness units.
The default is per steradian
but if the keyword \cdCommand{arcsec} appears then the surface brightness will be per square arcsec.

\section{Print macros}
This prints the name and status of the macros that are used in the
\cdFilename{cddefines.h} header file.
These macros are either set by the user at compiler time with the
\cdMono{-DMACRO} option on the compile command or by the compiler itself.

\section{Print off}

This turns off the print out, as with the \cdCommand{print quiet} command.  This is normally paired with a later \cdCommand{print on} command
to avoid printing parts of the output.

There is a possible problem.
The code can read its own output as input,
to make it easy to rerun a model.
In many initialization files the following
pair of commands appears:
\begin{verbatim}
print off
commands ....
print on
\end{verbatim}

The resulting output will print the first \cdCommand{print off} command, but will
not print the commands or the \cdCommand{print on} command.
If this output is used
as input no further output will be created for the new model.
This problem
will not occur if the \cdCommand{print off} command includes the keyword
\cdCommand{hide}.

\section{Print on}

This command turns on printout.
This is the opposite of the \cdCommand{print quiet}
or \cdCommand{print off} commands.

\section{Print only [header, zones]}

The keyword \cdCommand{only} shortens the printout somewhat by stopping the
calculation prematurely.
If it appears then another keyword,
\cdCommand{header} or
\cdCommand{zones}, must also appear.
The command \cdCommand{print only header} will cause the code
to stop after printing the header information.
The command \cdCommand{print
only zones}
will cause the code to return after printing the zone results on the first
iteration.
In both cases the calculation ends during the first iteration.

\section{Print path}

The path giving the location of the data files will be printed.

\section{Print quiet}

This sets \Cloudy's quiet mode, in which nothing is printed at all.
Printing can be turned off and then restarted at a particular zone by using
the \cdCommand{print starting at} command described below.

\section{Print recombiantion}

This reports the dielectronic and radiative recombination rate coefficients
at the current temperature.
An indication of the reference used for each ion is also give.

\section{Print short}

This shortens the detailed final printout.
Only the emission lines and
a short summary of some thermal properties of the model will be printed.

\section{Print starting at 61}

This option turns off \emph{all} printout \emph{until} the specified zone is reached.
This should come last in the input stream since command lines appearing
after it will not be printed.

\section{Print version}

This prints the code, compiler, and operating system versions, along
with other information.

\section{Print Voigt a=1.2e-3}

This prints two forms of the Voigt function and their ratio.
The damping constant must appear on the line.

\section{Print zone 1000 [5 37 93]}

\Cloudy\ will always print the results for the first and last zones.  This
command varies the number of zones printed between these two.
If more than
one number is entered then each applies to successive iterations.  The
example above will print every 1000 zones on the first iteration, every
5 zones on the second iteration, 37 on the next, etc.  If there are fewer
numbers entered than iterations performed then the last number entered will
be used for all further iterations.

\section{Save commands}

\subsection{Overview}

\cdCommand{Save} commands save results into a file that can be used later.
They
are the primary output mechanism for \Cloudy.
There are many options.
For
instance, physical quantities as a function of depth into the cloud,
including temperature, ionization, and density, can be saved for later
plotting.
The emitted spectrum, or other quantities predicted by the code,
can be output.
The general idea is for the file produced by this command to then
be post-processed by other plotting or analysis programs to produce final
results.

One keyword must appear and only one keyword per line is recognized.
Up to 100 \cdCommand{save} commands can be entered.

\subsection{Save vs punch commands}
In versions C08 and before the \cdCommand{save} command was
called \cdCommand{punch}.
``Punch'' was an output option in FORTRAN IV and was implemented by 
machines that produced holes on 
\href{http://en.wikipedia.org/wiki/Punched_card}{Hollerith cards}.
Those machines and cards now exist only in museums. 
This version of \Cloudy\ continues to accept
\cdCommand{punch} as an alias for \cdCommand{save}.

\subsection{An output file name must appear inside double quotes}

Each \cdCommand{save} command must specify a file name\footnote{In versions 90 and before Fortran default save units, with names
like fort.9, could be used for save output.  The filename must be specified
with versions 91 and later.} for the resulting output.
This file name must appear between a pair of double quotes as in
\cdFilename{"output.txt"}.
It must be a valid file name for your operating system.
The following is an example.
\begin{verbatim}
save overview "model.ovr"
\end{verbatim}
The code will stop if a valid file name is not present.

\subsection{Setting a prefix for all save files}

A prefix can be set for all filenames with the
\cdCommand{set save prefix} command 
(see Section \ref{sec:CommandSetSavePrefix}).
This makes it possible to set a prefix only one time for several save files, as in
\begin{verbatim}
set save prefix "Den11"
save overview ".ovr"
save continuum units micron ".con"
\end{verbatim}
The files \cdFilename{Den11.ovr} and \cdFilename{Den11.con}
will be created. 

\subsection{The ``last iteration'' option}

Each \cdCommand{save} command also has a keyword \cdCommand{last} that will cause the output
to only be produced on the last iteration.
It this keyword does not appear
then output will be produced for every iteration.
The results of each
iteration are separated by a line of hash marks (``\#\#\#'').
In grid runs this behavior will be slightly modified. See the
description in Section~\ref{sec:GridOutputOptions}.

\subsection{The ``no buffering'' option}

If the option \cdCommand{no buffering} appears then
file buffering will be turned
off for that file.
This slows down the output considerably but ensures
that all output will exist if the code crashes.
There is also a stand-alone
\cdCommand{no buffering} command to turn off buffering
for the code's standard output.

\subsection{The ``clobber/no clobber'' option}

When the code is used as a stand-alone program to compute a
single model
it will open the save file at the start of the calculation and close it
at the end.
In a sequence of models as in an optimization run this will
happen for each new model and so will overwrite results of all previous
calculations.

The \cdCommand{no\_clobber} keyword on the \cdCommand{save} command
will produce one long file
containing results of consecutive models.
It tells the code to never close
the file at the end of any but the last calculation and not try to reopen
this file once it is open.

The default, with one exception, is to overwrite files.
The
\cdCommand{grid} command computes a series of simulations with a single
input file.
The entire set of output is usually needed so the default
in this single case is to not overwrite files,
but rather produce one large file.

Include the \cdCommand{clobber} keyword if you want to overwrite files,
and the \cdCommand{no clobber} keyword if you want one
large save file with successive predictions.

\subsection{The ``no hash'' option}
\label{sec:SaveNoHashOption}
When more than one iteration is done the results of each iteration end
with a series of hash marks, ``\#\#\#'', to make the start of each iteration easy to find in an editor.
These hash marks can cause problems if the
file is then read in by other programs.
The hash marks will not be produced
if the \cdCommand{no hash} keyword appears.

The character string that is printed between iterations can be changed
with the \cdCommand{set save hash} command
described on page \pageref{sec:CommandSetSaveHash}.

\subsection{The ``title'' option}

The title\footnote{The title was printed by default in versions 95 and before of the
code.  The title was generally deleted so that the save file could be used
to make plots so it is now missing by default.} of the model and the version number of the code will be printed
on the first line of the save file.

\subsection{The ``separate'' option}
\label{sec:save:separate}

The default behavior of the code is to concatenate save output from different
models in a grid run into a single large file. The only exception to this is
the \cdCommand{save FITS} command since it would violate the FITS standard to
combine multiple FITS spectra into a single file. If the keyword
\cdCommand{separate} is included on the save command line, each model in the
grid will produce a separate save file. They will have names
\cdFilename{grid000000000\_filename}, \cdFilename{grid000000001\_filename},
etc., where \cdFilename{filename} is the file name you supplied between double
quotes. The meaning of the grid index embedded in the filename can be found
with the \cdCommand{save grid} command described in
Section~\ref{sec:save:grid}. When the save output is split up, only the first
file will contain the save header.

\subsection{Depth versus radius}

The code and this documentation make a consistent distinction between
depth and radius.
The \cdTerm{radius}
is the distance from a point in the cloud to the center of symmetry,
generally the center of the central object.
The \cdTerm{depth} is the distance from
a point in the cloud to the illuminated face of the cloud.
In both cases
the distance is to the center of the current zone.

The output from each \cdCommand{save} command is described in the following sections.
In those cases where quantities are given as a function of position into
the cloud, the first column will usually give the depth, not the radius.
You need to add the inner radius of the cloud to the depth to get the radius.

\section{Save abundances}

The log of the gas-phase densities [cm$^{-3}$] of the elements will be saved
for each zone.
This is the sum of the abundances of a chemical element
in atoms, ions, molecules, and ices, but does not include grains.
This provides a check for the effects of the \cdCommand{element table}
and \cdCommand{fluctuations abundances} commands.

\section{Save ages}

The timescales for several physical processes will be saved as a
function of depth.

\section{Save agn [options]}

This produces output files that were used to create data tables in the
2$^{\mathrm{nd}}$ edition of \emph{Astrophysics of Gaseous Nebulae}, referred to as AGN3 here.
The options are the following:  \cdCommand{charge} transfer,
\cdCommand{recombination} coefficients,
\cdCommand{recc} for hydrogen recombination cooling, \cdCommand{opacity},
\cdCommand{hemis}, and \cdCommand{hecs} (for He$^0$
collision strengths).

\section{Save monitors}

The \cdCommand{monitor} command provides
an automated way to validate the predictions of the code.
Normally the
results from these checks will be printed on the standard output.
If this
command appears then the same output will also be sent to a file.

\section{Save average \dots}
\label{sec:CommandSaveAverage}

This reports averages of various quantities.
It was included as a way
to bring together information generated with the \cdCommand{grid} command.

The \cdCommand{save} command is followed by a series of lines
which say which average to generate.
These end with a line that starts with the word \cdCommand{end}.
The following is an example:
\begin{verbatim}
save averages, file="hii.avr" last no clobber
temperature, hydrogen 1 over volume
ionization, helium 2 over radius
column density oxygen 3
end of averages
\end{verbatim}

\subsection{Temperature average}

The keyword \cdCommand{temperature} begins the line.
The average temperature can
be weighted with respect to any atom or ion.
The name of one of the elements
and the ionization stage, 1 for the atom, 2 for the first ion, etc,
then follow.

The code computes averages weighted over radius or over volume.
If the
keyword \cdCommand{volume} appears then the volume-weighted mean temperature will be
reported.
The default is weighting over radius.
The log of the temperature
is reported.

The command works by calling \cdRoutine{cdTemp} described in
Part 2 of this document.
This command has all the options described there.

\subsection{Ionization average}

This reports the average ionization fraction of an atom or ion.
The
keyword \cdCommand{ionization} begins the line.
It is followed by the name of one of
the elements, then the ionization stage, 1 for the atom, 2 for the first
ion, etc.

The code computes ionization fractions weighted over radius or over
volume.
If the keyword \cdCommand{volume} appears then the volume-weighted fraction
will be reported.
The default is weighting over radius.
The log of the
ionization fraction is reported.

The hydrogen molecular fraction $2n\left( {{\mathrm{H}}_2 } \right)/n\left(
{{\mathrm{H}}_{tot} } \right)$
can be obtained by asking for ionization stage 0 of the element hydrogen.
This is a special case.
Other molecular fractions cannot now be obtained.

The \cdCommand{save ionization means} command described on 
page \pageref{sec:CommandSaveIonizationMeans} will save
the mean ionization of all elements in the save form as that given
at the end of the standard output.

\subsection{Column density}

The log of the column density of any atom or ion is reported.
The keyword
\cdCommand{column density} begins the line.
It is followed by the name of one of the
elements, then the ionization stage, 1 for the atom,
2 for the first ion, etc.

\section{Save chemistry options}

\subsection{Save chemistry rates ``filename'' species ``molecule''}
\label{s:savechemrate}

This command saves rates for molecular reactions involving a specific
species.  Due to current design constraints, the molecule name must come 
second at present.

By default, all non-catalytic rates will be printed.  
There are several optional keywords to change this.
The keywords \cdCommand{creation} and \cdCommand{destruction}
select only those reactions which create or destroy the species, respectively.
The keyword \cdCommand{catalytic} selects all reactions for which 
the specified species acts as a catalyst. 
Finally, the keyword \cdCommand{all} prints all reactions, including the catalytic ones.

\section{Save column density}

The column densities [\pscm] of the gas
constituents are saved.
\begin{description}
\item[save column density] will report column densities of all
molecules and ions.

\item[save some column densities] allows you to specify which column densities
to output.  The code reads in a series of lines that give chemical elements
and ionization stages.  These end with a line that starts with \cdCommand{end}.  The
logs of the column densities of these species will be output in one line
with each column density separated by a tab character.  The following is
an example:
\end{description}
\begin{verbatim}
save some column densities "test.col"
hydrogen 2
helium 2
carbon 2
end of column densities
\end{verbatim}
The name of a chemical element must appear in the first four columns of
each line and be followed by the ionization stage.
One is the atom, 2 the first ion, etc.

The column densities in molecules or in levels within an ion can be
obtained.
The command works by saving the first four letters on each line
together with the ionization stage.
These are then passed as the first
two arguments to \cdRoutine{cdColm},
a routine described in
Section~\ref{Hazy2-sec:SubroutineCdColm} of Hazy 2
``\cdSectionTitle{\refname{Hazy2-sec:SubroutineCdColm}}''.
That section describes how to find
molecular or state-specific column densities.
If the ion stage is one or
greater than the species will be interpreted as an atom or ion.
An ion
stage of zero indicates that one of the special cases listed where
\cdTerm{cdColm}
is described.
As an example, the following will obtain the column densities
of molecules and levels
\begin{verbatim}
save some column densities "test.col"
H2   0   // the hydrogen molecule
CO   0   // the carbon monoxide molecule
C11* 0   // the J = 0 level of atomic carbon
end of column densities
\end{verbatim}
This command can be combined with the \cdCommand{save grid} command
to save predictions from a series of grid calculations.

The \cdCommand{save FeII column density} command and
\cdCommand{save H2 column density} commands are described elsewhere.

\section{Save continuum}
\label{sec:CommandSaveContinuum}

This command is a primary mechanism for saving the predicted
spectrum.

\subsection{Lines in the spectrum}

Emission lines are included in the output for all
\cdCommand{save continuum} commands
except \cdCommand{save transmitted continuum}.
They are visible in the net emitted
continuum.
Labels giving the strongest lines contributing to each wavelength
are given in the third to last column in the save output.
More than one
line will contribute to many wavelength cells and the last column indicates
the number of lines within that cell.

The \cdCommand{print continuum indices} command will list
the labels for all lines that enter into each cell.
This provides a way
to see all lines that contribute.
The \cdCommand{print line sort wavelength} can be used to understand the 
relative contributions when multiple lines contribute
at a particular wavelength or energy.

Figure \ref{fig:WarmAbsorberReynoldsFabian} shows the incident
SED as the smooth red line, while the black line gives 
the net emission with a warm absorber long the line of sight. 

\begin{figure}
\centering
\begin{centering}
\includegraphics[scale=0.9]{WarmAbsorberReynoldsFabian}
\caption[Incident and net emission]{
\label{fig:WarmAbsorberReynoldsFabian}
The predicted X-ray spectrum of a warm absorber 
in an Active Galactic Nucleus. Prominent emission and absorption lines are present along with broad 
UTA absorption features. The parameters are from Reynolds \& Fabian (1995, MNRAS, 273, 1167).}
\end{centering}
\end{figure}

\subsection{Emission line - continuum contrast}

In a real spectrometer the line-to-continuum contrast
depends on the spectrometer resolution if a line is unresolved.
The higher the resolution, the higher the line will appear in the spectrum.
In \Cloudy, lines are  unresolved on the coarse continuum mesh that is reported
in most versions of the \cdCommand{save continuum} command.
The default behavior of \Cloudy\ is to add the emission-line intensities directly to the continuum.
This assures that the flux in the line is conserved. 

Real spectrometers may have significantly higher or lower resolution than 
\Cloudy 's coarse continuum.
The \cdCommand{set save line width / resolution} command,
described on page \pageref{sec:CommandSetSaveLWidth}, 
changes the lines relative to the continuum to make the spectrum
look like that observed with a spectrometer with a resolution that is different
from the coarse continuum.
Changing the velocity width with the
the \cdCommand{set save line width} command  
has the same effect as changing the 
velocity resolution of a spectrometer measuring an unresolved line.
Smaller velocity widths will make the line rise higher above the continuum.
Alternatively you can also use the \cdCommand{set save resolution}
command to specify the spectral resolution of a spectrograph. Higher
values for the resolution will make the line rise higher above the continuum.

Note that this command will {\em only} adjust the height of the line, not the
width. The latter will always be the width of one cell in the coarse continuum mesh
(even if the line is broader than that cell). This implies that
the line flux in the continuum array is artificially changed by the
\cdCommand{set save line width / resolution} command.
Changing the spectral resolution can be useful to emphasize weak lines in a plot,
but should never be used when energy conservation is important, e.g. when
you want to postprocess the file to fold the saved continuum with a photometric passband.
\subsection{Pumped contributions to the lines}

Continuum pumping and fluorescence are included as excitation processes
for all lines.
These contributions are usually not printed as a separate
quantity but will be if the \cdCommand{print line pump} command is entered.  Whether or not the pumped contribution actually
adds to the observed line emission depends on the geometry.
Continuum
pumping increases the line emission if no related continuum absorption is
seen by the observer.
This will be the case if the continuum source is
either not observed or not covered by absorbing gas on the observer's line
of sight.
If absorbing gas covers an observed continuum source then the
situation is like the P Cygni problem, emission produced by absorption
and pumping will not increase the total intensity of the line at~all.

The line intensity includes fluorescent excitation unless the
\cdCommand{no induced processes} command is entered.
That command is unphysical since it turns
off all induced processes.
You can judge how great the contribution of
the pumped part of the line is by printing it with the
\cdCommand{print line pump} command.

In general the treatment of scattering is very geometry dependent.
The
output produced by the \cdCommand{save continuum} commands \emph{does not} include the pumped
part of the line contribution.
This is correct if the continuum source
is included in the beam, but is not if only the gas is observed.

\subsection{The units option - changing the continuum units}
\label{output_units}

By default, the energy units for the first column, which gives the
wavelength or energy for each point in the continuum, are Rydbergs.  The
units can be changed to any of several energy or wavelength units with the
\cdCommand{units} keyword that appears on a \cdCommand{save continuum} command.  The following
keywords are recognized: \cdCommand{\_micron}, \cdCommand{\_eV\_}, \cdCommand{\_keV},
\cdCommand{\_MeV}, \cdCommand{wavenumber}, \cdCommand{centimeter} (also
\cdCommand{\_cm\_}), \cdCommand{\_mm\_}, \cdCommand{\_nm\_}, \cdCommand{Angstrom},
\cdCommand{\_Hz\_},\cdCommand{\_kHz}, \cdCommand{\_MHz}, \cdCommand{\_GHz},
\cdCommand{Kelvin} (also \cdCommand{\_K\_}), \cdCommand{erg\_}, and
\cdCommand{\_Rydberg}.
Both the keyword \cdCommand{units} and one of
these units must appear for the units of the energy scale to be changed.

\subsection{Units of the save output}
The units of the predicted continuum depend on whether the intensity
or luminosity case is used.
In the intensity
case continua are given as the intensity per octave
$ 4\pi \,\nu J_\nu [\ergpscmps ]$.
In the luminosity case they are
${{\nu L_\nu  }/{4\pi r_{\mathrm{o}}^2 }}$
[$\ergpscmps $] relative to the inner radius
of the cloud so the
monochromatic luminosity per octave is the predicted quantity
multiplied by $ 4\pi r_{\mathrm{o}}^2$.

\subsection{Save continuum predictions}

The \cdCommand{save continuum} command,
with no other keywords,
produces a file
with the following information.
The different contributors to the continuum
are defined in the Chapter \cdSectionTitle{Definitions}.

\begin{description}
\item[Column 1.]  The first column gives the photon energy in the units set
with the \cdCommand{units} option.  The default
units are Rydbergs.

\item[Column 2.]  This is the incident continuum at the illuminated face of
the cloud.

\item[Column 3.]  This is the transmitted incident continuum and does not include
diffuse emission from the cloud.

\item[Column 4.]  This is the outward portion of the emitted continuum and line
emission.  This includes a covering factor if one was specified.
The total emission from the cloud will
be this multiplied by the inner area of the cloud.  This does not include
the attenuated or reflected portions of the incident continuum.

\item[Column 5.]  This gives the net transmitted continuum,
the sum of the
attenuated incident (column 3) and diffuse (column 4) continua and lines.
This would be the observed continuum if the continuum source were viewed
through the gas.  It includes the covering factor.

\item[Column 6.]  This is the reflected continuum
and is only predicted for an open geometry.

\item[Column 7.]  This is the sum of the transmitted and reflected continua
and lines.  The attenuated incident continuum is included.

\item[Column 8.] The sum of all reflected line emission.

\item[Column 9.] The sum of all outward line emission.

\item[Column 10 and 11.]  Line and continuum labels indicate the lines and
continuum edges that might contribute at that energy.  The line label gives the
label for the strongest line in the total spectrum (reflected plus outward) 
the line-center of which lies in that bin. 
(This is new in C10.  All previous versions simply reported the first line 
encountered, as is still the case with the continuum label.)   
The continuum labels are established when the code
is set up and they do not mean that the continuum feature is actually
present in the spectrum.  

\item[Column 12.]  This gives the number of emission lines within that continuum
bin, divided by the ratio of the energy width of the cell to the cell's
central energy, $dE/E$.  So this is the number of lines per unit relative
energy.
\end{description}

\subsection{What is observed}

Figure \ref{fig:EmissionSaveComponents} illustrates several
possible geometries.
Two lines of sight to the central object are shown,
and two clouds are shown.
Each cloud produces both a reflected and transmitted emission component.

\begin{figure}
\centering
\begin{centering}
\includegraphics[scale=0.9]{EmissionSaveComponents}
\caption[Radiation field components]{
\label{fig:EmissionSaveComponents}
This figure illustrates several components of the radiation field that enter in
the calculations.}
\end{centering}
\end{figure}

Three possible geometries, indicated by the letter on the figure, occur
depending on how we view the central source and clouds: a) we do not directly
observe the central object although we may see it by reflection from the
illuminated face of a cloud, b) we observe the transmitted continuum and
the outward emission from the emitting cloud, and c) we observe the
unattenuated continuum directly without absorption.
Column 2 gives the
unattenuated continuum, and column 3 gives the attenuated continuum.

There are also three possible situations for the line emission.
First,
we might only observe clouds that lie on the near side of the continuum
source.
In this case we see the ``outward'' line emission.
Second, we
might only observe clouds that lie on the far side of the continuum source.
In this case we only see the ``reflected'' or inward component.
Lastly,
we might observe a symmetric geometry with reflected emission from the far
side and outward emission from the near side.

In most cases an observer at large distance from the structure would
observe \emph{both} the central object and the cloud and would measure the quantity
listed in column 5 (if only transmitted emission is detected) or column
7 (if both reflected and transmitted continua are seen).  If the central
object is not seen then the quantity in column 4 would be observed.

\subsection{Save continuum bins}

This saves the continuum energy bins.
The first column is the center
of the bin.
The second column, which is nearly equal to the first, is the
mean energy of the cell, weighted by the continuum shape.
This has a slight
dependence on the continuum shape.
The last number is the cell width $\delta\nu$.
The bin extends from $\nu-\delta-\nu/2$ to $\nu+\delta\nu/2$.

\subsection{Save cumulative continuum}
\label{sec:CommandSaveCumulativeContinuum}

This gives the continuum integrated over a time-dependent simulation.
The usual \cdCommand{save continuum} command gives the
continuum for the current time step in these calculations.
The units of the usual \cdCommand{save continuum} command
are flux per octave, $\nu f_{\nu}\; [\ergpscmps ]$.
This command gives the time-integraded energy,
$\nu E_{\nu}\; [\ergpscm ]$.

\subsection{Save diffuse continuum}

This reports the local diffuse line and continuous emission
coefficient $4 \pi \nu j_{\nu}$ [\ergpccmps ].
Optical depth effects are not included.

By default this reports the diffuse emission from the last zone.
The first column of the output gives
the photon energy including the \cdCommand{units} option.
The second column gives the diffuse continuous emission.
The third column gives the line emission in the same units,
including the effects of the
\cdCommand{set save line width / resolution} command described on page
\pageref{sec:CommandSetSaveLWidth} when appropriate.
The last column gives the total.

If the keyword \cdCommand{zone} appears then the diffuse emission
\emph{from every zone} will be reported.
The first row gives the wavelength or energy scale.
The remaining rows give the total (line and continuum)
emission coefficients $4 \pi \nu j_{\nu}$
at each energy.

\subsection{Save continuum emissivity 12 [units micron]}

This command will save the continuum volume emissivity $4\pi \nu j_\nu$ (in
\ergpccmps), as well as the local absorption and scattering opacity (in
cm$^{-1}$) as a function of radius and depth (in cm). This output can be used by an
external program to do more specialized radiative transfer, e.g.\ to determine
the continuum flux through an aperture. To make this process second-order
accurate, the radius and depth in the middle of each zone is reported. One number should
be supplied on the command line, which is the wavelength / frequency at which
the emissivity and opacity will be evaluated. You can use the keyword
\cdCommand{units} as described in Sect.~\ref{output_units}. By default the
frequency is assumed to be in Rydberg.

\subsection{Save emitted continuum}

The continuum emitted and reflected from the nebula is saved.
The
first column is the photon energy.
The second column is the reflected
spectrum.
The third column is the outward diffuse emission.
The fourth
column is the total emission (the sum of the inward and outward emission).
This would be the observed emission from the nebula if the central continuum
source was not in the beam but clouds uniformly cover the continuum source.
The last two columns are labels for lines and continua contributing at each
energy.
The attenuated incident continuum is not included in any of these
components.
All continua have units
$\nu f_{\nu}$ [\ergpscmps ]
at the inner radius.

\subsection{Save fine continuum [range, merge]}

The code transfers the continuum on a coarse mesh, needed for speed in
evaluating photo-interaction rates, and on a fine mesh, needed for automatic
treatment of line overlap.
The coarse continuum is the one given in output
from the \cdCommand{save continuum} command and it includes all the components shown in Figure \ref{fig:EmissionSaveComponents}.
The fine continuum gives
a normalized attenuated incident continuum and does not include diffuse
emission from the cloud.  This multi-grid approach is needed to combine
precision and speed.  This command will output the transmission coefficient,
$I_{transmitted}/I_{incident}$, for the fine continuum.

The resulting output will be huge if the entire fine continuum is saved.
The command accepts a \cdCommand{range} option to limit the size of the output file.
If the keyword \cdCommand{range} appears then
the lower and upper limits to the range
of the fine continuum must be entered.
The command also accepts
a \cdCommand{units} option,
described on \pageref{output_units}, to change the units used
in the specified energy range, and in resulting output.
The optional third numerical parameter gives the number
of fine continuum cells to average together, again with the intent of
reducing the size of the output file.  The default is to average over 10
cells.  If the number of cells to be combined is specified then it must
be the third number on the command line, following the limits
of the range.

\subsection{Save grain continuum}

The thermal emission by grains is part of the emergent continuum.  This
command saves only the grain emission in the optically thin limit for
the last zone.  It is mainly intended as a debugging aid.

The first column gives the photon energy in the units specified with
the \cdCommand{units} option.  The second column gives the total emission from
carbonaceous grains (including amorphous carbon and PAH's).  The third column
gives all emission from all constituents that are not carbonaceous.  In
practice this will be mainly the silicates.  The last column gives the sum
of the two.

\subsection{Save incident continuum}

The incident continuum, that emitted by the central object and striking
the illuminated face of the cloud, will be saved.  The two columns give
the photon energy and the continuum $\nu f_{\nu}$ [erg cm$^{-2}
\mathrm{s}^{-1}$].

\subsection{Save interactive continuum}

This gives the integral of the product of the internal radiation field
times the gas opacity.  The results are produced for each zone and give
the attenuated incident continuum, the OTS line, the OTS continuum, the
outward continuum and the outward lines.  The first optional number is the
lowest energy in the output.  If missing or zero, the lowest energy
considered by the code will be used.  Numbers less than 100 are interpreted
as the energy in Rydbergs and those greater than 100 as the cell number.

\subsection{Save ionizing continuum [options]}

This creates a file that can be used to indicate ionization sources.
If the keyword \cdCommand{every} occurs then this is saved for every zone, otherwise
it is only saved for the last zone.

The first optional number on the command line is the lowest energy to
include in the output.  If it is missing or zero then the lowest energy
considered by the code will be used.  It is interpreted as the energy in
Rydbergs if the number is less than 100 and as the cell number if it is
greater than 100.  The second optional number is the threshold for the
faintest interaction to print.  The default is one percent of the quantity
given in the \cdMono{rate/tot} column.
Enter zero for this number if you want
all interactions to be printed.  The optional numbers may be omitted from
right to left.

The first column in the resulting output is the cell number
of the C scale, so the first cell is zero.
Next comes the photon energy
in Rydbergs unless changed with the \cdCommand{units} option.  The third column, with
the header \cdMono{flux}, is the flux of photons within this frequency bin
(\emph{not}
per unit frequency) with units s$^{-1}$~cm$^{-2}$.  The forth column gives the
photo-interaction rate, the product of the flux multiplied by the gas
absorption cross secton
[cm$^{-2}$] and so with units s$^{-1}$.  The next five numbers are the fractions of
this photo-interaction rate due to the attenuated incident continuum, the
OTS line, the OTS continuum radiation fields, and the outward lines and
continua.  The 10$^{\mathrm{th}}$ column, with the heading \cdMono{rate/tot}, is the ratio
of this photo rate to the total integrated radiation-field interaction rate.
The next column, with the heading \cdMono{integral}, is the integrated cumulative
interaction, the integral of the previous column over energy.  This makes
it easy to identify the portions of the radiation field that have the
dominant interaction with the gas.  The last two labels on the line indicate
which lines and continua contribute at that energy.

\subsection{Save NLTE continuum}
This saves a version of the emitted spectrum in the units required by
the NLTE7 workshop.  See Section \ref{sec:NLTEoutput} for more details.

\subsection{Save outward continuum}

The photon energy is followed by the attenuated incident continuum, the
outwardly directed diffuse continuum, the outward lines, and the sum of
the two.  If the \cdCommand{local} keyword also appears then only the outward continuum
produced in the last computed zone will be saved.

\subsection{Save raw continuum}

This saves the \cdTerm{raw} continua.
This is exactly the continuum used
within the code.  The first number is the photon energy.  The next columns
are the contents of many of the continuum arrays at each energy.  Consult
the source to see which arrays are now saved.  Each gives the number of
photons stored in that cell with units photons s$^{-1}$ cm$^{-2}$
cell$^{-1}$.  The last
number is the number of lines within that cell.

\subsection{Save reflected continuum}

The reflected continuum is output if \cdCommand{sphere} is not set.  The first column
is the photon energy, the second the reflected continuum $4\pi \,\nu J_\nu
$ [erg  cm$^{-2}$~s$^{-1}$] at that energy.  The third gives the reflected lines
and the fourth is the sum of these two.  Someone who could only see the
illuminated face of the cloud would observe this.  The next column is the
effective albedo of the cloud, the ratio of the reflected to incident
continuum (the \cdCommand{save total opacity} command will give the
true albedo).  The last column gives the label
for continuum processes with thresholds at each energy.

\subsection{Save transmitted continuum}

This saves the transmitted (attenuated incident and outward component
of diffuse) continuum predicted at the end of the calculation.

This save file can be used as part of the incident continuum in a later
calculation by reading it with the \cdCommand{table read} command.
Three cautions apply when reading this file as an
input continuum.  First, if the keyword \cdCommand{last} does not appear on this command
then the continuum from each iteration will be saved and the code will
become confused when it tries to read this file.  You should include the
\cdCommand{last} option on the command since you only want results from the last iteration.
Second, save output should not be written into the same file
as the input file during the second calculation.  The file containing the
first continuum will be overwritten if this occurs.  Finally, the first
two lines contain header information and they are skipped.  They should
not be deleted.

The line-to-continuum contrast factor \cdVariable{Resolution}
set by the \cdCommand{set save line width / resolution} command
(see page \pageref{sec:CommandSetSaveLWidth})
is not used in this command.  This is to insure that lines have
the correct intensity in the save file, as needed for energy conservation.

\subsection{Save two photon continuum}

This saves the total two-photon continuum and is mainly a debugging
aid.  The photon energy is followed by the number of photons emitted per
Rydberg per second, then by $\nu F_\nu$.  The details of two photon emission,
including induced processes, are discussed by \citet{Bottorff2006}.

\section{Save convergence [reason, error]}

These commands produce information about various aspects of the converged
solution.

\subsection{Save convergence base}

The gives computed values of many quantities that are converged during
a calculation.  The values are given as they are at the exit to the base
convergence routine.  Depending on the convergence properties of the
solution, there will be between only a few up to many
dozens of evaluations in each zone.

\subsection{Save convergence error}

This will produce information concerning the quality of the converged
pressure, electron density, and heating-cooling solution.  The correct value,
converged value, and percentage error, (correct-converged) $\times$ (100/correct), will be produced for each zone.

\subsection{Save convergence reason}

This will save the reason the model was declared ``not converged'' at
the end of each iteration when the
\cdCommand{iterate to convergence} command is used.

\section{Save cooling}

This saves the cooling agents for each zone.  The first number is the
depth [cm] followed by the temperature [K].  The next two numbers are the
total heating and cooling rates [erg cm$^{-3}$~s$^{-1}$].  The remaining labels
indicate contributors to the cooling array and the fraction of the total
cooling carried by that agent. The faintest coolant saved is normally
0.05 of the total and can be reset with the \cdCommand{set WeakHeatCool} command.

This is mainly used for debugging and its output is not well documented.
The line labels may, or may not, correspond to labels used in the main
emission-line output.  The code adds individual coolants to the total cooling
by calling routine \cdRoutine{CoolAdd}.
The arguments to that call include the string
and a number that follows it.   To discover the process for a particular
label you will need to search over the entire code to find where that string
occurs in a call to \cdRoutine{CoolAdd}.
The string will be within a pair of double
quotes.
As an example, two coolants that might appear are
\cdTerm{dust 0}, and \cdTerm{H2cX 0}.  A search on the string \cdMono{"H2cX"} (include the beginning and ending double
quotes) will find the string occurring in two places, where the cooling
is added with the call to \cdRoutine{CoolAdd} and another place where the cooling itself
is evaluated.  Comments around the call to \cdRoutine{CoolAdd}
indicate that \cdTerm{H2xC} is
cooling due to collisional excitation within the ground electronic state
of \htwo.   A search on the string \cdMono{"dust"} finds its call to
\cdRoutine{CoolAdd} with
the comment that it is cooling due to grain recombination cooling.

Cooling due to the unified iso-electronic sequences is different since
the label that occurs in the call to \cdRoutine{CoolAdd} is generated by the routine
that evaluates the cooling and does not explicitly occur in the source.
The iso-electronic cooling labels begin with \cdMono{"IS"},
followed by a string
indicating the process, and followed by strings giving the iso-electronic
sequence and the element.  Search for the start of the string but not for
the element name.  An example might be the string
\cdMono{"IScionH H"}.  The \cdMono{"IS}
indicates that it is cooling due to an ion along the iso-electronic sequences
and the two ending H's indicate that the coolant is H-like hydrogen.  The
string \cdMono{"IScion"} occurs in the source and comments indicate that the process
is collisional ionization cooling.  The iso-electronic cooling strings do
not include a pair of double quotes in the source since the ending double
quote occurs after the element names.  You would search for the string
\cdMono{"IScion"}.

\subsection{Save cooling each}

If keyword \cdCommand{each} appear after \cdCommand{save cooling}
command, the cooling of each element and for certain
special cases will be saved for each zone. 
The unit of the cooling rate is [erg cm$^{-3}$~s$^{-1}$]. 
Notice that bremsstrahlung cooling includes H, He, and metals.  
The cooling due to molecules is listed separately.

\section{Save charge transfer}

Charge transfer recombination and ionization rate coefficients
   [cm$^3\mathrm{s}^{-1}$]
for hydrogen onto heavier elements will be output.  The rates will be
evaluated at the temperature of the last computed zone.  Rates for
recombination (${\mathrm{A}}^{ + x}  + {\mathrm{H}}\to{\mathrm{A}}^{ + x + 1}  + {\mathrm{H}}^
+$) are first, followed by the rates for the opposite ionization process.
The first number is the atomic number of the species.

\section{Save Chianti}
\label{sec:CommandSaveChianti}

This saves collision strengths for Chianti transitions over a certain temperature range.
The output gives species, lower level, upper level, wavelength in Angstroms, 
and collision strengths for each temperature given in the header row.
This reports data for all active Chianti species in that particular run.

\section{Save dr}

The logic behind the choice of zone thickness will be described.

\section{Save dynamics options}

This produces some information concerning the dynamics solutions.

\subsection{Save dynamics advection}

This produces information about advection terms.

\section{Save element \emph{name}}

This will save the ionization structure of any element. The output will
have one line per zone giving the ion fraction\footnote{Before version 96 the ionization fractions only included atoms and
ions.  They now include molecules.  The sum of the atomic and ionic fractions
will not add up to unity if a significant fraction of the element is in
molecules.} of each successive stage
of ionization.  The keyword \cdCommand{element} must be followed by the element name.

The first number on the resulting output is the depth [cm] into the cloud.
The remaining lines give the relative ionization fraction of the $n+1$ possible
stages of ionization where $n$ is the atomic number of the element.  These
may be followed by some of the more abundance molecules.

If the keyword \cdCommand{density} appears on the command line then the
density [cm$^{-3}$]
will be given rather than the dimensionless fraction.

\section{Save enthalpy}

The file will list the depth into the cloud, followed by the total
enthalpy, and various contributors to it.

\section{Save execution times}

The code will output the zone number, the time required to compute that
zone, and the elapsed time since the start of the calculation.  This is
intended as a mechanism to identify zones that require large amounts of
work to converge.  
This command is being superseded by the \cdCommand{save performance} command.

\section{Save FeII [options \dots]}
\label{sec:CommandSaveFeII}

This produces some information about the \feii\ atom.  The atom
is only included when the \cdCommand{atom FeII} command,
described on page \pageref{sec:AtomFeIICommand}, is included.

Both ``\cdCommand{FeII}'' with no spaces and ``\cdCommand{Fe II}'' with a space are accepted.
The following examples show the first style but both are correct.

\subsection{Save FeII column densities}

This gives the excitation energy of the levels [wavenumbers], their
statistical weights, and the column densities [$\pscm$].

\subsection{Save FeII continuum}

This reports the pseudo-continuum of \feii\ lines produced
by the large \feii\ atom.

Each output file begins with the photon energy at the center of each continuum bin.
This is given in Rydbergs by default but the
\cdCommand{units} option can be used to change
to other units.
The intensities are the integrated intensity
or luminosity of \feii\ emission over each band.
The units of the intensity in the intensity and luminosity
cases follow those for the
\cdCommand{save continuum} command
(page \pageref{sec:CommandSaveContinuum}).

The output can distinguish between the total, inward, and outwardly
directed \feii\ emission.
This is discussed for the case of quasars by \citet{FerlandHuEtAl2009}.

The \cdCommand{set FeII continuum} command, described on
page \pageref{sec:CommandSetFeIIContinuum}, can be used to adjust
the lower and upper bounds to the energy range and the number
of bins that occur over this range.

\subsubsection{The default four-column output}

By default the photon energy and the total, inwardly directed, and outwardly directed
components are given as four columns.

\subsubsection{The row option}

If the keyword \cdCommand{row} appears then the photon
energy will be given in the first row and the intensities
will be given in a single row with a large number of columns.
This \cdCommand{row} option is more suitable for
large grids of calculations.

By default this reports the total \feii\ emission.
It will give the inward emission if the keyword
\cdCommand{inward} appears and the outward emission if
the keyword \cdCommand{outward} appears.

The \cdCommand{set FeII continuum} command, described on
page \pageref{sec:CommandSetFeIIContinuum}, can be used to adjust
the lower and upper bounds to the energy range and the number
of bins that occur over this range.

\subsection{Save FeII departure}

The departure coefficients will be saved.  This is normally only listed
for selected levels.  All levels will be saved if the keyword
\cdCommand{all} appears.

\subsection{Save FeII levels}

A list of the energy levels in the large \feii\ atom will be produced.
The first column gives the energy of the level [wavenumbers] above ground
and the second column gives the statistical weight of the level.

\subsection{Save FeII lines  [faint=0.1, range 0.1 to 0.3 Ryd]}

This gives the intrinsic intensities of
all $\sim 10^5$ lines predicted by the large \feii\ atom at the
end of the calculation.
The upper and lower level indices are given on
the physics, not C, scale, so the lowest level is one.
Next is the line
wavelength in Angstroms, followed by the log of the intensity or luminosity
of the corresponding \feii\ line.
This is followed by the linear intensity
relative to the line set with the \cdCommand{normalize} command.  The optical depth
is given in the last column.
If the keyword \cdCommand{short} appears then the relative
intensity and the optical depth are not saved.

Three optional numbers can appear on the command line.  The first is
the intensity of the faintest line to be saved.  This is relative to the
normalization line which is usually H$\beta$.  The second and third optional
numbers are the lower and upper limits to the range of line energies
in Rydbergs.  Both numbers are interpreted as logs if either is negative.
These optional numbers can be omitted from right to left.

\subsection{Save FeII optical depths}

The optical depths of all lines in the large \feii\ atom will be produced.
The first two columns give the index of the lower and upper levels on the
physics (not C) scale, the third column gives the wavelength of the
transition in Angstroms, and the last column gives the optical depth.

\subsection{Save FeII populations}

The level populations [cm$^{-3}$] for selected levels of the large
\feii\ atom are saved by default.
All levels will be saved if the keyword \cdCommand{all} appears.
If the \cdCommand{range} keyword appears then a pair of numbers, the lower
and upper indices for the levels, will be read.  The populations are per
unit volume by default.  If the keyword \cdCommand{relative} appears
then they will be given relative to the total Fe$^+$ density.

\section{Save FITS}

This command produces photon energies and transmitted continuum into
a two-column file in FITS (Flexible Image Transport System) format.  FITS
is a standard format used in astronomy, and endorsed by both NASA and the
International Astronomical Union.  The most current definition of the FITS
format is by \citet{Hanisch2001}.  This was added by Ryan Porter and its
first application is given in \citet{Porter2006}.

Since only one spectrum can be stored in a FITS file, the command will
implicitly behave as if the keyword \cdCommand{last} was included on the
command line.

The following creates a FITS file with a blackbody continuum
\begin{verbatim}
blackbody 1e5 K
ionization parameter -2
save FITS "filename"
\end{verbatim}

This command is often used with the \cdCommand{grid} command which creates
grids of calculations. In this case, the command produces separate FITS files
for each grid point. They will have names
\cdFilename{grid000000000\_filename}, \cdFilename{grid000000001\_filename},
etc., where \cdFilename{filename} is the file name you supplied between double
quotes. The meaning of the grid index embedded in the filename can be found with
the \cdCommand{save FITS} command described in Section~\ref{sec:save:grid}.

\section{Save gammas}

This gives the photoionization rates for all subshells of all ions for
the last zone.  The numbers are the element, ion, and subshell numbers,
followed by the photoionization and heating rates from that subshell.  The
remaining numbers are the fractional electron Auger yields.

\subsection{Save gammas element oxygen 1}

If the \cdCommand{element} keyword appears then the detailed contributors to the
photoionization rate for the valence shell of a particular element will
be produced by calling \cdRoutine{GammaPrt}.
The ionization stage must also appear,
with 1 the atom, 2 the first ion, etc.

\section{Save gaunt factors}

This produces a table showing the free-free gaunt factors as a function
of photon energy and temperature.

\section{Save grains [options]}

These commands give grain properties.  Several grain species are usually
included in a calculation.   Often there are several size bins per grain
type.  These commands will print a line giving a list of the grain labels,
followed by a line giving the grain radius in $\mu m$.
The following lines then give the individual grain properties
(temperature, potential, etc) for each size and type.

Details of the grain physics are given in \citet{Baldwin1991},
\citet{Weingartner2001a},
\citet{VanHoof2004}, and \citet{Weingartner2006}.

\subsection{Save grain abundance}

The grain abundance [g cm$^{-3}$] for each grain bin and the total grain
abundance is given as a function of depth.

\subsection{Save grain charge}

The first number is the electron density [cm$^{-3}$] contributed by grains.
A positive number indicates that grains where a net source of electrons
so they have a net positive charge.  The remaining columns print the charge
of each grain size and type, in number of elementary charges per grain,
for each zone.

\subsection{Save grain continuum}

This is listed in the \cdSectionTitle{save continuum} section.

\subsection{Save grain D/G ratio}

The dimensionless dust to gas ratio for each grain bin and the total
grain abundance is given as a function of depth.

\subsection{Save grain drift velocity}

The drift velocity [km s$^{-1}$] of each grain species is printed for each zone.

\subsection{Save grain extinction}

The grain extinction at the $V$ filter will be saved as a function of
depth.  This extinction only includes grains, although they should provide
nearly all the extinction when they are present.  The first column gives
the depth into the cloud [cm], the second is the extinction [mag] at the
$V$ filter for an extended source, like a PDR, and the third number is the
extinction for a point source like a star.  This distinction is discussed
in Sections 7.2 and 7.6 of AGN3.  The extended source extinction discounts
forward scattering by writing the scattering opacity as $\sigma ( 1-g )$,
where $\sigma$ is the total scattering opacity and $g$ is the grain asymmetry
factor.
The quantity in the last column does not include the $({1-g})$
term.

\subsection{Save grain H2rate}

The grain \htwo\ formation rate is given for each size and type of grain
and for each zone.

\subsection{Save grain heating}

The grain heating [erg cm$^{-3} \mathrm{s}^{-1}$] is output for each zone.

\subsection{Save grain opacity}

This gives the grain opacity as a function of the photon energy in the last
zone of the model.  The first column is the photon energy in the units set
with the \cdCommand{units} option, the second the total (absorption plus
scattering) cross section, followed by the absorption and scattering cross
sections.  These are the summed cross section per proton for all grain
species in the calculation. Column 5 is the pure scattering cross section
summed over all grains and column 6 is the grain albedo.   Columns 2, 4,
and 6 use the scattering cross section multiplied by (1-g), while column
5 does not. The opacities have units [cm$^{2}$ H$^{-1}$] using the actual
grain abundance from the last zone.

\subsection{Save grain potential}

 The grain floating potential [eV] is output for each grain size bin and
each zone. The grain potential is defined~as
\begin{equation}
\varphi _g  = \frac{{\left( {\left\langle Z \right\rangle  + 1} \right)e^2
}}{a}
\end{equation}
where $\langle Z\rangle$ is the average grain charge of the grain size bin.  In reality
there is a distribution of grain charges in each bin, so this quantity does
not relate to any individual grain. It is approximately the amount of energy
needed to move an electron from the grain surface (after it has been lifted
out of the grain potential well) to infinity, averaged over all charge
states.
\citet{Weingartner2001a}, \citet{VanHoof2004} and \citet{Weingartner2006} provide further details.

The grain potential given here and the (average) grain charge
(see \cdCommand{save grain charge}) differ only by constants.  It
is probably best to use the latter since that quantity will be far easier
to define. Refer to \citet{Weingartner2001a} and
\citet{VanHoof2004}
for more details.

\subsection{Save grain qs}

The photon energy is followed by the absorption and scattering $Q$s for
each grain species.  These are defined in Chapter 7 of AGN3.

\subsection{Save grain temperature}

The temperature of each grain species is printed for each zone.

\section{Save grid}
\label{sec:save:grid}

This is used with the \cdCommand{grid} command to
create a file giving the parameters for each simulation in a large grid
of calculations.  This can be combined with other \cdCommand{save} commands to create
files giving the derived quantities for a large set of calculations.

The first row gives tab-separated column titles.  The column title for the parameters
that are varied will give the first few characters of the command line for
that parameter.  Each of the following lines summarizes a particular grid point.  The
first column gives the index number in the grid. This is useful if you
have separate output for each grid point (e.g. from the \cdCommand{save FITS}
command). The index number will be part of the file name in that case. It is
also useful for finding back the output from a particular grid point in a
save file (see Section~\ref{sec:GridOutputOptions} for more details).
The next two columns indicate whether the calculation had a failure or had any
warnings.  A successful calculation will have ``F'' (for false) indicating
no failure or warning occurred.  If either of these is ``T'' (for true) then
that simulation had major problems. The following column is a string giving
a bit more detail about the exit code. It says ``ok'' if everything went fine
and ``warnings'' if warnings were present in the run, but nothing more serious.
If the simulation failed completely, you could see strings like ``cloudy abort''
or ``early termination''. You should look at the detailed output
to find out what went wrong. The next two columns give the number of the
MPI rank that executed the simulation (will be zero in non-MPI runs) and the sequence
number of the simulation on that rank (they are executed in random order). These
numbers are used for debugging the code. The next columns give numerical parameters for
each simulation in the grid.  The last column gives all the grid parameters
as a single string.  Many plotting programs will allow you to add this string
next to each of the plotted data points.

This command does not produce any output if the \cdCommand{grid} command
is not used. In grid runs it is highly recommended to always include this command.
It allows you to see in one glance if the run was successful and where the problems
are in case it was not. It is also useful to include this output in case you want
to file a bug report.

\section{Save heating}

The code will save the heating agents for each zone.  The two columns
give the depth [cm] and temperature [K].  The next two columns give the
total heating and cooling rates [erg cm$^{-3} \mathrm{s}^{-1}$].  This is followed by a set
of labels for various heat sources and the fraction of the total heating
carried by that agent.  The faintest agent saved is normally 0.05 of the
total and can be reset with the \cdCommand{set WeakHeatCool} command.

The heating labels will probably not correspond to any entries in the
emission-line list.  If the identification of a heat source is in question
the best recourse is to search for the heating label over the entire code.

\section{Save [option] history}

\subsection{Save pressure history}

This follows the pressure and density convergence history.

\subsection{Save temperature history}

This follows the temperature and heating---cooling convergence history.

\section{Save H2}

Some details of the large \htwo\ molecule are output as a save file.  One
of the following options must appear.  The large \htwo\ atom is not included
by default but is turned on with the \cdCommand{atom H2} command.

Many studies of \htwo\ properties will use plots showing populations as a
function of excitation energy.  The slope gives a population temperature,
which may be related to the kinetic temperature under some circumstances.
Theoretical plots can be made using the
\cdCommand{save H2 column density}
or \cdCommand{save H2 populations} commands described below.
The level energy in K, given in
the save output, is the x-axis and the column density or population in
each level is the y-axis.

The \cdCommand{save grain H2rate} command gives
the \htwo\ formation rate for each of the grain species included in the calculation.

\subsection{Save H2 column density}

This saves the column density of ro-vibrational states within the ground
electronic state.  This command recognizes the same options as the \cdCommand{save H2 populations} command.

The file begins with the total \htwo\ column densities
in the ortho and para forms, followed by the total \htwo\ column density.  The remainder of the file
gives the $v$ and $J$ quantum indices, followed by the excitation energy of
the level in K, the total column density in that level, and finally the
column density divided by the statistical weight of the level.

\subsection{Save H2 cooling}

This produces a file containing heating and cooling rates
[$\pcc\ \ps$] as a function of depth.

\subsection{Save H2 creation}

This command has been superseded by the \cdCommand{save chemistry rates} command.

\subsection{Save H2 destruction}

This command has been superseded by the \cdCommand{save chemistry rates} command.

\subsection{Save H2 heating}

This produces a file containing the depth, total heating rate [erg
cm$^{-3}\mathrm{s}^{-1}$], and \htwo\ heating predicted by an expression in \citet{Tielens1985a}, together with the heating predicted by the large model of the \htwo\ molecule.

\subsection{Save H2 levels}

This creates an energy-ordered list of the levels within X.  The first
column gives the energy in wavenumbers relative to the lowest level, the
second gives the statistical weight, and the next two columns give the
vibration and rotation quantum numbers.  The sum of the transition
probabilities is given, followed by the critical density of the level for
each of the colliders included in the calculation.

\subsection{Save H2 lines}

The intensities of all significant \htwo\ emission lines that are produced
within the ground electronic configuration are given.  The file also gives the
information needed to convert an emission-line spectrum into a level
population vs excitation energy diagram.

Each line of output begins with a spectroscopic designation of the line,
followed by the upper and lower electronic, vibration, and rotation quantum
numbers.
This is followed by the wavelength of the line in microns.
The
line wavelength is then printed as it appears in the output.
The log of
the intensity or luminosity in the line (depending on whether the intensity
or luminosity case is specified), and the intensity of the line relative
to the normalization line, follow.
The excitation energy of the upper
level of the transition in Kelvin and the product
$g_u h\nu A_{ul} $  for each line are also given.
This product is needed to convert
intensities into excited-state column densities.

Only lines brighter than 10$^{-4}$ of the reference line are given by default.
The intensity of the faintest line, relative to the normalization line,
is set with the first optional number that can appear on the command line.
If the number is negative then it is interpreted as the log of the limit.

By default only lines within the ground electronic system are saved
but this can be changed if the keyword \cdCommand{electronic}
appears on the command line.
If the keyword \cdCommand{all} also appears then lines
within all electronic systems are saved.
If the keyword \cdCommand{ground} appears then only lines the
ground system are saved.  This is the default.  If a number appears then
it is the number of electronic systems to be saved, 1 for only the ground
electronic state.  If the number of systems is specified then it must be
the second number on the line---the first being
the intensity of the faintest line to print.

The following give examples.  The first sets the faintest \htwo\ line to
save.  Only lines within the ground electronic system will be produced.
\begin{verbatim}
save H2 lines, faintest -4 "filename"
\end{verbatim}
This sets the faintest line, and also requests all lines produced by all
electronic configurations.
\begin{verbatim}
save H2 lines, faintest -4 all "filename"
\end{verbatim}
This example requests only lines for the lowest three electronic
configurations.
\begin{verbatim}
save H2 lines, faintest -4 electronic 3 "filename"
\end{verbatim}

\subsection{Save H2 populations}

The level populations for the ground electronic state are given for the
last computed zone.  The populations are relative to the total \htwo\ abundance.

There are several optional parameters.
The quantum numbers of the highest
vibrational and rotational levels to save can be specified as consecutive
numbers on the command line.
These occur in the order $v$ then $J$.
If no
numbers occur, or if a limit that is less then or equal to zero is entered,
then populations of all levels will be saved.

If the keyword \cdCommand{zone} appears then the level populations 
will be saved for every zone.   These are all given along one long line,
a format that is different from the other output options.  Otherwise the
populations are only saved at the end of the iteration using the output
options described next.

If output is only saved for the last zone then it can be in either
a triplet format, with the vibration and rotation quantum numbers followed
by the population, or as a matrix, with all populations of a given vibration
quantum number lying along a single row.  The triplet form is done by
default, and the second will occur if the keyword
\cdCommand{matrix} occurs on the command line.

The \cdCommand{save H2 column densities} command provides similar output
options but for integrated column densities.

\subsection{Save H2 PDR}

The output contains useful information regarding conditions within a PDR.

\subsection{Save H2 rates}

The output contains useful information regarding \htwo\ formation and
destruction rates.

\subsection{Save H2 Solomon}

The output will give the total rate for photo-excitation from the ground
to electronic excited states and then identify those levels which are the
dominant contributor to the total rate.

\subsection{Save H2 special}

This provides infrastructure to save debugging information.  It can
be easily changed to suite particular needs.

\subsection{Save H2 temperatures}

The depth [cm], 21 cm spin temperature [K], gas kinetic temperature [K],
and several temperatures derived from relative populations of $J$ levels within
the H$_2\, v=0$ ground  electronic state [K], are saved for each zone.

\subsection{Save H2 thermal}

A variety of heating---cooling processes involving \htwo\ are given
for each zone.

\section{Save helium [options..]}

\subsection {Save helium line wavelengths}

This gives wavelengths of lines from $n=2$ levels of He-like ions.

\section{Save hydrogen}

\subsection{Save hydrogen 21 cm}

This gives some information related to the spin temperature of the 21
cm line.
The keyword is either \cdCommand{21 cm} or \cdCommand{21cm}.
The level populations
within 1s are determined including radiative excitation by \la, pumping by
the external and diffuse continua, collisions, and radiative decay.  Several
of the resulting populations and temperatures are included in the output.

\subsection{Save hydrogen conditions}

This gives the physical conditions and populations of various forms of
hydrogen are given as a function of depth.  The depth [cm], temperature
[K], hydrogen density [cm$^{-3}$], and electron density [cm$^{-3}$] are followed by
the densities of \hO, \hplus, \htwo, H$_{2^{+}}$, H$_{3^{+}}$, and H$^-$ relative to the total hydrogen
density.

\subsection{Save hydrogen ionization}

This gives rates for processes affecting the hydrogen ionization as a
function of depth.  The columns give the ground state photoionization rate
[s$^{-1}$], the total and Case~B recombination coefficients [cm$^3$~s$^{-1}$], the
predicted ratio of $n$(\hplus) to $n$(\hO), and the theoretical ratio for the simple
case.  Finally, contributors to the ground state photoionization rate are
produced with a call to \cdRoutine{GammaPrt}.

\subsection{Save hydrogen lines}

The upper and lower quantum indices, the line energy, and the optical
depth in the line, will be saved.

\subsection{Save hydrogen Lya}

This produces some information related to the excitation, destruction,
and escape of the \la\ line of hydrogen.  The optical depth from the
illuminated face to the outer edge of the current zone is followed by the
excitation temperature, electron kinetic temperature, and the ratio of these.

\subsection{Save hydrogen populations}

This gives the depth [cm], the densities of \hO\ and \hplus\ [cm$^{-3}$],
followed by the level population densities [cm$^{-3}$]
for the levels in the order $n = 1, 2s, 2p, 3, 4, 5,\dots$ for each zone.

\section{Save ionization means}
\label{sec:CommandSaveIonizationMeans} 

The mean\footnote{Before version 96 the ionization fractions only included atoms and
ions.  They now also include molecules.  The sum of the atomic and ionic
fractions will not add up to unity if a significant fraction of the element
is in molecular form.} ionization of all elements included in the calculation will
be output.  The format is exactly the same as the mean ionization printout
produced at the end of the standard output.

The \cdCommand{save averages} command described on
page \pageref{sec:CommandSaveAverage} can save
the average ionization fraction for a particular species.

\section{Save ionization rates carbon}

The total ionization and recombination rates for a specified element
will be saved as a function of depth.
The name of an element must appear
on the command line.
Each line of output will have the depth [cm], electron
density [cm$^{-3}$], and the sink timescale for loss of particles due to advection
out of the region [s$^{-1}$].
The remaining numbers give quantities for each
possible stage of ionization of the element.  For each ionization stage
the set of numbers that are printed give the density of atoms in that
ionization stage [cm$^{-3}$], the total ionization rate [s$^{-1}$],
the total recombination rate [s$^{-1}$], and the rate new atoms
are advected into the region [s$^{-1}$].

\section{Save ip}

This gives the ionization potentials of all shells of all ions and atoms
of the \LIMELM\ elements included in the code.  The first row is the spectroscopic
designation of the ion.  Each additional row gives the subshell and
ionization potential of that subshell in eV.

\section{Save Leiden}

This command produces an output file designed for the comparison
calculations presented in the 2004 Leiden meeting on PDR calculations
(\citealp{Roellig2007}).

\section{Save lines, options}

This set of commands will save some details about line formation.

\subsection{Save lines, array}

This gives the intensities of all lines in a form in which they can easily
be plotted by other software.  The first column lists the line energy in
Rydbergs.  The next gives the spectroscopic designation of the ion.  The
following two columns give the log of the intrinsic and emergent intensities
or luminosities of the line.  Only lines with non-zero intensity are
included.
All lines that appear in the \Cloudy\ output will also appear in
the resulting output file.\footnote{In versions 90 and before of the code, only the level 1 and level
2 lines were output by this command.}

Lines energy are in Rydbergs by default.  This command recognizes the
\cdCommand{units} option.

\subsection{Save lines, cumulative}

This option tells the code to save the log of the cumulative intensity
of up to 100 emission lines as a function of depth into the cloud.  The
emission lines are specified on the following input lines and end with a
line with the keyword \cdCommand{end} in columns 1--3.

The code distinguishes between intrinsic and emergent
line intensities.
This command reports the intrinsic line intensity by default.
If the keyword \cdCommand{emergent} appears then it will
report the emergent line intensity.

The label used by \Cloudy\ to identify each line in the main emission-line
output must appear in column 1--4 of the line and the line wavelength appears
as a free-format number in later columns.  These must match the label and
wavelength used by the code exactly.  You can obtain this either from the
main printout or from the output of the \cdCommand{save line labels} command.

The line labels and wavelengths are followed by the depth into the cloud
and the integrated intensities of the lines [erg cm$^{-2} \mathrm{s}^{-1}$] for each zone.
This information can be used to follow the build up of emission lines across
a computed structure.

The following illustrates its use;
\begin{verbatim}
save lines, cumulative, "lines.cum"
totl 4861
o  3 5007
totl 3727
o  1 6300
end of lines
\end{verbatim}

If the optional keyword \cdCommand{relative} is specified then the quantities will
be given relative to the normalization line. The default is to give
the intensity $4\pi J [\mathrm{erg\, cm}^{-2} \mathrm{s}^{-1}$].

The \cdCommand{save lines cumulative} and \cdCommand{save lines emissivity} commands use the
same line array so both commands cannot be used in the same calculation.

\subsection{Save line data}

This saves some atomic data for all lines included in the line transfer
arrays.  It can be used to generate a table listing many lines and their
atomic parameters.
The code will stop after the data have been saved since
it is left in a disturbed state.

The first set of lines consists of recombination lines from \citet{Nussbaumer1984} and \citet{Pequignot1991}.  For these
the spectroscopic designation and wavelength are given followed by the log
of the recombination rate coefficient.

The remaining sets of lines are those that are treated with full radiative
transfer.
The first are the \cdTerm{level 1} lines,
those with accurate atomic
collision data and wavelengths.
The next \cdTerm{level 2} lines have many more
lines and uses Opacity Project wavelengths and various g-bar approximations
to generate approximate collision strengths.   These are followed by the
hydrogen and helium iso-electronic sequences, then the $^{12}$CO and $^{13}$CO lines.
The \htwo\ and \feii\ lines come last if these large atoms are included.

By default the atomic parameters will be evaluated at a temperature of
10$^4$~K.  Other temperatures can be selected by entering a
\cdCommand{constant temperature} command.
The number of H-like, He-like, CO,
\htwo, and \feii\ lines that are printed is controlled by the size of the
relevant atoms when the \cdCommand{save line data} command is executed.

This command recognizes the \cdCommand{units} option.
The line
can be given in any of the wavelength or energy units
it understoods.

\subsection{Save lines, emissivity}

This saves the emissivity of up to 100 emission lines as a function
of depth into the cloud.  This information can then be used by other codes
to reconstruct the surface brightness distribution of a resolved
emission-line object.  The \cdTerm{emissivity}
is the net emission
$4\pi \bar J = n_u A_{ul} P_{ul} h\nu $
[erg cm$^{-3}$~s$^{-1}$] produced at a point and escaping the cloud.
This includes the escape probability $P_{ul}$.

The code distinguishes between intrinsic and emergent
line intensities.
This command reports the intrinsic line intensity by default.
If the keyword \cdCommand{emergent} appears then it will
report the emergent line intensity.

The emission lines are specified on the input lines that follow the
command and end with a line with the keyword \cdCommand{end} in columns 1--3.
The label used by \Cloudy\ to identify each line
(use the \cdCommand{save lines labels} command
or look at the main emission-line intensity printout to obtain a list of
lines) must appear in column 1--4 of the line and the line wavelength appears
as a free-format number in later columns.  The easiest way to obtain this
information is to copy and paste the line identification and wavelength
from a \Cloudy\ output.  The label and line must match exactly.

The save output begins with emission-line labels and wavelengths.  The
remaining output gives the emission structure.  The first column is the
depth [cm] into the cloud.  The remaining columns give the volume emissivity
[erg cm$^{-3}$~s$^{-1}$] for each line.  The intensity is for a fully filled volume
so the saved intensity should be multiplied by the filling factor to
compare with observations of a clumpy medium.

The following illustrates its use;
\begin{verbatim}
save lines, emissivity, "lines.str"
totl 4861
o  3 5007
totl 3727
o  1 6300
end of lines
\end{verbatim}

The \cdCommand{save lines cumulative} and \cdCommand{save lines emissivity} commands use the
same line array so these commands cannot be used in the same calculation.

\subsection{Save lines, intensity [every 5 zones]}

This gives the
intrinsic or emergent intensities of all lines with
intensities greater than zero in the format used for the final printout
(line label, wavelength, intensity).

The default is to give the intrinsic intensities.
If the keyword \cdCommand{emergent} appears then
those will be given instead.

The default is for this to be done
only after the last zone is computed.  Results for intermediate zones can
be saved if the additional keyword \cdCommand{every} appears.
In this case the first
number on the line is the interval between zones to save,
as in the \cdCommand{print every} command.

The save output will have the line information spread over 6 columns.
For some data base applications it would be better to have a single column
of results.  If the keyword \cdCommand{column} appears then a single column is produced.

Lines with non-zero intensities are reported by default.  
If the keyword \cdCommand{all} appears then all lines are reported.

\subsection{Save line labels}

This creates a file listing all emission-line labels and wavelengths
in the same format as they appear in the main output's emission-line list.
This is a useful way to obtain a list of lines to use when looking for a
specific line.  The file is tab-delimited, with the first column giving
the line's index within the large stack of emission lines, the second giving
the character string that identifies the line in the output, and the third giving
the line's wavelength in any of several units.  The line ends with a
description of the line.

There are a vast number of emission lines predicted by the code and many
lines will have the same wavelength.  The line label can usually be used
to distinguish between various lines with the same wavelength. This is seldom
the case for contributions to the line however.  The line index can be used
to resolve this degeneracy in cases where you want to obtain a line's
intensity with a call to a routine.
Routine \cdRoutine{cdLine\_ip} (described in the
header file \cdFilename{cddrive.h} and also in Part 2 of this document)
uses the line index to find the relative intensity and
luminosity of a particular line.
But note that this index is not necessarily the same in different
calculations.  It will always be the same for a particular set of input
conditions but it depends on the sizes of various atoms and which chemical
elements are used in the calculation.

Most emission lines in the code share a common structure.  Each of these
lines will enter the following into the emission-line stack:
\begin{verbatim}
532 H  1  6563A predicted line, all processes included
533 Inwd  6563A predicted line, all processes included
534 Coll  6563A predicted line, all processes included
535 Pump  6563A predicted line, all processes included
536 Heat  6563A predicted line, all processes included
537 H  1  4861A predicted line, all processes included
538 Inwd  4861A predicted line, all processes included
539 Coll  4861A predicted line, all processes included
540 Pump  4861A predicted line, all processes included
541 Heat  4861A predicted line, all processes included
\end{verbatim}

The entries marked ``Inwd'', ``Coll'', ``Pump'', and ``Heat'' indicate
the inward fraction, the collisional and radiative pumped contribution to
the line, and the line heating.  All of these entries will occur in the
file if the keyword long appears.  By default these contributions to the
line are now given so the above would appear as
\begin{verbatim}
532 H  1  6563A predicted line, all processes included
537 H  1  4861A predicted line, all processes included
\end{verbatim}

\subsection{Save line list [absolute]}

This reads in a list of emission lines from a file and reports the
predicted line intensities.  It is designed as a way to obtain predictions
for a subset of the lines that are predicted during a series of calculations.
It is often used together with the \cdCommand{grid} command
when doing grids of calculations or with the \cdCommand{time} command
when following the evolution of a time-varying
continuum source.

\emph{Filenames}  These are tricky since two filenames appear in this command.
All \cdCommand{save} commands have the name of an output file
in double quotes.
This is the first filename on the command line.
The file containing the list
of emission lines is within the second pair of quotes.  In the following
example
\begin{verbatim}
save linelist "output.txt"  "LineListHII.dat"
\end{verbatim}
the save output will go to \cdFilename{output.txt}
and \cdFilename{LineListHII.dat} contains the
set of emission lines.
Predicted intensities for the list of lines contained
in the second file will be output into the first file.
 
This command works by calling routine \cdRoutine{cdGetLineList}
which is described in Part~3 of this document.
The filename within the second pair of quotes
is sent to this routine.
You can build your own file and several sample
files giving lists of emission lines are included in the data directory.
They have names that are of the form \cdFilename{LineList*.dat}
and are intended for different circumstances.
\cdRoutine{cdGetLineList} will first look for the list of
emission lines in the current directory and then search the data directory.

By default results are presented as rows of emission lines.
The output file will have the list of emission-line labels in the first
row.  The first column gives the iteration number and the remaining
entries across the row give the line predictions.
The \cdCommand{column} option will produces columns instead.

\emph{Units of the line brightness}
Intrinsic line intensities are given by default.
The keyword \cdCommand{emergent} will give those instead.
The lines will be relative to the reference line by default.
If the keyword \cdCommand{absolute} appears then they will be given
in absolute units, the same units as the third column in
the main emission-line output.
By default these are \ergpscmps\
for the intensity case and \ergps\ for the luminosity case.
The \cdCommand{print line surface brightness} command,
described on page \pageref{sec:CommandPrintLineSurfaceBrightness},
can change the absolute units for all the lines to surface brightness,
either sr$^{-1}$ or arcsec$^{-2}$.

\emph{The ratio option}
If the keyword \cdCommand{ratio} appears then the ratio of adjacent
lines will be output.
There must be an even number of lines in the line-list file.
The output will have the ratio of the intensity of the first divided
by the second, the third divided by the fourth, etc.
This provides a quick way to look at line ratios as a function
of other parameters.
The \cdCommand{grid} command can produce grids of calculations.
Suppose the file \cdFilename{linelist.dat} contains the following:
\begin{verbatim}
o  3     5007
totl     4363
\end{verbatim}
This specifies the [\oiii] $\lambda$5007 and $\lambda$4363 lines.
The following input script
uses the \cdCommand{grid} command to predict the [\oiii] line ratio as a function of
$n$ and $T$.
\begin{verbatim}
c produce the save output
save line list "O3.pun" "linelist.dat" ratio no hash
save grid "O3.grd"
c following three commands do H and O-only, and set O
c ionization so that little O+3 is present (to prevent
c formation of 4363 by recombination).
init ``honly.ini''
element oxygen on
element oxygen ionization 1 1 1 0.01
c set the continuum
blackbody 4e4 K
ionization parameter -2
c next 4 commands vary Te and n
constant temperature 4 vary
grid 4000 17000 3000
hden 4 vary
grid 2 6.1 1
c must stop this constant Te model
stop zone 1
\end{verbatim}
This produces two output files, \cdFilename{O3.grd}
containing the densities and temperatures,
and \cdFilename{O3.pun}, containing the ratio $I$(5007) / $I$(4363)
for each density and temperature.
These could be plotted to show this line ratio
as a function of density and temperature,
as shown in the Figure \ref{fig:SaveLineRatio}.
\begin{figure}
\centering
\includegraphics[scale=1.4]{SaveLineRatio}
\caption[Save line ratio example]{
\label{fig:SaveLineRatio}
The [O III] line ratio as a function of density and temperature.}
\end{figure}

\subsection{Save line optical depths, limit=-2}

This gives the total optical depths for all lines.  By default all lines
with optical depths greater than 0.1 will be included.  The lower limit
can be reset with the optional number that appears on the line---it is the
log of the smallest optical depth to be printed.  This command recognizes
the \cdCommand{units} option so the line
wavelengths can be in any of the wavelength or energy units
understood by this option.

The line identification, element and ion, starts the output line, in
the form used in the usual emission-line printout.
Next follows the line's wavelength or energy.
Finally the line's optical depth and damping constant
are printed.

Results are reported for the last computed zone unless the \cdCommand{every} option
appears.

\subsection{Save line pressure.}

This produces a list of the most important contributors to the line
radiation pressure for each zone.

\subsection{Save line populations, limit$=-$2}

This will output some information concerning the atomic parameters and
level populations for all lines that are transferred.

By default all transitions with upper level densities greater than zero
will be included.  The lower limit to the density threshold can be reset
with the optional number than can appear on the line---this is the log of
the smallest population density [cm$^{-3}$] to be printed.  This can be used
to make the print out somewhat shorter.
If the keyword \cdCommand{off} appears then
the limit to the smallest population to print will be turned off.
All
populations will be reported.

The first block of information gives an index to identify each line.
This is followed by the line's label.  This will usually be the spectrum,
as in ``H  1'' followed by the wavelength, as in ``1215A''.  The lower and
upper statistical weights are next, followed by the energy of the line in
wavenumbers and the $gf$ value for the transition.

The population densities for each zone follow this block of information.
Each line begins with the index used for that line in the atomic parameter
list.  This is followed by the populations of the lower and upper level
of the transition [cm$^{-3}$].

\subsection{Save line RT}

This produces a file containing information concerning line radiative
transfer.  A series of lines that specify which emission lines to produce
follow the command.  The line label is in columns one through four and is
followed by the line wavelength.  They end with a line that starts with
\cdCommand{end}.

\section{Save map, zone 3 [range 3999 to 4500]}

This produces a map of the heating and cooling rates as a function of
temperature.  The details of the map are described in the description of
the \cdCommand{map} command.
The first number is the zone
for the map, zero if only a map of the first zone

The optional keyword \cdCommand{range} specifies the temperature range of the map.
If this option is specified then the zone number must come first and is
followed by the lower and upper temperature limits to the map.
Both
temperatures will be interpreted as logs if the first number is $\leq 10$.
The keyword \cdCommand{linear} will force that interpretation.  If the temperature range
is specified then there must be three numbers on the line---the stopping
zone number followed by the lower and upper limits to the temperature.

Normally 20 steps occur between the lowest and highest temperature in
the map.
The number of steps is reset with the \cdCommand{set nmaps} command.

\section{Save molecules}

The densities [cm$^{-3}$] of all molecules will be saved.  The depth and
the point and extended visual extinction into the cloud are given in the
first three columns.  The first line of the output gives header labels for
the molecules.

\section{Save NLTE}
\label{sec:NLTEoutput}
This command saves some averages reported for the 
NLTE7 Workshop, \url{http://nlte.nist.gov/NLTE7/}.
You must enable the \cdCommand{USE\_NLTE7} macro when compiling
to use this feature.
To do so, add \cdCommand{EXTRA$=$"-DUSE\_NLTE7"} to the end of the 
\cdCommand{make} command used to build the code
in the \cdCommand{sys\_XXXX} directory that you want to use.
A typical example might be
\begin{verbatim}
make -j 4 EXTRA="-DUSE_NLTE7"
\end{verbatim}

\section{Save opacities [total, grain, element]}

This gives some of the opacity sources considered by the code. The photon
energy is given in the first column and the opacities are in the columns that
follow. This command recognizes the \cdCommand{units} option to change the
energy scale. One of the keywords described in the following sections must
appear.

The opacities are only defined over the energy range over which the incident
radiation field is defined. The resulting opacities will not extend to high energies
for softer continua. A hard continuum such as \cdCommand{table agn} should use
used in the input stream to obtain the opacities over the full energy range.

Results are reported for the last computed zone unless the \cdCommand{every} option
appears.

\subsection{Save total opacity}

If the keyword \cdCommand{total} appears then the total opacity $\kappa$,
the absorption
cross section multiplied by the density of the absorber, summed over all
constituents, will be saved.
This has units cm$^{-1}$.
The optical depth would
be $\kappa $ multiplied by a physical depth.  This opacity includes all constituents,
gas phase and grains, for the last computed zone, with unit filling factor.
The first column is the photon energy and the second is the total opacity.
The absorption and scattering opacities follow.  The fifth column gives
the albedo, the ratio $\kappa _s /( {\kappa _s  + \kappa _\nu  }$).   The
$\kappa $'s are the scattering and absorption parts of the total continuous
opacity.  The last column is a label indicating the ionization edge for
each species included in the calculation.

\subsection{Save grain opacity}

The total grain opacity (all grain types that are included) will be
saved after the last zone is calculated.  Successive columns give the
photon energy, the total (absorption plus scattering) opacity, the absorption
opacity, and the scattering opacity.  The total and scattering opacity
discount forward scattering so are for the extended source case.  The last
column gives the scattering opacity with forward scattering included so
is for the stellar case.

\subsection{Save fine opacities range 0.7 to 1 Ryd, coadd 15 cells}

The code's execution time is partially set by the resolution of the
continuum mesh due to the need for frequent reevaluations of opacities and
rates.
A very fine continuum mesh, with resolution of 1~km~s$^{-1}$ or better,
is used to automatically treat line overlap.
The main opacity array cannot
use this resolution because single models would then have \emph{very} long execution
times.
Instead, the code uses a multi-grid approach where a coarse continuum
is used for most integrated quantities but a fine continuum grid is also
present to handle the line overlap problem.  This command will output the
current contents of the fine opacity array.  This only includes lines, not
the continuum.

Only cells with non-zero opacity will be output.  Even then, the file
will be huge.  If the keyword \cdCommand{range} occurs then the first two numbers on
the command line are the lower and upper bounds to the energy range in the
output.  If neither is specified then the full energy range is reported.
The \cdCommand{units} keyword, described on \pageref{output_units},
can be used to change the units of the range and the resulting output.
The last optional number says how many neighboring cells to co-add.  If
no number appears then 10 are coadded to reduce the amount of output.

\subsection{Save element opacity [name]}

If neither the \cdCommand{total} or \cdCommand{grains} keywords appear then the name of an element must be specified.
The keyword consists of the first four characters of
any one of the \LIMELM\ elements now incorporated in the code.
The photon energy
(eV) and total photoionization cross section (Megabarns [10$^{-18}
\mathrm{cm}^{-2}$]) for
all stages of ionization of the specified element will be saved.
A save
file name must still be specified to get past the command line parser but
is totally ignored.

The photoionization cross section of each stage of ionization is saved
in a series of files.  The name of the file will start with the first four
characters of the element's name, followed by the stage of ionization (the
atom is one), ending with \cdFilename{.opc}.  Examples are \cdFilename{CARB1.opc} or
\cdFilename{CARB6.opc}.

The code stops after producing these files.
Only one element can be treated at a time because of this.
If you want to examine the opacity files for more than one element
you will need to run the code one time with each element.

This version of the \cdCommand{save opacity} command is misnamed.
It actually saves the photoionization cross section, not the opacity due to the element.

\subsection{Save opacity figure}

This version of the command creates the file needed to generate one of
the figures used in another Part of \Hazy.
The output gives the energy in Rydbergs,
then keV, following by the hydrogen, helium, and total gas opacities.
The
opacities are in units of $10^{24} \mathrm{cm}^{-2}$ and have been multiplied by the cube
of the energy in Rydbergs.

\subsection{Save opacity shell 26 5 3}

This saves the state-specific photoionization cross section for a
subshell of any species.  The first number is the atomic number of the
element, the second number the ionization stage, 1 for an atom, and the
third number the subshell, between 1 and 7 representing $1s, 2s, 2p$, etc.
The save file will contain the incident photon energy in Rydbergs
followed by the cross section [cm$^2$].

\section{Save optical depths}

This gives the total, absorption, and scattering continuum optical depths
for the computed geometry.  For a spherical geometry this is the optical
depth from the illuminated face to the outer edge of the cloud and not the
total optical depth.  The photon energy is followed by the total absorption
and scattering optical depths.
This command recognizes the \cdCommand{units} option
to change the energy scale.

\subsection{Save fine optical depths}

The code's execution time is partially set by the resolution of the
continuum mesh, due to frequent reevaluations of opacities and rates.
For problems related to line overlap, a very fine continuum mesh, with resolution
of 1~km~s$^{-1}$ or better, is used.
The main continuum array cannot use this
resolution because single models would then have \emph{very} long execution times.
Instead, the code uses a multi-scale approach, where a coarse continuum
is used for most integrated quantities, but a fine continuum grid is also
present to handle the line overlap problem.  This command gives the current
contents of the fine optical depth array.  This only includes lines, not
the continuum.

Only cells with non-zero opacity will be output.  Even then, the file
will be huge.  If the keyword \cdCommand{range} occurs then the first two numbers on
the command line are the lower and upper bounds to the energy range to be
output.  If neither is specified then the full energy range is output.
The \cdCommand{units} keyword, described on \pageref{output_units},
can be used to change the units of the range and the resulting output.
The last optional number says how many neighboring cells to co-add.  If
no number appears then 10 cells are averaged together to reduce the size of the output.

\section{Save OTS}

The line and continuum on-the-spot fields will be saved.

\section{Save overview}

This option saves an overview of the thermal and ionization structure
of the cloud and is a major output mechanism for the code.
The first numbers
are the depth [cm], temperature [K], local heating [erg cm$^{-3}$~s$^{-1}$], total
hydrogen density [cm$^{-3}$], and electron density [cm$^{-3}$].
All are given as
logs except for the depth.

These are followed by various ionization fractions, also given as logs
of the quantity.  The \htwo\ molecular fraction is expressed as
$2n(\mathrm{H}_2)/n(\mathrm{H})$.
Neutral and ionized hydrogen fractions are followed by the ionization
fractions for the three stages of ionization of helium, the carbon molecular
fraction $n$(CO)/$n$(C), the first four stages of ionization of carbon, and
the first six stages of oxygen.  The last column gives the visual extinction
(for point and extended extinction) from the illuminated face to the current
position.

\section{Save PDR}

This gives some quantities relevant to a photodissociation region (PDR).
The first column gives the depth into the cloud [cm].  The second is the
total hydrogen column density [cm$^{-2}$].  The gas kinetic temperature follows.
These are followed by the ratios of densities of \hO, 2\htwo\ and 2\htwo* to total
hydrogen, C$^0$ and CO to total carbon, and water to total oxygen.  The next
number is the (dimensionless) intensity of the UV continuum relative to
the Habing background. The last columns give the total extinction in
magnitudes in the $V$ filter measured from the illuminated face
of the cloud for a point and extended source.

\section{Save performance}

The code will output the zone number, the time required to compute that
zone, the elapsed time since the start of the calculation, and
the number of times per zone that the most nested (ionization) solver was called.
This is intended as a mechanism to identify zones that require large amounts of
work to converge. 

\section{Save pointers}

This gives the element number, ion stage, and the shell number, for all
shells of the elements heavier than helium.
This is followed by the energy
of the lower and upper ranges of this shell and the photoionization cross
sections at these bounds.

\section{Save physical conditions}

The physical conditions as a function of depth will be saved.  The
depth into the cloud [cm] is followed by the temperature [K], hydrogen and
electron densities [cm$^{-3}$], heating [erg cm$^{-3}$~s$^{-1}$], the radiative acceleration
[cm~s$^{-2}$], and filling factor.

\section{Save pressure}

Various contributors to the total pressure in the gas equation of state
will be saved.  Pressures are given in dynes cm$^{-2}$.
Successive columns give the following:
\begin{description}
\item \emph{depth} is the depth [cm] from the illuminated face to the center of the
current zone.

\item \emph{Pcorrect} is the correct pressure at the current position.  This is the
sum of all contributors to the total pressure.  This may include, among
other terms, gas, radiation, turbulent, magnetic, and ram pressure.

\item \emph{Pcurrent} is the current pressure.  It will be equal to the correct total
pressure, the previous term in the output, if the pressure has been
converged.  The tolerance on the pressure convergence is controlled with
the \cdCommand{set pressure convergence} command.

\item  \emph{PIn+Pinteg} is the sum of the gas and radiation pressure due to the
incident continuum evaluated at the current position.  In a hydrostatic
model, such as the Orion model proposed by \citet{Baldwin1991}, this will
be the total pressure and will be equal to the sum of the gas pressure at
the illuminated face and the momentum absorbed from the incident continuum.

\item \emph{Pgas(r0)} is the gas pressure at the illuminated face of the cloud.

\item \emph{Pgas} is the current gas pressure.

\item \emph{Pram} is the current ram pressure.  This is only non-zero if the gas is
moving, which only occurs when the wind geometry is computed.

\item \emph{Prad(line)} is the current line radiation pressure.

\item \emph{Pinteg} is the current integrated pressure due to attenuation of the
incident continuum.

\item \emph{V(wind km/s)} is the wind velocity in km s$^{-1}$.  This is only non-zero for
a wind geometry.

\item  \emph{cad(wind km/s)} is adiabatic sound speed in km s$^{-1}$.

\item \emph{P(mag)} is magnetic pressure at the current position.

\item \emph{V(turb km/s)} is the turbulent velocity in km s$^{-1}$.

\item \emph{P(turb)} is the turbulent pressure.

\item \emph{int thin elec} the integrated radiation force
for electron scattering opacity only, in the absence of
any absorption.

\item  \emph{conv} This is ``T'' if the pressure is conserved and ``F'' if it is not.
\end{description}

\section{Save qheat}

The probability distribution for the grain temperatures is saved.
The first column is the grain temperature and the second column gives
$dP/d\ln T$ as defined using the nomenclature of \citet{Guhathakurta1989}.
Peter van Hoof added this command.

\section{Save radius}

The zone number is followed by the distance to the central object, the
depth to the illuminated face of the cloud, and the zone thickness, all
in cm.  If the keyword \cdCommand{outer} appears then it will only write this information
for the outer radius.

\section{Save recombination [option]}

\subsection{Save recombination coefficients}

Total recombination coefficients, the sum of radiative, dielectronic
and three-body, will be produced for all elements in the code.  These rate
coefficients [cm$^3 \mathrm{s}^{-1}$] are evaluated at the current electron temperature.

\subsection{Save recombination efficiency}

This gives the recombination efficiency for hydrogen, singlet helium
and the helium ion.

\section{Save results}

The intrinsic intensities of all emission lines with non-zero
intensities, and all column densities,
can be saved at the end of the calculation by entering the command \cdCommand{save results last iteration}.
This is one way to save the results of a grid of
models.
The resulting file contains the entire input stream as well.

The resulting save output will have the line information spread over
6 columns.
For some data base applications it would be better to have a
single column of results.
If the keyword \cdCommand{column} appears then a single column
is produced.
If no keyword occurs, or the keyword \cdCommand{array} does, then the
wide format is produced.

\section{Save secondaries}

The rate of secondary ionization of \hO, dissociation of \htwo,
and excitation
of \hi\ L$\alpha $, are given as a function of depth into the cloud.

\section{Save source function [depth, spectrum]}

\subsection{Save source function, spectrum}

The continuum source function for the local diffuse radiation field will
be saved.  The first column is the photon energy.  The second column is
the diffuse radiation field at that energy, in units of photons per second
per Rydberg.
Column three contains the total absorption opacity [cm$^{-1}$]
at that energy.
Column 4 contains the source function, the ratio of the
diffuse field to opacity (both have the units described above).
The last
column gives this ratio relative to the Planck function at the local
electron temperature.

The last column is a measure of the local source function relative to
the local Planck function.
This will generally be nearly unity for a thermal
plasma close to LTE.
Ground states of atoms of hydrogen and helium generally
have departure coefficients greater than unity so this ratio will be less
than unity at energies when their emission dominates.  The helium ion can
have departure coefficients much smaller than unity for nebular conditions
so the source function at helium-ionizing energies can be greater than the
Planck function.

\subsection{Save source function, depth}

The source function of the diffuse field at an energy slightly greater
than the Lyman continuum edge will be saved for all depths into the cloud.
All quantities are evaluated at the lowest energy continuum cell that lies
within the Lyman continuum.  The first column gives the integrated optical
depth from the illuminated face of the cloud to the current position.  The
second is the ratio of the diffuse field (photons per Rydberg per second)
to the absorption opacity.  The third is the OTS continuum at this frequency,
and the last is the ratio of the OTS continuum to the opacity, a photon
measure of the OTS source function.

%=============================================
\section{Save species [options]}
\label{sec:SaveSpecies}

These commands provide information about the molecules, atoms, and ions that are
treated by a unified ``species'' approach.

Several molecule models in the third-party database LAMDA separate species 
into ortho- and para- systems.  
The  \cdCommand{save species} command in this version of Cloudy has the limitation that 
only the last system in the LAMDA masterlist will be reported in the output.
This affects only the output of these commands.
All recognized systems will be included in the simulation.

\subsection{Specifying a particular species}
By default the \cdCommand{save species populations} and
\cdCommand{save species column densities} commands 
report details about all species that
exist during a calculation. 
If a string appears in double quotes, such as
\cdFilename{"He+2"} or \cdFilename{"H2O"},
only results for that particular species, in this case
\hePP\ or water, will be given.
The string must match one of the species labels, which are
listed with the \cdCommand{save species labels} command.
The species label must appear after the output file name,
as in the following example:
\begin{verbatim}
% save water column density
save species column density "pdr.col" "H2O"
\end{verbatim}

\subsection{Save species column densities}
This reports the column densities [\pscm] for all species, at the end of the iteration.
At low temperatures the highest levels may have no population so
only the lower levels with positive populations are printed.

\subsection{Save species energies}
This reports the level energies for all species.
The default is to give level energies in Rydbergs but this
can be changed with the \cdCommand{units} keyword.

\subsection{Save species labels}
\label{sec:SaveSpeciesLabels}
This gives a list of the species labels, a useful way to find out how
we refer to a particular atom, ion or molecule.

\subsection{Save species levels}
This reports the number of levels used for each species, for each zone.
If a species is not resolved, that is, it has no internal structure,
the number of levels will be given as zero.

\subsection{Save species populations}
This reports the level population [\pccm] for all species, for all zones.
The depth, species, and column densities for each level are given.
At low temperatures the highest levels may have no population so
only the lower levels with positive populations are printed.

%=============================================
\section{Save special}

If \cdCommand{special} is specified then routine
\cdRoutine{SaveSpecial} will be called.
This routine can be changed to fit the circumstances.

\section{Save tegrid}

The history of the last \cdVariable{NGRID} evaluations of the
heating and cooling will be saved.
\cdVariable{NGRID} is set in a header file.
This is one way to evaluate
the stability of the thermal solutions.

\section{Save temperature}

The radius is followed by the temperature and the derivative of the
cooling with respect to temperature $dC/dT$.
Next come the first and second spatial derivatives of the temperature
with respect to depth, $dT/dr$ and $d^2T/dr^2$.
These derivatives set the rates
of conductive heat flow and heat loss respectively.

\section{Save time dependent}
\label{sec:SaveTimeDependent}

This gives some information on a time-dependent model.

\section{Save TPredictor}

The code estimates the temperature of the next zone from the changes
in temperature that have occurred in previous zones.
This is only attempted
in a constant density geometry.
This output gives the old temperature,
the estimated new temperature, and the final equilibrium temperature.

\section{Save XSPEC [atable/mtable]}

This command produces a file in FITS format for input into the spectral
analysis program XSPEC (\citealp{Arnaud1996}).
This command was added by Ryan Porter
and its first application is given in \citet{Porter2006}.

Either \cdCommand{atable} or \cdCommand{mtable} must be specified. These
keywords refer to additive and multiplicative tables respectively. This
command is used with the \cdCommand{grid} command to produce grids of
calculations. The file produced by this command contains predictions
pertaining to the last iteration of each of the simulations (i.e.\ the keyword
\cdCommand{last} is implicitly in effect). A file produced with
\cdCommand{mtable} contains the energy bins and total optical depth,
exp($-\tau$), from the illuminated face to the last zone of each simulation in
the grid. A file produced with \cdCommand{atable} contains the energy bins and
some component of the spectrum, as determined by the following options:

\begin{description}

\item[total -] saves the sum of the outward spectrum and the reflected spectrum,
including diffuse and incident, lines and continua.

\item[[attenuated/reflected] incident continuum -] saves the incident
continuum, the attenuated incident continuum or the reflected incident
continuum;

\item[[reflected] diffuse continuum -] saves the outward diffuse continuum
or the reflected diffuse continuum;

\item[[reflected] lines -] saves outward lines or reflected lines; and

\item[[reflected] spectrum -] saves the total outward spectrum or the total
reflected spectrum.
\end{description}

By ``reflected'' we mean components escaping into
the $2\pi$~sr subtended by the illuminated face toward the continuum source.
If no options are specified for the \cdCommand{atable} command then the transmitted
spectra will be saved.  Note that the command can be specified multiple
times, allowing the user to individually save any or all of the separate
components of the predicted spectra.

By default the full spectral range will be saved.  The \cdCommand{range} option
will limit the range.  Both lower and upper limits must be specified.  The energies
must be in keV.

In the example below we specify that a blackbody is to be varied.
The
number on the \cdCommand{blackbody} line is ignored.
The \cdCommand{range} command specifies that
the log of the temperature of the blackbody will range from 4 to 6.
The
\cdCommand{grid} command specifies that we are calculating
a regularly spaced grid with 1 dex steps between 4 and 6.
In this case
since we only have one parameter varied with the \cdCommand{vary} keyword, there will
only be one dimension in the grid and only three simulations.
Each of the
two \cdCommand{save xspec atable} commands produces a FITS format file.  The first
file, named \cdFilename{filename1}, will contain the incident continuum for each of the
three simulations.
The second file, named \cdFilename{filename2}, will contain the
transmitted spectrum for each of the three simulations.
The commands are as follows:
\begin{verbatim}
blackbody 1e5 K vary
grid range 4 to 6 in 1 dex steps
save xspec atable incident continuum "filename1"
save xspec atable spectrum "filename2"
\end{verbatim}

\section{Save wind}

The radius and depth [cm] are followed by the velocity [cm s$^{-1}$],
total radiative acceleration [cm~s$^{-2}$],
the accelerations due to lines and continua
alone, and the dimensionless force multiplier.
If the keyword
\cdCommand{terminal}
appears then this is only produced for the last zone, otherwise it is for
every zone.
This option can be combined with the \cdCommand{save grid} command
to save predictions from a series of grid calculations.

\begin{shaded}
\section{\experimental State [get; put] ``filename''}

This command either saves or recovers the conditions computed in a
previous calculation.
In both cases the name of a file must appear between
two double quotes.
If the keyword \cdCommand{get} appears then the file is opened
for reading.  It must contain the state variables for a previous iteration
of the same simulation.
If the keyword \cdCommand{put} appears then the file is opened
for writing and the code's state at the end of the calculation is saved
in the file.
If the keyword print appears on the command line then a
detailed printout of the contents of the state file is produced.

This is intended as a debugging aid for dynamics simulations which require
many dozens of iterations to approach a solution.  It is under development
and is not ready for use.
\end{shaded}

\section{Title ``This is a title''}

The argument is a title for the calculation and can be useful for
organizing the models.  The preferred form is a quoted string, but if
this is not present, the whole of the line after the command will be
used for backward compatibility.

The title is reprinted several times to label output.

\section{Trace zone 94 [iteration 2; options . .]}

This command turns on \cdTerm{trace} information to follow
the logical flow within \Cloudy.
The code uses adaptive logic to control the calculation
and this option provides a way to follow these internal decisions.

The trace begins \emph{after} the zone given by the first number on the line.
If the zone is zero, or if no numbers occur on the line, then the trace
is turned on at the beginning of the calculation.  The second (optional
with default of 1) number is the iteration on which the trace should be
started.  It should be set to 2 to turn on the trace for the second
iteration.
So the command \cdCommand{trace 0 2} would start the trace at the
beginning of the second iteration.

Table \ref{tab:trace_conv} lists the trace keywords in the first column.
The four-character part
of the key that must be matched is capitalized.
The purpose of each is indicated in the last column.

A string including the word \cdMono{DEBUG} is printed when the
\cdCommand{trace} command is parsed.
This will not be printed if the option \cdCommand{no print} occurs
on the \cdCommand{trace} command.

\begin{table}
\centering
\caption{\label{tab:trace_conv}Trace convergence keywords and routines}
\begin{tabular}{ll}
\hline
Keyword& Routine\\
\hline
\cdCommand{pressure}& ConvPresTempEdenIoniz\\
\cdCommand{temperature}& ConvTempEdenIoniz\\
\cdCommand{eden}& ConvEdenIoniz\\
\cdCommand{ionization}& ConvIoniz\\
\hline
\end{tabular}
\end{table}

\subsection{Trace convergence level}

This is a special form of the \cdCommand{trace} command that prints an overview of
the decisions made during the calculation.
The physical state of the gas
is determined by nested pressure, temperature, electron density, and
ionization solvers.
This \cdCommand{trace} option makes it possible to view the
decisions made by any of these solvers.

The code will check for one of the keywords
\cdCommand{pressure}, \cdCommand{temperature}, \cdCommand{eden},
or \cdCommand{ionization},
and produce output explaining the decisions made by that
solver and all higher ones.
With no keyword all levels are printed.
Successively deeper layers are obtained with the keywords listed in
Table \ref{tab:trace_conv}.

There are further keywords that create additional printout.
The \cdCommand{OTS}
keyword will identify source of OTS fields.
The \cdCommand{ESOURCE} option will identify
sources of free electrons.

\subsection{Trace H-like [element name, full]}

This turns on extensive printout describing the physics of one of the
model hydrogenic atoms. The same code is used to compute atomic properties
for all hydrogenic species.  If the keyword \cdCommand{full} appears then the printout
will be far more detailed.  If no element is specified then this will only
be for hydrogen itself.  If the name of any other element appears then the
printout will be for that element.

\subsection{Trace He-like [element name, full]}

This turns on extensive printout describing the physics of one of the
model helium-like sequence atoms.  The same code is used for all helium-like
species.
If the keyword \cdCommand{full} appears then the printout will be far more
detailed.
If no element is specified then this will only be for helium
itself.
If the name of any other element appears then the printout will
describe that element.

\begin{table}
\centering
\caption{\label{tab:trace_keywords}Trace Keywords and Effects}
\begin{tabular}{ll}
\hline
Keyword& Quantity traced\\
\hline
BETA& OI 8446-\la\ problem\\
CARBon& carbon ionization
equilibrium\\
CALCium& calcium ionization balance\\
COMPton& Compton heating,
cooling,  and ionization\\
CONTinuum& prints out photon arrays,
pointers\\
CONVergence& convergence loop, no other
printout\\
COOLants& cooling\\
DIFFuse fields& sum of recombination coef in
DIFFEM\\
DR& choice of next zone thickness\\
EDEN& changes in electron
density\\
GAUNt& the free-free gaunt factors\\
GRAIN& details dealing with grain
treatment\\
HEATing& heating agents\\
HEAVies& heavy element balance\\
HELIum& helium
ionization equilibrium\\
HELIum ATOM& Helium singlets ionization
equilibrium\\
HELIum IONized& helium ion ionization equilibrium\\
HELIum
SINGlet& Helium singlets ionization equilibrium\\
HELIum TRIPlet& helium ion
ionization equilibrium\\
HYDRogen& Minimal trce of the H ionization\\
IRON& Fe
abundance, K-alpha emission\\
LINEes& line pointers, opacity. A's,
etc\\
leveln& LevelN n level atom routine\\
Ly BETA& L$\beta$ - OI 8446 pumping
problem\\
MOLEcules& rate
coefficients for molecules\\
NEON& recombination, ionization for neon\\
OPTICal
depths& inner, outer optical depths in STARTR\\
OPTIMizer& Steps in optimize
command driver\\
OTS& ots ionization rates\\
POINters& pointers for element
thresholds\\
THREe body& three-body recombination rates for metals\\
TWO
photon& induced two photon processes\\
WIND& Wind geometry\\
\hline
\end{tabular}
\end{table}

