API Reference

Grackle has two versions of most functions.

  1. The Primary Functions, discussed in Calling the Available Functions, make use of internally stored instances of the chemistry_data and chemistry_data_storage structs declared in grackle.h.

  2. Local Functions require pointers to chemistry_data and chemistry_data_storage instances to be provided as arguments. These are explicity thread-safe as they use no global data.

Additionally, there are also some Miscellaneous Functions and Rate Functions.

Primary Functions

int set_default_chemistry_parameters(chemistry_data *my_grackle_data);

Initializes the grackle_data data structure. This must be called before run-time parameters can be set.

Parameters:
Return type:

int

Returns:

1 (success) or 0 (failure)

int initialize_chemistry_data(code_units *my_units);

Loads all chemistry and cooling data, given the set run-time parameters. This can only be called after set_default_chemistry_parameters().

Parameters:

  • my_units (code_units*) – code units conversions

Return type:

int

Returns:

1 (success) or 0 (failure)

int free_chemistry_data();

Deallocates all data allocations made during the call to initialize_chemistry_data(). Issues may arise if the global grackle_data data structure was mutated between the call to initialize_chemistry_data() and the call to this function.

Return type:

int

Returns:

1 (success) or 0 (failure)

void set_velocity_units(code_units *my_units);

Sets the velocity_units value of the input my_units code_units struct. For proper coordinates, velocity units are equal to length_units / time_units. For comoving coordinates, velocity units are equal to (length_units / a_value) / time_units.

Parameters:

  • my_units (code_units*) – code units conversions

double get_velocity_units(const code_units *my_units);

Returns the appropriate value for velocity units given the values of length_units, a_value, and time_units in the input my_units code_units struct. For proper coordinates, velocity units are equal to length_units / time_units. For comoving coordinates, velocity units are equal to (length_units / a_value) / time_units. Note, this function only returns a value, but does not set it in the struct. To set the value in the struct, use set_velocity_units.

Parameters:

  • my_units (code_units*) – code units conversions

Return type:

double

Returns:

velocity_units

double get_temperature_units(const code_units *my_units);

Returns the factor that includes unit conversions and fundamental constants that must be multiplied by internal_energy (in units of velocity_units2) to get temperature (in units of K). In more detail:

  • the returned value is defined as mH*velocity_units2/kb, where mH is the Hydrogen mass and kb is the Boltzmann constant.

  • under the standard assumption of an ideal gas, temperature is given by internal_energy*temperature_units*\((\gamma - 1)\)*\(\mu\), where \(\gamma\) is the adiabatic index and \(\mu\) is the mean molecular weight.

Parameters:

  • my_units (code_units*) – code units conversions

Return type:

double

Returns:

temperature_units

int solve_chemistry(code_units *my_units, grackle_field_data *my_fields, double dt_value);

Evolves the species densities and internal energies over a given timestep by solving the chemistry and cooling rate equations.

Parameters:

  • my_units (code_units*) – code units conversions

  • my_fields (grackle_field_data*) – field data storage

  • dt_value (double) – the integration timestep in code units

Return type:

int

Returns:

1 (success) or 0 (failure)

int calculate_cooling_time(code_units *my_units, grackle_field_data *my_fields, gr_float *cooling_time);

Calculates the instantaneous cooling time.

Parameters:

  • my_units (code_units*) – code units conversions

  • my_fields (grackle_field_data*) – field data storage

  • cooling_time (gr_float*) – array which will be filled with the calculated cooling time values

Return type:

int

Returns:

1 (success) or 0 (failure)

int calculate_gamma(code_units *my_units, grackle_field_data *my_fields, gr_float *my_gamma);

Calculates the effective adiabatic index. This is only useful with primordial_chemistry >= 2 as the only thing that alters gamma from the single value is H2.

Parameters:

  • my_units (code_units*) – code units conversions

  • my_fields (grackle_field_data*) – field data storage

  • my_gamma (gr_float*) – array which will be filled with the calculated gamma values

