API Reference

Grackle has two versions of most functions. The Primary Functions, discussed in Calling the Available Functions, make use of the grackle_field_data struct and internally stored instances chemistry_data and chemistry_data_storage structs. A set of Internal Functions also exist and require the user to provide their own instances of the chemistry_data and chemistry_data_storage.

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 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:
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:
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)

Internal Functions

These functions are mostly for internal use, but can also be used to call the various functions with different parameter values within a single code.

chemistry_data _set_default_chemistry_parameters(void);

Initializes and returns chemistry_data data structure. This must be called before run-time parameters can be set.

Returns:data structure containing all run-time parameters and all chemistry and cooling data arrays
Return type:chemistry_data
int _initialize_chemistry_data(chemistry_data *my_chemistry, chemistry_data_storage *my_rates, code_units *my_units);

Creates all chemistry and cooling rate data and stores within the provided chemistry_data_storage struct. This can only be called after _set_default_chemistry_parameters().

Parameters:
Return type:

int
Returns:

1 (success) or 0 (failure)
int _solve_chemistry(chemistry_data *my_chemistry, chemistry_data_storage *my_rates, code_units *my_units, double dt_value, int grid_rank, int *grid_dimension, int *grid_start, int *grid_end, gr_float *density, gr_float *internal_energy, gr_float *x_velocity, gr_float *y_velocity, gr_float *z_velocity, gr_float *HI_density, gr_float *HII_density, gr_float *HM_density, gr_float *HeI_density, gr_float *HeII_density, gr_float *HeIII_density, gr_float *H2I_density, gr_float *H2II_density, gr_float *DI_density, gr_float *DII_density, gr_float *HDI_density, gr_float *e_density, gr_float *metal_density);

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

Parameters:
  • my_chemistry (chemistry_data*) – the structure returned by _set_default_chemistry_parameters()
  • my_rates (chemistry_data_storage*) – chemistry and cooling rate data structure
  • my_units (code_units*) – code units conversions
  • dt_value (double) – the integration timestep in code units
  • grid_rank (int) – the dimensionality of the grid
  • grid_dimension (int*) – array holding the size of the baryon field in each dimension
  • grid_start (int*) – array holding the starting indices in each dimension of the active portion of the baryon fields. This is used to ignore ghost zones
  • grid_end (int*) – array holding the ending indices in each dimension of the active portion of the baryon fields. This is used to ignore ghost zones.
  • density (gr_float*) – array containing the density values in code units
  • internal_energy (gr_float*) – array containing the specific internal energy values in code units corresponding to erg/g
  • x_velocity (gr_float*) – array containing the x velocity values in code units
  • y_velocity (gr_float*) – array containing the y velocity values in code units
  • z_velocity (gr_float*) – array containing the z velocity values in code units
  • HI_density (gr_float*) – array containing the HI densities in code units equivalent those of the density array. Used with primordial_chemistry >= 1.
  • HII_density (gr_float*) – array containing the HII densities in code units equivalent those of the density array. Used with primordial_chemistry >= 1.
  • HM_density (gr_float*) – array containing the H- densities in code units equivalent those of the density array. Used with primordial_chemistry >= 2.
  • HeI_density (gr_float*) – array containing the HeI densities in code units equivalent those of the density array. Used with primordial_chemistry >= 1.
  • HeII_density (gr_float*) – array containing the HeII densities in code units equivalent those of the density array. Used with primordial_chemistry >= 1.
  • HeIII_density (gr_float*) – array containing the HeIII densities in code units equivalent those of the density array. Used with primordial_chemistry >= 1.
  • H2I_density (gr_float*) – array containing the H2: densities in code units equivalent those of the density array. Used with primordial_chemistry >= 2.
  • H2II_density (gr_float*) – array containing the H2+densities in code units equivalent those of the density array. Used with primordial_chemistry >= 2.
  • DI_density (gr_float*) – array containing the DI (deuterium) densities in code units equivalent those of the density array. Used with primordial_chemistry = 3.
  • DII_density (gr_float*) – array containing the DII densities in code units equivalent those of the density array. Used with primordial_chemistry = 3.
  • HDI_density (gr_float*) – array containing the HD densities in code units equivalent those of the density array. Used with primordial_chemistry = 3.
  • e_density (gr_float*) – array containing the e- densities in code units equivalent those of the density array but normalized to the ratio of the proton to electron mass. Used with primordial_chemistry >= 1.
  • metal_density (gr_float*) – array containing the metal densities in code units equivalent those of the density array. Used with metal_cooling = 1.
Return type:

int
Returns:

1 (success) or 0 (failure)
int _calculate_cooling_time(chemistry_data *my_chemistry, chemistry_data_storage *my_rates, code_units *my_units, int grid_rank, int *grid_dimension, int *grid_start, int *grid_end, gr_float *density, gr_float *internal_energy, gr_float *x_velocity, gr_float *y_velocity, gr_float *z_velocity, gr_float *HI_density, gr_float *HII_density, gr_float *HM_density, gr_float *HeI_density, gr_float *HeII_density, gr_float *HeIII_density, gr_float *H2I_density, gr_float *H2II_density, gr_float *DI_density, gr_float *DII_density, gr_float *HDI_density, gr_float *e_density, gr_float *metal_density, gr_float *cooling_time);

Calculates the instantaneous cooling time.

