Reference on kuibit.cactus_waves¶
The cactus_waves
module provides classes to access gravitational
and electromagnetic wave signals computed using Weyl scalars.
The classes in this module specialize the ones in cactus_multipoles
to deal with gravitational and electromagnetic wave data.
There classes defined in this module are:
:py:class`~.GravitationalWavesOneDet` and :py:class`~.ElectromagneticWavesOneDet`, which extend
MultipoleOneDet
adding methods to compute quantities like strain, or energy lost.:py:class`~.WavesDir` (derived from :py:class`~.MultipoleAllDets`), from which we derive :py:class`~.GravitationalWavesDir` and :py:class`~.ElectromagneticWavesDir`, which organize the available data in terms of extraction radii.

class
kuibit.cactus_waves.
ElectromagneticWavesDir
(sd)[source]¶  This class provides access electromagneticwave data at different radii as
computed from the Phi2 Weyl scalar.
This is dictionarylike objects with keys the extraction radii and values the corresponding
ElectromagneticWavesOneDet
.Constructor.
derived_type_one_det
is the type that the values of this dictionarylike object has to have. Parameters
sd (
SimDir
) – Simulation directory.l_min (int) – Minimum value of
l
to consider.var (str (Psi4 or Phi2)) – Name of the variable that has be consider
derived_type_one_det (class) – Class of the derived object that has to be initialized.

copy
()¶ Return a deep copy.
 Returns
Deep copy of
self
. Return type

has_detector
(mult_l, mult_m, dist)¶ Check if a given multipole component extracted at a given distance is available.
 Parameters
mult_l (int) – Multipole component l.
mult_m (int) – Multipole component m.
dist (float) – Distance of the detector.
 Returns
If available or not.
 Return type
bool

keys
()¶ Return available extraction radii.
 Returns
Available extraction radii.
 Return type
dict_keys

class
kuibit.cactus_waves.
ElectromagneticWavesOneDet
(dist, data)[source]¶ Electromagnetic waves computed with the NewmanPenrose approach, using Phi2.
(These are useful when studying charged black holes, for instance)
Constructor.
 Parameters
dist (float) – Radius of the spherical surface.
data (list of tuple
(l, m, timeseries)
) – List of tuples with the two multipolar numbers and the data asTimeSeries
.
 Variables
l_min – l smaller than
l_min
are dropped.

copy
()¶ Return a deep copy.
 Returns
Deep copy of
self
. Return type

get_energy_lm
(mult_l, mult_m)[source]¶ Return the cumulative energy lost in the mode (l, m).
 Parameters
mult_l – l multipole moment.
mult_m (int) – m multipole moment.
 Returns
Energy lost up to the time t in the mode
(l, m)
as a function of time. Return type
TimeSeries

get_power_lm
(mult_l, mult_m)[source]¶ Return the instantaneous power in the mode (l, m).
This is computed with Eq. 2.23 in 1311.6483
 Parameters
mult_l – l multipole moment.
mult_m (int) – m multipole moment.
 Returns
Instantaneous power in the mode
(l, m)
as a function of time. Return type
TimeSeries

get_total_energy
(l_max=None)[source]¶ Return the cumulative energy lost in all the modes up to l_max.
 Parameters
l_max (int) – Ignore multipoles with l > l_max
 Returns
Cumulative total energy lost up to time in the modes up to
l_max
as a function of time. Return type
TimeSeries

get_total_power
(l_max=None)[source]¶ Return the total power in all the modes up to
l_max
. Parameters
l_max (int) – Ignore multipoles with l > l_max
 Returns
Instantaneous total power in the modes up to
l_max
as a function of time. Return type
TimeSeries

keys
()¶ Return available multipolar numbers.
 Returns
Available multipolar numbers.
 Return type
dict_keys

