py21cmfast.wrapper.spin_temperature

py21cmfast.wrapper.spin_temperature(*, astro_params=None, flag_options=None, redshift=None, perturbed_field=None, previous_spin_temp=None, init_boxes=None, cosmo_params=None, user_params=None, regenerate=None, write=None, direc=None, random_seed=None, cleanup=True, hooks=None, **global_kwargs) → TsBox[source]

Compute spin temperature boxes at a given redshift.

See the notes below for how the spin temperature field is evolved through redshift.

Parameters:

  • astro_params (AstroParams, optional) – The astrophysical parameters defining the course of reionization.

  • flag_options (FlagOptions, optional) – Some options passed to the reionization routine.

  • redshift (float, optional) – The redshift at which to compute the ionized box. If not given, the redshift from perturbed_field will be used. Either redshift, perturbed_field, or previous_spin_temp must be given. See notes on perturbed_field for how it affects the given redshift if both are given.

  • perturbed_field (PerturbField, optional) – If given, this field will be used, otherwise it will be generated. To be generated, either init_boxes and redshift must be given, or user_params, cosmo_params and redshift. By default, this will be generated at the same redshift as the spin temperature box. The redshift of perturb field is allowed to be different than redshift. If so, it will be interpolated to the correct redshift, which can provide a speedup compared to actually computing it at the desired redshift.

  • previous_spin_temp (TsBox or None) – The previous spin temperature box.

  • init_boxes (InitialConditions, optional) – If given, and perturbed_field not given, these initial conditions boxes will be used to generate the perturbed field, otherwise initial conditions will be generated on the fly. If given, the user and cosmo params will be set from this object.

  • user_params (UserParams, optional) – Defines the overall options and parameters of the run.

  • cosmo_params (CosmoParams, optional) – Defines the cosmological parameters used to compute initial conditions.

  • cleanup (bool, optional) – A flag to specify whether the C routine cleans up its memory before returning. Typically, if spin_temperature is called directly, you will want this to be true, as if the next box to be calculate has different shape, errors will occur if memory is not cleaned. However, it can be useful to set it to False if scrolling through parameters for the same box shape.

  • **global_kwargs – Any attributes for GlobalParams. This will temporarily set global attributes for the duration of the function. Note that arguments will be treated as case-insensitive.

Returns:

TsBox – An object containing the spin temperature box data.

Other Parameters:

regenerate, write, direc, random_seed – See docs of initial_conditions() for more information.

Notes

Typically, the spin temperature field at any redshift is dependent on the evolution of spin temperature up until that redshift, which necessitates providing a previous spin temperature field to define the current one. This function provides several options for doing so. Either (in order of precedence):

  1. a specific previous spin temperature object is provided, which will be used directly,

  2. a previous redshift is provided, for which a cached field on disk will be sought,

  3. a step factor is provided which recursively steps through redshift, calculating previous fields up until Z_HEAT_MAX, and returning just the final field at the current redshift, or

  4. the function is instructed to treat the current field as being an initial “high-redshift” field such that specific sources need not be found and evolved.

Note

If a previous specific redshift is given, but no cached field is found at that redshift, the previous spin temperature field will be evaluated based on z_step_factor.

Examples

To calculate and return a fully evolved spin temperature field at a given redshift (with default input parameters), simply use:

>>> ts_box = spin_temperature(redshift=7.0)

This will by default evolve the field from a redshift of at least Z_HEAT_MAX (a global parameter), in logarithmic steps of z_step_factor. Thus to change these:

>>> ts_box = spin_temperature(redshift=7.0, zprime_step_factor=1.2, z_heat_max=15.0)

Alternatively, one can pass an exact previous redshift, which will be sought in the disk cache, or evaluated:

>>> ts_box = spin_temperature(redshift=7.0, previous_spin_temp=8.0)

Beware that doing this, if the previous box is not found on disk, will continue to evaluate prior boxes based on the z_step_factor. Alternatively, one can pass a previous spin temperature box:

>>> ts_box1 = spin_temperature(redshift=8.0)
>>> ts_box = spin_temperature(redshift=7.0, previous_spin_temp=ts_box1)

Again, the first line here will implicitly use z_step_factor to evolve the field from around Z_HEAT_MAX. Note that in the second line, all of the input parameters are taken directly from ts_box1 so that they are consistent. Finally, one can force the function to evaluate the current redshift as if it was beyond Z_HEAT_MAX so that it depends only on itself:

>>> ts_box = spin_temperature(redshift=7.0, zprime_step_factor=None)

This is usually a bad idea, and will give a warning, but it is possible.