py21cmfast

The py21cmfast package.

Submodules

Attributes

config

A singleton Config object used to manage global configuration options.

Classes

AngularLightconer

Angular lightcone slices constructed from rectlinear coevals.

AstroOptions

Options for the ionization routines which enable/disable certain modules.

AstroParams

Astrophysical parameters.

BrightnessTemp

A class containing the brightness temperature box.

CacheConfig

A configuration object that specifies whether a certain field should be cached.

Coeval

A full coeval box with all associated data.

CosmoParams

Cosmological parameters.

EmissivityFields

A class containing all gridded halo properties.

GlobalEvolution

Structure that contains the global evolution (as a function of redshift) of all the fields in the simulation.

HaloBox

Deprecated alias for EmissivityFields.

HaloCatalog

A class containing all fields related to halos.

InitialConditions

A class representing an InitialConditions C-struct.

InputParameters

A class defining a collection of InputStruct instances.

IonizedBox

A class containing all ionized boxes.

LightCone

A full Lightcone with all associated evolved data.

MatterOptions

Structure containing options which affect the matter field (ICs, perturbedfield, halos).

OutputCache

An object that manages cache files from 21cmFAST simulations.

PerturbedField

A class containing all perturbed field boxes.

PerturbedHaloCatalog

A class to hold a HaloCatalog whose coordinates are in real (Eulerian) space.

RadiationFields

A class containing the radiation fields.

RectilinearLightconer

The class rectilinear lightconer.

RunCache

An object that specifies all cache files that should/can exist for a full run.

SimulationOptions

Structure containing broad simulation options.

TsBox

