introduction.tex

\section{Introduction} \label{sec:intro}

\subsection{Why are chemistry and radiative cooling necessary in
  simulations?}

Modeling of plasma chemistry and radiative cooling is absolutely
essential in a wide range of astrophysical phenomena.  At a
fundamental level, virtually all astrophysical objects begin as a
cloud of diffuse plasma in a gravitational potential that is created
primarily either by the plasma itself (i.e., stars) or by a dark
matter halo (i.e., cosmological structure).  In these situations, in
the absense of any additional physical processes, the plasma will
arrange itself so that pressure is in rough equilibrium with gravity,
and no further evolution will occur without some external influence.
Some physical process that allows this plasma to lose energy is
necessary in order to break this stalemate, thus allowing the
formation of stars and galaxies.  The process that typically enables
this energy loss is radiative cooling, often facilitated by a series
of chemical reactions that further enhance the plasma's ability to
lose energy.

Radiative cooling plays a critical role in several important
astrophysical processes.  There is a complex interplay of gas- and
dust-phase chemistry in star formation, which completely dominates the
dynamics of the evolving pre-stellar cloud, and may strongly influence
the resulting stellar initial mass function
\citep{2002Sci...295...93A, 2011ApJ...726...55T,
2008AIPC..990...25G}. At 
a smaller physical scale, radiative cooling can profoundly affect the
structure and behavior of accretion disks around stars and compact
objects \citep{1973A&A....24..337S}. The shape of the `cooling curve'
of diffuse astrophysical plasmas -- i.e., the cooling rate as a
function of density and temperature -- is responsible for the thermal
instability that generates a multiphase interstellar medium
\citep{1977ApJ...218..148M, 1978ppim.book.....S}.  In cosmological
structure formation, gas collapsing into dark matter halos generally
experiences a strong shock at roughly the virial radius, which heats
the gas to roughly the virial temperature.  Optically-thin radiative
cooling of this plasma allows gas to concentrate at the center of dark
matter halos, and ultimately to form molecular clouds and stars
\citep{1977MNRAS.179..541R, 1991ApJ...379...52W}.

Chemistry is often an important component of the evolution of
astrophysical plasmas.  The creation of simple molecules via gas- and
dust-phase chemical reactions can greatly enhance the efficacy of
cooling \citep{1979ApJS...41..555H, 2005ApJ...626..627O}.  The formation
and destruction of simple molecules can be energetically important in
some circumstances, such as Population III star formation
\citep{1998ApJ...508..141O, 2002Sci...295...93A, 2008MNRAS.388.1627G,
2009Sci...325..601T}.
And, from a dynamical perspective, the non-equilibrium evolution of
particular ions can have a strong effect on the ability of gas to cool
\citep{1997NewA....2..181A, 1997NewA....2..209A} and on common
observational quantities such as the column density of O {\sc vi} absorption
line systems in the intergalactic medium that are used to estimate the
metal content of the intergalactic medium and to trace the ``missing
baryons'' \citep{2006ApJ...650..573C, 2011ApJ...731....6S,
  2013MNRAS.430.1548H, 2013MNRAS.434.1043O, 2014ApJ...796...49S}.

\subsection{Why is a multi-code library a good thing?}

Utilizing identical implementations of microphysical solvers, such as
those for chemistry, provides several distinct advantages to the
developers and users of simulation codes as well as the broader
community of researchers who synthesize results of those simulation
codes.

Firstly, and most importantly, the development of a microphysical solver that
can be applied to multiple independent simulation codes reduces the technical,
social and cognitive overhead for collaboration amongst simulators.
This collaboration is a positive benefit in and of itself (particularly as it
reduces duplication of effort) but also provides opportunities to share
understanding, propagate bug fixes, and also to collaboratively implement 
algorithms that provide higher-fidelity results.  Increasing the ability of
researchers to directly collaborate around technology will increase overall
productivity.

With libraries such as the one presented here, where there is a set of
reference
physical values (such as chemical kinetic rate coefficients, drawn from
experimentation or detailed theoretical calculation), the existence of such a
library provides a fixed reference point for calculations that utilize those
reference values.  For instance, by citing a particular version of
the libary in a simulation paper, researchers can indicate which set of
values were used in the calculation.  In cases where results are found to
sensitively depend on these values, or when these reference values are updated,
this can guide deeper physical understanding.

An often underrecognized benefit of portable libraries
is the impact they have on the education and training of early-stage researchers.
For researchers at early stages in their career (such as graduate students and
postdocs) where changing institutions may mean utilizing a different simulation
platform, a shared chemistry package enables them to immediately transfer
developed code to new projects, rather than having to reimplement in a new
system.  Additionally, exposure to such a code that is a mix
of legacy and modern development styles, from several different maintainers,
provides insight into practices in computational science.

Perhaps the most obvious benefit to utilizing a multi-platform library such as
that which we shall now present, particularly in domains such as galaxy formation (where
controlled comparisons are necessary to decouple effects of star formation
prescriptions), is the simplification of directly comparing and reducing the
number of potential sources of difference between multiple calculations.

\subsection{Introducing Grackle}

In this paper, we introduce the \texttt{Grackle} chemistry and cooling
library for astrophysical simulations.  The aim of the
\texttt{Grackle} project is to provide all of the benefits outlined
above: to provide a community resource for accessing and disseminating
data and methods, create a citable version history for evolving
functionality, simplify comparison of results, and reduce the overhead
for collaboration.  In Section \ref{sec:origins}, we give an account
of the history of the \texttt{Grackle} source code and its development
leading up to this publication.  Following this, we describe the
library in full.  In Section \ref{sec:primordial_chemistry}, we detail
the non-equilibrium primordial chemistry solver.  In Section
\ref{Cooling}, we discuss the radiative cooling and heating processes
that are included.  In Section \ref{section:radback}, we describe
the treatment of UV radiation backgrounds.  In Section
\ref{methods:code}, we discuss implementation details, including the
simulation code API, the Python interface, the organization of
the source code, and the procedure for adding to the code.  In Section
\ref{sec:profiling-and-testing}, we describe the testing
infrastructure, the optimization strategy, and present performance
metrics.  Finally, we conclude in Section \ref{sec:summary} with a
discussion of the physical conditions in which the code is valid,
other limitations that should be considered, a list of simulation
codes known to have implemented \texttt{Grackle}, and some future
directions for the project.  Table \ref{tab:resources} lists the
locations of important \texttt{Grackle}-related resources.

\begin{table}
  \centering
  \caption{Important \texttt{Grackle} resources.}
  \label{tab:resources}
  \begin{tabular}{ll}
    \hline
    Source code & https://bitbucket.org/grackle/grackle\\
    Documentation & https://grackle.readthedocs.io/\\
    Mailing list & ``grackle-cooling-users'' on Google Groups\\
    \hline
  \end{tabular}
\end{table}


\section{Origins and Early History}
\label{sec:origins}

The original \texttt{Grackle} source code dates back to work done in
1995 by Peter Anninos and collaborators
\citep{1997NewA....2..209A} who developed a static Eulerian code
focused on primordial gas (e.g. Lyman alpha forest, first stars).
This code was then incorporated into the \texttt{Enzo} codebase in 2000
and modified to include more rates and physical processes.  Metal
cooling using tables from \texttt{Cloudy} was added in 2007
\citep{2008MNRAS.385.1443S}.  In 2012, the AGORA simulation comparison
project \citep{2014ApJS..210...14K} was first organized with the goal
of using a ``common physics package'' to eliminate differences in
results due to the use of cooling solvers that were specific to each
simulation code.  The modularity of \texttt{Enzo}'s cooling solver made
it relatively straightforward to extract it from the \texttt{Enzo}
source.  The initial commit to the \texttt{Grackle} repository,
marking the extraction of the core chemistry and cooling machinery,
was made on October 2, 2012.  The first official release
(\texttt{Grackle} 1.0) occurred on January 10, 2014, with five
additional major releases following over the next two and half years.
Integer increments of the version number marked changes to the
application program interface (API), while decimal releases included
only new features and bugfixes.  A list of all major releases is given
in Table \ref{tab:releases}.  A summary of \texttt{Grackle}'s
development history can be found at
\url{https://www.openhub.net/p/thegrackle}.

\begin{table}
  \centering
  \caption{Dates of major \texttt{Grackle} releases.}
  \label{tab:releases}
  \begin{tabular}{ll}
    \hline
    Version & Release Date\\
    \hline
    1.0 & January 10, 2014\\
    1.1 & October 1, 2014\\
    2.0 & October 1, 2014\\
    2.1 & June 3, 2015\\
    2.2 & May 18, 2016\\
    3.0 & November 1, 2016\\
    \hline
  \end{tabular}
\end{table}