Skip to content

torchsky.cosmology

Stability: core. Names on this page follow the deprecation policy in contributing.

Differentiable FLRW distance and protected geometry primitives.

Guides: cosmology, spectral-axes

This reference is generated from the package source. Names are grouped by the module that defines them; import every name from the public namespace torchsky.cosmology unless the group text says otherwise.

Top-level namespace

Differentiable FLRW distance and protected geometry primitives.

No learnable parameters or cosmological priors live here. Science projects pass plain tensors (including nn.Parameter instances) through :class:FLRW.

Defaults are Planck 2018: H0=67.66 km/s/Mpc, Om0=0.3111, w0=-1. Distances are Mpc; distance modulus is magnitudes; times are Gyr (Julian years). c = 299792.458 km/s. Radiation is neglected. Curvature follows the standard convention Ok0 > 0 for an open universe. wa uses the CPL law w(a) = w0 + wa (1-a).

HUBBLE_TIME_GYR module-attribute 

HUBBLE_TIME_GYR = _MPC_KM / _GYR_S

PLANCK18_H0 module-attribute 

PLANCK18_H0 = 67.66

PLANCK18_OM0 module-attribute 

PLANCK18_OM0 = 0.3111

PLANCK18_W0 module-attribute 

PLANCK18_W0 = -1.0

SPEED_OF_LIGHT_KM_S module-attribute 

SPEED_OF_LIGHT_KM_S = 299792.458

APScaling dataclass 

APScaling(
    alpha_parallel: Tensor,
    alpha_perpendicular: Tensor,
    f_ap: Tensor,
)

Alcock--Paczynski geometry at a redshift.

alpha_parallel and alpha_perpendicular are dimensionless ratios relative to the supplied reference cosmology. f_ap = D_M H / c is the absolute, dimensionless AP observable for the evaluated cosmology.

alpha_parallel instance-attribute 

alpha_parallel: Tensor

alpha_perpendicular instance-attribute 

alpha_perpendicular: Tensor

f_ap instance-attribute 

f_ap: Tensor

FLRW dataclass 

FLRW(
    H0: Tensor | float = PLANCK18_H0,
    Om0: Tensor | float = PLANCK18_OM0,
    Ok0: Tensor | float = 0.0,
    w0: Tensor | float = PLANCK18_W0,
    wa: Tensor | float = 0.0,
)

Matter + curvature + CPL dark-energy FLRW parameters.

Fields may be scalar tensors so callers can differentiate with respect to cosmological parameters. This container deliberately owns no priors.

Parameters:

Name Type Description Default
H0 Tensor | float

Present-day Hubble parameter in km/s/Mpc.

 PLANCK18_H0
Om0 Tensor | float

Present-day matter density parameter.

 PLANCK18_OM0
Ok0 Tensor | float

Present-day curvature density parameter.

 0.0
w0 Tensor | float

Dark-energy equation-of-state value at scale factor one.

 PLANCK18_W0
wa Tensor | float

CPL dark-energy evolution coefficient.

 0.0

Examples:

>>> import torch
>>> from torchsky.cosmology import FLRW
>>> FLRW().comoving_distance(torch.tensor(0.0)).item()
0.0

H0 class-attribute instance-attribute 

H0: Tensor | float = PLANCK18_H0

Ok0 class-attribute instance-attribute 

Ok0: Tensor | float = 0.0

Om0 class-attribute instance-attribute 

Om0: Tensor | float = PLANCK18_OM0

w0 class-attribute instance-attribute 

w0: Tensor | float = PLANCK18_W0

wa class-attribute instance-attribute 

wa: Tensor | float = 0.0

age 

age(z: Tensor) -> Tensor

angular_diameter_distance 

angular_diameter_distance(z: Tensor) -> Tensor

comoving_distance 

comoving_distance(z: Tensor) -> Tensor

differential_comoving_volume 

differential_comoving_volume(z: Tensor) -> Tensor

distance_modulus 

distance_modulus(z: Tensor) -> Tensor

e 

e(z: Tensor) -> Tensor

hubble_parameter 

hubble_parameter(z: Tensor) -> Tensor

lookback_time 

lookback_time(z: Tensor) -> Tensor

luminosity_distance 

luminosity_distance(z: Tensor) -> Tensor

transverse_comoving_distance 

transverse_comoving_distance(z: Tensor) -> Tensor

FlatWCDM dataclass 

