API Reference

echopipeline

This module contains the class pipeline.

class echo21.echopipeline.pipeline(cosmo=None, astro=None, sfrd=None, Z_eval=None, grid_on=False, path='echo21_outputs/')

This class runs the cosmic history solver and produces the global signal, globally-averaged nuetral hydrogen fraction, optical depth and the corresponding redshifts. There are three inputs required for a complete specification – cosmological parameters, astrophysical parameter, and star formation related parameters. They are supplied through arguments, cosmo, astro, and sfrd, respectively. The notation for the parameters is as follows. All of these need to be dictionaries. For example:

cosmo = {'Ho':67.4, 'Om_m':0.315, 'Om_b':0.049, 'sig8':0.811, 'ns':0.965, 'Tcmbo':2.725, 'Yp':0.245},
astro = {'fLy':1, 'sLy' : 2.64, 'fX':1, 'wX':1.5, 'fesc':0.01},
sfrd = {'type':'phy', 'hmf':'press74', 'mdef':'fof', 'Tmin_vir':1e4}

Arguments

cosmo: dict

Dictionary of cosmological parameters. They are:

Hofloat, optional: Hubble parameter today in units of \(\mathrm{km\,s^{-1}\,Mpc^{-1}}\). Default value 67.4.
Om_mfloat, optional: Relative matter density. Default value 0.315.
Om_bfloat, optional: Relative baryon density. Default value 0.049.
sig8float, optional: Amplitude of density fluctuations. Default value 0.811.
nsfloat, optional: Spectral index of the primordial scalar spectrum. Default value 0.965.
Tcmbofloat, optional: CMB temperature today in kelvin. Default value 2.725.
Ypfloat, optional: Primordial helium fraction by mass. Default value 0.245.

astro: dict

Dictionary of cosmological parameters. They are:

fLyfloat, optional: \(f_{\mathrm{Ly}}\), a dimensionless parameter which controls the emissivity of the Lyman series photons. Default value 1.0.
sLyfloat, optional: \(s\), spectral index of Lyman series SED, when expressed as \(\epsilon\propto E^{-s}\). \(\epsilon\) is energy emitted per unit energy range and per unit volume. Default value 2.64.
fXfloat, optional: \(f_{\mathrm{X}}\), a dimensionless parameter which controls the emissivity of the X-ray photons. Default value 1.0.
wXfloat, optional: \(w\), spectral index of X-ray SED, when expressed as \(\epsilon\propto E^{-w}\). \(\epsilon\) is energy emitted per unit energy range and per unit volume. Default value 1.5.
fescfloat, optional: \(f_{\mathrm{esc}}\), a dimensionless parameter which controls the escape fraction of the ionizing photons. Default value 0.01.

sfrddict

This should be a dictionary containing all the details of SFRD.

typestr, optional

Available types are ‘phy’ (default), ‘semi-emp’, and ‘emp’, for a physically-motivated, semi-empirical, and an empiricaly-motivated SFRD, respectively.

hmfstr, optional

HMF model to use. Default value press74. Other commonly used HMFs are

sheth99 (for Sheth & Tormen 1999)
tinker08 (for Tinker et al 2008)

For the full list see colossus page.

mdef: str, optional: Definition for halo mass. Default is fof. For most HMFs such as Press-Schechter or Sheth-Tormen, friends-of-friends (fof) algorithm is used. For Tinker08, it is an integer times mean matter density (<int>m). See the colossus documentation for definition page
Tmin_virfloat, optional: Minimum virial temperature (in units of kelvin) for star formation. Default value 1e4.
t_starfloat, optional: Star formation timescale in units of the Hubble time. Default value 0.5. (This is only relevant for the semi-empirical SFRD model.)
afloat, optional: Power law index for the SFRD in the empirical model. Default value 0.257. (This is only relevant for the empirical SFRD model.)

Z_eval: float

Array of \(1+z\) where you want to compute the quantities.

grid_on: bool

Whether to do generate a grid of parameter combinations. Default is True, i.e., then all possible combinations of the parameters will be generated. If False, parameters are varied one at a time. In this case all varied parameters should have the same number of values.

Methods

run_simulation(): This function solves the thermal and ionization history for default values of redshifts and then interpolates the quantities at your choice of redshifts. Then it solves reionization. Finally, it computes the spin temperature and hence the global 21-cm signal. A text file is generated which will contain the basic information about the simulation.

echofuncs

This module contains class funcs.

