py21cmfast.drivers.single_field

Compute single physical fields.

These functions are high-level wrappers around C-functions that compute 3D fields, for example initial conditions, perturbed fields and ionization fields.

Attributes

logger

Functions

brightness_temperature(...)

Compute a coeval brightness temperature box.

compute_emissivity_fields(...)

Compute grids of halo properties from a catalogue.

compute_halo_grid(...)

Compute the emissivity fields.

compute_initial_conditions(...)

Compute initial conditions.

compute_ionization_field(...)

Compute an ionized box at a given redshift.

compute_radiation_fields(...)

Compute the radiation fields, given the past emissivity fields.

compute_spin_temperature(...)

Compute spin temperature boxes at a given redshift.

determine_halo_catalog(...)

Find a halo list, given a redshift.

interp_emissivity_fields(...)

Interpolate EmissivityFields history to the desired redshift.

perturb_field(→ py21cmfast.wrapper.outputs.PerturbedField)

Compute a perturbed field at a given redshift.

perturb_halo_catalog(...)

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

setup_radiation_fields(...)

Set up arrays and quantities that are needed for calculating the radiation fields at this redshift.

Module Contents

py21cmfast.drivers.single_field.brightness_temperature(*, ionized_box: py21cmfast.wrapper.outputs.IonizedBox, perturbed_field: py21cmfast.wrapper.outputs.PerturbedField, spin_temp: py21cmfast.wrapper.outputs.TsBox | None = None) → py21cmfast.wrapper.outputs.BrightnessTemp[source]

Compute a coeval brightness temperature box.

Parameters:

  • ionized_box (IonizedBox) – A pre-computed ionized box.

  • perturbed_field (PerturbedField) – A pre-computed perturbed field at the same redshift as ionized_box.

  • spin_temp (TsBox, optional) – A pre-computed spin temperature, at the same redshift as the other boxes.

Returns:

BrightnessTemp instance.

Parameters:
Return type:

py21cmfast.wrapper.outputs.BrightnessTemp

py21cmfast.drivers.single_field.compute_emissivity_fields(*, redshift: float, initial_conditions: py21cmfast.wrapper.outputs.InitialConditions | None = None, inputs: py21cmfast.wrapper.inputs.InputParameters | None = None, halo_catalog: py21cmfast.wrapper.outputs.HaloCatalog | None = None, perturbed_field: py21cmfast.wrapper.outputs.PerturbedField | None = None, previous_spin_temp: py21cmfast.wrapper.outputs.TsBox | None = None, previous_ionize_box: py21cmfast.wrapper.outputs.IonizedBox | None = None) → py21cmfast.wrapper.outputs.EmissivityFields[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, optional) – The initial conditions of the run. Becomes relevant only for Lagrangian source models, or alternatively, if the user uses a Eulerian source model with USE_MCGS==True and V_CB_MODEL = “FLUCTS”.

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

  • perturbed_field (PerturbedField, optional) – The perturbed field at the current redshift. Becomes relevant only for Eulerian source models.

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

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

Returns:

EmissivityFields – An object containing the emissivity fields.

Other Parameters:

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

Parameters:
Return type:

py21cmfast.wrapper.outputs.EmissivityFields

py21cmfast.drivers.single_field.compute_halo_grid(**kwargs) → py21cmfast.wrapper.outputs.EmissivityFields[source]

Compute the emissivity fields.

This is a deprecated function. Use compute_emissivity_fields instead.

Return type:

py21cmfast.wrapper.outputs.EmissivityFields

py21cmfast.drivers.single_field.compute_initial_conditions(*, inputs: py21cmfast.wrapper.inputs.InputParameters, initial_density: numpy.ndarray | float | None = None) → py21cmfast.wrapper.outputs.InitialConditions[source]

Compute initial conditions.

Parameters:

  • inputs – The InputParameters instance defining the run.

  • initial_density (np.ndarray or float, optional) – A realization of the density field on the high resolution grid. This input can also be used to determine the global density field, in case we have a single cell in the box.

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