FlatWCDM(
    H0: Tensor | float = PLANCK18_H0,
    Om0: Tensor | float = PLANCK18_OM0,
    Ok0: Tensor | float = 0.0,
    w0: Tensor | float = PLANCK18_W0,
    wa: Tensor | float = 0.0,
)

Bases: FLRW

Flat wCDM. w0=-1 is ΛCDM.

age 

age(
    z: Tensor,
    *,
    H0: Tensor | float = PLANCK18_H0,
    om0: Tensor | float = PLANCK18_OM0,
    ok0: Tensor | float = 0.0,
    w0: Tensor | float = PLANCK18_W0,
    wa: Tensor | float = 0.0,
) -> Tensor

Age of the universe at redshift z, t_H int_z^inf dz'/((1+z')E), in Gyr.

In scale factor the integral is int_0^{a(z)} da / (a E). Substituting a = a(z) s^2 makes the integrand 2 a s / sqrt(a^2 E^2) smooth at the big bang whenever matter dominates there, so the 64-node Gauss-Legendre rule converges to machine precision. a^2 E^2 is evaluated directly so no power of 1+z overflows. Requires Om0 > 0; negative z is treated as zero. Radiation is neglected: with Planck parameters it shortens the present age by about 0.02 per cent, and much more at high redshift.

Parameters:

Name Type Description Default
z Tensor

Redshift tensor (age(0) is the present age).

 required
H0 Tensor | float

Present-day Hubble parameter in km/s/Mpc.

 PLANCK18_H0
om0 Tensor | float

Present-day matter density parameter.

 PLANCK18_OM0
ok0 Tensor | float

Present-day curvature density parameter.

 0.0
w0 Tensor | float

Dark-energy equation-of-state value at scale factor one.

 PLANCK18_W0
wa Tensor | float

CPL dark-energy evolution coefficient.

 0.0

Returns:

Type Description
Tensor

Ages in Gyr with the shape of z.

Examples:

>>> import torch
>>> from torchsky.cosmology import age
>>> round(float(age(torch.tensor(0.0, dtype=torch.float64), H0=70.0, om0=1.0)), 6)
9.312307

alcock_paczynski_scaling 

alcock_paczynski_scaling(
    z: Tensor, cosmology: FLRW, reference: FLRW
) -> APScaling

AP geometry at strictly positive redshift.

The alpha values are relative to reference; f_ap is the absolute D_M(z) H(z) / c observable for cosmology.

angular_diameter_distance 

angular_diameter_distance(
    z: Tensor,
    *,
    H0: Tensor | float = PLANCK18_H0,
    om0: Tensor | float = PLANCK18_OM0,
    ok0: Tensor | float = 0.0,
    w0: Tensor | float = PLANCK18_W0,
    wa: Tensor | float = 0.0,
) -> Tensor

D_A = D_M / (1+z) in Mpc.

comoving_distance 

comoving_distance(
    z: Tensor,
    *,
    H0: Tensor | float = PLANCK18_H0,
    om0: Tensor | float = PLANCK18_OM0,
    ok0: Tensor | float = 0.0,
    w0: Tensor | float = PLANCK18_W0,
    wa: Tensor | float = 0.0,
) -> Tensor

Line-of-sight comoving distance D_C in Mpc.