total_function_on_available_lm
(function, *args, l_max=None, **kwargs)¶ Evaluate
function
on each multipole and accumulate the result.total_function_on_available_lm
will callfunction
with the following arguments:function(timeseries, mult_l, mult_m, dist, *args, **kwargs)
If
function
does not need some paramters, it should use take the*args
argument to ignore the additional paramters that are always passed(l, m, r)
.Values of l larger than
l_max
are ignored.This method is used to compute quantities like the total power in gravitational waves.
function
can take additional paramters passed directly fromtotal_function_on_available_lm
(e.g.pcut
for FFI). Params function
Function that has to be applied on each multipole.
 Returns
Sum of function applied to each monopole
 Return type
return type of function

class
kuibit.cactus_waves.
GravitationalWavesDir
(sd)[source]¶  This class provides access gravitationalwave data at different radii as
computed from the Psi4 Weyl scalar.
This is dictionarylike objects with keys the extraction radii and values the corresponding
GravitationalWavesOneDet
.Constructor.
derived_type_one_det
is the type that the values of this dictionarylike object has to have. Parameters
sd (
SimDir
) – Simulation directory.l_min (int) – Minimum value of
l
to consider.var (str (Psi4 or Phi2)) – Name of the variable that has be consider
derived_type_one_det (class) – Class of the derived object that has to be initialized.

copy
()¶ Return a deep copy.
 Returns
Deep copy of
self
. Return type

extrapolate_strain_lm_to_infinity
(mult_l, mult_m, pcut, detectors_distances, retarded_times, *args, window_function=None, trim_ends=False, mass=1, order=2, extrapolate_amplitude_phase=False, **kwargs)[source]¶ Extrapolate strains to spatial infinity with the method described in 1307.5307.
If
extrapolate_amplitude_phase
is True, extrapolate amplitude and phase of the complex strain instead of real and imaginary parts.TODO: Test this function!
[Equation (29)]
 Parameters
mult_l (int) – Multipolar component l.
mult_m (int) – Multipolar component m.
pcut (float) – Period that enters the fixedfrequency integration. Typically, the longest physical period in the signal.
retarded_times (float or 1D NumPy array) – Times at which the waves have to be evaluated
detectors_distances (1D NumPy array) – Extraction radii
mass (float) – ADM mass of the system
order (int) – Order of the extrapolation.
window_function (callable, str, or None) – If not None, apply window_function to the series before computing the strain.
trim_ends (bool) – If True, a portion of the resulting strain is removed at both the initial and final times. The amount removed is equal to pcut.
extrapolate_amplitude_phase (int) – If True, extrapolate phase and amplitude, if False, extrapolate real and imaginary parts.
 Returns
Waves evaluated at the retarded times.
 Return type
List of
TimeSeries

has_detector
(mult_l, mult_m, dist)¶ Check if a given multipole component extracted at a given distance is available.
 Parameters
mult_l (int) – Multipole component l.
mult_m (int) – Multipole component m.
dist (float) – Distance of the detector.
 Returns
If available or not.
 Return type
bool

keys
()¶ Return available extraction radii.
 Returns
Available extraction radii.
 Return type
dict_keys

class
kuibit.cactus_waves.
GravitationalWavesOneDet
(dist, data)[source]¶ This class represents is an abstract class to represent multipole signals from Weyl scalars available at a given distance.
To check if component is available, use the operator “in”. You can iterate over all the availble components with a for loop.
This class is derived from
MultipoleOneDet
, so it shares most of the features, while expanding with methods specific for gravitational waves (e.g, to compute the strain).This class is not intended to be initialized directly.
Constructor.
 Parameters
dist (float) – Radius of the spherical surface.
data (list of tuple
(l, m, timeseries)
) – List of tuples with the two multipolar numbers and the data asTimeSeries
.

copy
()¶ Return a deep copy.
 Returns
Deep copy of
self
. Return type

get_angular_momentum_z_lm
(mult_l, mult_m, pcut)[source]¶ Return the cumulative angular momentum lost in the mode (l, m).
 Parameters
mult_l – l multipole moment.
mult_m (int) – l multipole moment.
pcut (float) – Period that enters the fixedfrequency integration. Typically, the longest physical period in the signal.
 Returns