class echo21.echofuncs.funcs(params=None, dm_model='CDM')

Function names starting with ‘basic_cosmo’ include the basic \(\Lambda\) CDM-cosmology-related functions, such as Hubble function, CMB temperature, etc.

Function names starting with ‘recomb’ include recombination-physics-related functions.

Function names starting with ‘heating’ include all the heating terms. All the terms are in the form of \(-(1+z)\mathrm{d}T_{\mathrm{k}}/\mathrm{d}z\) and hence, in units of temperature.

Function names starting with ‘hyfi’ include all the functions related to the computation of 21-cm signal. These are \(\kappa_{\mathrm{HH}}, \kappa_{\mathrm{eH}}, x_{\mathrm{k}}, x_{\mathrm{Ly}}, T_{\mathrm{s}}\) and \(T_{21}\).

Arguments

params: dict: A dictionary containing all the cosmological and astrophysical parameters.

Methods

basic_cosmo_mu(xe)

The average baryon mass.

Arguments

xefloat: Electron fraction, dimensionless

Returns

\(\mu\), dimensionless

basic_cosmo_xHe()

Ratio of helium number density to hydrogen number density

Arguments

No arguments required.

Returns

float: \(n_{\mathrm{He}}/n_{\mathrm{H}}\)

basic_cosmo_Tcmb(Z)

CMB temperature at a given redshift

Arguments

Zfloat: 1+z

Returns

float: CMB temperature at the given redshift in kelvin

basic_cosmo_rho_crit()

Critical density of the Universe today

Arguments

No arguments required.

Returns

float: Critical density today, \(\rho_{\mathrm{crit}}=\frac{3H_0^2}{8\pi G_{\mathrm{N}}}\) in units of \(\mathrm{kg}\,\mathrm{m}^{-3}\)

basic_cosmo_nH(Z)

Hydrogen number density (proper).

Arguments

Zfloat: 1+z

Returns

float: Proper hydrogen number density at given redshift in units of \(\mathrm{m}^{-3}\)

basic_cosmo_H(Z)

Hubble factor in SI units.

Arguments

Zfloat: 1+z

Returns

float: Hubble parameter at a given redshift in units of \(\mathrm{s}^{-1}\).

recomb_alpha(T)

\(\alpha_{\mathrm{B}}=\alpha_{\mathrm{B}}(T)\)

The effective case-B recombination coefficient for hydrogen. See Eq. (70) from Seager et al (2000).

Arguments

Tfloat: Temperature in units of kelvin.

Returns

float: The effective case-B recombination coefficient for hydrogen \((\mathrm{m}^3\mathrm{s}^{-1})\).

recomb_beta(T)

\(\beta=\beta(T)\)

The total photoionization rate. See description below Eq. (71) from Seager et al (2000). Relation between \(\alpha_{\mathrm{B}}\) and \(\beta\):

\(\beta=\alpha_{\mathrm{B}}\left(\frac{2\pi m_{\mathrm{e}}k_{\mathrm{B}}T}{h_{\mathrm{P}}^2}\right)^{3/2}\exp\left(-\frac{B_2}{k_{\mathrm{B}}T}\right)\)

Arguments

Tfloat: Temperature in units of kelvin.

Returns

float: The total photoionization rate in \((\mathrm{s}^{-1})\).

recomb_Krr(Z)

Redshifting rate appearing in the Peebles’ ‘C’ factor

Arguments

Zfloat: 1+z

Returns

float: Redshifting rate in units of \(\mathrm{m^3s}\)

recomb_Peebles_C(Z, xe, T)

\(C_{\mathrm{P}}\)

Arguments

Zfloat: 1 + redshift, dimensionless
xefloat: Electron fraction, dimensionless
Tkfloat: Temperature in units of kelvin.

Returns

float: Peebles ‘C’ factor appearing in Eq. (71) from Seager et al (2000), dimensionless.

recomb_Saha_xe(Z, T)

Electron fraction predicted by the Saha’s equation. This is important to initialize the differential equation for \(x_{\mathrm{e}}\). At high redshift such as \(z=1500\), Saha’s equation gives accurate estimate of \(x_{\mathrm{e}}\).

Arguments

Zfloat: 1 + redshift, dimensionless
Tfloat: Temperature in units of kelvin

Returns

float: Electron fraction predicted by Saha’s equation. Dimensionless.

dndlnM(M, Z)

The halo mass function (HMF) in the form of \(\mathrm{d}n/\mathrm{d\,ln}M\). Note the natural logarithm.