py21cmfast.wrapper.outputs.InitialConditions

py21cmfast.drivers.single_field.compute_ionization_field(*, perturbed_field: py21cmfast.wrapper.outputs.PerturbedField, initial_conditions: py21cmfast.wrapper.outputs.InitialConditions, inputs: py21cmfast.wrapper.inputs.InputParameters | None = None, previous_perturbed_field: py21cmfast.wrapper.outputs.PerturbedField | None = None, previous_ionized_box: py21cmfast.wrapper.outputs.IonizedBox | None = None, spin_temp: py21cmfast.wrapper.outputs.TsBox | None = None, emissivity_fields: py21cmfast.wrapper.outputs.EmissivityFields | None = None, halobox: py21cmfast.wrapper.outputs.EmissivityFields | None = None) → py21cmfast.wrapper.outputs.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:

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

  • perturbed_field (PerturbedField) – The perturbed density field.

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

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

  • emissivity_fields (EmissivityFields or None, optional) – If passed, this contains the emissivity fields, such as n_ion and weighted star formation density rate. Required only for lagrangian source models.

  • halobox (EmissivityFields or None, optional) – Deprecated. This argument has been renamed to emissivity_fields. Please use emissivity_fields instead.

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.single_field.compute_radiation_fields(*, emissivity_fields_list: list[py21cmfast.wrapper.outputs.EmissivityFields] | None = None, redshift: float, rad_setup: py21cmfast.wrapper.outputs.RadiationFieldsSetup | None = None, previous_ionize_box: py21cmfast.wrapper.outputs.IonizedBox | None = None, perturbed_field: py21cmfast.wrapper.outputs.PerturbedField | None = None, previous_spin_temp: py21cmfast.wrapper.outputs.TsBox | None = None, hboxes: list[py21cmfast.wrapper.outputs.EmissivityFields] | None = None) → py21cmfast.wrapper.outputs.RadiationFields[source]

Compute the radiation fields, given the past emissivity fields.

This will filter over the emissivity history in annuli, computing the contribution to the radiation fields.

Parameters:

  • redshift (float) – The redshift at which to compute the radiation fields.

  • rad_setup (RadiationFieldsSetup or None) – An object containing the required arrays for computing the radiation fields at this redshift.

  • emissivity_fields_list (Sequence of EmissivityFields instances) – This contains the list of EmissivityFields instances which are used to create this source field

  • hboxes (list of EmissivityFields instances or None) – Deprecated. This argument has been renamed to emissivity_fields_list. Please use emissivity_fields_list instead.

  • previous_ionize_box (IonizedBox or None) – An ionized box at higher redshift. This is only used if LYA_MULTIPLE_SCATTERING is true.

  • previous_spin_temp (TsBox or None) – The spin temperature box at the previous redshift. Becomes relevant only when redshift < Z_HEAT_MAX.

Returns:

RadiationFields – 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.RadiationFields

py21cmfast.drivers.single_field.compute_spin_temperature(*, initial_conditions: py21cmfast.wrapper.outputs.InitialConditions, perturbed_field: py21cmfast.wrapper.outputs.PerturbedField, inputs: py21cmfast.wrapper.inputs.InputParameters | None = None, radiation_fields: py21cmfast.wrapper.outputs.RadiationFields | None = None, previous_spin_temp: py21cmfast.wrapper.outputs.TsBox | None = None) → py21cmfast.wrapper.outputs.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:

  • 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) – The perturbed density field.

  • radiation_fields (RadiationFields or None) – This input specifies radiation fields, i.e. X-ray heating rate, photoionization rate, and Lyman-alpha flux. Required to compute the box, but may be None if the TsBox is read from the cache.

  • 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.single_field.determine_halo_catalog(*, redshift: float, inputs: py21cmfast.wrapper.inputs.InputParameters | None = None, initial_conditions: py21cmfast.wrapper.outputs.InitialConditions, descendant_halos: py21cmfast.wrapper.outputs.HaloCatalog | None = None) → py21cmfast.wrapper.outputs.HaloCatalog[source]