Return type:

int

Returns:

1 (success) or 0 (failure)

int calculate_pressure(code_units *my_units, grackle_field_data *my_fields, gr_float *pressure);

Calculates the gas pressure.

Parameters:

  • my_units (code_units*) – code units conversions

  • my_fields (grackle_field_data*) – field data storage

  • pressure (gr_float*) – array which will be filled with the calculated pressure values

Return type:

int

Returns:

1 (success) or 0 (failure)

int calculate_temperature(code_units *my_units, grackle_field_data *my_fields, gr_float *temperature);

Calculates the gas temperature.

Parameters:

  • my_units (code_units*) – code units conversions

  • my_fields (grackle_field_data*) – field data storage

  • temperature (gr_float*) – array which will be filled with the calculated temperature values

Return type:

int

Returns:

1 (success) or 0 (failure)

int calculate_dust_temperature(code_units *my_units, grackle_field_data *my_fields, gr_float *dust_temperature);

Calculates the dust temperature. The dust temperature calculation is modified from its original version (Section 4.3 of Smith et al. 2017) to also include the heating of dust grains by the interstellar radiation field following equation B15 of Krumholz (2014).

Using this function requires dust_chemistry > 0 or h2_on_dust > 0.

Parameters:

  • my_units (code_units*) – code units conversions

  • my_fields (grackle_field_data*) – field data storage

  • dust_temperature (gr_float*) – array which will be filled with the calculated dust temperature values

Return type:

int

Returns:

1 (success) or 0 (failure)

grackle_version get_grackle_version();

Constructs and returns a grackle_version struct that encodes the version information for the library.

Return type:

grackle_version

Local Functions

These can be used to create explicitly thread-safe code or to call the various functions with different parameter values within a single code.

Initializing/Configuring Chemistry Parameters and Storage

The approach for initializing/configuring the chemistry_data and chemistry_data_storage structs for use with the Local Functions differs to some degree from the previously described approach that is used with Primary Functions.

We highlight the steps down below. For the sake of argument let’s imagine that the user is storing the chemistry data in a variable called my_chemistry.

  1. First, the user should allocate my_chemistry and initialize the stored parameters with local_initialize_chemistry_parameters().

    chemistry_data *my_chemistry = new chemistry_data;
if (local_initialize_chemistry_parameters(my_chemistry) == 0) {
   fprintf(stderr, "Error in local_initialize_chemistry_parameters.\n");
}

  2. Next, the user can configure the stored parameters. They can do this by directly modifying the stored parameters (e.g. my_chemistry->use_grackle = 1) or by using the Dynamic configuration of Chemistry Data.

After the user has finished initializing my_chemistry, and has configured an instance of code_units (more detail provided here), they can initialize an instance of chemistry_data_storage with local_initialize_chemistry_data():

chemistry_data_storage* my_rates = new chemistry_data_storage;
if (local_initialize_chemistry_data(my_chemistry, my_rates, &my_units) == 0) {
  fprintf(stderr, "Error in local_initialize_chemistry_data.\n");
  return 0;
}

Configuration/Cleanup Functions

int local_initialize_chemistry_parameters(chemistry_data *my_chemistry);

Initializes the parameters stored in the chemistry_data data structure to their default values. This should be called before run-time parameters are set.

This is the “local” counterpart to set_default_chemistry_parameters().

Parameters:
Return type:

int

Returns:

1 (success) or 0 (failure)

int local_initialize_chemistry_data(chemistry_data *my_chemistry, chemistry_data_storage *my_rates, code_units *my_units);

Allocates storage for and initializes the values of all relevant chemistry and cooling rate data. This data is stored within the provided chemistry_data_storage struct. This is the “local” counterpart to initialize_chemistry_data().

This function should only be called after the user has finished configuring both my_chemistry and my_units. This function assumes that none of my_rates’s members of pointer type hold valid memory addresses (i.e. where applicable, the function allocates fresh storage and makes no attempts to deallocate/reuse storage).

