The Grackle project: turning a research code into a software package


I will present the Grackle project: a library for chemistry and cooling in astrophysical simulations. As a library, Grackle provides functionality needed by almost all astrophysical simulation codes with an API that is easy to implement. As an open-source project, Grackle provides a resource to the astronomical community where new models and data can be easily shared. I will discuss some of the key features of Grackle, such as its primary functions and Python interface, as well as how research software engineers can grow a project like this from a piece of single-use research code into a package with community development, user support, documentation, and testing.



Modeling the evolution of astrophysical structures requires the combination of a host of non-linear phenomena, including gravity, hydrodynamics, and the atomic-scale physics that determines the efficiency with which a plasma can lose energy through radiative and chemical processes. Simulation codes follow all of these processes simultaneously by solving the relevant partial differential equations for a set of moving particles or stationary grid cells that represent a spatial distribution of gas and dark matter. Numerous simulation codes exist within the astronomical community with a variety of solvers that are distinct not only in terms of their implementation but often algorithmically speaking as well. For gravity and hydrodynamics, the governing equations are well-known and effectively complete such that a solver that has been shown to work correctly will never have to be updated for reasons of accuracy (barring paradigm shifts in our understanding of fluid motion and gravity on large scales).

This is not the case for gas chemistry. Computing the chemical evolution of a gas requires solving a complicated network of reactions whose complexity grows exponentially with the number of elements and species of those elements (e.g., the various ionization states and molecular forms) considered. For a typical modern simulation containing millions to billions of particles/cells, this becomes prohibitively expensive with just a few elements. Additionally, the rates for many of these reactions are highly uncertain (e.g., (Glover 2008, Turk 2011)) with accepted values periodically changing due to new results from experimentation (see (Kreckel 2010, O’Connor 2015, de Ruette 2016) for just a few examples). Thus, chemistry and cooling solvers represent, at best, a snapshot of an ever-evolving body of knowledge. However, similar to gravity and hydro solvers, they are largely developed in-house for use with the specific simulation code used by that research group. Hence, the burden of keeping them up-to-date is one carried by many throughout the community but not shared.

We present the Grackle11 project as a solution to this problem. Grackle is an open-source library for solving chemistry and cooling in astrophysical simulations with interfaces to C, C++, Fortran, and Python codes. In response to the call for a ”common physics package” made by the AGORA simulation comparison project (Kim 2014) in 2012, the core machinery of the chemistry solver implemented in the Enzo simulation code (Bryan) was converted into an external library, marking the beginning of the Grackle project. Since that time, the code has been developed independently from Enzo. The library has been implemented into roughly a dozen different simulation codes and has become a community resource for both accessing and disseminating new rates, models, and methods. The primary goal of this paper is to document the path of Grackle from a niche research code to a community software project. Before that, we present an overview of the core functionality in Section \ref{sec:func} and the APIs in Section \ref{sec:api}. Then, in Section \ref{sec:dev}, we discuss the evolution of the project and the key components that enable development and use by a distributed community. A conclusion follows in Section \ref{sec:conclusion}.



The primary function of Grackle is to evolve the internal energy for a set of computational elements representing parcels of gas. The internal energy of gas changes due to radiative losses from atomic and molecular transitions and heat input from an incident radiation field. For both historical and pragmatic reasons, Grackle treats the primordial elements (those created in the Big Bang, i.e., Hydrogen and Helium) separately from heavier elements (those created in stellar processes, e.g., Carbon, Oxygen, Iron, etc.), referred to in the astronomical community as metals. These components are discussed individually below. Both the primordial and metal species can be heated by radiation fields. As this component can be activated independently, we describe it in its own section. The details of Grackle’s functionality are presented in full in the official Grackle method paper, Smith et al., in preparation11See the Citation section in