mayawaves.coalescence module

class mayawaves.coalescence.Coalescence(h5_filepath: str)

Fundamental class for interacting with all data about a simulation of a compact object coalescence.

property average_run_speed: float

Average speed of the simulation in M/hr.

property catalog_id: str

The id of the simulation if it exists within a catalog.

property center_of_mass: tuple

Center of mass of the primary and secondary compact object. Computed with the coordinate positions and horizon mass.

close()

Close the Coalescence object by closing its associated h5 file.

compact_object_by_id(id: int) → CompactObject

Compact object associated with a given object id.

Parameters:

id (int) – ID for the desired object

Returns:

Compact object associated with the provided id

Return type:

CompactObject

compact_object_data_for_object(object_num) → ndarray

Function to be used internally to return all the data for a given compact object.

compact_object_metadata_dict() → dict

Function to be used internally to retrieve the metadata relating to the compact objects.

property compact_objects: list

List of all initial and final compact objects.

dEnergy_dt_radiated(lmin: int | None = None, lmax: int | None = None, l: int | None = None, m: int | None = None, extraction_radius: float | None = None) → tuple

Rate at which energy is radiated in gravitational waves

Computed using the method described in https://arxiv.org/abs/0707.4654. If no lmin, lmax, l, or m are provided, it computes the total sum of all modes.

Parameters:

• lmin (int, optional) – minumum value of l range

• lmax (int, optional) – maximum value of l range

• l (int, optional) – specific l value

• m (int, optional) – specific m value

• extraction_radius (float, optional) – radius for gravitational wave extraction. If not provided, extrapolates to infinite radius.

Returns:

time np.array: dE/dt

Return type:

np.array

dP_dt_radiated(lmin: int | None = None, lmax: int | None = None, l: int | None = None, m: int | None = None, extraction_radius: float | None = None) → tuple

Derivative of linear momentum radiated.

The rate of linear momentum being radiated through gravitational waves, computed using the method described in https://arxiv.org/abs/0707.4654. If no lmin, lmax, l, or m are provided, it computes the total sum of all modes.

Parameters:

• lmin (int, optional) – minumum value of l range

• lmax (int, optional) – maximum value of l range

• l (int, optional) – specific l value

• m (int, optional) – specific m value

• extraction_radius (float, optional) – radius for gravitational wave extraction. If not provided, extrapolates to infinite radius.

Returns:

time np.ndarray: dP/dt

Return type:

np.ndarray

eccentricity_and_mean_anomaly_at_time(start_time, desired_time) → tuple

Eccentricity and mean anomaly at desired time.

Compute the eccentricity and the mean anomaly using the orbital frequency as described in https://arxiv.org/abs/1810.00036. Computes the eccentricity averaged over four orbits. If it is unable to fit four orbits of data successfully, it returns an estimate of the eccentricity based on the initial momentum. Mean anomaly is defined as :math:`2 pi *

