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 electromagnetic-wave data at different radii as: computed from the Phi2 Weyl scalar.

This is dictionary-like objects with keys the extraction radii and values the corresponding ElectromagneticWavesOneDet.

Constructor.

derived_type_one_det is the type that the values of this dictionary-like 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: MultipoleAllDets

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 Newman-Penrose 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 as TimeSeries.

Variables

l_min – l smaller than l_min are dropped.

copy()¶

Return a deep copy.

Returns: Deep copy of self.
Return type: MultipoleOneDet

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 call function 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 from total_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 gravitational-wave data at different radii as: computed from the Psi4 Weyl scalar.

This is dictionary-like objects with keys the extraction radii and values the corresponding GravitationalWavesOneDet.

Constructor.

derived_type_one_det is the type that the values of this dictionary-like 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: MultipoleAllDets

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 fixed-frequency 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 as TimeSeries.

copy()¶

Return a deep copy.

Returns: Deep copy of self.
Return type: MultipoleOneDet

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 fixed-frequency 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 fixed-frequency 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 fixed-frequency 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 fixed-frequency 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 and phi_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 z-axis.
pcut (float) – Period that enters the fixed-frequency 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 fixed-frequency 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 fixed-frequency 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

TimeSeries

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. If window_function is None, no tapering is performed. If window_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) If window_function is a string, use the method with corresponding name from the TimeSeries 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 fixed-frequency 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 fixed-frequency 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

TimeSeries

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 fixed-frequency 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 fixed-frequency 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 fixed-frequency 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 fixed-frequency 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 fixed-frequency 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 fixed-frequency 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 call function 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 from total_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 gravitational-wave data at different radii.

It is based on MultipoleAllDets with the difference that takes as input SimDir. Objects inside MultipoleAllDets are redefined as GravitationalWavesDet.

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 dictionary-like 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: MultipoleAllDets

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

Reference on kuibit.cactus_waves¶

Previous topic

Next topic

Versions