Parameters:
  • my_chemistry (chemistry_data*) – the structure returned by _set_default_chemistry_parameters()
  • my_rates (chemistry_data_storage*) – chemistry and cooling rate data structure
  • my_units (code_units*) – code units conversions
  • grid_rank (int) – the dimensionality of the grid
  • grid_dimension (int*) – array holding the size of the baryon field in each dimension
  • grid_start (int*) – array holding the starting indices in each dimension of the active portion of the baryon fields. This is used to ignore ghost zones
  • grid_end (int*) – array holding the ending indices in each dimension of the active portion of the baryon fields. This is used to ignore ghost zones.
  • density (gr_float*) – array containing the density values in code units
  • internal_energy (gr_float*) – array containing the specific internal energy values in code units corresponding to erg/g
  • x_velocity, y_velocity, z_velocity (gr_float*) – arrays containing the x, y, and z velocity values in code units
  • HI_density, HII_density, HM_density, HeI_density, HeII_density, HeIII_density, H2I_density, H2II_density, DI_density, DII_density, HDI_density, e_density, metal_density (gr_float*) – arrays containing the species densities in code units equivalent those of the density array
  • 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(chemistry_data *my_chemistry, chemistry_data_storage *my_rates, code_units *my_units, int grid_rank, int *grid_dimension, int *grid_start, int *grid_end, gr_float *density, gr_float *internal_energy, gr_float *HI_density, gr_float *HII_density, gr_float *HM_density, gr_float *HeI_density, gr_float *HeII_density, gr_float *HeIII_density, gr_float *H2I_density, gr_float *H2II_density, gr_float *DI_density, gr_float *DII_density, gr_float *HDI_density, gr_float *e_density, gr_float *metal_density, 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_chemistry (chemistry_data*) – the structure returned by _set_default_chemistry_parameters()
  • my_rates (chemistry_data_storage*) – chemistry and cooling rate data structure
  • my_units (code_units*) – code units conversions
  • grid_rank (int) – the dimensionality of the grid
  • grid_dimension (int*) – array holding the size of the baryon field in each dimension
  • grid_start (int*) – array holding the starting indices in each dimension of the active portion of the baryon fields. This is used to ignore ghost zones
  • grid_end (int*) – array holding the ending indices in each dimension of the active portion of the baryon fields. This is used to ignore ghost zones.
  • density (gr_float*) – array containing the density values in code units
  • internal_energy (gr_float*) – array containing the specific internal energy values in code units corresponding to erg/g
  • HI_density, HII_density, HM_density, HeI_density, HeII_density, HeIII_density, H2I_density, H2II_density, DI_density, DII_density, HDI_density, e_density, metal_density (gr_float*) – arrays containing the species densities in code units equivalent those of the density array
  • 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(chemistry_data *my_chemistry, chemistry_data_storage *my_rates, code_units *my_units, int grid_rank, int *grid_dimension, int *grid_start, int *grid_end, gr_float *density, gr_float *internal_energy, gr_float *HI_density, gr_float *HII_density, gr_float *HM_density, gr_float *HeI_density, gr_float *HeII_density, gr_float *HeIII_density, gr_float *H2I_density, gr_float *H2II_density, gr_float *DI_density, gr_float *DII_density, gr_float *HDI_density, gr_float *e_density, gr_float *metal_density, gr_float *pressure);

Calculates the gas pressure.

Parameters:
  • my_chemistry (chemistry_data*) – the structure returned by _set_default_chemistry_parameters()
  • my_rates (chemistry_data_storage*) – chemistry and cooling rate data structure
  • my_units (code_units*) – code units conversions
  • grid_rank (int) – the dimensionality of the grid
  • grid_dimension (int*) – array holding the size of the baryon field in each dimension
  • grid_start (int*) – array holding the starting indices in each dimension of the active portion of the baryon fields. This is used to ignore ghost zones
  • grid_end (int*) – array holding the ending indices in each dimension of the active portion of the baryon fields. This is used to ignore ghost zones.
  • density (gr_float*) – array containing the density values in code units
  • internal_energy (gr_float*) – array containing the specific internal energy values in code units corresponding to erg/g
  • HI_density, HII_density, HM_density, HeI_density, HeII_density, HeIII_density, H2I_density, H2II_density, DI_density, DII_density, HDI_density, e_density, metal_density (gr_float*) – arrays containing the species densities in code units equivalent those of the density array
  • 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(chemistry_data *my_chemistry, chemistry_data_storage *my_rates, code_units *my_units, int grid_rank, int *grid_dimension, int *grid_start, int *grid_end, gr_float *density, gr_float *internal_energy, gr_float *HI_density, gr_float *HII_density, gr_float *HM_density, gr_float *HeI_density, gr_float *HeII_density, gr_float *HeIII_density, gr_float *H2I_density, gr_float *H2II_density, gr_float *DI_density, gr_float *DII_density, gr_float *HDI_density, gr_float *e_density, gr_float *metal_density, gr_float *temperature);
Parameters:
  • my_chemistry (chemistry_data*) – the structure returned by _set_default_chemistry_parameters()
  • my_rates (chemistry_data_storage*) – chemistry and cooling rate data structure
  • my_units (code_units*) – code units conversions
  • grid_rank (int) – the dimensionality of the grid
  • grid_dimension (int*) – array holding the size of the baryon field in each dimension
  • grid_start (int*) – array holding the starting indices in each dimension of the active portion of the baryon fields. This is used to ignore ghost zones
  • grid_end (int*) – array holding the ending indices in each dimension of the active portion of the baryon fields. This is used to ignore ghost zones.
  • density (gr_float*) – array containing the density values in code units
  • internal_energy (gr_float*) – array containing the specific internal energy values in code units corresponding to erg/g
  • HI_density, HII_density, HM_density, HeI_density, HeII_density, HeIII_density, H2I_density, H2II_density, DI_density, DII_density, HDI_density, e_density, metal_density (gr_float*) – arrays containing the species densities in code units equivalent those of the density array
  • temperature (gr_float*) – array which will be filled with the calculated temperature values
Return type:

int
Returns:

1 (success) or 0 (failure)

Calculates the gas temperature.