Arguments

Mfloat: The desired halo mass at which you want to evaluate HMF. Input M in units of solar mass.
Zfloat: 1 + redshift, dimensionless.

Returns

float: HMF, \(\mathrm{d}n/\mathrm{d\,ln}M=M\mathrm{d}n/\mathrm{d}M\), in units of \(\mathrm{cMpc}^{-3}\), where ‘cMpc’ represents comoving mega parsec.

dndM(M, Z)

The halo mass function (HMF) in a different form, i.e., \(\mathrm{d}n/\mathrm{d}M\).

Arguments

Mfloat: The desired halo mass at which you want to evaluate HMF. Input M in units of solar mass (\(\mathrm{M}_{\odot}\)).
Zfloat: 1 + z, dimensionless.

Returns

float: HMF in a different form, \(\mathrm{d}n/\mathrm{d}M\), in units of \(\mathrm{cMpc}^{-3}\mathrm{M}_{\odot}^{-1}\), where ‘cMpc’ represents comoving mega parsec and \(\mathrm{M}_{\odot}\) represents the solar mass.

m_min(Z)

The minimum halo mass for which star formation is possible.

Arguments

Zfloat: 1 + z, dimensionless. It can be a single number or an array.

Returns

float: The mass returned is in units of \(\mathrm{M}_{\odot}/h\).

f_coll(Z)

Collapse fraction – fraction of total matter that collapsed into the haloes. See definition below. \(F_{\mathrm{coll}}=\frac{1}{\bar{\rho}^0_{\mathrm{m}}}\int_{M_{\mathrm{min}}}^{\infty} M\frac{\mathrm{d}n}{\mathrm{d} M}\,\mathrm{d} M\,,\)

Arguments

Zfloat: 1 + z, dimensionless. Can be a single quantity or an array.

Returns

float: Collapse fraction. Single number or an array accordingly as Z is single number or an array.

dfcoll_dz(Z): Redshift derivative of the collapse fraction, i.e., \(\mathrm{d}F_{\mathrm{coll}}/\mathrm{d}z\)

sfrd(Z)

This function returns the comoving star formation rate density (SFRD, \(\dot{\rho}_{\star}\)).

Arguments

Zfloat: 1 + z, dimensionless. Can be a single quantity or an array.

Returns

float: Comoving SFRD in units of \(\mathrm{kgs^{-1}m^{-3}}\). Single number or an array accordingly as Z is single number or an array. To convert to solar mass per year per cubic Mpc, use the factor Msolar_by_Mpc3_year_to_kg_by_m3_sec available in the module const.

phi_Ly(E)

Spectral energy distribution (SED) of Lyman series photons in units of number of photons per unit frequency per stellar baryon.

Arguments

Efloat: Energy in eV.

Returns

float: SED in dimensions \(\mathrm{Hz^{-1}}\).

eps_Ly(Z, E)

Emissivity of Lyman series photons in units of number of photons per unit frequency per unit comoving volume per unit time. Construction:

\(\epsilon_{\mathrm{Ly}}=\frac{1}{m_{\mathrm{b}}}\phi_{\mathrm{Ly}}\dot{\rho}_{\star}\)

Arguments

Zfloat: 1+z
Efloat: Energy in eV.

Returns

float: Emissivity in dimensions \(\mathrm{m^{-3}Hz^{-1}s^{-1}}\).

lya_spec_inten(Z)

Specific intensity of Ly \(\alpha\) photons, \(J_{\mathrm{Ly}}\), due to continuum and injected photons.

Arguments

Zfloat: 1 + z, dimensionless. Can be array.

Returns

float: Specific intensity in terms of number per unit time per unit area per unit frequency per unit solid angle (\(\mathrm{m^{-2}s^{-1}Hz^{-1}sr^{-1}}\)). Two values are returned, namely intensity due to continuum and injected photons, respectively.

heating_Ecomp(Z, xe, Tk)

See Eq.(2.32) from Mittal et al (2022), JCAP. (However, there is a typo in that equation; numerator has an \(x_{\mathrm{e}}\) missing.)

Arguments

Zfloat: 1 + z, dimensionless.
xefloat: Electron fraction.
Tkfloat: Gas kinetic temperature.

Returns

float: Compton heating. Units kelvin.

heating_Elya(Z, xe, Tk)

Ly \(\alpha\) heating rate. For details see Mittal & Kulkarni (2021) or the ECHO21 paper Mittal et al (2025)