A class containing all spin temperature boxes.

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_luminosity_function(→ tuple[numpy.ndarray, ...)

Compute a the luminosity function over a given number of bins and redshifts.

compute_radiation_fields(...)

Compute the radiation fields, given the past emissivity fields.

compute_rms(→ collections.abc.Sequence[float])

Compute the root-mean-square of a field at given redshifts.

compute_spin_temperature(...)

Compute spin temperature boxes at a given redshift.

compute_tau(→ float)

Compute the optical depth to reionization under the given model.

configure_logging()

Configure logging for the '21cmFAST' logger.

create_params_from_template(→ dict[str, ...)

Construct the required InputStruct instances for a run from a given template.

determine_halo_catalog(...)

Find a halo list, given a redshift.

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.

get_logspaced_redshifts(→ tuple[float, ...])

Compute a sequence of redshifts to evolve over that are log-spaced.

list_templates(→ list[dict])

Return a list of the available templates.

load_high_level_simulation(path[, safe])

Read a saved high-level simulation output, determining its type automatically.

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.

read_inputs(→ py21cmfast.wrapper.inputs.InputParameters)

Read the InputParameters from a cache file.

read_output_struct(...)

Read an output struct from an HDF5 file.

run_classy(→ classy.Class)

Run CLASS with specified input parameters.

run_coeval(→ list[Coeval])

Run a coeval simulation and return the resulting coeval boxes.

run_global_evolution(→ GlobalEvolution)

Compute the global evolution of all the fields in the simulation.

run_lightcone(→ LightCone)

Run a lightcone simulation and return the final lightcone object.

setup_photon_cons(initial_conditions[, inputs])

Set up the photon non-conservation correction.

write_output_to_hdf5(output, path[, group, mode])

Write an output struct in standard HDF5 format.

write_template(inputs, template_file[, mode, only_structs])

Write a set of input parameters to a template file.

Package Contents

py21cmfast.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.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.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.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.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.compute_luminosity_function(*, redshifts: collections.abc.Sequence[float], inputs: py21cmfast.wrapper.inputs.InputParameters, nbins: int = 100, mturnovers: numpy.ndarray | None = None, mturnovers_mini: numpy.ndarray | None = None, lightcone: py21cmfast.drivers.lightcone.LightCone | None = None, global_evolution: py21cmfast.drivers.global_evolution.GlobalEvolution | None = None, component: Literal['both', 'acg', 'mcg'] = 'both') → tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray][source]

Compute a the luminosity function over a given number of bins and redshifts.

Parameters:

  • redshifts (array-like) – The redshifts at which to compute the luminosity function.

  • inputs (InputParameters) – The input parameters defining the simulation run.

  • nbins (int, optional) – The number of luminosity bins to produce for the luminosity function.

  • lightcone (LightCone or None, optional) – The lightcone object to use for the computation. If None, the function will consider global_evolution for the global turnover masses, otherwise they will be extracted from the given lightcone.

  • global_evolution (GlobalEvolution or None, optional) – The global evolution object to use for the computation. If None, the function will run a global evolution to estimate the global turnover masses, otherwise they will be extracted from the given global evolution.

  • component (str, {‘both’, ‘acg’, ‘mcg}) – The component of the LF to be calculated. Forced to be ‘acg’ if USE_MCGS is False.

Returns:

  • Muvfunc (np.ndarray) – Magnitude array (i.e. brightness). Shape [nredshifts, nbins]

  • Mhfunc (np.ndarray) – Halo mass array. Shape [nredshifts, nbins]

  • lfunc (np.ndarray) – Number density of haloes corresponding to each bin defined by Muvfunc. Shape [nredshifts, nbins].

Parameters:
Return type:

tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

py21cmfast.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.compute_rms(classy_output: classy.Class, kind: str = 'd_m', redshifts: collections.abc.Sequence[float] = 0, smoothing_radius: float = 0) → collections.abc.Sequence[float][source]

Compute the root-mean-square of a field at given redshifts.

Parameters:

  • classy_output (classy.Class) – An object containing all the information from the CLASS calculation.

  • kind (str, optioanl) – The type of field for which the rms shall be computed. Options are:

    • “d_b”, “d_cdm”, “d_m”: density field of baryons, cold dark matter, or all matter (including massive neutrinos).

    • “v_b”, “v_cdm”: magnitude of the velocity vector field of baryons or CDM (this is gauge dependent).

    • “v_cb”: magnitude of the relative velocity vector field between baryons and CDM (this is gauge independent).

    Default is “d_m”.

  • redshifts (np.array or a float, optional) – The redshifts at which the rms shall be computed. Default is 0.

  • smoothing_radius (float, optional) – If non-zero, the field will be smoothed with a top hat filter (in real space) with comoving radius that is set to R_smooth. Can also be passed as type ‘astropy.units.quantity.Quantity’ with length unit. Default is 0.

Returns:

rms (np.array) – Array of the rms of the desired field at the given redshifts.

Parameters:

  • classy_output (classy.Class)

  • kind (str)

  • redshifts (collections.abc.Sequence[float])

  • smoothing_radius (float)

Return type:

collections.abc.Sequence[float]

py21cmfast.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.compute_tau(*, redshifts: collections.abc.Sequence[float], global_xHI: collections.abc.Sequence[float], inputs: py21cmfast.wrapper.inputs.InputParameters, z_re_HeII: float = 3.0) → float[source]

Compute the optical depth to reionization under the given model.

Parameters:

  • redshifts (array-like) – Redshifts defining an evolution of the neutral fraction.

  • global_xHI (array-like) – The mean neutral fraction at redshifts.

  • inputs (InputParameters) – Defines the input parameters of the run

  • z_re_HeII (float, optional) – The redshift at which helium reionization occurs.

Returns:

tau (float) – The optical depth to reionization

Raises:

ValueError : – If redshifts and global_xHI have inconsistent length or if redshifts are not in ascending order.

Parameters:
Return type:

float

py21cmfast.configure_logging()[source]

Configure logging for the ‘21cmFAST’ logger.

py21cmfast.create_params_from_template(template_name: str | pathlib.Path | collections.abc.Sequence[str | pathlib.Path], **kwargs) → dict[str, py21cmfast.wrapper.inputs.InputStruct][source]

Construct the required InputStruct instances for a run from a given template.

Parameters:

template_name (str,) – defines the name/alias of the native template (see templates/manifest.toml for a list) alternatively, is the path to a TOML file containing tables titled [CosmoParams], [SimulationOptions], [AstroParams] and [AstroOptions] with parameter settings

Other Parameters:

  • Any other parameter passed is considered to be a name and

  • value of a parameter in any of the `InputStruct` subclasses,

  • and will be used to over-ride the template values.

Returns:

input_dict (dict containing:) –

cosmo_paramsCosmoParams

Instance containing cosmological parameters

simulation_optionsSimulationOptions

Instance containing general run parameters

simulation_optionsMatterOptions

Instance containing general run flags and enums

astro_paramsAstroParams

Instance containing astrophysical parameters

astro_optionsAstroOptions

Instance containing astrophysical flags and enums

Parameters:

template_name (str | pathlib.Path | collections.abc.Sequence[str | pathlib.Path])

Return type:

dict[str, py21cmfast.wrapper.inputs.InputStruct]

py21cmfast.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.generate_coeval(*, inputs: py21cmfast.wrapper.inputs.InputParameters | None = None, out_redshifts: float | tuple[float, ...] = (), regenerate: bool | None = None, write: py21cmfast.io.caching.CacheConfig | bool = True, cache: py21cmfast.io.caching.OutputCache | None = None, initial_conditions: py21cmfast.wrapper.outputs.InitialConditions | None = None, progressbar: bool = 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).

  • 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.generate_lightcone(*, lightconer: py21cmfast.lightconers.Lightconer, inputs: py21cmfast.wrapper.inputs.InputParameters, initial_conditions: py21cmfast.wrapper.outputs.InitialConditions | None = None, include_dvdr_in_tau21: bool = True, apply_rsds: bool = False, n_rsd_subcells: int = 4, write: py21cmfast.io.caching.CacheConfig = _cache, cache: py21cmfast.io.caching.OutputCache | None = _ocache, regenerate: bool = True, progressbar: bool = False, lightcone_filename: str | pathlib.Path | None = 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.

  • 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.get_logspaced_redshifts(min_redshift: float, z_step_factor: float, max_redshift: float) → tuple[float, ...][source]

Compute a sequence of redshifts to evolve over that are log-spaced.

Parameters:

  • min_redshift (float)

  • z_step_factor (float)

  • max_redshift (float)

Return type:

tuple[float, …]

py21cmfast.list_templates() → list[dict][source]

Return a list of the available templates.

Return type:

list[dict]

py21cmfast.load_high_level_simulation(path: str | pathlib.Path, safe: bool = True)[source]

Read a saved high-level simulation output, determining its type automatically.

This is a convenience wrapper around the from_file methods of the high-level simulation outputs, for when you don’t know (or don’t care) which kind of output a file holds. To read the lower-level cache files instead, use read_output_struct().

Parameters:

  • path – The path to a saved coeval, lightcone or global-evolution file.

  • safe – Whether to raise an error if the input parameters in the file are not readable by this version of 21cmFAST.

Returns:

Coeval, LightCone or GlobalEvolution – The object stored in the file.

Raises:

ValueError – If the file is not a recognized 21cmFAST high-level output.

Parameters:

  • path (str | pathlib.Path)

  • safe (bool)

py21cmfast.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.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.read_inputs(group: h5py.Group | pathlib.Path | h5py.File, safe: bool = True) → py21cmfast.wrapper.inputs.InputParameters[source]

Read the InputParameters from a cache file.

Parameters:

  • group (h5py.Group | Path | h5py.File) – A file, or HDF5 Group within a file, to read the input parameters from.

  • safe (bool, optional) – If in safe mode, errors will be raised if keys exist in the file that are not valid attributes of the InputParameters. Otherwise, only warnings will be raised.

Returns:

inputs (InputParameters) – The input parameters contained in the file.

Parameters:

  • group (h5py.Group | pathlib.Path | h5py.File)

  • safe (bool)

Return type:

py21cmfast.wrapper.inputs.InputParameters

py21cmfast.read_output_struct(path: pathlib.Path, group: str = '/', struct: str | None = None, safe: bool = True) → py21cmfast.wrapper.outputs.OutputStruct[source]

Read an output struct from an HDF5 file.

Parameters:

  • path (Path) – The path to the HDF5 file.

  • group (str, optional) – A path within the HDF5 heirarchy to the top-level of the OutputStruct. This is usually the root of the file.

  • struct – A string specifying the kind of OutputStruct to read (e.g. InitialConditions). Generally, this does not need to be provided, as cache files contain just a single output struct.

  • safe – Whether to read the file in “safe” mode. If True, keys found in the file that are not valid attributes of the struct will raise an exception. If False, only a warning will be raised.

Returns:

OutputStruct – An OutputStruct that is contained in the cache file.

Parameters:

  • path (pathlib.Path)

  • group (str)

  • struct (str | None)

  • safe (bool)

Return type:

py21cmfast.wrapper.outputs.OutputStruct

py21cmfast.run_classy(**kwargs) → classy.Class[source]

Run CLASS with specified input parameters.

Parameters:

kwargs – Optional keywords to pass to CLASS.

Returns:

output (classy.Class) – An object containing all the information from the CLASS calculation.

Return type:

classy.Class

py21cmfast.run_coeval(**kwargs) → list[Coeval][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.run_global_evolution(inputs: py21cmfast.wrapper.inputs.InputParameters, source_model: str | None = None, progressbar: bool = False, overdensity_z0: float | None = None) → GlobalEvolution[source]

Compute the global evolution of all the fields in the simulation.

Parameters:

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

  • source_model (str, optional) – The source model to use in the simulation. If not provided, it is taken from inputs, unless inputs.matter_options.has_discrete_halos is True, in which case an error is thrown. Options are: E-INTEGRAL : The traditional excursion-set formalism, where source properties are

    defined on the Eulerian grid after 2LPT in regions of filter scale R (see the X_FILTER options for filter shapes). This integrates over the CHMF using the smoothed density grids, then multiplies the result. by (1 + delta) to get the source properties in each cell.

    CONST-ION-EFF: Similar to E-INTEGRAL, but ionizing efficiency is constant and does not depend on the halo mass

    (see Mesinger+ 2010).

    L-INTEGRALAnalagous to the ‘ESF-L’ model described in Trac+22, where source properties

    are defined on the Lagrangian (IC) grid by integrating the CHMF prior to the IGM physics and then mapping properties to the Eulerian grid using 2LPT.

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

  • overdensity_z0 (float, optional) – The linear matter overdensity at z=0. Default is 0. This input argument could be useful for doing linear perturbation analysis with 21cmFAST.

Returns:

global_evolution (GlobalEvolution) – The object containing the global evolution of the fields in the simulation.

Raises:

  • ValueError – If source_model is None and inputs.matter_options.has_discrete_halos, or if source_model is provided,:

  • but is not one of the said options above. –

Parameters:
Return type:

GlobalEvolution

Notes

For convenience, the provided InputParameters object by the user is overwritten to allow this function to work smoothly in all cases. The InputParameters object that was used in this function can be accessed via global_evolution.inputs. Note for example that the actual InputParameters object that is used by this function has only one cell (HII_DIM=DIM=1) and no 2LPT is performed (since we have only one cell). In addition, note that the classic reionization module of 21cmFAST (where the excursion-set algorithm is applied to find ionized bubbles) is not called by this function, since there are no bubbles in a one cell box! Instead, we compute the global reionization history based on the global volume filling factor Q. For that reason, note that the correction due to photon non-conservation in the excursion-set algorithm is never applied when this function is called.

py21cmfast.run_lightcone(**kwargs) → LightCone[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

py21cmfast.setup_photon_cons(initial_conditions: py21cmfast.wrapper.outputs.InitialConditions, inputs: py21cmfast.wrapper.inputs.InputParameters | None = None, **kwargs)[source]

Set up the photon non-conservation correction.

First performs a simplified calibration simulation and saves its neutral fraction history, to be matched to the analytic expression from solving the filling factor ODE.

This matching can happen via a redshift adjustment, or an adjustment to the escape fraction power-law parameters

Parameters:

  • initial_conditions (InitialConditions,) – The InitialConditions instance to use for the photonconservation calculation

  • inputs (InputParameters, optional) – An InputParameters instance. If not given will taken from initial_conditions.

Other Parameters:

Any other parameters able to be passed to :func:`compute_initial_conditions`.

Parameters:
py21cmfast.write_output_to_hdf5(output: py21cmfast.wrapper.outputs.OutputStruct, path: pathlib.Path, group: str | None = None, mode: str = 'w')[source]

Write an output struct in standard HDF5 format.

Parameters:

  • output – The OutputStruct to write.

  • path (Path) – The path to write the output struct to.

  • group (str, optional) – The HDF5 group into which to write the object. By default, this is the root.

  • mode (str) – The mode in which to open the file.

Parameters:
py21cmfast.write_template(inputs: py21cmfast.wrapper.inputs.InputParameters, template_file: pathlib.Path | str, mode: TOMLMode = 'full', only_structs: bool | None = None)[source]

Write a set of input parameters to a template file.

Parameters:

  • inputs – The inputs to write to file.

  • template_file – The path of the output.

Parameters:
py21cmfast.config

A singleton Config object used to manage global configuration options.