lfkit.photometry.luminosity_function module#

Luminosity function utilities for LFKit.

This module provides simple standalone functions for evaluating common galaxy luminosity function parameterization.

All luminosity functions in this module are defined in rest-frame absolute magnitude space. Functions with names ending in _from_m are convenience wrappers that accept apparent magnitudes, convert them to absolute magnitudes, and then evaluate the luminosity function in absolute magnitude space.

Implemented models:

  • Standard Schechter LF in rest-frame absolute magnitudes

  • Schechter LF with configurable redshift evolution of parameters

  • Double-power-law Schechter LF in rest-frame absolute magnitudes

The magnitude-space Schechter function is

\[\phi(M) = 0.4 \ln(10) \, \phi_\star \, x^{\alpha + 1} \exp(-x),\]

where

\[x = 10^{-0.4 (M - M_\star)}.\]

Redshift evolution is handled by separate helper functions for phi_star(z), M_star(z), and alpha(z). Built-in options include constant evolution and common linearized forms such as

\[M_\star(z) = M_{0,\star} - q (z - z_{\mathrm{ref}})\]
\[\phi_\star(z) = \phi_{0,\star} \, 10^{0.4 p z}.\]

For more information see The CNOC2 Field Galaxy Luminosity Function I: A Description of Luminosity Function Evolution by Lin et al. 1999 (arXiv:9902249) or GAMA: ugriz galaxy luminosity functions by Loveday et al. (arXiv:1111.0166).

All returned quantities are NumPy arrays of dtype float.

lfkit.photometry.luminosity_function.double_schechter(absolute_mag, *, phi_star, m_star, alpha, beta, m_transition)[source]#

Return a double-power-law Schechter luminosity function in magnitude space.

This implements the Loveday/GAMA-style faint-end extension

\[\phi(L) = \phi_\star (L/L_\star)^\alpha \exp(-L/L_\star) \times \left[1 + (L/L_t)^\beta\right]\]

converted into a per-magnitude luminosity function.

Since

\[\phi(M) \, dM = \phi(L) \, dL\]

and

\[\frac{dL}{dM} = -0.4 \ln(10) \, L,\]

the magnitude-space form becomes

\[\phi(M) = 0.4 \ln(10) \, \phi_\star \, x^{\alpha + 1} \exp(-x) \times \left[1 + (x / x_t)^\beta\right]\]

with \(x = L/L_\star\) and \(x_t = L_t/L_\star\).

