py21cmfast ========== .. py:module:: py21cmfast .. autoapi-nested-parse:: The py21cmfast package. .. !! processed by numpydoc !! Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/py21cmfast/cli/index /autoapi/py21cmfast/drivers/index /autoapi/py21cmfast/input_serialization/index /autoapi/py21cmfast/io/index /autoapi/py21cmfast/lightconers/index /autoapi/py21cmfast/management/index /autoapi/py21cmfast/plotting/index /autoapi/py21cmfast/rsds/index /autoapi/py21cmfast/utils/index /autoapi/py21cmfast/wrapper/index /autoapi/py21cmfast/yaml/index Attributes ---------- .. autoapisummary:: py21cmfast.DATA_PATH py21cmfast.__version__ py21cmfast.config Classes ------- .. toctree:: :hidden: /autoapi/py21cmfast/AngularLightconer /autoapi/py21cmfast/AstroOptions /autoapi/py21cmfast/AstroParams /autoapi/py21cmfast/BrightnessTemp /autoapi/py21cmfast/CacheConfig /autoapi/py21cmfast/CosmoParams /autoapi/py21cmfast/HaloBox /autoapi/py21cmfast/HaloCatalog /autoapi/py21cmfast/InitialConditions /autoapi/py21cmfast/InputParameters /autoapi/py21cmfast/IonizedBox /autoapi/py21cmfast/LightCone /autoapi/py21cmfast/MatterOptions /autoapi/py21cmfast/OutputCache /autoapi/py21cmfast/PerturbedField /autoapi/py21cmfast/PerturbedHaloCatalog /autoapi/py21cmfast/RectilinearLightconer /autoapi/py21cmfast/RunCache /autoapi/py21cmfast/SimulationOptions /autoapi/py21cmfast/TsBox /autoapi/py21cmfast/XraySourceBox .. autoapisummary:: py21cmfast.AngularLightconer py21cmfast.AstroOptions py21cmfast.AstroParams py21cmfast.BrightnessTemp py21cmfast.CacheConfig py21cmfast.CosmoParams py21cmfast.HaloBox py21cmfast.HaloCatalog py21cmfast.InitialConditions py21cmfast.InputParameters py21cmfast.IonizedBox py21cmfast.LightCone py21cmfast.MatterOptions py21cmfast.OutputCache py21cmfast.PerturbedField py21cmfast.PerturbedHaloCatalog py21cmfast.RectilinearLightconer py21cmfast.RunCache py21cmfast.SimulationOptions py21cmfast.TsBox py21cmfast.XraySourceBox Functions --------- .. autoapisummary:: py21cmfast.brightness_temperature py21cmfast.compute_halo_grid py21cmfast.compute_initial_conditions py21cmfast.compute_ionization_field py21cmfast.compute_luminosity_function py21cmfast.compute_rms py21cmfast.compute_spin_temperature py21cmfast.compute_tau py21cmfast.compute_xray_source_field py21cmfast.configure_logging py21cmfast.construct_fftw_wisdoms py21cmfast.create_params_from_template py21cmfast.determine_halo_catalog py21cmfast.generate_lightcone py21cmfast.get_logspaced_redshifts py21cmfast.list_templates py21cmfast.perturb_field py21cmfast.perturb_halo_catalog py21cmfast.read_inputs py21cmfast.read_output_struct py21cmfast.run_classy py21cmfast.run_lightcone py21cmfast.setup_photon_cons py21cmfast.write_output_to_hdf5 py21cmfast.write_template Package Contents ---------------- .. py:function:: brightness_temperature(*, ionized_box, perturbed_field, spin_temp = None) Compute a coeval brightness temperature box. :Parameters: * **ionized_box** (:class:`IonizedBox`) -- A pre-computed ionized box. * **perturbed_field** (:class:`PerturbedField`) -- A pre-computed perturbed field at the same redshift as `ionized_box`. * **spin_temp** (:class:`TsBox`, optional) -- A pre-computed spin temperature, at the same redshift as the other boxes. :returns: :class:`BrightnessTemp` instance. .. !! processed by numpydoc !! .. py:function:: compute_halo_grid(*, redshift, initial_conditions, inputs = None, halo_catalog = None, previous_spin_temp = None, previous_ionize_box = None) 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** (:class:`~InitialConditions`) -- The initial conditions of the run. * **inputs** (:class:`~InputParameters`, optional) -- The input parameters specifying the run. * **halo_catalog** (:class:`~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** (:class:`TsBox`, optional) -- The previous spin temperature box. Used for feedback when USE_MINI_HALOS==True * **previous_ionize_box** (:class:`IonizedBox` or None) -- An at the last timestep. Used for feedback when USE_MINI_HALOS==True :returns: :class:`~HaloBox` -- An object containing the halo box data. :Other Parameters: **regenerate, write, cache** -- See docs of :func:`initial_conditions` for more information. .. !! processed by numpydoc !! .. py:function:: compute_initial_conditions(*, inputs) 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: :class:`~InitialConditions` .. !! processed by numpydoc !! .. py:function:: compute_ionization_field(*, perturbed_field, initial_conditions, inputs = None, previous_perturbed_field = None, previous_ionized_box = None, spin_temp = None, halobox = None) 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** (:class:`~InitialConditions` instance) -- The initial conditions. * **inputs** (:class:`~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** (:class:`~PerturbedField`) -- The perturbed density field. * **previous_perturbed_field** (:class:`~PerturbedField`, optional) -- An perturbed field at higher redshift. This is only used if USE_MINI_HALOS is included. * **previous_ionize_box** (:class:`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** (:class:`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** (:class:`~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: :class:`~IonizedBox` -- An object containing the ionized box data. .. rubric:: 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. .. !! processed by numpydoc !! .. py:function:: compute_luminosity_function(*, redshifts, inputs, nbins = 100, mturnovers = None, mturnovers_mini = None, component = 'both') 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** (:class:`~InputParameters`) -- The input parameters defining the simulation run. * **nbins** (*int, optional*) -- The number of luminosity bins to produce for the luminosity function. * **mturnovers** (*array-like, optional*) -- The turnover mass at each redshift for massive halos (ACGs). Only required when USE_MINI_HALOS is True. * **mturnovers_mini** (*array-like, optional*) -- The turnover mass at each redshift for minihalos (MCGs). Only required when USE_MINI_HALOS is True. * **component** (*str, {'both', 'acg', 'mcg}*) -- The component of the LF to be calculated. :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]. .. !! processed by numpydoc !! .. py:function:: compute_rms(classy_output, kind = 'd_m', redshifts = 0, smoothing_radius = 0) Compute the root-mean-square of a field at given redshifts. :Parameters: * **classy_output** (:class:`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. .. !! processed by numpydoc !! .. py:function:: compute_spin_temperature(*, initial_conditions, perturbed_field, inputs = None, xray_source_box = None, previous_spin_temp = None, cleanup = False) 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** (:class:`~InitialConditions`) -- The initial conditions * **inputs** (:class:`~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** (:class:`~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** (:class:`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** (:class:`TsBox` or None) -- The previous spin temperature box. Needed when we are beyond the first snapshot :returns: :class:`~TsBox` -- An object containing the spin temperature box data. :Other Parameters: **regenerate, write, cache** -- See docs of :func:`initial_conditions` for more information. .. !! processed by numpydoc !! .. py:function:: compute_tau(*, redshifts, global_xHI, inputs, z_re_HeII = 3.0) 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** (:class:`~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. .. !! processed by numpydoc !! .. py:function:: compute_xray_source_field(*, initial_conditions, hboxes, redshift) 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** (:class:`~InitialConditions`) -- The initial conditions of the run. The user and cosmo params * **hboxes** (Sequence of :class:`~HaloBox` instances) -- This contains the list of Halobox instances which are used to create this source field :returns: :class:`~XraySourceBox` -- An object containing x ray heating, ionisation, and lyman alpha rates. :Other Parameters: **regenerate, write, cache** -- See docs of :func:`initial_conditions` for more information. .. !! processed by numpydoc !! .. py:function:: configure_logging() Configure logging for the '21cmFAST' logger. .. !! processed by numpydoc !! .. py:function:: construct_fftw_wisdoms(*, use_fftw_wisdom) Construct all necessary FFTW wisdoms. :Parameters: **USE_FFTW_WISDOM** (*bool*) -- Whether we are interested in having FFTW wisdoms. .. !! processed by numpydoc !! .. py:function:: create_params_from_template(template_name, **kwargs) 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_params : CosmoParams Instance containing cosmological parameters simulation_options : SimulationOptions Instance containing general run parameters simulation_options : MatterOptions Instance containing general run flags and enums astro_params : AstroParams Instance containing astrophysical parameters astro_options : AstroOptions Instance containing astrophysical flags and enums .. !! processed by numpydoc !! .. py:function:: determine_halo_catalog(*, redshift, inputs = None, initial_conditions, descendant_halos = None) Find a halo list, given a redshift. :Parameters: * **redshift** (*float*) -- The redshift at which to determine the halo list. * **initial_conditions** (:class:`~InitialConditions` instance) -- The initial conditions fields (density, velocity). * **descendant_halos** (:class:`~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: :class:`~HaloCatalog` :Other Parameters: **regenerate, write, cache** -- See docs of :func:`initial_conditions` for more information. .. !! processed by numpydoc !! .. py:function:: 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) 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** (:class:`~Lightconer`) -- This object specifies the dimensions, redshifts, and quantities required by the lightcone run * **inputs** (:class:`~InputParameters`) -- This object specifies the input parameters for the run, including the random seed * **initial_conditions** (:class:`~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** (:class:`~py21cmfast.LightCone`) -- The lightcone object. * **coeval_callback_output** (*list*) -- Only if coeval_callback in not None. :Other Parameters: **regenerate, write, direc, hooks** -- See docs of :func:`initial_conditions` for more information. .. !! processed by numpydoc !! .. py:function:: get_logspaced_redshifts(min_redshift, z_step_factor, max_redshift) Compute a sequence of redshifts to evolve over that are log-spaced. .. !! processed by numpydoc !! .. py:function:: list_templates() Return a list of the available templates. .. !! processed by numpydoc !! .. py:function:: perturb_field(*, redshift, inputs = None, initial_conditions) Compute a perturbed field at a given redshift. :Parameters: * **redshift** (*float*) -- The redshift at which to compute the perturbed field. * **initial_conditions** (:class:`~InitialConditions` instance) -- The initial conditions. :returns: :class:`~PerturbedField` :Other Parameters: **regenerate, write, cache** -- See docs of :func:`initial_conditions` for more information. .. rubric:: 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``. .. !! processed by numpydoc !! .. py:function:: perturb_halo_catalog(*, initial_conditions, inputs = None, previous_spin_temp = None, previous_ionize_box = None, halo_catalog) Given a halo list, perturb the halos for a given redshift. :Parameters: * **initial_conditions** (:class:`~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: :class:`~PerturbedHaloCatalog` :Other Parameters: **regenerate, write, direc** -- See docs of :func:`initial_conditions` for more information. .. rubric:: Examples Fill this in once finalised .. !! processed by numpydoc !! .. py:function:: read_inputs(group, safe = True) 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. .. !! processed by numpydoc !! .. py:function:: read_output_struct(path, group = '/', struct = None, safe = True) 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. .. !! processed by numpydoc !! .. py:function:: run_classy(**kwargs) Run CLASS with specified input parameters. :Parameters: **kwargs** -- Optional keywords to pass to CLASS. :returns: **output** (:class:`classy.Class`) -- An object containing all the information from the CLASS calculation. .. !! processed by numpydoc !! .. py:function:: run_lightcone(**kwargs) Run a lightcone simulation and return the final lightcone object. This simply wraps :func:`generate_lightcone` and returns the final lightcone object after the generator has been exhausted. All parameters are passed directly to :func:`generate_lightcone`. .. !! processed by numpydoc !! .. py:function:: setup_photon_cons(initial_conditions, inputs = None, **kwargs) 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** (:class:`~InitialConditions`,) -- The InitialConditions instance to use for the photonconservation calculation * **inputs** (:class:`~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`.** .. !! processed by numpydoc !! .. py:function:: write_output_to_hdf5(output, path, group = None, mode = 'w') 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. .. !! processed by numpydoc !! .. py:function:: write_template(inputs, template_file, mode = 'full') 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. .. !! processed by numpydoc !! .. py:data:: DATA_PATH .. py:data:: __version__ .. py:data:: config