Find a halo list, given a redshift.

Parameters:

  • redshift (float) – The redshift at which to determine the halo list.

  • initial_conditions (InitialConditions instance) – The initial conditions fields (density, velocity).

  • descendant_halos (HaloCatalog instance, optional) – The halos that form the descendants (i.e. lower redshift) of those computed by this function. If this is not provided, we generate the initial stochastic halos directly in this function (and progenitors can then be determined by these).

Returns:

HaloCatalog

Other Parameters:

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

Parameters:
Return type:

py21cmfast.wrapper.outputs.HaloCatalog

py21cmfast.drivers.single_field.interp_emissivity_fields(emissivity_fields_list: list[py21cmfast.wrapper.outputs.EmissivityFields], interp_fields: list[str], redshift: float, need_c: bool) → py21cmfast.wrapper.outputs.EmissivityFields[source]

Interpolate EmissivityFields history to the desired redshift.

Photon conservation & Xray sources require emissivity_fields at redshifts that are not equal to the current redshift, and may be between redshift steps. So we need a function to interpolate between two emissivity_fields. We assume here that z_arr is strictly INCERASING

Parameters:

  • emissivity_fields_list (list of EmissivityFields instances) – The emissivity fields history to be interpolated

  • interp_fields (list[str]) – The properties of the emissivity fields to be interpolated

  • redshift (float) – The desired redshift of interpolation

  • need_c (bool) – Whether we need to compute the radiation field boxes in the C code or not.

Returns:

EmissivityFields – An object containing the emissivity fields data

Parameters:
Return type:

py21cmfast.wrapper.outputs.EmissivityFields

py21cmfast.drivers.single_field.perturb_field(*, redshift: float, inputs: py21cmfast.wrapper.inputs.InputParameters | None = None, initial_conditions: py21cmfast.wrapper.outputs.InitialConditions) → py21cmfast.wrapper.outputs.PerturbedField[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.single_field.perturb_halo_catalog(*, initial_conditions: py21cmfast.wrapper.outputs.InitialConditions, inputs: py21cmfast.wrapper.inputs.InputParameters | None = None, previous_spin_temp: py21cmfast.wrapper.outputs.TsBox | None = None, previous_ionize_box: py21cmfast.wrapper.outputs.IonizedBox | None = None, halo_catalog: py21cmfast.wrapper.outputs.HaloCatalog) → py21cmfast.wrapper.outputs.PerturbedHaloCatalog[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.single_field.setup_radiation_fields(*, emissivity_fields_list: list[py21cmfast.wrapper.outputs.EmissivityFields], redshift: float, previous_rad_setup: py21cmfast.wrapper.outputs.RadiationFieldsSetup | None = None, previous_spin_temp: py21cmfast.wrapper.outputs.TsBox | None = None) → py21cmfast.wrapper.outputs.RadiationFieldsSetup[source]

Set up arrays and quantities that are needed for calculating the radiation fields at this redshift.

Parameters:

  • redshift (float) – The redshift at which to compute the radiation fields.

  • emissivity_fields_list (Sequence of EmissivityFields instances) – This contains the list of EmissivityFields instances which are used to create this source field

  • previous_rad_setup (RadiationFieldsSetup or None) – An initialized object containing the required arrays for computing the radiation fields.

  • previous_spin_temp (TsBox or None) – The spin temperature box at the previous redshift. Becomes relevant only when redshift < Z_HEAT_MAX.

Returns:

RadiationFieldsSetup – An object containing the required arrays for computing the radiation fields, at this redshift.

Other Parameters:

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

Parameters:
Return type:

py21cmfast.wrapper.outputs.RadiationFieldsSetup

py21cmfast.drivers.single_field.logger[source]