Cumulative angular momentum in the z direction in the mode (l, m) as a function of time.
 Return type
TimeSeries

get_energy_lm
(mult_l, mult_m, pcut)[source]¶ Return the cumulative energy lost in the mode (l, m).
 Parameters
mult_l – l multipole moment.
mult_m (int) – m multipole moment.
pcut (float) – Period that enters the fixedfrequency integration. Typically, the longest physical period in the signal.
 Returns
Energy lost up to the time t in the mode
(l, m)
as a function of time. Return type
TimeSeries

get_force_z_lm
(mult_l, mult_m, pcut)[source]¶ Return the instantaneous linear momentum along the z direction lost in the mode (l, m).
This is computed with Eq. (3.15) in Ruiz 2008 (0707.4654).
 Parameters
mult_l – l multipole moment.
mult_m (int) – m multipole moment.
pcut (float) – Period that enters the fixedfrequency integration. Typically, the longest physical period in the signal.
 Returns
Instantaneous force along the z axis in the mode
(l, m)
as a function of time. Return type
TimeSeries

get_linear_momentum_z_lm
(mult_l, mult_m, pcut)[source]¶ Return the cumulative linear momentum lost along the z direction in the mode (l, m).
 Parameters
mult_l – l multipole moment.
mult_m (int) – m multipole moment.
pcut (float) – Period that enters the fixedfrequency integration. Typically, the longest physical period in the signal.
 Returns
Linear momentum along the z direction lost up to the time t in the mode
(l, m)
as a function of time. Return type
TimeSeries

get_observed_strain
(right_ascension, declination, time_utc, theta_gw, phi_gw, pcut, *args, window_function=None, polarization=0, l_max=None, trim_ends=False, **kwargs)[source]¶ Return the strain accounting for all the multipoles and the spin weighted spherical harmonics as observed by Hanford, Livingston and Virgo.
\[h_+(r,t)  i h_\times(r,t) = \sum_{l=2}^{l=l_{\mathrm{max}}} \sum_{m=l}^{m=l} h(r, t)^{lm} {}_{2}Y_{lm}(\theta, \phi)\]Here theta and phi are the arguments
theta_gw
andphi_gw
.Then, for each detector
\[h(r,t) = F_\times h_\times(theta_gw, phi_gw) + F_+ h_+(theta_gw, phi_gw)\] 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
phi_gw (theta_gw,) – Spherical coordinates of the observer from the binary’s frame, taking the angular momentum of the binary to point along the zaxis.
pcut (float) – Period that enters the fixedfrequency integration. Typically, the longest physical period in the signal.
window_function (callable, str, or None) – If not None, apply
window_function
to the series before computing the strain.trim_ends (bool) – If True, a portion of the resulting strain is removed at both the initial and final times. The amount removed is equal to pcut.
l_max (int) – Ignore multipoles with l > l_max
 Returns
\(r (h^+  i h^\times)\)
 Return type
Detectors of
TimeSeries

get_power_lm
(mult_l, mult_m, pcut)[source]¶ Return the instantaneous power in the mode (l, m).
This is computed with Eq. (9.139) in Baumgarte Shapiro.
\[\]frac{dE}{dt}(r, t) = frac{r^2}{16 pi} sum_{l=2}^{l=l_{mathrm{max}}} sum_{m=l}^{m=l} psi^{lm}_4(theta, phi, r, t)
 Parameters
mult_l – l multipole moment.
mult_m (int) – m multipole moment.
pcut (float) – Period that enters the fixedfrequency integration. Typically, the longest physical period in the signal.
 Returns
Instantaneous power in the mode
(l, m)
as a function of time. Return type
TimeSeries

get_psi4_lm
(mult_l, mult_m)[source]¶ Return the multipolar components l and m of Psi4.
 Parameters
mult_l (int) – Multipole component l.
mult_m (int) – Multipole component m.
 Returns
\(\Psi_4^{lm}\)
 Return type
complex
TimeSeries

