lfkit.photometry.lf_integrals module#

Luminosity-function integration utilities.

This module provides generic numerical integrals of luminosity function callables over finite absolute magnitude ranges.

The core API accepts a luminosity function callable with signature

lf(absolute_mag, z)

where absolute_mag and z are NumPy arrays that can be broadcast together. This keeps the integration machinery independent of any specific luminosity function parameterization, catalog selection, or cosmology backend.

These helpers are intentionally generic. Catalog completeness, LF-dependent redshift densities, luminosity-density calculations, and selection-weighted integrals can all call this module instead of duplicating magnitude-grid logic.

lfkit.photometry.lf_integrals.cumulative_number_density(z, lf, *, m_threshold, m_bright, m_faint, brighter_than=True, n_m=512)[source]#

Return cumulative LF number density around a magnitude threshold.

If brighter_than is True, this computes

\[n(< M_{\mathrm{thr}}, z) = \int_{M_{\mathrm{bright}}}^{\min(M_{\mathrm{thr}}, M_{\mathrm{faint}})} \phi(M, z)\,dM.\]

If brighter_than is False, this computes

\[n(> M_{\mathrm{thr}}, z) = \int_{\max(M_{\mathrm{thr}}, M_{\mathrm{bright}})}^{M_{\mathrm{faint}}} \phi(M, z)\,dM.\]
Parameters:

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

  • lf (Callable[[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]]) – Luminosity-function callable with signature lf(M, z).

  • m_threshold (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Absolute magnitude threshold. May be scalar or array-like.

  • m_bright (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Bright absolute magnitude bound. May be scalar or array-like.

  • m_faint (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Faint absolute magnitude bound. May be scalar or array-like.

  • brighter_than (bool) – If True, integrate galaxies brighter than the threshold. If False, integrate galaxies fainter than the threshold.

  • n_m (int) – Number of magnitude-grid points used for the integral.

Returns:

NumPy array of cumulative number densities evaluated at z.

Return type:

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

lfkit.photometry.lf_integrals.integrated_luminosity_density(z, lf, *, m_bright, m_faint, m_reference=0.0, n_m=512)[source]#

Return luminosity density from a luminosity function.

This computes

\[\rho_L(z) = \int_{M_{\mathrm{bright}}(z)}^{M_{\mathrm{faint}}(z)} L(M)\,\phi(M, z)\,dM,\]

using relative luminosities

\[L(M) / L_{\mathrm{ref}} = 10^{-0.4(M - M_{\mathrm{ref}})}.\]
Parameters:

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

  • lf (Callable[[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]]) – Luminosity-function callable with signature lf(M, z).

  • m_bright (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Bright absolute magnitude bound. May be scalar or array-like.

  • m_faint (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Faint absolute magnitude bound. May be scalar or array-like.

  • m_reference (float) – Reference absolute magnitude defining the luminosity unit.

  • n_m (int) – Number of magnitude-grid points used for the integral.

Returns:

NumPy array of luminosity densities in units of the reference luminosity.

Return type:

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

lfkit.photometry.lf_integrals.integrated_number_density(z, lf, *, m_bright, m_faint, n_m=512)[source]#

Return finite-range number density from a luminosity function.

This computes

\[n(z) = \int_{M_{\mathrm{bright}}(z)}^{M_{\mathrm{faint}}(z)} \phi(M, z) \, dM.\]

Magnitudes are ordered so that more negative values are brighter.

Parameters:

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

  • lf (Callable[[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]]) – Luminosity-function callable with signature lf(M, z).

  • m_bright (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Bright absolute magnitude bound. May be scalar or array-like.

  • m_faint (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Faint absolute magnitude bound. May be scalar or array-like.

  • n_m (int) – Number of magnitude-grid points used for the integral.

Returns:

NumPy array of number densities evaluated at z.

Return type:

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

lfkit.photometry.lf_integrals.lf_weighted_integral(z, lf, *, m_bright, m_faint, weight_fn, n_m=512)[source]#

Return a weighted luminosity function integral.

This computes

\[I(z) = \int_{M_{\mathrm{bright}}(z)}^{M_{\mathrm{faint}}(z)} w(M, z)\,\phi(M, z)\,dM.\]
Parameters:

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

  • lf (Callable[[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]]) – Luminosity-function callable with signature lf(M, z).

  • m_bright (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Bright absolute magnitude bound. May be scalar or array-like.

  • m_faint (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Faint absolute magnitude bound. May be scalar or array-like.

  • weight_fn (Callable[[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]]) – Weight callable with signature weight_fn(M, z). Its return values must be broadcastable to the magnitude-redshift grid.

  • n_m (int) – Number of magnitude-grid points used for the integral.

Returns:

NumPy array of weighted LF integrals evaluated at z.

Return type:

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

lfkit.photometry.lf_integrals.magnitude_window_number_density(z, lf, *, m_bright=None, m_faint=None, apparent_m_bright=None, apparent_m_faint=None, luminosity_distance_mpc_fn=None, k_correction_fn=None, e_correction_fn=None, n_m=512)[source]#

Return LF number density inside a magnitude-selection window.

This integrates a luminosity function over a finite absolute magnitude range. The bright and faint limits may be supplied directly as absolute magnitudes, converted from apparent magnitudes, or supplied as a mixture of both.

Magnitudes are ordered so that more negative values are brighter. Apparent magnitude limits are converted to absolute magnitude limits at each redshift before integration.

This helper is science-use-case agnostic. It only defines the LF integral over a magnitude window; interpretation of that selected population belongs to the calling analysis.

Parameters:

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

  • lf (Callable[[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]]) – Luminosity-function callable with signature lf(M, z).

  • m_bright (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Bright absolute magnitude bound.

  • m_faint (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Faint absolute magnitude bound.

  • apparent_m_bright (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Bright apparent magnitude bound.

  • apparent_m_faint (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Faint apparent magnitude bound.

  • luminosity_distance_mpc_fn (Callable[[ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]] | None) – Callable returning luminosity distance in Mpc. Required when either apparent magnitude bound is supplied.

  • k_correction_fn (Callable[[ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]] | None) – Optional K-correction callable evaluated at z.

  • e_correction_fn (Callable[[ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]] | None) – Optional E-correction callable evaluated at z.

  • n_m (int) – Number of magnitude-grid points used for the integral.

Returns:

NumPy array of number densities evaluated at z.

Raises:

ValueError – If a bright or faint bound is missing, if both absolute and apparent values are supplied for the same bound, or if an apparent bound is supplied without a luminosity-distance callable.

Return type:

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

lfkit.photometry.lf_integrals.mean_luminosity(z, lf, *, m_bright, m_faint, m_reference=0.0, n_m=512)[source]#

Return mean luminosity over a finite magnitude range.

This computes

\[\langle L \rangle(z) = \frac{\int L(M)\,\phi(M, z)\,dM} {\int \phi(M, z)\,dM}.\]

The luminosity is returned in units of the reference luminosity defined by m_reference.

Parameters:

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

  • lf (Callable[[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]]) – Luminosity-function callable with signature lf(M, z).

  • m_bright (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Bright absolute magnitude bound. May be scalar or array-like.

  • m_faint (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Faint absolute magnitude bound. May be scalar or array-like.

  • m_reference (float) – Reference absolute magnitude defining the luminosity unit.

  • n_m (int) – Number of magnitude-grid points used for the integral.

Returns:

NumPy array of mean luminosities. Entries are zero where the integrated number density is zero.

Return type:

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

lfkit.photometry.lf_integrals.selection_weighted_number_density(z, lf, *, m_bright, m_faint, selection_fn, n_m=512)[source]#

Return number density weighted by a selection function.

This computes

\[n_{\mathrm{sel}}(z) = \int_{M_{\mathrm{bright}}(z)}^{M_{\mathrm{faint}}(z)} S(M, z)\,\phi(M, z)\,dM.\]
Parameters:

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

  • lf (Callable[[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]]) – Luminosity-function callable with signature lf(M, z).

  • m_bright (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Bright absolute magnitude bound. May be scalar or array-like.

  • m_faint (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Faint absolute magnitude bound. May be scalar or array-like.

  • selection_fn (Callable[[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]]) – Selection callable with signature selection_fn(M, z). Values should usually lie between 0 and 1, although this function only requires finite non-negative values.

  • n_m (int) – Number of magnitude-grid points used for the integral.

Returns:

NumPy array of selection-weighted number densities evaluated at z.

Return type:

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