py21cmfast.wrapper.ionize_box

py21cmfast.wrapper.ionize_box(*, astro_params=None, flag_options=None, redshift=None, perturbed_field=None, previous_perturbed_field=None, previous_ionize_box=None, spin_temp=None, pt_halos=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) → IonizedBox[source]

Compute an ionized box at a given redshift.

This function has various options for how the evolution of the ionization is computed (if at all). See the Notes below for details.

Parameters:

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

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

  • redshift (float, optional) – The redshift at which to compute the ionized box. If perturbed_field is given, its inherent redshift will take precedence over this argument. If not, this argument is mandatory.

  • 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.

  • previous_perturbed_field (PerturbField, optional) – An perturbed field at higher redshift. This is only used if mini_halo is included.

  • 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.

  • previous_ionize_box (IonizedBox or None) – An ionized box at higher redshift. This is only used if INHOMO_RECO and/or do_spin_temp are true. If either of these are true, and this is not given, then it will be assumed that this is the “first box”, i.e. that it can be populated accurately without knowing source statistics.

  • spin_temp (TsBox or None, optional) – A spin-temperature box, only required if do_spin_temp is True. If None, will try to read in a spin temp box at the current redshift, and failing that will try to automatically create one, using the previous ionized box redshift as the previous spin temperature redshift.

  • pt_halos (PerturbHaloField or None, optional) – If passed, this contains all the dark matter haloes obtained if using the USE_HALO_FIELD. This is a list of halo masses and coords for the dark matter haloes. If not passed, it will try and automatically create them using the available initial conditions.

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

IonizedBox – An object containing the ionized box data.

Other Parameters:

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

Notes

Typically, the ionization field at any redshift is dependent on the evolution of xHI up until that redshift, which necessitates providing a previous ionization field to define the current one. This function provides several options for doing so. First, if neither the spin temperature field, nor inhomogeneous recombinations (specified in flag options) are used, no evolution needs to be done. Otherwise, either (in order of precedence)

  1. a specific previous :class`~IonizedBox` 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 ionization field will be evaluated based on z_step_factor.

Examples

By default, no spin temperature is used, and neither are inhomogeneous recombinations, so that no evolution is required, thus the following will compute a coeval ionization box:

>>> xHI = ionize_box(redshift=7.0)

However, if either of those options are true, then a full evolution will be required:

>>> xHI = ionize_box(redshift=7.0, flag_options=FlagOptions(INHOMO_RECO=True,USE_TS_FLUCT=True))

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

>>> xHI = ionize_box(redshift=7.0, zprime_step_factor=1.2, z_heat_max=15.0,
>>>                  flag_options={"USE_TS_FLUCT":True})

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

>>> ts_box = ionize_box(redshift=7.0, previous_ionize_box=8.0, flag_options={
>>>                     "USE_TS_FLUCT":True})

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

>>> xHI_0 = ionize_box(redshift=8.0, flag_options={"USE_TS_FLUCT":True})
>>> xHI = ionize_box(redshift=7.0, previous_ionize_box=xHI_0)

Again, the first line here will implicitly use ZPRIME_STEP_FACTOR to evolve the field from Z_HEAT_MAX. Note that in the second line, all of the input parameters are taken directly from xHI_0 so that they are consistent, and we need not specify the flag_options.

As the function recursively evaluates previous redshift, the previous spin temperature fields will also be consistently recursively evaluated. Only the final ionized box will actually be returned and kept in memory, however intervening results will by default be cached on disk. One can also pass an explicit spin temperature object:

>>> ts = spin_temperature(redshift=7.0)
>>> xHI = ionize_box(redshift=7.0, spin_temp=ts)

If automatic recursion is used, then it is done in such a way that no large boxes are kept around in memory for longer than they need to be (only two at a time are required).