Creating and storing data¶
The events dictionary¶
The gwfast functions take as input dictionaries containing the parameters of the events to analyse.
As an example, the dictionary can be structured as
- events¶
- Type
dict(array, array, …)
events = {
'Mc':np.array([…]),'eta':np.array([…]),'dL':np.array([…]),'theta':np.array([…]),'phi':np.array([…]),'iota':np.array([…]),'psi':np.array([…]),'tcoal':np.array([…]),'Phicoal':np.array([…]),'chi1x':np.array([…]),'chi2x':np.array([…]),'chi1y':np.array([…]),'chi2y':np.array([…]),'chi1z':np.array([…]),'chi2z':np.array([…]),'LambdaTilde':np.array([…]),'deltaLambda':np.array([…]),'ecc':np.array([…])}
Note
The arrays in the events dictionary have to be 1-D and all of the same size.
Parameters names and conventions¶
Here we report the naming conventions used in gwfast, as well as the units of the parameters and their physical range
Parameter symbol |
Parameter name |
Parameter description |
Units in |
Physical range |
|---|---|---|---|---|
\({\cal M}_c\) |
|
detector-frame chirp mass |
\(\rm M_{\odot}\) |
\((0,\,+\infty)\) |
\(\eta\) |
|
symmetric mass ratio |
– |
\((0,\,0.25]\) |
\(m_1\) |
|
detector-frame primary mass \((m_1 \geq m_2)\) |
\(\rm M_{\odot}\) |
\((0,\,+\infty)\) |
\(m_2\) |
|
detector-frame secondary mass \((m_2 \leq m_1)\) |
\(\rm M_{\odot}\) |
\((0,\, m_1]\) |
\(d_L\) |
|
luminosity distance |
\(\rm Gpc\) |
\((0,\,+\infty)\) |
\(\theta,\, \phi\) |
|
sky position |
\(\rm rad\) |
\([0,\,\pi]\), \([0,\,2\pi]\) |
\(\alpha,\, \delta\) |
|
sky position (astro.) |
\(\rm rad\) |
\([0,\,2\pi]\), \([-\pi/2,\,\pi/2]\) |
\(\iota\) |
|
inclination angle with respect to orbital angular momentum |
\(\rm rad\) |
\([0,\,\pi]\) |
\(\theta_{JN}\) |
|
inclination angle with respect to total angular momentum |
\(\rm rad\) |
\([0,\,\pi]\) |
\(\psi\) |
|
polarisation angle |
\(\rm rad\) |
\([0,\,\pi]\) |
\(t_{c, {\rm GMST}}\) |
|
GMST time of coalescence |
\(\rm day\) |
\([0,\,1]\) |
\(t_{c, {\rm GPS}}\) |
|
GPS time of coalescence |
\(\rm s\) |
\([0,\,+\infty)\) |
\(\Phi_c\) |
|
phase at coalescence |
\(\rm rad\) |
\([0,\,2\pi]\) |
\(\chi_{1,x}\) |
|
spin of object 1 along the axis \(x\) |
– |
\([-1,\,1]\) |
\(\chi_{2,x}\) |
|
spin of object 2 along the axis \(x\) |
– |
\([-1,\,1]\) |
\(\chi_{1,y}\) |
|
spin of object 1 along the axis \(y\) |
– |
\([-1,\,1]\) |
\(\chi_{2,y}\) |
|
spin of object 2 along the axis \(y\) |
– |
\([-1,\,1]\) |
\(\chi_{1,z}\) |
|
spin of object 1 along the axis \(z\) |
– |
\([-1,\,1]\) |
\(\chi_{2,z}\) |
|
spin of object 2 along the axis \(z\) |
– |
\([-1,\,1]\) |
\(\chi_s\) |
|
symmetric spin component |
– |
\([-1,\,1]\) |
\(\chi_a\) |
|
asymmetric spin component |
– |
\([-1,\,1]\) |
\(\chi_1\) |
|
spin magnitude of object 1 |
– |
\([0,\,1]\) |
\(\chi_2\) |
|
spin magnitude of object 2 |
– |
\([0,\,1]\) |
\(\theta_{s,1}\) |
|
spin tilt of object 1 |
\(\rm rad\) |
\([0,\,\pi]\) |
\(\theta_{s,2}\) |
|
spin tilt of object 2 |
\(\rm rad\) |
\([0,\,\pi]\) |
\(\phi_{JL}\) |
|
azimuthal angle of orbital angular momentum relative to total angular momentum |
\(\rm rad\) |
\([0,\,2\pi]\) |
\(\phi_{1,2}\) |
|
difference in azimuthal angle between spin vectors |
\(\rm rad\) |
\([0,\,2\pi]\) |
\(\Lambda_1\) |
|
adimensional tidal deformability of object 1 |
– |
\([0,\,+\infty)\) |
\(\Lambda_2\) |
|
adimensional tidal deformability of object 2 |
– |
\([0,\,+\infty)\) |
\(\tilde{\Lambda}\) |
|
adimensional tidal deformability of combination \(\tilde{\Lambda}\) |
– |
\([0,\,+\infty)\) |
\(\delta\tilde{\Lambda}\) |
|
adimensional tidal deformability of combination \(\delta\tilde{\Lambda}\) |
– |
\((-\infty,\,+\infty)\) |
\(e_0\) |
|
orbital eccentricity at reference frequency \(f_{e_{0}}\) |
– |
\([0,\,1)\) |
Warning
The spin components are defined on a sphere, i.e. they have to satisfy \(\chi_{1,x}^2 + \chi_{1,y}^2 + \chi_{1,z}^2\leq 1\) and \(\chi_{2,x}^2 + \chi_{2,y}^2 + \chi_{2,z}^2\leq 1\).
Note
The symmetric and asymmetric spin components are defined as
Note
The adimensional tidal deformability combinations \(\tilde{\Lambda}\) and \(\delta\tilde{\Lambda}\) are defined as (see arXiv:1402.5156).
Save and load data¶
To store a dictionary containing data in h5 format, it is possible to use the function
- gwfast.gwfastUtils.save_data(fname, data)[source]¶
Store a dictionary containing the events parameters in
h5file.
Note
See https://www.h5py.org for details on the h5 binary format.
The gwfast.gwfastUtils.load_population function can instead be used to load a dictionary with the parameters, in h5 format
- gwfast.gwfastUtils.load_population(name, nEventsUse=None, calculate_params=[], keys_skip=[])[source]¶
Load a dictionary containing the events parameters in h5 file, compute some useful cobinations and perform checks.
- Parameters
name (str) – The name of the file to load the events from. This has to include the path and the
h5orhdf5extension.nEventsUse (int or None) – Number of the events in the given file to load.
calculate_params (list(str)) – Parameters not present in the file to compute. The supported parameters are
'LambdaTilde','deltaLambda','Lambda1','Lambda2','theta','phi','ra','dec'.keys_skip (list(str)) – Parameters present in the file to skip.
- Returns
Dictionary conatining the loaded events, as in
events.- Return type
dict(array, array, …)
To select a subsample of events from a catalog it is possible to use the functions
Convert between parameters¶
gwfast provides some useful functions to convert between different parameters. All of them are vectorised, and can thus be used on arrays containing the parameters of multiple events.
Sky position angles¶
Conversions between the sky position angles \((\theta,\, \phi)\) and \((\alpha,\, \delta)\)
- gwfast.gwfastUtils.ra_dec_from_th_phi_rad(theta, phi)[source]¶
Compute \(\alpha\) and \(\delta\) in \(\rm rad\) from \(\theta\) and \(\phi\) in \(\rm rad\).
- gwfast.gwfastUtils.th_phi_from_ra_dec_rad(ra, dec)[source]¶
Compute \(\theta\) and \(\phi\) in \(\rm rad\) from \(\alpha\) and \(\delta\) in \(\rm rad\).
- Parameters
- Returns
\(\theta\) and \(\phi\) in \(\rm rad\).
- Return type
- gwfast.gwfastUtils.ra_dec_from_th_phi(theta, phi)[source]¶
Compute \(\alpha\) and \(\delta\) in \(\rm deg\) from \(\theta\) and \(\phi\) in \(\rm rad\).
- gwfast.gwfastUtils.th_phi_from_ra_dec(ra, dec)[source]¶
Compute \(\theta\) and \(\phi\) in \(\rm rad\) from \(\alpha\) and \(\delta\) in \(\rm deg\).
- Parameters
- Returns
\(\theta\) and \(\phi\) in \(\rm rad\).
- Return type
- gwfast.gwfastUtils.theta_to_dec_degminsec(theta)[source]¶
Compute \(\delta\) in degree, minutes, seconds from \(\theta\).
Tidal deformability parameters¶
Conversions between the individual tidal deformabilities of the two objects \(\Lambda_1\) and \(\Lambda_2\) and the combinations \(\tilde{\Lambda}\) and \(\delta\tilde{\Lambda}\) (see the previous note).
- gwfast.gwfastUtils.Lamt_delLam_from_Lam12(Lambda1, Lambda2, eta)[source]¶
Compute the dimensionless tidal deformability combinations \(\tilde{\Lambda}\) and \(\delta\tilde{\Lambda}\), defined in arXiv:1402.5156 eq. (5) and (6), as a function of the dimensionless tidal deformabilities of the two objects and the symmetric mass ratio.
- Parameters
- Returns
\(\tilde{\Lambda}\) and \(\delta\tilde{\Lambda}\).
- Return type
- gwfast.gwfastUtils.Lam12_from_Lamt_delLam(Lamt, delLam, eta)[source]¶
Compute the dimensionless tidal deformabilities of the two objects as a function of the dimensionless tidal deformability combinations \(\tilde{\Lambda}\) and \(\delta\tilde{\Lambda}\), defined in arXiv:1402.5156 eq. (5) and (6), and the symmetric mass ratio.
- Parameters
- Returns
\(\Lambda_1\) and \(\Lambda_2\).
- Return type
Masses¶
Conversions between the component masses and the chirp mass and symmetric mass ratio.
- gwfast.gwfastUtils.m1m2_from_Mceta(Mc, eta)[source]¶
Compute the component masses of a binary given its chirp mass and symmetric mass ratio.
Precessing spins¶
Conversions between the components of the spins in cartesian frame given and the angular variables (see the parameters table).
- gwfast.gwfastUtils.TransformPrecessing_angles2comp(thetaJN, phiJL, theta1, theta2, phi12, chi1, chi2, Mc, eta, fRef, phiRef)[source]¶
Compute the components of the spin in cartesian frame given the angular variables. Adapted from
LALSimInspiral.c, functionXLALSimInspiralTransformPrecessingNewInitialConditions, line 5885. For a scheme of the conventions, see https://lscsoft.docs.ligo.org/lalsuite/lalsimulation/group__lalsimulation__inference.html.- Parameters
thetaJN (array or float) – Inclination between total angular momentum (\(J\)) and the direction of propagation, \(\theta_{JN}\) (so that \(\theta_{JN} \to \iota\) for \(\chi_1 + \chi_2 \to 0\)).
phiJL (array or float) – Azimuthal angle of the Newtonian orbital angular momentum \(L_N\) on its cone about the total angular momentum \(J\), \(\phi_{JL}\).
theta1 (array or float) – Inclination (tilt angle) of object 1 measured from the Newtonian orbital angular momentum (\(L_N\)), \(\theta_{s,1}\).
theta2 (array or float) – Inclination (tilt angle) of object 2 measured from the Newtonian orbital angular momentum (\(L_N\)), \(\theta_{s,2}\).
phi12 (array or float) – Difference in azimuthal angles between the two spins, \(\phi_{1,2}\).
chi1 (array or float) – Dimensionless spin magnitude of object 1, \(\chi_1\).
chi2 (array or float) – Dimensionless spin magnitude of object 2, \(\chi_2\).
Mc (array or float) – Chirp mass of the binary, \({\cal M}_c\), in units of \(\rm M_{\odot}\).
eta (array or float) – The symmetric mass ratio(s), \(\eta\), of the objects.
fRef (array or float) – Reference frequency, in \(\rm Hz\).
phiRef (array or float) – Reference phase, in \(\rm rad\).
- Returns
\(\iota\), \(\chi_{1,x}\), \(\chi_{1,y}\), \(\chi_{1,z}\), \(\chi_{2,x}\), \(\chi_{2,y}\), \(\chi_{2,z}\).
- Return type
tuple(array, array, array, array, array, array, array) or tuple(float, float, float, float, float, float, float)
- gwfast.gwfastUtils.TransformPrecessing_comp2angles(iota, S1x, S1y, S1z, S2x, S2y, S2z, Mc, eta, fRef, phiRef)[source]¶
Compute the angular variables of the spins given the components in cartesian frame Adapted from
LALSimInspiral.c, functionXLALSimInspiralTransformPrecessingWvf2PE, line 6105. For a scheme of the conventions, see https://lscsoft.docs.ligo.org/lalsuite/lalsimulation/group__lalsimulation__inference.html.- Parameters
iota (array or float) – Inclination between the orbital angular momentum and the direction of propagation.
S1x (array or float) – spin of object 1 along the axis \(x\), \(\chi_{1,x}\).
S1y (array or float) – spin of object 1 along the axis \(y\), \(\chi_{1,y}\).
S1z (array or float) – spin of object 1 along the axis \(z\), \(\chi_{1,z}\).
S2x (array or float) – spin of object 2 along the axis \(x\), \(\chi_{2,x}\).
S2y (array or float) – spin of object 2 along the axis \(y\), \(\chi_{2,y}\).
S2z (array or float) – spin of object 2 along the axis \(z\), \(\chi_{2,z}\).
Mc (array or float) – Chirp mass of the binary, \({\cal M}_c\), in units of \(\rm M_{\odot}\).
eta (array or float) – The symmetric mass ratio(s), \(\eta\), of the objects.
fRef (array or float) – Reference frequency, in \(\rm Hz\).
phiRef (array or float) – Reference phase, in \(\rm rad\).
- Returns
\(\theta_{JN}\), \(\phi_{JL}\), \(\theta_{s,1}\), \(\theta_{s,2}\), \(\phi_{1,2}\), \(\chi_1\), \(\chi_2\).
- Return type
tuple(array, array, array, array, array, array, array) or tuple(float, float, float, float, float, float, float)
Time¶
Conversion between the GPS time and the Local Mean Sidereal Time (LMST).
- gwfast.gwfastUtils.GPSt_to_LMST(t_GPS, lat, long)[source]¶
Compute the Local Mean Sidereal Time (LMST) in units of fraction of day, from GPS time and location (given as latitude and longitude in degrees)
Note
The Greenwich Mean Sidereal Time (GMST) is the LMST computed at longitude = 0°. To obtain this quantity it is then sufficient to use
>>> gwfast.gwfastUtils.GPSt_to_LMST(t_GPS, lat=0., long=0.)
Note
It is possible to associate a GMST to each GPS time, but to each GMST an infinite number of GPS times is associated for periodicity, thus the inverse function is not provided.
Note
New in version 1.1.2.
To avoid errors that can arise from the astropy implementation when using times in the far future (having no IERS data), we provide an approximate function to compute the GMST.