lfkit.photometry.luminosities module#

Luminosity and magnitude conversion utilities for LFKit.

This module provides lightweight helpers for converting between magnitude differences and luminosity ratios, as well as common Schechter-function quantities expressed in luminosity space.

The core convention is

\[L_1 / L_2 = 10^{-0.4 (M_1 - M_2)},\]

where M1 and M2 may be absolute or apparent magnitudes, as long as they are defined in the same photometric system.

All returned quantities are NumPy arrays of dtype float.

lfkit.photometry.luminosities.luminosity_from_magnitude(magnitude, *, reference_magnitude=0.0, reference_luminosity=1.0)[source]#

Return luminosity corresponding to a magnitude relative to a reference.

This uses

\[L = L_{\mathrm{ref}} \, 10^{-0.4 (m - m_{\mathrm{ref}})}.\]
Parameters:

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

  • reference_magnitude (float) – Reference magnitude m_ref.

  • reference_luminosity (float) – Reference luminosity L_ref.

Returns:

NumPy array of luminosities in the same units as reference_luminosity.

Raises:

ValueError – If reference_luminosity is not strictly positive.

Return type:

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

lfkit.photometry.luminosities.luminosity_ratio(absolute_mag, m_star)[source]#

Return the luminosity ratio relative to the characteristic luminosity.

For magnitudes,

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

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

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

Returns:

NumPy array of luminosity ratios L / L_star.

Return type:

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

lfkit.photometry.luminosities.luminosity_ratio_from_magnitudes(magnitude, ref_magnitude)[source]#

Return luminosity relative to a reference magnitude.

This uses \(L / L_{\mathrm{ref}} = 10^{-0.4 (m - m_{\mathrm{ref}})}\).

Parameters:

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

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

Returns:

NumPy array of luminosity ratios \(L / L_{\mathrm{ref}}\).

Return type:

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

lfkit.photometry.luminosities.luminosity_weight_from_magnitude(magnitude, reference_magnitude=0.0)[source]#

Return an unnormalized luminosity weight from a magnitude.

This uses

\[L \propto 10^{-0.4 M}.\]
Parameters:

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

  • reference_magnitude (float) – Reference zero-point magnitude for the proportionality constant.

Returns:

NumPy array proportional to luminosity.

Return type:

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

lfkit.photometry.luminosities.magnitude_difference_from_luminosity_ratio(ratio)[source]#

Return the magnitude difference corresponding to a luminosity ratio.

This uses

\[m_1 - m_2 = -2.5 \log_{10}(L_1 / L_2).\]
Parameters:

ratio (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Luminosity ratio value(s) L1 / L2.

Returns:

NumPy array of magnitude differences m1 - m2.

Raises:

ValueError – If any luminosity ratio is not strictly positive.

Return type:

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

lfkit.photometry.luminosities.sample_schechter_luminosity(size, *, l_star, alpha, rng=None)[source]#

Sample luminosities from a normalized Schechter distribution.

This samples from

\[p(L) \propto (L / L_*)^{\alpha} \exp(-L / L_*),\]

which is equivalent to a Gamma distribution in

\[x = L / L_*,\]

with shape parameter

\[k = \alpha + 1.\]
Parameters:

  • size (int | tuple[int, ...]) – Number or shape of samples to draw.

  • l_star (float) – Characteristic luminosity L_star.

  • alpha (float) – Faint-end slope.

  • rng (Generator | None) – Optional NumPy random number generator.

Returns:

NumPy array of sampled luminosities.

Raises:

ValueError – If l_star is not strictly positive or alpha <= -1.

Return type:

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

lfkit.photometry.luminosities.schechter_cumulative_number_density_luminosity(luminosity_min, *, phi_star, l_star, alpha)[source]#

Return cumulative Schechter number density above a luminosity threshold.

This evaluates

\[n(L > L_{\min}) = \phi_* \, \Gamma(\alpha + 1, L_{\min} / L_*),\]

where Gamma is the upper incomplete gamma function.

Parameters:

  • luminosity_min (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Lower luminosity threshold(s).

  • phi_star (float) – Schechter normalization.

  • l_star (float) – Characteristic luminosity L_star.

  • alpha (float) – Faint-end slope.

Returns:

NumPy array of cumulative number densities above luminosity_min.

Raises:

ValueError – If phi_star is negative, l_star is not strictly positive, or alpha <= -1.

Return type:

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

lfkit.photometry.luminosities.schechter_luminosity_density(*, phi_star, l_star, alpha)[source]#

Return total luminosity density for a Schechter luminosity function.

This evaluates

\[\rho_L = \phi_* \, L_* \, \Gamma(\alpha + 2).\]
Parameters:

  • phi_star (float) – Schechter normalization.

  • l_star (float) – Characteristic luminosity L_star.

  • alpha (float) – Faint-end slope.

Returns:

Total luminosity density.

Raises:

ValueError – If phi_star is negative, l_star is not strictly positive, or alpha <= -2.

Return type:

float

lfkit.photometry.luminosities.schechter_mean_luminosity(*, l_star, alpha)[source]#

Return the mean luminosity of a normalized Schechter distribution.

This evaluates

\[\langle L \rangle = L_* \, \Gamma(\alpha + 2) / \Gamma(\alpha + 1).\]

For finite values this simplifies to

\[\langle L \rangle = L_* (\alpha + 1),\]

provided alpha > -1.

Parameters:

  • l_star (float) – Characteristic luminosity L_star.

  • alpha (float) – Faint-end slope.

Returns:

Mean luminosity.

Raises:

ValueError – If l_star is not strictly positive or alpha <= -1.

Return type:

float

lfkit.photometry.luminosities.schechter_selection_function(luminosity_min, *, l_star, alpha)[source]#

Return the Schechter selection fraction above a luminosity threshold.

This evaluates

\[S(L_{\min}) = n(L > L_{\min}) / n_{\mathrm{tot}} = \Gamma(\alpha + 1, L_{\min} / L_*) / \Gamma(\alpha + 1),\]

which is equivalently

\[S(L_{\min}) = \mathrm{gammaincc}(\alpha + 1, L_{\min} / L_*).\]
Parameters:

  • luminosity_min (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Lower luminosity threshold(s).

  • l_star (float) – Characteristic luminosity L_star.

  • alpha (float) – Faint-end slope.

Returns:

NumPy array of selection fractions between 0 and 1.

Raises:

ValueError – If l_star is not strictly positive, any luminosity threshold is negative, or alpha <= -1.

Return type:

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