rac{t - T_{prev}}{T_{next} - T_{prev}}` where :math:`T_{next}’ and :math:`T_{prev}’ are

periapsis times.

Args:

start_time (float): time from which to begin fitting eccentricity desired_time (float): time at which to return the eccentricity

Returns:

tuple: averaged eccentricity over first four orbits and the mean anomaly at the desired time

energy_radiated(lmin: int | None = None, lmax: int | None = None, l: int | None = None, m: int | None = None, extraction_radius: float | None = None) → tuple

Cummulative nergy radiated in gravitational waves.

Returns the cumulative energy radiated computed using the method described in https://arxiv.org/abs/0707.4654. If no lmin, lmax, l, or m are provided, it computes the total sum of all modes.

Parameters:

• lmin (int, optional) – minumum value of l range

• lmax (int, optional) – maximum value of l range

• l (int, optional) – specific l value

• m (int, optional) – specific m value

• extraction_radius (float, optional) – radius for gravitational wave extraction. If not provided, extrapolates to infinite radius.

Returns:

time np.array: cumulative energy radiated for a given l range and extraction radius

Return type:

np.array

extrapolate_psi4_to_infinite_radius(order: int = 1, extraction_radius: float | None = None)

Calculate \(\Psi_4\) at infinite radius by extrapolation.

Extrapolates from a finite radius to obtain \(\Psi_4\) at infinite radius using the method described in https://arxiv.org/abs/1008.4360 and https://arxiv.org/abs/1108.4421.

Parameters:

• order (int, optional) – order of extraction. Defaults to 1.

• extraction_radius – radius to extrapolate from

property final_compact_object: CompactObject

A reference to the final compact object. This is the remnant that is formed after the merger.

property h5_filepath: str

The path to the h5 file containing the coalescence data.

property included_extraction_radii: list

List of all extraction radii included.

property included_modes: list

\(\Psi_4\) is decomposed into spherical harmonics labeled by (l, m). This provides a list of all (l, m) modes included.

property initial_orbital_frequency: float

Inital orbital frequency of the coalescence. Computed from the separation vector between the primary and secondary compact objects.

property initial_separation: float

Initial separation of the coalesence. Computed as the coordinate separation between the centers of the primary and secondary compact objects.

property l_max: int

Maximum l mode included.

linear_momentum_radiated(lmin: int | None = None, lmax: int | None = None, l: int | None = None, m: int | None = None, extraction_radius: float | None = None) → tuple

Cummulative inear momentum radiated.

Cummulative linear momentum radiated through gravitational waves, computed using the method described in https://arxiv.org/abs/0707.4654. If no lmin, lmax, l, or m are provided, it computes the total sum of all modes.

Parameters:

• lmin (int, optional) – minumum value of l range

• lmax (int, optional) – maximum value of l range

• l (int, optional) – specific l value

• m (int, optional) – specific m value

• extraction_radius (float, optional) – radius for gravitational wave extraction. If not provided, extrapolates to infinite radius.

Returns:

time np.ndarray: cummulative linear momentum radiated

Return type:

np.ndarray

property mass_ratio: float

Mass ratio of the coalescence. Always greater than 1. Defined as the horizon mass of the larger compact object divided by the horizon mass of the smaller compact object. \(q = m_1/m_2 > 1\)

property merge_time: float

Time at which the coordinate separation goes below 1e-2

property name: str

The name of the coalescence. This is what the simulation was named when it was performed.

property object_numbers: list

List of all object ids included.

property orbital_angular_momentum_unit_vector: tuple

Time and orbital angular momentum unit vector over time.

Unit vector for the orbital angular momentum computed from the coordinate positions of the primary and secondary compact objects.

orbital_angular_momentum_unit_vector_at_time(desired_time: float) → ndarray

Orbital angular momentum unit vector at desired time.

Unit vector for the orbital angular momentum computed from the coordinate positions of the primary and secondary compact objects.

Parameters:

desired_time (float) – time at which to return the orbital separation

Returns:

unit vector of the orbital angular momentum at the desired time

Return type:

numpy.ndarray

property orbital_frequency: tuple

Time and orbital frequency over time.

Compute and return the orbital frequency as a function of time, calculated from the coordinate separation between the primary and secondary compact objects.

orbital_frequency_at_time(desired_time: float) → float

Orbital frequency at given time.

Compute and return the orbital frequency at the desired time, calculated from the coordinate separation between the primary and secondary compact objects.

Parameters:

desired_time (float) – time at which to return the orbital separation

Returns:

orbital frequency at the desired time

Return type:

float

property orbital_phase_in_xy_plane: tuple

Time and orbital phase over time in the xy plane computed from the coordinate positions.

property parameter_files: dict

Dictionary containing the text of the parameter files (.rpar and .par) used to create the simulation

The keys are “par” and “rpar”

property primary_compact_object: CompactObject

A reference to the primary compact object. This is the larger of the two initial compact objects.

psi4_amp_phase_for_mode(l: int, m: int, extraction_radius: float = 0) → tuple

Amplitude and phase of \(\Psi_4\) for a given mode.

Returns the time and the amplitude and phase of \(\Psi_4\) for a given mode and extraction radius.

Parameters:

• l (int) – l value of mode

• m (int) – m value of mode

• extraction_radius (float, optional) – radius for gravitational wave extraction. If not provided, extrapolates to infinite radius.

Returns:

time, amplitude, and phase of \(\Psi_4\) for a given mode and extraction radius

Return type:

tuple

psi4_max_time_for_mode(l: int, m: int, extraction_radius: float = 0) → float

Time of maximum \(\Psi_4\) amplitude for a given mode.

The time at which the amplitude of \(\Psi_4\) reaches its peak.

Parameters:

• l (int) – specific l value at which to compute and sum

• m (int) – specific m value to specify a single mode

• extraction_radius (float, optional) – radius for gravitational wave extraction. If not provided, extrapolates to infinite radius.

Returns:

time of \(\Psi_4\) max for given mode and extraction radius

Return type:

float

psi4_real_imag_for_mode(l: int, m: int, extraction_radius: float = 0) → tuple

Real and imaginary components of \(\Psi_4\) for a given mode.

Returns the time and real and imaginary parts of \(\Psi_4\) for a given mode and extraction radius.

Parameters:

• l (int) – l value of mode

• m (int) – m value of mode

• extraction_radius (float, optional) – radius for gravitational wave extraction. If not provided, extrapolates to infinite radius.

Returns:

time, \(\Psi_4\) real component, and \(\Psi_4\) imaginary component for a given mode and extraction radius

Return type:

tuple

property psi4_source: str

Source of the \(\Psi_4\) data. Could by ascii or h5 forms of WeylScal or Multipole.

property radiation_frame: str

The current frame of the radiation data

property radiationbundle: RadiationBundle

A reference to the RadiationBundle object.

property radius_for_extrapolation

Radius to use when extrapolating data to infinite radius.

recoil_speed(km_per_sec: bool = False) → float

Magnitude of the recoil of the final object.

Computed from the momentum radiated in gravitational waves.

Parameters:

km_per_sec (bool, optional) – whether to report the speed in km/s. Defaults to reporting as a fraction of c.

Returns:

the speed of the recoil

Return type:

float

recoil_velocity(km_per_sec: bool = False) → ndarray

Kick vector of the final object

Computed from the momentum radiated in gravitational waves.

Parameters:

km_per_sec (bool, optional) – whether to report the velocity in km/s. Defaults to reporting as a fraction of c.

Returns:

the recoil velocity

Return type:

np.ndarray

property runstats_data: ndarray

All runstats data stored as a pandas dataset.

property secondary_compact_object: CompactObject

A reference to the secondary compact object. This is the smaller of the two initial compact objects.

separation_at_time(desired_time: float) → float

Separation at a given time.

Computes and returns the coordinate separation between the primary and secondary compact object centers at the desired time. Points from the primary object to the secondary object.

Parameters:

desired_time (float) – time at which to return the separation

Returns:

separation at the desired time

Return type:

float

separation_unit_vector_at_time(desired_time: float) → ndarray

Separation unit vector at desired time.

Unit vector for the separation computed from the coordinate positions of the primary and secondary compact objects. Points from the primary object to the secondary object.

Parameters:

desired_time (float) – time at which to return the separation unit vector

Returns:

unit vector of the separation at the desired time

Return type:

numpy.ndarray

property separation_vector: tuple

Coordinate separation vector between the primary and secondary compact objects. Returns the time and the separation vector in a tuple. Points from the primary object to the secondary object.

set_radiation_frame(center_of_mass_corrected: bool = False)

Set the frame for the radiation mode decomposition.

Options are center of mass drift corrected or the original, raw frame

Parameters:

center_of_mass_corrected (bool, optional) – Whether to correct for center of mass drift. Default False. If false, the frame is set back to the original, raw frame.

property spin_configuration: str

Spin configuration. Can be non-spinning, aligned-spins, or precessing. Non-spinning means neither black hole has a spin. Aligned-spins means the spin of each black hole is either aligned or anti-aligned with the orbital angular momentum. Precessing means at least one compact object has a spin not aligned or anti-aligned with the orbital angular momentum.

strain_amp_phase_for_mode(l: int, m: int, extraction_radius: float = 0) → tuple

Amplitude and phase of strain for a given mode.

Returns the time and amplitude and phase of the strain for a given mode and extraction radius. The strain is the second time integral of \(\Psi_4\) computed using fixed-frequency integration.

Parameters:

• l (int) – l value of mode

• m (int) – m value of mode

• extraction_radius (float, optional) – radius for gravitational wave extraction. If not provided, extrapolates to infinite radius.

Returns:

time, \(rh_+\), and \(rh_{\times}\) for a given mode and extraction radius

Return type:

tuple

strain_for_mode(l: int, m: int, extraction_radius: float = 0) → tuple

Real and imaginary components of strain for a given mode.

Returns the time and the plus and cross components of \(rh\) for a given mode and extraction radius, where r is the extraction radiys. The strain is the second time integral of \(\Psi_4\) computed using fixed-frequency integration.

Parameters:

• l (int) – l value of mode

• m (int) – m value of mode

• extraction_radius (float, optional) – radius for gravitational wave extraction. If not provided, extrapolates to infinite radius.

Returns:

time, \(rh_+\), and \(rh_{\times}\) for a given mode and extraction radius

Return type:

tuple

strain_recomposed_at_sky_location(theta: float, phi: float, extraction_radius: float = 0) → tuple

Time, plus, and cross components of strain recomposed at a given sky location

The strain is recomposed by summing up the modes using spin weighted spherical harmonics as \(h(t,\theta,\phi) = \sum_{\ell,m} {}_{-2}Y_{\ell,m}(\theta, \phi) h_{ \ell,m}(t)\)

Parameters:

• theta (float) – \(0 \leq \theta \lt \pi\)

• phi (float) – \(0 \leq \phi \lt 2\pi\)

• extraction_radius (float, optional) – radius for gravitational wave extraction. If not provided, extrapolates to infinite radius.

Returns:

time, \(rh_+\), and \(rh_{\times}\) recomposed at a given sky location and extraction radius

Return type:

tuple

property symmetric_mass_ratio: float

Symmetric mass ratio of the coalescence. Computed using the horizon masses as \(\eta = m_1 m_2/(m_1+m_2)^2\)