Integrates 1/E(z') per point with fixed Gauss-Legendre nodes in ln(1+z); results are independent of the other batch entries. Negative z is treated as zero; D_C(0) = 0.

Parameters:

Name Type Description Default
z Tensor

Redshift tensor.

 required
H0 Tensor | float

Present-day Hubble parameter in km/s/Mpc.

 PLANCK18_H0
om0 Tensor | float

Present-day matter density parameter.

 PLANCK18_OM0
ok0 Tensor | float

Present-day curvature density parameter.

 0.0
w0 Tensor | float

Dark-energy equation-of-state value at scale factor one.

 PLANCK18_W0
wa Tensor | float

CPL dark-energy evolution coefficient.

 0.0

Returns:

Type Description
Tensor

Line-of-sight comoving distances in Mpc with the shape of z.

Examples:

>>> import torch
>>> from torchsky.cosmology import comoving_distance
>>> comoving_distance(torch.tensor([0.0])).tolist()
[0.0]

comoving_position 

comoving_position(
    unit_xyz: Tensor, z: Tensor, cosmology: FLRW = FLRW()
) -> Tensor

Flat-FLRW Cartesian comoving position chi(z) * unit_xyz in Mpc.

A curved spatial slice has no global Euclidean Cartesian representation; use :func:comoving_separation there.

comoving_separation 

comoving_separation(
    unit_xyz_a: Tensor,
    z_a: Tensor,
    unit_xyz_b: Tensor,
    z_b: Tensor,
    cosmology: FLRW = FLRW(),
) -> Tensor

Constant-curvature FLRW spatial geodesic separation in Mpc.

differential_comoving_volume 

differential_comoving_volume(
    z: Tensor, cosmology: FLRW = FLRW()
) -> Tensor

Observed-coordinate volume Jacobian dV_c/(dOmega dz).

The result is c D_M(z)^2 / H(z) in Mpc^3 sr^-1 per unit redshift. It is the measure factor needed by observed-coordinate point-process likelihoods; selection functions are not included.

distance_modulus 

distance_modulus(
    z: Tensor,
    *,
    H0: Tensor | float = PLANCK18_H0,
    om0: Tensor | float = PLANCK18_OM0,
    ok0: Tensor | float = 0.0,
    w0: Tensor | float = PLANCK18_W0,
    wa: Tensor | float = 0.0,
) -> Tensor

μ = 5 log10(D_L / 10 pc) with D_L in Mpc.

The logarithm argument is floored so μ(0) stays finite; D_L(0) itself is zero.

e_of_z 

e_of_z(
    z: Tensor,
    *,
    om0: Tensor | float = PLANCK18_OM0,
    ok0: Tensor | float = 0.0,
    w0: Tensor | float = PLANCK18_W0,
    wa: Tensor | float = 0.0,
) -> Tensor

Dimensionless Hubble function E(z) = H(z)/H0 for CPL FLRW.

hubble_parameter 

hubble_parameter(
    z: Tensor,
    *,
    H0: Tensor | float = PLANCK18_H0,
    om0: Tensor | float = PLANCK18_OM0,
    ok0: Tensor | float = 0.0,
    w0: Tensor | float = PLANCK18_W0,
    wa: Tensor | float = 0.0,
) -> Tensor

Hubble parameter H(z) in km/s/Mpc.

lookback_time 

lookback_time(
    z: Tensor,
    *,
    H0: Tensor | float = PLANCK18_H0,
    om0: Tensor | float = PLANCK18_OM0,
    ok0: Tensor | float = 0.0,
    w0: Tensor | float = PLANCK18_W0,
    wa: Tensor | float = 0.0,
) -> Tensor

Lookback time t_L(z) = t_H int_0^z dz' / ((1+z') E(z')) in Gyr.

t_H = 1/H0. The integrand is 1/E in u = ln(1+z) and uses the same per-point 64-node Gauss-Legendre rule as :func:comoving_distance. Negative z is treated as zero. Radiation is neglected.

Parameters:

Name Type Description Default
z Tensor

Redshift tensor.

 required
H0 Tensor | float

Present-day Hubble parameter in km/s/Mpc.

 PLANCK18_H0
om0 Tensor | float

Present-day matter density parameter.

 PLANCK18_OM0
ok0 Tensor | float

Present-day curvature density parameter.

 0.0
w0 Tensor | float

Dark-energy equation-of-state value at scale factor one.

 PLANCK18_W0
wa Tensor | float

CPL dark-energy evolution coefficient.

 0.0

Returns:

Type Description
Tensor

Lookback times in Gyr with the shape of z.

Examples:

>>> import torch
>>> from torchsky.cosmology import lookback_time
>>> lookback_time(torch.tensor([0.0])).tolist()
[0.0]

luminosity_distance 

luminosity_distance(
    z: Tensor,
    *,
    H0: Tensor | float = PLANCK18_H0,
    om0: Tensor | float = PLANCK18_OM0,
    ok0: Tensor | float = 0.0,
    w0: Tensor | float = PLANCK18_W0,
    wa: Tensor | float = 0.0,
) -> Tensor

D_L = (1+z) D_M in Mpc.

transverse_comoving_distance 

transverse_comoving_distance(
    z: Tensor,
    *,
    H0: Tensor | float = PLANCK18_H0,
    om0: Tensor | float = PLANCK18_OM0,
    ok0: Tensor | float = 0.0,
    w0: Tensor | float = PLANCK18_W0,
    wa: Tensor | float = 0.0,
) -> Tensor

Transverse comoving distance D_M in Mpc.

A series around Ok0 = 0 keeps the value and curvature gradient finite.