zeus21.LFs ========== .. py:module:: zeus21.LFs .. autoapi-nested-parse:: Compute LFs given our SFR and HMF models. Authors: zeus21 v2 collaboration - June 2026 Emily Bregou ; Hector Afonso G. Cruz ; Sarah Libanore ; Julian B. Muñoz ; Yonny Sklansky ; Emilie Thélie ; Alessandra Venditti arXiv:2302.08506, arXiv:2306.09403, arXiv:2407.18294, Sklansky et al. (in prep) Classes ------- .. autoapisummary:: zeus21.LFs.LFbias_band_outputs zeus21.LFs.LFbias_core_output zeus21.LFs.LF_class zeus21.LFs.Ha_UV_ratio Module Contents --------------- .. py:class:: LFbias_band_outputs(LF_Init, CosmoParams, AstroParams, HMFinterp, LFParams, which_band, vCB=None, J21LW_interp=None) Output container for binned luminosity-function and bias results in one band. This class groups the luminosity-function outputs for a single observable band, either UV or Halpha. It stores the binning information for the selected band and the requested population components. :param LF_Init: Parent LF object used to compute population-level LF and bias outputs. :type LF_Init: LF_class :param CosmoParams: :type CosmoParams: Cosmo_Parameters :param AstroParams: :type AstroParams: Astro_Parameters :param HMFinterp: :type HMFinterp: HMF_interpolator :param LFParams: :type LFParams: LF_Parameters :param which_band: Which LF band to compute. "UV" uses ``LFParams.MUVcenters`` and ``LFParams.MUVwidths``; "Ha" uses ``LFParams.log10LHacenters`` and ``LFParams.log10LHawidths``. :type which_band: {"UV", "Ha"} :param vCB: Baryon-CDM relative streaming velocity used for Pop III SFR feedback. Only relevant for Pop III calculations. :type vCB: float, None or False, optional :param J21LW_interp: LW background interpolator used for Pop III SFR feedback. Only relevant for Pop III calculations. :type J21LW_interp: interpolator, None or False, optional .. attribute:: bin_centers Centers of the LF bins for the selected band. :type: array .. attribute:: bin_widths Widths of the LF bins for the selected band. :type: array .. attribute:: pop2 Pop II LF/bias output, if requested. :type: LFbias_core_output or None .. attribute:: pop3 Pop III LF/bias output, if requested. :type: LFbias_core_output or None .. attribute:: tot Total LF/bias output, if requested. :type: LFbias_core_output or None .. py:attribute:: pop2 :value: None .. py:attribute:: pop3 :value: None .. py:attribute:: tot :value: None .. py:class:: LFbias_core_output(LF=None, bias_num=None) Output container for a single LF/bias component. This class stores the luminosity-function output and the corresponding bias numerator for a single component. :param LF: Binned luminosity function, when computed. :type LF: array or None, optional :param bias_num: Numerator of the LF-weighted halo bias, when computed. :type bias_num: array or None, optional .. attribute:: LF Binned luminosity function. :type: array or None .. attribute:: bias_num Numerator of the LF-weighted halo bias. :type: array or None .. attribute:: Properties .. attribute:: ---------- .. attribute:: bias LF-normalized average bias, computed as ``bias_num / LF``. This property requires both ``LF`` and ``bias_num`` to be available. :type: array .. rubric:: Notes Adding two ``LFbias_outputs`` objects returns a new ``LFbias_outputs`` object whose available fields are the sum of the corresponding fields. This is used to build total outputs from population-level outputs. .. py:attribute:: LF :value: None .. py:attribute:: bias_num :value: None .. py:property:: bias Bias normalized by the LF. The raw 'bias' returned by the LF machinery is bias_num = b * LF. .. py:class:: LF_class(UserParams, CosmoParams, AstroParams, HMFinterp, LFParams, z_Init=None, SFRD_Init=None, SFH_Init=None, vCB=None, J21LW_interp=None) Compute all quantities and methods associated with luminosity functions :param UserParams: :type UserParams: User_Parameters :param CosmoParams: :type CosmoParams: Cosmo_Parameters :param AstroParams: :type AstroParams: Astro_Parameters :param HMFinterp: :type HMFinterp: HMF_interpolator :param LFParams: :type LFParams: LF_Parameters :param z_Init: Initial redshift matrices to be used in full-SFRD and PSD calculations. Only instantiated when a full SFRD object is required. If None (default), initialized internally. :type z_Init: Z_init or None, optional :param SFRD_Init: Precomputed SFRD object. Only instantiated when a full SFRD object is required i.e. for PSD calculations, and for Pop III non-PSD calculations when LW is not provided explicitly. If None (default), initialized internally. :type SFRD_Init: SFRD_class or None, optional :param SFH_Init: Precomputed SFH object to be used in PSD calculations. Only instantiated for PSD calculations. If None (default), initialized internally. :type SFH_Init: SFH_class or None, optional :param vCB: Baryon-CDM relative streaming velocity used for Pop III non-PSD SFR feedback. If None (default), cosmological mean from ``CosmoParams`` is used. False to fully disable streaming velocity feedback. :type vCB: float, None or False, optional :param J21LW_interp: LW background interpolator as a function of redshift used for Pop III SFR feedback. If None (default), the converged background from ``SFRD_Init`` is used. False to fully disable LW feedback. :type J21LW_interp: interpolator, None or False, optional .. attribute:: z_Init Initial redshift matrices used by full-SFRD and PSD calculations, when initialized. :type: Z_init class .. attribute:: SFRD_Init Full or lightweight SFRD object used to evaluate SFRs and, when available, self-consistent LW backgrounds. :type: SFRD_class .. attribute:: SFH_Init SFH object used for PSD-based observables. :type: SFH_class .. attribute:: DZ_TOINT Redshift offsets, in units of ``LFParams.zwidth``, used to average the HMF over the redshift bin. :type: array .. attribute:: WEIGHTS_TOINT Gaussian weights associated with ``DZ_TOINT``. :type: array .. attribute:: biasM Tinker halo bias evaluated at the redshift samples used for the LF bin. Only defined when bias is requested as an output in ``LFParams``. :type: array .. attribute:: UV UV luminosity-function and bias output containter object, when requested by ``LFParams.FLAG_COMPUTE_UVLF``. :type: LFbias_band_outputs .. attribute:: Ha Halpha luminosity-function and bias output container object, when requested by ``LFParams.FLAG_COMPUTE_HaLF``. :type: LFbias_band_outputs .. py:attribute:: WEIGHTS_TOINT .. py:method:: Hz_from_angstrom(wavelength=1500.0) Convert rest-frame wavelength in Angstrom to frequency in Hz. :param wavelength: Rest-frame wavelength in Angstrom. Default is 1500. :type wavelength: float, optional :returns: **nu** -- Frequency in Hz. :rtype: float .. py:method:: Mag_of_L_ergsHz(L) Convert specific luminosity in erg/s/Hz to AB absolute magnitude (from 1703.02913). :param L: Specific luminosity (L_nu) in erg/s/Hz. :type L: float or array :returns: **Mag** -- AB absolute magnitude. :rtype: float or array .. py:method:: Mag_of_L_ergs(L, wavelength=1500.0) Convert specific luminosity in erg/s to AB absolute magnitude (from 1703.02913). :param L: Specific luminosity (nuL_nu) in erg/s. :type L: float or array :param wavelength: Rest-frame wavelength in Angstrom used to convert nuL_nu to L_nu. Default is 1500. :type wavelength: float, optional :returns: **Mag** -- AB absolute magnitude. :rtype: float or array .. py:method:: L_ergsHz_of_Mag(Mag) Convert AB absolute magnitude to specific luminosity in erg/s/Hz (from 1703.02913). :param Mag: AB absolute magnitude. :type Mag: float or array :returns: **L** -- Specific luminosity (L_nu) in erg/s/Hz. :rtype: float or array .. py:method:: L_ergs_of_Mag(Mag, wavelength=1500.0) Convert AB absolute magnitude to specific luminosity in erg/s (from 1703.02913). :param Mag: AB absolute magnitude. :type Mag: float or array :param wavelength: Rest-frame wavelength in Angstrom. Default is 1500. :type wavelength: float, optional :returns: **L** -- specific luminosity (nuL_nu) in erg/s. :rtype: float or array .. py:method:: logorMag_of_L(L, which_band, renormalize_L, sigma=None) Convert luminosity to the LF observable coordinate (log-luminosity/magnitude). Mean luminosity can be shifted so that a lognormal scatter preserves the linear mean. :param L: Average luminosity. For ``which_band`` = "UV", it is interpreted as specific luminosity in erg/s/Hz (L_nu). For ``which_band`` = "Ha", it is intepreted as integrated line luminosity (L_Halpha) in erg/s. :type L: float or array :param which_band: Observable band to compute. :type which_band: {"UV", "Ha"} :param renormalize_L: Whether to renormalize the linear luminosity before converting to the LF coordinate. :type renormalize_L: bool :param sigma: Scatter used for the renormalization. Required when ``renormalize_L`` is True. :type sigma: float or array, optional :returns: **logL_or_mag** -- UV magnitude for ``which_band`` = "UV" or log10(L_Halpha) for ``which_band`` = "Ha". Non-finite values are replaced by arbitrarily faint values. :rtype: float or array .. py:method:: compute_pop_LFbias_binned(CosmoParams, AstroParams, HMFinterp, LFParams, which_band, pop, vCB=None, J21LW_interp=None) Compute a single population (Pop III or Pop II) contribution to a binned luminosity function. :param CosmoParams: :type CosmoParams: Cosmo_Parameters :param AstroParams: :type AstroParams: Astro_Parameters :param HMFinterp: :type HMFinterp: HMF_interpolator :param LFParams: :type LFParams: LF_Parameters :param which_band: Which LF band to compute. :type which_band: {"UV", "Ha"} :param pop: Stellar population, 2 for Pop II or 3 for Pop III. :type pop: int :param vCB: Baryon-CDM relative streaming velocity used for Pop III non-PSD SFR feedback. If None (default), cosmological mean from ``CosmoParams`` is used. False to fully disable streaming velocity feedback. :type vCB: float, None or False, optional :param J21LW_interp: LW background interpolator as a function of redshift used for Pop III SFR feedback. If None (default), the converged background from ``SFRD_Init`` is used. False to fully disable LW feedback. :type J21LW_interp: interpolator, None or False, optional :returns: **outputs** :rtype: Same output type as returned by the core method ``compute_LFbias_binned_from_avgsigma`` .. py:method:: compute_LFbias_binned_from_SFRlist(SFRlist, HMFinterp, LFParams, zcenter, zwidth, logLcenters, logLwidths, kappa, sigma, renormalize_L, which_band, include_dust, computeLF, computeBias) Compute binned LF outputs from a precomputed SFR list. :param SFRlist: Star formation rate evaluated on ``HMFinterp.Mhtab``. :type SFRlist: array :param HMFinterp: :type HMFinterp: HMF_interpolator :param LFParams: :type LFParams: LF_Parameters :param zcenter: Redshift bin center and width. :type zcenter: float :param zwidth: Redshift bin center and width. :type zwidth: float :param logLcenters: LF bin centers and widths. These are UV magnitudes bins for ``which_band`` = "UV" and log10(L_Ha) bins for ``which_band`` = "Halpha". :type logLcenters: array :param logLwidths: LF bin centers and widths. These are UV magnitudes bins for ``which_band`` = "UV" and log10(L_Ha) bins for ``which_band`` = "Halpha". :type logLwidths: array :param kappa: SFR-to-luminosity conversion factor. :type kappa: float :param sigma: Scatter in the LF observable coordinate. :type sigma: float or array :param renormalize_L: Whether to renormalize the luminosity before adding lognormal scatter to preserve the linear mean. :type renormalize_L: bool :param which_band: Which LF band to compute. :type which_band: {"UV", "Ha"} :param include_dust: Whether to apply dust corrections. :type include_dust: bool :param computeLF: Select which output entries to compute. :type computeLF: bool :param computeBias: Select which output entries to compute. :type computeBias: bool :returns: **outputs** :rtype: Same output type as returned by the core method ``compute_LFbias_binned_from_avgsigma``. .. py:method:: compute_LFbias_binned_from_PSD(CosmoParams, AstroParams, HMFinterp, LFParams, zcenter, zwidth, logLcenters, logLwidths, which_band, pop, include_dust, computeLF, computeBias) Compute binned LF outputs from PSD-derived observable statistics. :param CosmoParams: :type CosmoParams: Cosmo_Parameters :param AstroParams: :type AstroParams: Astro_Parameters :param HMFinterp: :type HMFinterp: HMF_interpolator :param LFParams: :type LFParams: LF_Parameters :param zcenter: Redshift bin center and width. :type zcenter: float :param zwidth: Redshift bin center and width. :type zwidth: float :param logLcenters: LF bin centers and widths. :type logLcenters: array :param logLwidths: LF bin centers and widths. :type logLwidths: array :param which_band: Which LF band to compute. :type which_band: {"UV", "Ha"} :param pop: Stellar population, 2 for Pop II or 3 for Pop III. :type pop: int :param include_dust: Whether to apply dust corrections. :type include_dust: bool :param computeLF: Select which output entries to compute. :type computeLF: bool :param computeBias: Select which output entries to compute. :type computeBias: bool :returns: **outputs** :rtype: Same output type as returned by the core method ``compute_LFbias_binned_from_avgsigma``. .. py:method:: compute_LFbias_binned_from_avgsigma(logL_avglist, sigma, HMFinterp, zcenter, zwidth, logLcenters, logLwidths, computeLF, computeBias) Compute LF and/or bias given the average log-luminosity/magnitude associated with each halo mass and its lognormal scatter. This is the common numerical core for LF computation, shared by the SFR-list and PSD branches: it convolves the mean LF coordinate at each halo mass with a Gaussian scatter and integrates over the HMF. :param logL_avglist: Mean LF coordinate (UV magnitude or log10(L_Halpha)) at each halo mass. :type logL_avglist: array :param sigma: Scatter in the same coordinate. :type sigma: float or array :param HMFinterp: :type HMFinterp: HMF_interpolator :param zcenter: Redshift bin center and width. :type zcenter: float :param zwidth: Redshift bin center and width. :type zwidth: float :param logLcenters: LF bin centers and widths. :type logLcenters: array :param logLwidths: LF bin centers and widths. :type logLwidths: array :param computeLF: Select which output entries to compute. :type computeLF: bool :param computeBias: Select which output entries to compute. :type computeBias: bool :returns: **output** -- Output object containing LF and/or bias_num. :rtype: LFbias_outputs .. py:method:: apply_dust_correction(LFParams, z, logL_or_mag, sigma, which_band) Apply dust attenuation to intrinsic LF coordinate(s) and scatter. :param LFParams: :type LFParams: LF_Parameters :param z: Redshift. :type z: float :param logL_or_mag: Intrinsic LF coordinate. :type logL_or_mag: array :param sigma: Intrinsic scatter. :type sigma: float or array :param which_band: Observable band. :type which_band: {"UV", "Ha"} :returns: * **logL_or_mag_dust** (*array*) -- Dust-corrected observed coordinate(s). * **sigma_dust** (*float or array*) -- Scatter after optional dust contribution. .. py:method:: dust_attenuation(LFParams, z, logL_or_mag, which_band) Return the mean attenuation for the requested observable. For UV, this is given as a function of OBSERVED z and magnitude. If using on theoretical intrinsice magnitudes, iterate until convergence. The ``LFParams.HIGH_Z_DUST`` flag controls whether to apply dust attenuation at higher z than 0 or set attenuation to 0. If true, fix betaUV for attenuation calculation at ``LFParams._zmaxdata`` redshift value. Halpha dust attenuation not currently implemented. :param LFParams: :type LFParams: LF_Parameters :param z: Redshift. :type z: float :param logL_or_mag: Observed LF coordinate to be dust attenuated. :type logL_or_mag: array :param which_band: Observable band. :type which_band: {"UV", "Ha"} :returns: **Adust** -- Attenuation in magnitudes for UV. Halpha currently raises a ``ValueError`` because no calibrated model is implemented. :rtype: array .. py:method:: betaUV_dust(LFParams, z, MUV) Compute the UV continuum slope used by the dust model, currently implementing Bowens+13,14 or Zhao+24 model. :param LFParams: :type LFParams: LF_Parameters :param z: Redshift. :type z: float or array :param MUV: UV absolute magnitude. :type MUV: float or array :returns: **beta** -- UV slope from the selected dust model. :rtype: array .. py:method:: correct_AP_LF(z, Deltaz, CosmoParams_data, CosmoParams, logLormag_data, Phi_data, errPhi_data, errPhi_asy_data=None, which_band='UV') Corrects the observed LF from the assumed cosmology CosmoParams to another with CosmoParams_out. Note: no dust correction since it's applied directly to theory->model .. py:method:: meanandsigma_observable_PSD(CosmoParams, AstroParams, HMFinterp, LFParams, GreensFunction, pop) Compute PSD-derived mean and scatter for a given observable (e.g. LUV, Ha, etc...) from the power spectrum of the SFRD. :param CosmoParams: :type CosmoParams: Cosmo_Parameters :param AstroParams: :type AstroParams: Astro_Parameters :param HMFinterp: :type HMFinterp: HMF_interpolator :param LFParams: :type LFParams: LF_Parameters :param GreensFunction: Time-domain response function G(t) for the observable of interest. :type GreensFunction: callable :param pop: Stellar population, 2 for Pop II or 3 for Pop III. :type pop: int :returns: * **avgobs** (*array*) -- Mean observable at each halo mass. * **sigmaobs** (*array*) -- Scatter of the observable at each halo mass. .. py:method:: sigma_MUV_from_meansandsigmas(LUV1mean, LUV2mean, sigmaLUV1, sigmaLUV2) Combine short- and long-timescale UV statistics into mean UV magnitudes and scatter. These components are considered mostly uncorrelated. :param LUV1mean: Mean UV luminosity components. :type LUV1mean: array :param LUV2mean: Mean UV luminosity components. :type LUV2mean: array :param sigmaLUV1: Scatter of the UV luminosity components. :type sigmaLUV1: array :param sigmaLUV2: Scatter of the UV luminosity components. :type sigmaLUV2: array :returns: * **MUV_avg** (*array*) -- Mean UV magnitude. * **sigma_MUV** (*array*) -- UV-magnitude scatter. .. py:class:: Ha_UV_ratio(UserParams, CosmoParams, AstroParams, HMFinterp, LFParams, z_Init=None, SFRD_Init=None, SFH_Init=None, LF_Init=None) Compute the Halpha-to-UV luminosity ratio distribution. This helper combines the UV luminosity function, Halpha luminosities and PSD-derived covariance terms to evaluate the probability distribution of ``log10(L_Ha / L_UV)`` or the equivalent ``xi_ion`` quantity. :param UserParams: :type UserParams: User_Parameters :param CosmoParams: :type CosmoParams: Cosmo_Parameters :param AstroParams: :type AstroParams: Astro_Parameters :param HMFinterp: :type HMFinterp: HMF_interpolator :param LFParams: :type LFParams: LF_Parameters :param z_Init: Precomputed redshift matrices. :type z_Init: Z_init, optional :param SFRD_Init: Precomputed SFRD object. :type SFRD_Init: SFRD_class, optional :param SFH_Init: Precomputed SFH object. :type SFH_Init: SFH_class, optional :param LF_Init: Precomputed LF object. If None, initialized internally. :type LF_Init: LF_class, optional .. py:method:: PDF_log10HaUVratio(LUV_mean, LHa_mean, sigmaLHa, sigmasquaredcross, log10etavalues) Returns the PDF of log10(LHa/LUV) at fixed Mh (NOTE: integrated over all MUVs). Assumed dust corrected! Parameters: ----------- LUVmean : array_like The mean LUV value LHa_mean : array_like The mean LHa value sigmaLHa : array_like The sigma of LHa value sigmasquaredcross : array_like The cross sigma squared (sigma^2) of LHa and LUV This is the covariance between LHa and LUV, computed from their window functions. From cross_sigma_squared_PSD. Returns: -------- log10etavalues : ndarray The log10eta values (same for all input array elements) PDFlog10eta : ndarray Array of shape (len(LUVmean), len(log10etavalues)) with PDFs .. py:method:: PDF_HaUV_ratio(CosmoParams, AstroParams, HMFinterp, LFParams, log10etavalues, FLAG_supersample_MUV=False) Returns Ha/UV ratio PDF, binned in MUV_bin_edges and log10eta bins, if provided. Parameters: ----------- AstroParams : Astro Parameters CosmoParams : Cosmo Parameters HMFinterp : HMFinterp zcenter, zwidth: the z where it is calculated (no width for now, ignored) log10etavalues: the log10(Ha/UV) ratios where the PDF is computed. Assigned by function if None FLAG_supersample_MUV : Whether to super-sample to integrate within MUV_bin_edges better. If =False then just computes at the center of each bin Returns: -------- log10etavalues: bins of log10Ha/UV pdf_binned: the PDF(log10etavalues) in those log10etavalues bins, and the MUV bins chosen UVLFvalues: the UVLF at the MUV binned, so the user can sum stuff easily .. py:method:: log10eta_fromlog10xiion(log10xiion) Returns log10(LHa/LUV) [both in erg/s] given xiion .. py:method:: log10xiion_fromlog10eta(log10eta) Returns log10(xiion) [in Hz/erg] given log10(LHa/LUV) [both in erg/s] .. py:method:: cross_sigma_squared_PSD(GreensFunction1, GreensFunction2, CosmoParams, AstroParams, HMFinterp, LFParams) Returns the cross sigma squared of two observables, given their window functions and SFH