py21cmfast.drivers

Driving functions for computing 21cmFAST outputs.

In this sub-package, we have functions both for running the low-level outputs (e.g. initial conditions, perturb fields, spin temperature, etc.) and for high-level outputs such as coeval boxes and lightcones.

Submodules

Classes

Coeval

A full coeval box with all associated data.

LightCone

A full Lightcone with all associated evolved data.

Functions

compute_halo_grid(*, redshift, initial_conditions[, ...])

Compute grids of halo properties from a catalogue.

compute_initial_conditions(*, inputs)

Compute initial conditions.

compute_ionization_field(*, perturbed_field, ...[, ...])

Compute an ionized box at a given redshift.

compute_spin_temperature(*, initial_conditions, ...[, ...])

Compute spin temperature boxes at a given redshift.

compute_xray_source_field(*, initial_conditions, ...)

Compute filtered grid of SFR for use in spin temperature calculation.

generate_coeval(*[, inputs, out_redshifts, ...])

Perform a full coeval simulation of all fields at given redshifts.

generate_lightcone(*, lightconer, inputs[, ...])

Create a generator function for a lightcone run.

perturb_field(*, redshift[, inputs])

Compute a perturbed field at a given redshift.

perturb_halo_catalog(*, initial_conditions[, inputs, ...])

Given a halo list, perturb the halos for a given redshift.

run_coeval(**kwargs)

Run a coeval simulation and return the resulting coeval boxes.

run_lightcone(**kwargs)

Run a lightcone simulation and return the final lightcone object.

Package Contents

py21cmfast.drivers.compute_halo_grid(*, redshift, initial_conditions, inputs=None, halo_catalog=None, previous_spin_temp=None, previous_ionize_box=None)[source]

Compute grids of halo properties from a catalogue.

At the moment this simply produces halo masses, stellar masses and SFR on a grid of HII_DIM. In the future this will compute properties such as emissivities which will be passed directly into ionize_box etc. instead of the catalogue.

Parameters:

  • initial_conditions (InitialConditions) – The initial conditions of the run.

  • inputs (InputParameters, optional) – The input parameters specifying the run.

  • halo_catalog (HaloCatalog, optional) – This contains all the dark matter haloes obtained if using a discrete halo model. This is a list of halo masses and coordinates for the dark matter halos.

  • previous_spin_temp (TsBox, optional) – The previous spin temperature box. Used for feedback when USE_MINI_HALOS==True

  • previous_ionize_box (IonizedBox or None) – An at the last timestep. Used for feedback when USE_MINI_HALOS==True

Returns:

HaloBox – An object containing the halo box data.

Other Parameters:

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

Parameters:
Return type:

py21cmfast.wrapper.outputs.HaloBox

py21cmfast.drivers.compute_initial_conditions(*, inputs)[source]

Compute initial conditions.

Parameters:

  • inputs – The InputParameters instance defining the run.

  • regenerate (bool, optional) – Whether to force regeneration of data, even if matching cached data is found.

  • cache – An OutputCache object defining how to read cached boxes.

  • write – A boolean specifying whether we need to cache the box.

Returns:

InitialConditions

Parameters:

inputs (py21cmfast.wrapper.inputs.InputParameters)

Return type:

py21cmfast.wrapper.outputs.InitialConditions