Arguments

Zfloat: 1 + z, dimensionless.
xefloat: Electron fraction.
Tkfloat: Gas kinetic temperature.

Returns

float: Net heating by the Lyman series photons. Units kelvin.

heating_Ex(Z, xe)

We use the parametric approach for X-ray heating as in Furlanetto (2006). We adopt the \(L_{\mathrm{X}}/\mathrm{SFR}\) relation from Lehmer et al. (2024).

Arguments

Zfloat: 1 + z, dimensionless.
xefloat: Electron fraction.

Returns

float: Net heating by the X-ray photons. Units kelvin.

Gamma_x(Z, xe)

Ionization (of bulk IGM) rate due to X-ray photons.

Zfloat: 1 + z, dimensionless.
xefloat: Electron fraction.

Returns

float: Ionization due to X-ray photons in units of \(\mathrm{s}^{-1}\).

u_t(xe, Tk, Tx, target='p')

The characteristic thermal sound speed of the DM-baryon fluid.

Arguments

xefloat: Electron fraction.
Tkfloat: Gas kinetic temperature (K).
Txfloat: DM temperature (K).

Returns

float: \(u_{\mathrm{th}} (\mathrm{m\,s^{-1}})\).

r_t(xe, Tk, Tx, v_bx, target='p')

Ratio of relative velocity of DM and baryons to the characteristic thermal sound speed.

Arguments

xefloat: Electron fraction.
Tkfloat: Gas kinetic temperature (K).
Txfloat: DM temperature (K).
v_bxfloat: Relative velocity of DM and baryons (m/s).

Returns

float: \(v_{\mathrm{b}\chi}/u_{\mathrm{th}}\), dimensionless.

Drag(Z, xe, Tk, Tx, v_bx)

Drag due to DM baryon interaction.

Arguments

Zfloat: 1+z
xefloat: Electron fraction.
Tkfloat: Gas kinetic temperature (K).
Txfloat: DM temperature (K).
v_bxfloat: Relative velocity of DM and baryons (m/s).

Returns

float: \(D (\mathrm{m\,s^{-2}})\).

mu_bx(xe)

Reduced mass for DM-baryon system.

Arguments

xefloat: Electron fraction.

Returns

float: \(\mu_{\mathrm{b}\chi} (\mathrm{kg})\)

Ex2b(Z, xe, Tk, Tx, v_bx)

This corresponds to the heat that flows into the baryonic system from the DM.

Arguments

Zfloat: 1+z
xefloat: Electron fraction.
Tkfloat: Gas kinetic temperature (K).
Txfloat: DM temperature (K).
v_bxfloat: Relative velocity of DM and baryons \((\mathrm{m\,s^{-1}})\).

Returns

float: \(\dot{Q}_{\mathrm{k}} (\mathrm{K})\).

Eb2x(Z, xe, Tk, Tx, v_bx)

This corresponds to the heat that flows into the DM from baryons.

Arguments

Zfloat: 1+z
xefloat: Electron fraction.
Tkfloat: Gas kinetic temperature (K).
Txfloat: DM temperature (K).
v_bxfloat: Relative velocity of DM and baryons (m/s).

Returns

float: \(\dot{Q}_{\chi}\) (K).

reion_clump(Z): Clumping factor for the ionization of hydrogen. From Shull et al. (2012).

reion_tau(Z)

Compute the Thomson-scattering optical depth up to a 1+redshift=Z.

Arguments

Zfloat: 1+z to which you want to calculate \(\tau_{\mathrm{e}}\).

Returns

float: \(\tau_{\mathrm{e}}\) (dimensionless).

initial_conditions()

Initial conditions for the IGM equations at \(z=1500\). For CDM, we need electron fraction and gas kinetic temperature. For IDM, we also need DM temperature and relative velocity of DM and baryons.

Also, note that for gas temperature it is a transformed variable. Instead of \(T_{\mathrm{k}}\) we have \(\delta_T = (T_{\mathrm{k}}-T_{\gamma})/T_{\gamma}\).

Arguments

Zfloat: 1 + z, dimensionless.

Returns

tuple: Initial conditions. For CDM, the tuple is (xe_init, frac_temp_diff_init). For IDM, the tuple is (xe_init, frac_temp_diff_init, Tx_init, ln_vbx_init).

igm_solver(Z_solver, *initial_conditions, eqns_func)

