Reference on kuibit.gw_utils¶
The module gw_utils
contains convenience functions and
structures to analyze and work with gravitational waves.
First, the Detectors
object is defined. Detectors
is a named tuple
with fields “hanford”, “livingston”, “virgo”. This is used every time we
deal with specific detectors.
The functions provided are:
luminosity_distance_to_redshift()
: convert a given luminosity distance to a redshift in the ΛCDM cosmology.sYlm()
: return the spinweighted spherical harmonics at a given angle.ra_dec_to_theta_phi()
: convert right ascension and declination to spherical coordinates.antenna_responses()
: compute the antenna responses of a given angle.antenna_responses_from_sky_localization()
: compute the antenna responses for known detectors at a given sky localization.signal_to_noise_ratio_from_strain()
: compute the signal to noise for a given signal and a given noise curve.

class
kuibit.gw_utils.
Detectors
(hanford, livingston, virgo)¶ Create new instance of Detectors(hanford, livingston, virgo)

property
hanford
¶ Alias for field number 0

property
livingston
¶ Alias for field number 1

property
virgo
¶ Alias for field number 2

property

kuibit.gw_utils.
Schwarzschild_radius_to_tortoise
(radii, mass)[source]¶ Transform radial coordinates
radii
to tortoise coordinates assuming massmass
.Equation (26) in 1307.5307.
 Parameters
radii (float or 1D NumPy array) – Radius in Schwarzschild coordinates.
mass (float) – ADM mass.
 Returns
Tortoise radii.
 Return type
float or 1D NumPy array

kuibit.gw_utils.
antenna_responses
(theta, phi, polarization=0)[source]¶ Return the antenna response pattern of a detector on the z = 0 plane with the arms on the x and y directions for a given localization defined by the spherical angles
theta
andphi
. Parameters
theta (float) – Meridional angle.
phi (float) – Azimuthal angle.
polarization (float) – Polarization angle of the wave.
 Returns
Antenna response for cross and plus polarizations (in this order).
 Return type
tuple of floats.

kuibit.gw_utils.
antenna_responses_from_sky_localization
(right_ascension, declination, time_utc, polarization=0)[source]¶ Return the antenna responses for Hanford, Livingston and Virgo for a given source.
See, http://research.physics.illinois.edu/cta/movies/bhbh_sim/wavestrain.html.
utc_time
has to have the following formatting:%Y%m%d %H:%M
, (eg20150914 09:50:45
) Parameters
right_ascension (float) – Right ascension of the source in degrees
declination (str) – Declination of the source in degrees
time_utc – UTC time of the event
polarization (float) – Polarization of the wave
 Returns antenna_pattern
Cross and plus antenna pattern for the different interferometers.
 Return type
namedtuple with fields hanford, livingston, and virgo

kuibit.gw_utils.
luminosity_distance_to_redshift
(luminosity_distance, Omega_m=0.309, Omega_L=0.691, initial_guess=0.1)[source]¶ Compute redshift from luminosity distance in Mpc assuming the ΛCDM cosmology.
This function is useful to correctly reproduce observed signals from cosmological sources (e.g., binary black holes far away).
The redshift is computed via rootfinding, so an initial guess is needed.
 Parameters
luminosity_distance (float) – Luminosity distance in megaparsec.
Omega_m (float) – \(\Omega_m\) (matter) cosmological parameter.
Omega_L (float) – \(\Omega_m\) (dark energy) cosmological parameter.
initial_guess (float) – Initial guess to the redshift for the rootfinding routine.
 Returns z
Redshift
 Rtype z
float

kuibit.gw_utils.
ra_dec_to_theta_phi
(right_ascension, declination, time_utc)[source]¶ Compute the spherical angles
theta
andphi
for Hanford, Livingston and Virgo for a given source localization.utc_time
has to have the following formatting:%Y%m%d %H:%M
, (eg20150914 09:50:45
) Parameters
right_ascension (float) – Right ascension of the source in degrees.
declination (str) – Declination of the source in degrees.
time_utc – UTC time of the event.
 Returns spherical coordinates
Theta
,phi
for the different detectors. Return type
namedtuple with fields hanford, livingston, and virgo

kuibit.gw_utils.
retarded_times_to_coordinate_times
(retarded_times, radii, mass)[source]¶  Compute the coordinate times corresponding to the retarded times at the
coordinate radii.
First, the tortoise radius is computed from
radii
, then the coordinate times are computed with \(t = u + r_{tortoise}(radii)\).This function is used to extrapolate gravitational waves to infinity.
 Parameters
retarded_times (float or 1D NumPy array) – Retarded times.
radii (float or 1D NumPy array) – Radii of evaluation.
mass (float) – ADM mass (needed to compute tortoise radius).
 Returns
Coordinate times corresponding to the given retarded times and evaluation radii.
 Return type
float or 1D NumPy array

kuibit.gw_utils.
sYlm
(ss, ll, mm, theta, phi)[source]¶ Compute spinweighted spherical harmonics at the angles
theta
andphi
.When
ss = 0
, these are spherical harmonics. Parameters
ss (int) – Spin weight.
ll (int) – \(l\) multipolar number.
mm (int) – \(m\) multipolar number.
theta (float) – Meridional angle.
phi (float) – Azimuthal angle.
 Returns sYlm
Spinweighted spherical harmonic evaluated at
theta
andphi
. Rtype sYlm
float

kuibit.gw_utils.
signal_to_noise_ratio_from_strain
(h, *args, noise=None, fmin=0, fmax=inf, window_function=None, **kwargs)[source]¶ Return the signal to noise ratio given a strain and a power spectal density distribution for a detector.
If
window_function
is not None, the window will be applied to the signal. All the unknown arguments are passed to the window function.The SNR is computed as \(sqrt of 4 \int_fmin^fmax \tilde{h} f^2 / Sn(f) d f\) (equation from 1408.0740)
 Parameters
h (
TimeSeries
) – Gravitationalwave strain.noise (
FrequencySeries
) – Power spectral density of the noise of the detector.fmin (float) – Minimum frequency over which to compute the SNR.
fmax (float) – Maximum frequency over which to compute the SNR.
window_function (callable, str, or None) – If not None, apply
window_function
to the series before computing the strain.kwargs (args,) – All the additional parameters are passed to the window function.
 Returns
Signaltonoise ratio.
 Return type
float