get_strain
(theta, phi, pcut, *args, window_function=None, l_max=None, trim_ends=False, **kwargs)[source]¶ Return the strain accounting for all the multipoles and the spin weighted spherical harmonics.
This is computed as:
\[h_+(r,t)  i h_\times(r,t) = \sum_{l=2}^{l=l_{\mathrm{max}}} \sum_{m=l}^{m=l} h(r, t)^{lm} {}_{2}Y_{lm}(\theta, \phi)\] Parameters
theta (float) – Meridional observation angle.
phi (float) – Azimuthal observation angle.
pcut (float) – Period that enters the fixedfrequency integration. Typically, the longest physical period in the signal.
window_function (callable, str, or None) – If not None, apply window_function to the series before computing the strain.
trim_ends (bool) – If True, a portion of the resulting strain is removed at both the initial and final times. The amount removed is equal to
pcut
.l_max (int) – Ignore multipoles with
l > l_max
 Returns
\(r (h^+  i h^\times)\)
 Return type

get_strain_lm
(mult_l, mult_m, pcut, *args, window_function=None, trim_ends=False, **kwargs)[source]¶ Return the strain associated to the multipolar component (l, m).
The strain returned is multiplied by the distance. The strain is extracted from the Weyl Scalar using the formula
\[h_+^{lm}(r,t)  i h_\times^{lm}(r,t) = \int_{\infty}^t \mathrm{d}u \int_{\infty}^u \mathrm{d}v\, \Psi_4^{lm}(r,v)\]The return value is the complex
TimeSeries
(r * h_plus  i r * h_cross)
.It is always important to have a function that goes smoothly to zero before taking Fourier transform (to avoid spectral leakage and aliasing). You can pass the
window_function
to apply as a parameter. Ifwindow_function
is None, no tapering is performed. Ifwindow_function
is a function, it has to be a function that takes as first argument the length of the array and returns a new array with the same length that is to be multiplied to the data (this is how SciPy’s windows work) Ifwindow_function
is a string, use the method with corresponding name from theTimeSeries
class. You must only provide the name (e.g, ‘tukey’ will call ‘tukey_windowed’). Optional arguments to the window function can be passed directly to this function.pcut
is the period associated to the angular velocity that enters in the fixed frequency integration (omega_th = 2 pi / pcut
). In general, a wise choise is to pick the longest physical period in the signal.For more information on the fixedfrequency integration method, see Reisswig 2011.
Optionally, remove part of the output signal at both the beginning and the end. If
trim_ends
is True,pcut
is removed. This is because those parts of the signal are typically not very accurate. Parameters
mult_l (int) – Multipolar component l.
mult_m (int) – Multipolar component m.
pcut (float) – Period that enters the fixedfrequency integration. Typically, the longest physical period in the signal.
window_function (callable, str, or None) – If not None, apply window_function to the series before computing the strain.
trim_ends (bool) – If True, a portion of the resulting strain is removed at both the initial and final times. The amount removed is equal to pcut.
 Returns
\(r (h^+  i h^\times)\)
 Return type

get_torque_z_lm
(mult_l, mult_m, pcut)[source]¶ Return the instantaneous torque in the z axis in the mode (l, m).
This is computed with Eq. (9.140) in Baumgarte Shapiro (or 9.137)
 Parameters
mult_l – l multipole moment.
mult_m (int) – m multipole moment.
 Returns
Instantaneous total torque in the z direction in the mode (l, m) as a function of time.
 Return type
TimeSeries

get_total_angular_momentum_z
(pcut, l_max=None)[source]¶ Return the cumulative angular momentum lost in all the modes up to
l_max
. Parameters
pcut (float) – Period that enters the fixedfrequency integration. Typically, the longest physical period in the signal.
l_max (int) – Ignore multipoles with l > l_max
 Returns
Cumulative angular momentum up to time in the modes up to
l_max
as a function of time. Return type
TimeSeries

