Grale Documentation

class grale.core.GWEvent(m1, m2)

Bases: object

chirp_mass(m1=None, m2=None)

Calculate the chirp mass M₀ = (m₁ * m₂)^{3/5} / (m₁ + m₂)^{1/5}, which determines the amplitude and frequency evolution of a GW signal.

Parameters:

• m1 (float, optional) – First mass. Defaults to self.m1.

• m2 (float, optional) – Second mass. Defaults to self.m2.

Returns:

Chirp mass value.

Return type:

float

Notes

The chirp mass is stored in self.M0 as a side effect.

redshift_range(delta=0.4, step=0.01, m1_range=None, m2_range=None, z_lens=None)

Compute a grid of chirp masses and their corresponding redshifts over a parameter space of m1 and m2. Optionally apply a redshift threshold to model lensing.

Parameters:

• delta (float) – Variation range ± around self.m1 and self.m2 if no ranges provided.

• step (float) – Step size for mass grid.

• m1_range (np.ndarray, optional) – Custom range of m1 values.

• m2_range (np.ndarray, optional) – Custom range of m2 values.

• z_lens (float, optional) – Minimum redshift to qualify as lensed.

Returns:

Contains mass ranges, chirp mass grid, redshift grid, and filters:

• ’m1_range’, ‘m2_range’

• ’chirp_masses’

• ’redshifts’

• ’plausible_redshifts’ (z ≥ 0)

• ’plausible_redshifts_lensed’ (z ≥ z_lens, if given)

Return type:

dict

true_redshift(M)

Compute the true redshift of a gravitational wave source, given the observed (redshifted) chirp mass and the intrinsic chirp mass.

Parameters:

M (float) – Observed redshifted chirp mass.

Returns:

Estimated redshift (z = M₀ / M - 1).

Return type:

float

class grale.core.LensingCalculator(cosmo, D_mu1, sigma, theta_offset)

Bases: object

angular_diameter_distance(z)

DS Return angular diameter distance (with units) for a given redshift z.

angular_diameter_distance_z1z2(z1, z2)

DLS: Return angular diameter distance between redshift z1 and z2.

comoving_distance(z)

Return comoving distance (with units) for a given redshift z.

comoving_distance_diff(z_source, z_lens)

Compute (D_C(z_source) - D_C(z_lens)) / (1 + z_source).

Parameters:

• z_source (float) – Source redshift.

• z_lens (float) – Lens redshift.

Returns:

Distance value in Mpc.

Return type:

Quantity

compute_over_redshift_range(z_array, z_lens)

Compute lensing quantities (D_S, D_LS, θ_E, μ_geo) over a source redshift array.

Parameters:

• z_array (array-like) – Source redshift values.

• z_lens (float) – Lens redshift.

Returns:

Computed lensing properties for each redshift:

• ’z’, ‘DS’, ‘DLS’, ‘r_E’, ‘mu_geo’

• ’plausible_magnifications’: μ_geo for z ≥ z_lens

Return type:

dict

einstein_radius(DLS, DS)

Compute Einstein radius in arcseconds.

Parameters:

• DLS (Quantity) – Angular diameter distance between lens and source.

• DS (Quantity) – Angular diameter distance to source.

Returns:

Einstein radius in arcseconds.

Return type:

Quantity

luminosity_distance(z)

DS: Return luminosity distance (with units) for a given redshift z.

magnification(D_true)

Compute lensing magnification μ = (D_true / D_mu1)^2.

Parameters:

D_true (Quantity) – True luminosity distance (must be positive).

Returns:

Lensing magnification factor.

Return type:

float

magnifying_power(einstein_radius)

Compute geometric magnification μ_geo = θ / (θ - θ_E).

Parameters:

einstein_radius (Quantity) – Einstein radius in arcseconds.

Returns:

Geometric magnification factor.

Return type:

float

Raises:

ValueError – If θ ≈ θ_E (unphysical case of infinite magnification).

reverse_calc(magn_range)

Estimate the redshifts and true luminosity distances corresponding to a given range of magnifications, assuming the observed distance is D_mu1.

Parameters:

magn_range (array-like) – Array of magnification values μ > 0.

Returns:

• reverse_redshifts (list): Redshifts corresponding to true distances.

• reverse_distances (list): True luminosity distances.

Return type:

tuple