The Grackle chemistry and cooling library for astrophysical simulations and models.
… image:: https://img.shields.io/badge/Users-List-lightgrey.svg
:target: https://groups.google.com/forum/#!forum/grackle-cooling-users
… image:: https://circleci.com/gh/grackle-project/grackle/tree/main.svg?style=svg
:target: https://circleci.com/gh/grackle-project/grackle/tree/main
… image:: https://readthedocs.org/projects/grackle/badge/?version=latest
:target: https://grackle.readthedocs.io/en/latest/?badge=latest)
Documentation <https://grackle.readthedocs.io/en/latest/>__ |
Installation <https://grackle.readthedocs.io/en/latest/Installation.html>__ |
Pygrackle Installation <https://grackle.readthedocs.io/en/latest/Python.html>__ |
Usage Guide <https://grackle.readthedocs.io/en/latest/Interaction.html>__ |
Integration Guide <https://grackle.readthedocs.io/en/latest/Integration.html>__ |
Contributing <https://grackle.readthedocs.io/en/latest/Contributing.html>__ |
Getting Help <https://grackle.readthedocs.io/en/latest/Help.html>__
… COMMENT: README-MAIN-BODY-START-ANCHOR
Grackle is a chemistry and radiative cooling library for astrophysical simulations and models.
The core library provides interfaces for C, C++ and Fortran simulation codes.
The project also offers the Pygrackle package to provide Python bindings.
Grackle provides functions to update chemistry species; solve radiative
cooling and update internal energy; and calculate cooling time, temperature,
pressure, and ratio of specific heats (γ).
The library offers
two options for primordial chemistry and cooling. It can (i) evolve a non-equilibrium chemistry network OR (ii) use tabulated cooling rates calculated with the photo-ionization code, Cloudy <http://nublado.org>__.
tabulated metal cooling rates calculated with Cloudy <http://nublado.org>__.
photo-heating and photo-ionization (with optional self-shielding corrections) from either the Faucher-Giguere et al. (2009) <http://adsabs.harvard.edu/abs/2009ApJ...703.1416F>__ or Haardt & Madau (2012) <http://adsabs.harvard.edu/abs/2012ApJ...746..125H>__ UV backgrounds.
support for user-provided arrays of volumetric and specific heating rates.
Our method paper <http://adsabs.harvard.edu/abs/2017MNRAS.466.2217S>__ provides more information.
Grackle is a popular tool (the method paper <http://adsabs.harvard.edu/abs/2017MNRAS.466.2217S>__ has over 290 citations) and has been used in a wide variety of calculations.
Below, we list open source projects that provide out-of-the-box support for Grackle:
ChaNGa <https://github.com/N-BodyShop/changa>,
Cholla <https://github.com/cholla-hydro/cholla>,
Enzo <https://enzo-project.org/>,
Enzo-E <https://enzo-e.readthedocs.io/en/latest/>,
Gamer <https://github.com/gamer-project/gamer>,
Gasoline <https://github.com/N-BodyShop/gasoline>,
GIZMO <http://www.tapir.caltech.edu/~phopkins/Site/GIZMO.html>,
Swift <https://github.com/SWIFTSIM/SWIFT>
We welcome PRs to add your simulation code (or python package) to this list.
Currently, Grackle must be built from source.
If you only need Grackle as a dependency of a simulation code and that code is built with CMake, then that code’s build system might be configured to automatically fetch, build, and link Grackle into the code for you (Enzo-E <https://enzo-e.readthedocs.io/en/latest/>__ is an example of a code configured in this manner).
If you contribute to a simulation code, our Integration Guide <https://grackle.readthedocs.io/en/latest/Integration.html>__ provides guidance on simplifying the process (for you and your users) of configuring your code to use Grackle.
Building the Core Grackle Library From Source
Grackle requires a C99 compiler, a Fortran compiler, and HDF5 (1.6 or newer).
On most platforms, compilation with the CMake build system (3.16 or newer) is as simple as:
.. code-block:: shell-session
cmake -B build # configure the build-directory
cmake --build ./build # perform the build
You can invoke the examples from within the ``build/examples`` directory (`we're adding support <https://github.com/grackle-project/grackle/pull/246>`__ to let you run them from anywhere).
To build Grackle as a shared lib, replace the first command with ``cmake -DBUILD_SHARED_LIBS=ON -Bbuild``.
To install Grackle, invoke ``cmake --install ./build [--prefix <prefix/path>]`` (the optional part lets you specify an install-path).
For more details **(especially if you encounter any errors),** see our comprehensive `Installation Guide <https://grackle.readthedocs.io/en/latest/Installation.html>`__.
It provides more context for inexperienced CMake users, describes additional configuration options (relevant if you encounter issues), and describes Grackle's "classic" build-system.
Building Pygrackle from Source
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Once you have a Fortran compiler and a copy of HDF5 (1.6 or newer), simply invoke the following from the root of the Grackle repository
.. code-block:: shell-session
~/grackle $ pip install .
For more about installation see our `Pygrackle installation guide <https://grackle.readthedocs.io/en/latest/Python.html>`__.
Getting Started
---------------
To help you start using Grackle, we provide:
- a `Usage Guide <https://grackle.readthedocs.io/en/latest/Interaction.html>`__
- example Grackle programs written in `C, C++, and Fortran <https://github.com/grackle-project/grackle/tree/main/src/example>`__
- an `Integration Guide <https://grackle.readthedocs.io/en/latest/Integration.html>`__ (for linking Grackle)
- a curated `guide <https://grackle.readthedocs.io/en/latest/Python.html#running-the-example-scripts>`__ for the Pygrackle examples
Contributing
------------
Grackle is a community project!
We welcome patches, features, and bugfixes from any member of the community!
For more details, please see our `Constribution Guide <https://grackle.readthedocs.io/en/latest/Contributing.html>`__ and our `Code of Conduct <https://grackle.readthedocs.io/en/latest/Conduct.html>`__
Citing Grackle
--------------
If you use Grackle please cite it.
More instructions are provided `here <https://grackle.readthedocs.io/en/latest/Citing.html>`__.