This function solves the coupled IGM differential equations. In case of CDM it is just electron fraction and gas temperature. When IDM is involed DM temperature and relative DM-baryon velocity is also solved. Note the following two points:

For thermal evolution, I don’t solve for \(T_{\mathrm{k}}\) but rather \(\delta_T = (T_{\mathrm{k}}-T_{\gamma})/T_{\gamma}\).

In case of IDM, the last value of the solution array is \(\ln v_{\mathrm{b}\chi}\) and not \(v_{\mathrm{b}\chi}\) itself.

Arguments

Z_solver: array: Redshift array (decreasing) over which to solve. Use Z_da for dark ages, Z_cd for cosmic dawn, or Z_default for the full range.
initial_conditions: tuple: Initial conditions for the ODE solver. For CDM, the tuple is (xe_init, frac_temp_diff_init). For IDM, the tuple is (xe_init, frac_temp_diff_init, Tx_init, ln_vbx_init). Use initial_conditions() to get the initial conditions when the starting redshift is 1500.
eqns_func: callable: The RHS function to pass to the ODE solver. Either dark ages or cosmic dawn.

Returns

array: \(x_{\mathrm{e}}\), \(\delta_T\), \(T_{\chi}\), \(\ln v_{\mathrm{b}\chi}\)

reion_eqn(Z, QHii)

The RHS of the differential equation governing the evolution of Q. Equation is (1+z)dQ/dz; eq.(17) from Madau & Fragos (2017).

Arguments

Zfloat: 1+z.
Qfloat: The volume filling factor of the ionized regions.

Returns

float: (1+z)dQ/dz

reion_solver()

Solves the reionization equation.

Arguments

None

Returns

float array: Q for the cosmic dawn redshifts, Z_cd. The redshifts can be access from the module const.

hyfi_kHH(Tk)

Volumetric spin flip rate for hydrogen-hydrogen collision. This fitting function and the next one is available from Pritchard & Loeb (2012).

Arguments

Tkfloat: Gas kinetic temperature.

Returns

float: \(k_{\mathrm{HH}}\) in units of \(\mathrm{m^3s^{-1}}\).

hyfi_keH(Tk)

Volumetric spin flip rate for electron-hydrogen collision.

Arguments

Tkfloat: Gas kinetic temperature.

Returns

float: \(k_{\mathrm{eH}}\) in units of \(\mathrm{m^3s^{-1}}\).

hyfi_kpH(Tk)

Volumetric spin flip rate for electron-proton collision. Fit taken from Mittal et al. (2022).

Arguments

Tkfloat: Gas kinetic temperature.

Returns

float: \(k_{\mathrm{pH}}\) in units of \(\mathrm{m^3s^{-1}}\).

hyfi_col_coup(Z, xe, Tk)

Collisional coupling.

Arguments

Zfloat: 1 + z, dimensionless.
xefloat: Electron fraction.
Tkfloat: Gas kinetic temperature.

Returns

float: \(x_{\mathrm{k}}\), dimensionless.

hyfi_lya_coup(Z, xe, Tk)

Ly \(\alpha\) coupling or the Wouthuysen–Field coupling.

Arguments

Zfloat: 1 + z, dimensionless.
xefloat: Electron fraction.
Tkfloat: Gas kinetic temperature.

Returns

float: \(x_{\mathrm{Ly}}\), dimensionless.

hyfi_spin_temp(Z, xe, Tk)

Spin temperature.

Arguments

Zfloat: 1 + z, dimensionless.
xefloat: Electron fraction.
Tkfloat: Gas kinetic temperature.

Returns

float: \(T_{\mathrm{s}}\), K.

hyfi_twentyone_cm(Z, xe, Q, Ts)

The global (sky-averaged) 21-cm signal.

Arguments

Zfloat: 1 + z, dimensionless.
xefloat: Electron fraction.
Qfloat: Volume-filling factor.
Tsfloat: Spin temperature.

Returns

float: \(T_{21}\), mK.

misc

This module contains non-physics functions.

echo21.misc.save_pipeline(obj, filename)

Save the class object pipeline for later use. It will save the object in the path where you have all the other outputs from this package.

Arguments

objclass: This should be the class object you want to save.
filenamestr: Give a file name only to your object, not the full path. obj will be saved in the obj.path directory.

echo21.misc.load_pipeline(filename)

To load the class object pipeline.

Arguments

filenamestr: This should be the name of the file you gave in save_pipeline() for saving class object pipeline. Important: provide the full path for filename with the extension .pkl.

Returns

class object