py21cmfast.drivers.compute_ionization_field(*, perturbed_field, initial_conditions, inputs=None, previous_perturbed_field=None, previous_ionized_box=None, spin_temp=None, halobox=None)[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:

  • initial_conditions (InitialConditions instance) – The initial conditions.

  • inputs (InputParameters) – The input parameters specifying the run. Since this may be the first box to use the astro params/flags, it is needed when we have not computed a TsBox or HaloBox.

  • perturbed_field (PerturbedField) – The perturbed density field.

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

  • previous_ionize_box (IonizedBox or None) – An ionized box at higher redshift. This is only used if INHOMO_RECO and/or USE_TS_FLUCT 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 USE_TS_FLUCT 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.

  • halobox (HaloBox or None, optional) – If passed, this contains all the dark matter haloes obtained if using the lagrangian source models. These are grids containing summed halo properties such as ionizing emissivity.

Returns:

IonizedBox – An object containing the ionized box data.

Parameters:
Return type:

py21cmfast.wrapper.outputs.IonizedBox

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. If neither the spin temperature field, nor inhomogeneous recombinations (specified in flag options) are used, no evolution needs to be done. If the redshift is beyond Z_HEAT_MAX, previous fields are not required either.

py21cmfast.drivers.compute_spin_temperature(*, initial_conditions, perturbed_field, inputs=None, xray_source_box=None, previous_spin_temp=None, cleanup=False)[source]

Compute spin temperature boxes at a given redshift.

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

Parameters:

  • initial_conditions (InitialConditions) – The initial conditions

  • inputs (InputParameters) – The input parameters specifying the run. Since this will be the first box to use the astro params/flags when SOURCE_MODEL=’E-INTEGRAL’ and USE_TS_FLUCT=True.

  • perturbed_field (PerturbedField, optional) – If given, this field will be used, otherwise it will be generated. To be generated, either initial_conditions and redshift must be given, or simulation_options, 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.

  • xray_source_box (XraySourceBox, optional) – When using a lagrangian source model, this box specifies the filtered sfr and xray emissivity at all redshifts/filter radii required by the spin temperature algorithm.

  • previous_spin_temp (TsBox or None) – The previous spin temperature box. Needed when we are beyond the first snapshot

Returns:

TsBox – An object containing the spin temperature box data.

Other Parameters:

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

Parameters:
Return type:

py21cmfast.wrapper.outputs.TsBox

py21cmfast.drivers.compute_xray_source_field(*, initial_conditions, hboxes, redshift)[source]

Compute filtered grid of SFR for use in spin temperature calculation.

This will filter over the halo history in annuli, computing the contribution to the SFR density

If no halo field is passed one is calculated at the desired redshift as if it is the first box.

Parameters:

  • initial_conditions (InitialConditions) – The initial conditions of the run. The user and cosmo params

  • hboxes (Sequence of HaloBox instances) – This contains the list of Halobox instances which are used to create this source field

Returns:

XraySourceBox – An object containing x ray heating, ionisation, and lyman alpha rates.

Other Parameters:

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

Parameters:
Return type:

py21cmfast.wrapper.outputs.XraySourceBox

py21cmfast.drivers.generate_coeval(*, inputs=None, out_redshifts=(), regenerate=None, write=True, cache=None, initial_conditions=None, cleanup=True, progressbar=False)[source]

Perform a full coeval simulation of all fields at given redshifts.

This is generally the easiest and most efficient way to generate a set of coeval cubes at a given set of redshifts. It self-consistently deals with situations in which the field needs to be evolved, and does this with the highest memory-efficiency, only returning the desired redshift. All other calculations are by default stored in the on-disk cache so they can be re-used at a later time.

Some calculations of the coeval quantities require redshift evolution, i.e. the calculation of higher-redshift coeval boxes up to some maximum redshift in order to integrate the quantities over cosmic time. The redshifts that define this evolution are set by the inputs.node_redshifts parameter. However, in some simple cases, this evolution is not required, and this parameter can be empty. Thus there is a distinction between the redshifts required for computing the physics (i.e. inputs.node_redshifts) and the redshifts at which the user wants to obtain the resulting coeval cubes. The latter is controlled by out_redshifts. If not set, out_redshifts will be set to inputs.node_redshifts, so that all computed redshifts are returned as coeval boxes.

Note

User-supplied out_redshifts are not used in the redshift evolution, so that the results depend precisely on the node_redshifts defined in the input parameters.

Parameters:

  • inputs (InputParameters) – This object specifies the input parameters for the run, including the random seed

  • out_redshifts (array_like, optional) – A single redshift, or multiple redshifts, at which to return results. By default, use all the inputs.node_redshifts. If neither is specified, an error will be raised.

  • regenerate (bool) – If True, regenerate all fields, even if they are in the cache.

  • write (CacheConfig, optional) – Either a bool specifying whether to write _all_ the boxes to cache (or none of them), or a CacheConfig object specifying which boxes to write.

  • cache (OutputCache, optional) – The cache object to use for reading and writing data from the cache. This should be an instance of OutputCache, which depends solely on specifying a directory to host the cache.

  • initial_conditions (InitialConditions, optional) – If given, use these intial conditions as a basis for computing the other fields, instead of re-computing the ICs. If this is defined, the inputs do not need to be defined (but can be, in order to overwrite the node_redshifts).

  • 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 calculated has different shape, errors will occur if memory is not cleaned. Note that internally, this is set to False until the last iteration.

  • progressbar (bool, optional) – If True, a progress bar will be displayed throughout the simulation. Defaults to False.

Returns:

coevals (list of Coeval) – The full data for the Coeval class, with init boxes, perturbed fields, ionized boxes, brightness temperature, and potential data from the conservation of photons. A list of such objects, one for each redshift in out_redshifts.

Parameters:
py21cmfast.drivers.generate_lightcone(*, lightconer, inputs, initial_conditions=None, include_dvdr_in_tau21=True, apply_rsds=False, n_rsd_subcells=4, cleanup=True, write=_cache, cache=_ocache, regenerate=True, progressbar=False, lightcone_filename=None)[source]

Create a generator function for a lightcone run.

This is generally the easiest and most efficient way to generate a lightcone, though it can be done manually by using the lower-level functions which are called by this function.

Parameters:

  • lightconer (Lightconer) – This object specifies the dimensions, redshifts, and quantities required by the lightcone run

  • inputs (InputParameters) – This object specifies the input parameters for the run, including the random seed

  • initial_conditions (InitialConditions, optional) – If given, the user and cosmo params will be set from this object, and it will not be re-calculated.

  • include_dvdr_in_tau21 (bool, optional) – If True, velocity gradient corrections to the 21cm optical depth will be applied. See Mao+ 2012. Default is True.

  • apply_rsds (bool, optional) – If True, all output lightcones will be transformed from real space to redshift space, according to the peculiar velocity fields. See Mao+ 2012. Default is False.

  • n_rsd_subcells (int, optional) – The number of subcells into which each cell is divided when redshift space distortions are applied. Becomes relevant only if apply_rsds is True. Default is False.

  • 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. Note that internally, this is set to False until the last iteration.

  • progressbar (bool, optional) – If True, a progress bar will be displayed throughout the simulation. Defaults to False.

  • lightcone_filename – The filename to which to save the lightcone. The lightcone is returned in memory, and can be saved manually later, but including this filename will save the lightcone on each iteration, which can be helpful for checkpointing.

Returns:

  • lightcone (LightCone) – The lightcone object.

  • coeval_callback_output (list) – Only if coeval_callback in not None.

Other Parameters:

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

Parameters:
py21cmfast.drivers.perturb_field(*, redshift, inputs=None, initial_conditions)[source]

Compute a perturbed field at a given redshift.

Parameters:

  • redshift (float) – The redshift at which to compute the perturbed field.

  • initial_conditions (InitialConditions instance) – The initial conditions.

Returns:

PerturbedField

Other Parameters:

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

Parameters:
Return type:

py21cmfast.wrapper.outputs.PerturbedField

Examples

>>> initial_conditions = compute_initial_conditions()
>>> field7 = perturb_field(7.0, initial_conditions)
>>> field8 = perturb_field(8.0, initial_conditions)

The user and cosmo parameter structures are by default inferred from the initial_conditions.

py21cmfast.drivers.perturb_halo_catalog(*, initial_conditions, inputs=None, previous_spin_temp=None, previous_ionize_box=None, halo_catalog)[source]

Given a halo list, perturb the halos for a given redshift.

Parameters:

  • initial_conditions (InitialConditions) – The initial conditions of the run. The user and cosmo params as well as the random seed will be set from this object.

  • halo_catalog (:class: ~HaloCatalog) – The halo catalogue in Lagrangian space to be perturbed.

Returns:

PerturbedHaloCatalog

Other Parameters:

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

Parameters:
Return type:

py21cmfast.wrapper.outputs.PerturbedHaloCatalog

Examples

Fill this in once finalised

py21cmfast.drivers.run_coeval(**kwargs)[source]

Run a coeval simulation and return the resulting coeval boxes.

This simply wraps generate_coeval() and returns a list of coeval objects at the requested output redshifts after the generator has been exhausted. All parameters are passed directly to generate_coeval().

Return type:

list[Coeval]

py21cmfast.drivers.run_lightcone(**kwargs)[source]

Run a lightcone simulation and return the final lightcone object.

This simply wraps generate_lightcone() and returns the final lightcone object after the generator has been exhausted. All parameters are passed directly to generate_lightcone().

Return type:

LightCone