API Reference
Grackle has two versions of most functions.
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.
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.
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:
-
- 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:
-
-
double get_velocity_units(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:
-
- Return type:
double
- Returns:
velocity_units
-
double get_temperature_units(code_units *my_units);
Returns the conversion factor between specific internal energy and temperature
assuming gamma (the adiabatic index) = 1, such that temperature in K is equal to
internal_energy * temperature_units. This unit conversion is
defined as mH * velocity_units2 / kb,
where mH is the Hydrogen mass and kb is the Boltzmann constant.
- Parameters:
-
- 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.
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");
}
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:
-
- 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:
-
- 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:
-
- 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.