get_total_energy
(pcut, l_max=None)[source]¶ Return the cumulative energy lost in all the modes up to
l_max
. Parameters
pcut (float) – Period that enters the fixedfrequency integration. Typically, the longest physical period in the signal.
l_max (int) – Ignore multipoles with l > l_max
 Returns
Cumulative total energy lost up to time in the modes up to
l_max
as a function of time. Return type
TimeSeries

get_total_force_z
(pcut, l_max=None)[source]¶ Return the total force along the z direction in all the modes up to
l_max
. Parameters
pcut (float) – Period that enters the fixedfrequency integration. Typically, the longest physical period in the signal.
l_max (int) – Ignore multipoles with l > l_max
 Returns
Instantaneous total force along the z direction in the modes up to
l_max
as a function of time. Return type
TimeSeries

get_total_linear_momentum_z
(pcut, l_max=None)[source]¶ Return the cumulative linear momentum lost in all the modes up to
l_max
. param pcut
Period that enters the fixedfrequency integration. Typically, the longest physical period in the signal.
 type pcut
float
 param l_max
Ignore multipoles with l > l_max
 type l_max
int
 Returns
 Cumulative total linear momentum along the z direction lost
up to time in the modes up to
l_max
as a function of time.
 rtype
TimeSeries

get_total_power
(pcut, l_max=None)[source]¶ Return the total power in all the modes up to
l_max
. Parameters
pcut (float) – Period that enters the fixedfrequency integration. Typically, the longest physical period in the signal.
l_max (int) – Ignore multipoles with l > l_max
 Returns
Instantaneous total power in the modes up to
l_max
as a function of time. Return type
TimeSeries

get_total_torque_z
(pcut, l_max=None)[source]¶ Return the total torque z in all the modes up to
l_max
. Parameters
pcut (float) – Period that enters the fixedfrequency integration. Typically, the longest physical period in the signal.
l_max (int) – Ignore multipoles with l > l_max
 Returns
Instantaneous total torque up to time in the modes up to
l_max
as a function of time. Return type
TimeSeries

keys
()¶ Return available multipolar numbers.
 Returns
Available multipolar numbers.
 Return type
dict_keys

total_function_on_available_lm
(function, *args, l_max=None, **kwargs)¶ Evaluate
function
on each multipole and accumulate the result.total_function_on_available_lm
will callfunction
with the following arguments:function(timeseries, mult_l, mult_m, dist, *args, **kwargs)
If
function
does not need some paramters, it should use take the*args
argument to ignore the additional paramters that are always passed(l, m, r)
.Values of l larger than
l_max
are ignored.This method is used to compute quantities like the total power in gravitational waves.
function
can take additional paramters passed directly fromtotal_function_on_available_lm
(e.g.pcut
for FFI). Params function
Function that has to be applied on each multipole.
 Returns
Sum of function applied to each monopole
 Return type
return type of function

class
kuibit.cactus_waves.
WavesDir
(sd, l_min, var, derived_type_one_det)[source]¶ This class provides acces gravitationalwave data at different radii.
It is based on
MultipoleAllDets
with the difference that takes as inputSimDir
. Objects insideMultipoleAllDets
are redefined asGravitationalWavesDet
. This class is an abstract class meant to be derived to describe gravitational waves
and electromagnetic waves.
Constructor.
derived_type_one_det
is the type that the values of this dictionarylike object has to have. Parameters
sd (
SimDir
) – Simulation directory.l_min (int) – Minimum value of
l
to consider.var (str (Psi4 or Phi2)) – Name of the variable that has be consider
derived_type_one_det (class) – Class of the derived object that has to be initialized.

copy
()¶ Return a deep copy.
 Returns
Deep copy of
self
. Return type

has_detector
(mult_l, mult_m, dist)¶ Check if a given multipole component extracted at a given distance is available.
 Parameters
mult_l (int) – Multipole component l.
mult_m (int) – Multipole component m.
dist (float) – Distance of the detector.
 Returns
If available or not.
 Return type
bool

keys
()¶ Return available extraction radii.
 Returns
Available extraction radii.
 Return type
dict_keys