After calling this function, the user should avoid modifying any of the fields of my_chemistry. The user should also be careful to only modify values in my_units in a way that satisfies the criteria discussed in Comoving Coordinates (this discussion also applies to proper coordinates).

To deallocate any storage allocated by this function, use free_chemistry_data().

Parameters:
Return type:

int

Returns:

1 (success) or 0 (failure)

Note

In addition to modifying the contents of my_rates, this function may also mutate the values stored in my_chemistry to set them to “more sensible” values (based on other values stored in my_chemistry).

int local_free_chemistry_data(chemistry_data *my_chemistry, chemistry_data_storage *my_rates);

Deallocates all data held by the members of my_rates allocated during its initialization in local_initialize_chemistry_data() (or initialize_chemistry_data()). Issues may arise if my_chemistry was mutated between the initialization of my_rates and the call to this function.

This is the “local” counterpart to free_chemistry_data().

Parameters:
Return type:

int

Returns:

1 (success) or 0 (failure)

Chemistry Functions

int local_solve_chemistry(chemistry_data *my_chemistry, chemistry_data_storage *my_rates, code_units *my_units, grackle_field_data *my_fields, double dt_value);

Evolves the species densities and internal energies over a given timestep by solving the chemistry and cooling rate equations.

Parameters:
Return type:

int

Returns:

1 (success) or 0 (failure)

int local_calculate_cooling_time(chemistry_data *my_chemistry, chemistry_data_storage *my_rates, code_units *my_units, grackle_field_data *my_fields, gr_float *cooling_time);

Calculates the instantaneous cooling time.

Parameters:
Return type:

int

Returns:

1 (success) or 0 (failure)

int local_calculate_gamma(chemistry_data *my_chemistry, chemistry_data_storage *my_rates, code_units *my_units, grackle_field_data *my_fields, gr_float *my_gamma);

Calculates the effective adiabatic index. This is only useful with primordial_chemistry >= 2 as the only thing that alters gamma from the single value is H2.

Parameters:
Return type:

int

Returns:

1 (success) or 0 (failure)

int local_calculate_pressure(chemistry_data *my_chemistry, chemistry_data_storage *my_rates, code_units *my_units, grackle_field_data *my_fields, gr_float *pressure);

Calculates the gas pressure.

Parameters:
Return type:

int

Returns:

1 (success) or 0 (failure)

int local_calculate_temperature(chemistry_data *my_chemistry, chemistry_data_storage *my_rates, code_units *my_units, grackle_field_data *my_fields, gr_float *temperature);

Calculates the gas temperature.

Parameters:
Return type:

int

Returns:

1 (success) or 0 (failure)

int local_calculate_dust_temperature(chemistry_data *my_chemistry, chemistry_data_storage *my_rates, code_units *my_units, grackle_field_data *my_fields, gr_float *dust_temperature);

Calculates the dust temperature.

Parameters:
Return type:

int

Returns:

1 (success) or 0 (failure)

Dynamic Configuration Functions

unsigned int grackle_num_params(const char *type_name)

Returns the number of parameters of a given type that are stored as members of the chemistry_data struct. The argument is expected to be "int", "double", or "string". This will return 0 for any other argument

The following functions are used to provide dynamic access to members of the chemistry_data struct. They will return NULL when my_chemistry is NULL, param_name isn’t a known parameter, or the param_name is not associated with the type mentioned in the function name.

int *local_chemistry_data_access_int(chemistry_data *my_chemistry, const char *param_name);

Returns the pointer to the member of my_chemistry associated with param_name.

Parameters:
Return type:

int*

double *local_chemistry_data_access_double(chemistry_data *my_chemistry, const char *param_name);

Returns the pointer to the member of my_chemistry associated with param_name.

Parameters:
Return type:

double*

char **local_chemistry_data_access_string(chemistry_data *my_chemistry, const char *param_name);

Returns the pointer to the member of my_chemistry associated with param_name.