Parameters:

  • absolute_mag (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Absolute magnitude value(s).

  • phi_star (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Overall normalization.

  • m_star (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Characteristic magnitude M_star.

  • alpha (float) – Bright/intermediate faint-end slope parameter.

  • beta (float) – Additional faint-end slope modifier.

  • m_transition (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Transition magnitude M_t corresponding to L_t.

Returns:

NumPy array of luminosity function values evaluated at absolute_mag.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

lfkit.photometry.luminosity_function.double_schechter_from_m(cosmo_obj, z, apparent_mag, *, phi_star, m_star, alpha, beta, m_transition, h=None, k_correction=None, e_correction=None)[source]#

Return a double-power-law Schechter luminosity function from apparent magnitudes.

This uses

\[M = m - \mu - K + E,\]

followed by

\[\phi(M) = 0.4 \ln(10) \, \phi_\star \, x^{\alpha + 1} \exp(-x) \times \left[1 + (x / x_t)^\beta\right],\]

where

\[x = 10^{-0.4 (M - M_\star)}\]
\[x_t = 10^{-0.4 (M_t - M_\star)}.\]
Parameters:

  • cosmo_obj (Any) – A PyCCL cosmology object.

  • z (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Redshift value or array-like of redshift values.

  • apparent_mag (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Apparent magnitude value(s).

  • phi_star (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Overall normalization.

  • m_star (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Characteristic magnitude M_star.

  • alpha (float) – Bright/intermediate faint-end slope parameter.

  • beta (float) – Additional faint-end slope modifier.

  • m_transition (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Transition magnitude M_t.

  • h (float | None) – Optional dimensionless Hubble parameter used in the distance-modulus convention.

  • k_correction (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Optional k-correction term(s).

  • e_correction (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Optional evolution-correction term(s).

Returns:

NumPy array of luminosity function values corresponding to the supplied apparent magnitudes.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

lfkit.photometry.luminosity_function.evolving_schechter(absolute_mag, z, *, phi_model='linear_p', phi_kwargs=None, m_star_model='linear_q', m_star_kwargs=None, alpha_model='constant', alpha_kwargs=None)[source]#

Return an evolving Schechter luminosity function in magnitude space.

This evaluates

\[\phi(M, z) = 0.4 \ln(10) \, \phi_\star(z) \, x(M, z)^{\alpha(z) + 1} \exp(-x(M, z)),\]

where

\[x(M, z) = 10^{-0.4 (M - M_\star(z))}.\]
Parameters:

  • absolute_mag (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Absolute magnitude value(s).

  • z (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Redshift value or array-like of redshift values.

  • phi_model (str) – Evolution model for phi_star.

  • phi_kwargs (Mapping[str, float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]] | None) – Keyword arguments passed to the selected phi_star evolution model.

  • m_star_model (str) – Evolution model for M_star.

  • m_star_kwargs (Mapping[str, float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]] | None) – Keyword arguments passed to the selected M_star evolution model.

  • alpha_model (str) – Evolution model for alpha.

  • alpha_kwargs (Mapping[str, float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]] | None) – Keyword arguments passed to the selected alpha evolution model.

Returns:

NumPy array of luminosity function values evaluated at absolute_mag and z.

Raises:

ValueError – If an unsupported evolution model is requested.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

lfkit.photometry.luminosity_function.evolving_schechter_from_m(cosmo_obj, z, apparent_mag, *, phi_model='linear_p', phi_kwargs=None, m_star_model='linear_q', m_star_kwargs=None, alpha_model='constant', alpha_kwargs=None, h=None, k_correction=None, e_correction=None)[source]#

Return an evolving Schechter luminosity function from apparent magnitudes.

This uses

\[M = m - \mu - K + E,\]

followed by

\[\phi(M, z) = 0.4 \ln(10) \, \phi_\star(z) \, x(M, z)^{\alpha(z) + 1} \exp(-x(M, z)),\]

where

\[x(M, z) = 10^{-0.4 (M - M_\star(z))}.\]
Parameters:

  • cosmo_obj (Any) – A PyCCL cosmology object.

  • z (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Redshift value or array-like of redshift values.

  • apparent_mag (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Apparent magnitude value(s).

  • phi_model (str) – Evolution model for phi_star.

  • phi_kwargs (Mapping[str, float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]] | None) – Keyword arguments passed to the selected phi_star evolution model.

  • m_star_model (str) – Evolution model for M_star.

  • m_star_kwargs (Mapping[str, float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]] | None) – Keyword arguments passed to the selected M_star evolution model.

  • alpha_model (str) – Evolution model for alpha.

  • alpha_kwargs (Mapping[str, float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]] | None) – Keyword arguments passed to the selected alpha evolution model.

  • h (float | None) – Optional dimensionless Hubble parameter used in the distance-modulus convention.

  • k_correction (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Optional k-correction term(s).

  • e_correction (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Optional evolution-correction term(s).

Returns:

NumPy array of luminosity function values corresponding to the supplied apparent magnitudes.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

lfkit.photometry.luminosity_function.schechter(absolute_mag, *, phi_star, m_star, alpha)[source]#

Return the standard Schechter luminosity function in magnitude space.

This computes

\[\phi(M) = 0.4 \ln(10) \, \phi_\star \, x^{\alpha + 1} \exp(-x),\]

where

\[x = 10^{-0.4 (M - M_\star)}.\]
Parameters:

  • absolute_mag (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Absolute magnitude value(s).

  • phi_star (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Schechter normalization.

  • m_star (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Characteristic magnitude.

  • alpha (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Faint-end slope. Can be a scalar or array-like.

Returns:

NumPy array of luminosity function values evaluated at absolute_mag.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

lfkit.photometry.luminosity_function.schechter_cumulative(magnitude_limit, *, phi_star, m_star, alpha, brighter_than=True)[source]#

Return the cumulative number density for a standard Schechter LF.

For a magnitude threshold \(M_{\mathrm{lim}}\), define

\[x_{\mathrm{lim}} = 10^{-0.4 (M_{\mathrm{lim}} - M_\star)}.\]

Then the cumulative number density of galaxies brighter than the threshold is

\[n(M < M_{\mathrm{lim}}) = \phi_\star \, \Gamma(\alpha + 1, x_{\mathrm{lim}}),\]

Then the cumulative number density of galaxies fainter than the threshold is

\[n(M > M_{\mathrm{lim}}) = \phi_\star \, \Gamma(\alpha + 1) - n(M < M_{\mathrm{lim}}).\]

Note

This analytic helper is provided only for the standard Schechter form. The double-power-law case is not included here because it is usually cleaner to integrate numerically.

Parameters:

  • magnitude_limit (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Magnitude threshold(s).

  • phi_star (float) – Schechter normalization.

  • m_star (float) – Characteristic magnitude.

  • alpha (float) – Faint-end slope.

  • brighter_than (bool) – If True, return number density brighter than the threshold. If False, return number density fainter than the threshold.

Returns:

NumPy array of cumulative number densities for the supplied magnitude threshold(s).

Return type:

ndarray[tuple[Any, …], dtype[float64]]

lfkit.photometry.luminosity_function.schechter_cumulative_evolving(magnitude_limit, z, *, phi_model='linear_p', phi_kwargs=None, m_star_model='linear_q', m_star_kwargs=None, alpha_model='constant', alpha_kwargs=None, brighter_than=True)[source]#

Return the cumulative number density for an evolving Schechter LF.

For a magnitude threshold \(M_{\mathrm{lim}}\), define

\[x_{\mathrm{lim}} = 10^{-0.4 (M_{\mathrm{lim}} - M_\star(z))}.\]

Then the cumulative number density of galaxies brighter than the threshold is

\[n(< M_{\mathrm{lim}}, z) = \phi_\star(z) \, \Gamma(\alpha(z) + 1, x_{\mathrm{lim}}),\]

Then the cumulative number density of galaxies fainter than the threshold is

\[n(M > M_{\mathrm{lim}}, z) = \phi_\star(z) \, \Gamma(\alpha(z) + 1) - n(M < M_{\mathrm{lim}}, z).\]
Parameters:

  • magnitude_limit (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Magnitude threshold(s).

  • z (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Redshift value or array-like of redshift values.

  • phi_model (str) – Evolution model for phi_star.

  • phi_kwargs (Mapping[str, float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]] | None) – Keyword arguments passed to the selected phi_star evolution model.

  • m_star_model (str) – Evolution model for M_star.

  • m_star_kwargs (Mapping[str, float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]] | None) – Keyword arguments passed to the selected M_star evolution model.

  • alpha_model (str) – Evolution model for alpha.

  • alpha_kwargs (Mapping[str, float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]] | None) – Keyword arguments passed to the selected alpha evolution model.

  • brighter_than (bool) – If True, return number density brighter than the threshold. If False, return number density fainter than the threshold.

Returns:

NumPy array of cumulative number densities evaluated at the supplied magnitude threshold(s) and redshift(s).

Raises:

ValueError – If an unsupported evolution model is requested.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

lfkit.photometry.luminosity_function.schechter_from_m(cosmo_obj, z, apparent_mag, *, phi_star, m_star, alpha, h=None, k_correction=None, e_correction=None)[source]#

Return the standard Schechter luminosity function from apparent magnitudes.

This uses

\[M = m - \mu - K + E,\]

followed by

\[\phi(M) = 0.4 \ln(10) \, \phi_\star \, x^{\alpha + 1} \exp(-x),\]

where

\[x = 10^{-0.4 (M - M_\star)}.\]

This is a convenience wrapper; the luminosity function itself is still defined and evaluated in rest-frame absolute magnitude space.

Parameters:

  • cosmo_obj (Any) – A PyCCL cosmology object.

  • z (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Redshift value or array-like of redshift values.

  • apparent_mag (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Observed apparent magnitude value(s), which are converted to rest-frame absolute magnitudes before LF evaluation.

  • phi_star (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Schechter normalization.

  • m_star (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Characteristic magnitude.

  • alpha (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Faint-end slope.

  • h (float | None) – Optional dimensionless Hubble parameter used in the distance-modulus convention.

  • k_correction (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Optional k-correction term(s).

  • e_correction (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Optional evolution-correction term(s).

Returns:

NumPy array of luminosity function values corresponding to the supplied apparent magnitudes.

Return type:

ndarray[tuple[Any, …], dtype[float64]]