Parameters:
Return type:

char**

The following functions are used to query the name of the ith field of the chemistry_data struct of a particular type.

const char *param_name_int(unsigned int i);

Query the name of the ith int field from chemistry_data.

Warning

The order of parameters may change between different versions of Grackle.

Parameters:

  • i (unsigned int) – The index of the accessed parameter

Return type:

const char*

Returns:

Pointer to the string-literal specifying the name. This is NULL, if chemistry_data has i or fewer int members

const char *param_name_double(unsigned int i);

Query the name of the ith double field from chemistry_data.

Warning

The order of parameters may change between different versions of Grackle.

Parameters:

  • i (unsigned int) – The index of the accessed parameter

Return type:

const char*

Returns:

Pointer to the string-literal specifying the name. This is NULL, if chemistry_data has i or fewer double members.

const char *param_name_string(unsigned int i);

Query the name of the ith string field from chemistry_data.

Warning

The order of parameters may change between different versions of Grackle.

Parameters:

  • i (unsigned int) – The index of the accessed parameter

Return type:

const char*

Returns:

Pointer to the string-literal specifying the name. This is NULL, if chemistry_data has i or fewer string members.

Miscellaneous Functions

int gr_initialize_field_data(grackle_field_data *my_fields);

Initializes the struct-members stored in the grackle_field_data data structure to their default values.

This function must assume that any existing data within the data structure is garbage data. In other words, when this function goes to overwrite a given member of grackle_field_data, it completely ignores the value currently held by the member (i.e. the function does not provide special handling for members holding non- NULL pointers). Consequently, this function should ONLY be called BEFORE initializing any members of the data structure (if it’s called at any other time, the program may leak memory resources).

Parameters:
Return type:

int

Returns:

1 (success) or 0 (failure)

double gr_query_units(const chemistry_data_storage *my_rates, const char *units_name, double current_a_value);

Added in version 3.4.

Queries the expected value of a unit quantity at an arbitrary cosmological scale factor.

In more detail, makes strong assumptions about the contents of the code_units data structure based on its initial configuration when initializing chemistry_data_storage (in initialize_chemistry_data() or local_initialize_chemistry_data()). The code_units’s contents cannot change in simulations without comoving coordinates. In simulations with comoving coordinates, grackle’s functions expect the caller to change the code_units’s configuration in a manner that is parameterized by the data structure’s initial configuration and the current cosmologial scale factor.

This function primarily exists as a convenience tool for downstream developers to query what the data structure’s contents should be at a given cosmological scale factor.

Parameters:

  • my_rates (const chemistry_data_storage*) – fully initialized chemistry and cooling rate data structure

  • units_name (const char*) – The name of the unit quantity to be queried. Allowed options include "a_value", "a_units”, "density_units", "length_units", "temperature_units", "time_units", "velocity_units".

  • current_a_value (double) – The current value of the expansion factor in units of a_units. When passed a value given by the GR_SPECIFY_INITIAL_A_VALUE constant, the function assumes that you want the value used during initial configuration.

Return type:

double

Returns:

Value associated with the quantity. A negative value denotes an error.

Note

The GR_SPECIFY_INITIAL_A_VALUE constant will always be defined in the same scope as this function. Be aware, we may allow the associated value to change over time.

Warning

If grackle was configured with comoving_coordinates == 0, this function considers any choice of current_a_value other than GR_SPECIFY_INITIAL_A_VALUE or an EXACT match to the initial choice of a_value to be an error.

int gr_check_consistency();

Added in version 3.4.

Verifies the consistency between the Grackle libraries used at compile time and runtime.

At the time of writing, the function simply verifies that the definitions of gr_float are consistent. In the future, this function may perform other checks (e.g. version consistency).

The most common cause for this function to fail is that an application was compiled with headers from one Grackle installation, and is dynamically linked against a shared library from a separate incompatible Grackle installation.

Return type:

int

Returns:

GR_SUCCESS if successful