mayawaves.utils package

mayawaves.utils.postprocessingutils module

mayawaves.utils.postprocessingutils.create_h5_from_simulation(raw_directory: str, output_directory: str, catalog_id: str | None = None) → str

Create a Mayawaves compatible h5 file storing all important information from the raw simulation.

Stitch and store the simulation data from the raw simulation into a h5 file which can then be read by the Coalescence class.

Parameters:

raw_directory (str) – directory of the raw simulation
output_directory (str) – directory to store the created h5 file
catalog_id (str, optional) – id for the simulation within a catalog

Returns:

path to the generated h5 file

Return type:

str

mayawaves.utils.postprocessingutils.determine_lvc_format(coalescence: Coalescence, initial_horizon_time: float) → int

Determine the LVC format number based upon the data available from the simulation and the definitions in https://arxiv.org/abs/1703.01076

Parameters:

coalescence (Coalescence) – the Coalescence object being exported
initial_horizon_time (float) – the time for initial data at the horizon

Returns:

the LVC format (1, 2, 3)

Return type:

int

mayawaves.utils.postprocessingutils.export_to_ascii(coalescence: Coalescence, output_directory: str, center_of_mass_correction: bool = False)

Export a Coalescence object to ascii format in the specified output directory.

Export all information contained in the Coalescence object to individual ascii files in the specified output directory.

Parameters:

coalescence (Coalescence) – the Coalescence object to be exported
output_directory (str) – the location to store the exported ascii data
center_of_mass_correction (bool, optional) – whether to correct for center of mass drift. Default False.

mayawaves.utils.postprocessingutils.export_to_lal_compatible_format(coalescence: Coalescence, output_directory, NR_group: str, NR_code: str, bibtex_keys: str, contact_email: str, extraction_radius: float = 0, name=None, license_type='LVC-internal', nr_techniques: str | None = None, comparable_simulation: str | None = None, files_in_error_series: str = '', production_run: bool = True, center_of_mass_correction: bool = False)

Exports the Coalescence object to a format compatible with LALSuite.

Exports the Coalescence object into the format required by https://arxiv.org/abs/1703.01076 in order to be readable by LALSuite and PyCBC. Less stringent requirements than the LVC-NR catalog.

Parameters:

coalescence (Coalescence) – the Coalescence object being exported
output_directory (str) – location to store the exported catalog file
NR_group (str) – NR group that performed this simulation
NR_code (str) – NR code that performed this simulation
bibtex_keys (str) – bibtex keys to use when citing this simulation
contact_email (str) – email to use if questions arise regarding this simulation
extraction_radius (float, optional) – radius at which to extract gravitational wave data
name (str, optional) – the tag to save the simulation as (e.g. MAYA0908)
license_type (str, optional) – whether it is public or LVC-internal
nr_techniques (str, optional) – what techniques were used in this simulation
comparable_simulation (str, optional) – other similar simulations
files_in_error_series (str, optional) – other simulations in the same error series
production_run (bool, optional) – whether this is a production run. Default True.
center_of_mass_correction (bool, optional) – whether to correct for center of mass drift. Default False.

mayawaves.utils.postprocessingutils.export_to_lvcnr_catalog(coalescence: Coalescence, output_directory: str, NR_group: str, NR_code: str, bibtex_keys: str, contact_email: str, name: str | None = None, license_type='LVC-internal', nr_techniques: str | None = None, comparable_simulation: str | None = None, files_in_error_series: str = '', production_run: bool = True, center_of_mass_correction: bool = False)

Exports the Coalescence object to the format required by LIGO to be included in the LVC-NR catalog.

Exports the Coalescence object into the format required by https://arxiv.org/abs/1703.01076 in order to be included in the LVC-NR catalog. Must have sufficient spin data and be able to compute eeccentricity. Will be extrapolated to infinite radius.

Parameters:

coalescence (Coalescence) – the Coalescence object being exported
output_directory (str) – location to store the exported catalog file
NR_group (str) – NR group that performed this simulation
NR_code (str) – NR code that performed this simulation
bibtex_keys (str) – bibtex keys to use when citing this simulation
contact_email (str) – email to use if questions arise regarding this simulation
name (str, optional) – the tag to save the simulation as (e.g. MAYA0908)
license_type (str, optional) – whether it is public or LVC-internal
nr_techniques (str, optional) – what techniques were used in this simulation
comparable_simulation (str, optional) – other similar simulations
files_in_error_series (str, optional) – other simulations in the same error series
production_run (bool, optional) – whether this is a production run. Default True.
center_of_mass_correction (bool, optional) – whether to correct for center of mass drift. Default False.

mayawaves.utils.postprocessingutils.get_stitched_data(raw_directory: str, filename: str) → ndarray

Stitch together the data for a given file.

Stitch the data from all outputs for a given file and return the full data as a numpy array with the same number of columns as the original files.

Parameters:

raw_directory (str) – directory of the raw simulation
filename (str) – filename to be stitched

Returns:

stitched data for the given filename

Return type:

numpy.ndarray

mayawaves.utils.postprocessingutils.low_pass_filter(time: ndarray, data: ndarray, low_pass_freq_cutoff: float) → ndarray

Filter out high frequency noise using a butter filter.

Parameters:

time (numpy.ndarray) – time stamps associated with data
data (numpy.ndarray) – data to filter
low_pass_freq_cutoff (float) – frequency cutoff to use with butter filter

Returns:

data with high frequencies removed

Return type:

numpy.ndarray

mayawaves.utils.postprocessingutils.summarize_coalescence(coalescence: Coalescence, output_directory: str | None = None)

Summarize data collected from a Coalescence simulation.

Create a summary.txt document and important plots in the specified output directory.

Parameters:

coalescence (Coalescence) – the Coalescence object to be summarized
output_directory (str, optional) – the location to store the summary file and plots. If a path is not provided, the plots are displayed rather than saved.

mayawaves.utils.catalogutils module

class mayawaves.utils.catalogutils.Catalog

Bases: object

Class for interacting with the MAYA catalog.

property aligned_spin_simulations: List of all simulations/waveforms with spins aligned or anti-aligned with the orbital angular momentum.

download_waveforms(waveforms: list, save_wf_path, safety: bool = True, lvcnr_format: bool = False)

Downloads waveforms from the MAYA Catalog given a list of waveform ids. By default, they are downloaded in the MAYA format, but they can also be downloaded in the lvc-nr format (https://arxiv.org/abs/1703.01076).

Parameters:

waveforms (list) – list of waveforms to download
save_wf_path (str) – where to save the downloaded waveforms
safety (bool, optional) – whether to request verification if the total size of waveforms exceeds 10 GB. Defaults to True.
lvcnr_format (bool, optional) – download the lvc-nr format instead of the MAYA format. Defaults to False.

get_parameters_for_simulation(catalog_id: str) → dict

Outputs all the metadata for a given waveform.

Parameters:: catalog_id (str) – simulation/waveform catalog id
Returns:: parameter dictionary
Return type:: dict

get_simulations_with_mass_ratio(mass_ratio: float, tol: float = 0.0001) → list

List of all waveforms with a given mass ratio within specified tolerance.

Mass ratio is defined as \(q=m_1 / m_2 \geq 1\)

Parameters:

mass_ratio (float) – desired mass ratio value
tol (float, optional) – tolerance

Returns:

a list of simulations/waveforms which satisfy the requirements.

Return type:

list

get_simulations_with_parameters(params: list, values: list, tol: list | None = None) → list

Takes in a list of parameters, their corresponding values and tolerances (optional, 0.0001 if not provided) and returns all the waveforms with those values within those tolerances.

Parameters:

params (list) – list of parameters
values (list) – list of corresponding values
tol (list, optional) – list of tolerances. If not provided, tolerances of 0.0001 will be used.

Returns:

a list of simulations/waveforms which satisfy the requirements

Return type:

list

get_simulations_with_symmetric_mass_ratio(eta: float, tol: float = 0.0001) → list

List of all waveforms with a given symmetric mass ratio within specified tolerance.

Symmetric mass ratio defined as \(q/(1+q)^2\)

Parameters:

eta (float) – desired symmetric mass ratio
tol (float, optional) – tolerance

Returns:

a list of simulations/waveforms which satisfy the requirements.

Return type:

list

property nonspinning_simulations: List of all simulations/waveforms with no spin.

plot_catalog_parameters(p1: Parameter, p2: Parameter, save_path: str = False, dpi: int = 300, color: str = 'cornflowerblue')

Plots the two parameter against each other as well as a histogram distribution of each parameter for all waveforms in the catalog. If a path is provided, figures will be saved in the provided directory. If a path is not provided, the figures will be displayed.

Parameters:

p1 (Parameter) – one of the parameters to plot
p2 (Parameter) – the other parameter to plot
save_path (str, optional) – path where you want to save the plots
dpi (int, optional) – dpi of the saved plots
color (str, optional) – color to be used for the plots

property precessing_simulations: List of all simulations/waveforms with precessing spins (spins not aligned with the orbital angular momentum).

spin_magnitudes_for_simulation(name: str) → tuple

Calculates spin magnitude for each object in the binary system and returns a tuple with individual spin magnitudes.

Parameters:: name (str) – simulation/waveform name
Returns:: spin of the primary object, spin of the secondary object
Return type:: tuple

class mayawaves.utils.catalogutils.Parameter(value)

Bases: Enum

Enum for easily referencing parameters of the simulations.

mayawaves.utils.postnewtonianutils module

mayawaves.utils.postnewtonianutils.dH_dr_from_separation(separation: float, mass_ratio: float, primary_dimensionless_spin: ndarray, secondary_dimensionless_spin: ndarray) → float

Derivative of the hamiltonian with respect to separation.

Derivative of the hamiltonian with respect to separation at the given separation for a binary with the provided parameters.

Parameters:

separation (float) – the separation between the two objects
mass_ratio (float) – the ratio of the masses of the two objects, \(q = m_1 / m_2 > 1\)
primary_dimensionless_spin (numpy.ndarray) – the dimensionless spin of the larger object
secondary_dimensionless_spin (numpy.ndarray) – the dimensionless spin of the smaller object

Returns:

derivative of the hamiltonian with respect to separation

Return type:

float

mayawaves.utils.postnewtonianutils.orbital_frequency_from_separation(separation: float, mass_ratio: float, primary_dimensionless_spin: ndarray, secondary_dimensionless_spin: ndarray) → float

The orbital frequency for a binary at a given separation.

For a quasi-circular binary with the provided parameters, this returns the orbital frequency at the requested separation. Uses equations from https://arxiv.org/pdf/1702.00872.pdf.

Parameters:

separation (float) – the separation between the two objects
mass_ratio (float) – the ratio of the masses of the two objects, \(q = m_1 / m_2 > 1\)
primary_dimensionless_spin (numpy.ndarray) – the dimensionless spin of the larger object
secondary_dimensionless_spin (numpy.ndarray) – the dimensionless spin of the smaller object

Returns:

orbital frequency for a quasi-circular binary at the given separation

Return type:

float

mayawaves.utils.postnewtonianutils.radial_momentum_from_separation(separation: float, mass_ratio: float, primary_dimensionless_spin: ndarray, secondary_dimensionless_spin: ndarray)

The radial momentum for a quasi-circular binary at the given separation.

For a binary of the provided parameters, this gives the radial momentum to obtain a quasi-circular orbit. Uses equations from https://arxiv.org/pdf/1702.00872.pdf and https://arxiv.org/pdf/1810.00036.pdf.

Parameters:

separation (float) – the separation between the two objects
mass_ratio (float) – the ratio of the masses of the two objects, \(q = m_1 / m_2 > 1\)
primary_dimensionless_spin (numpy.ndarray) – the dimensionless spin of the larger object
secondary_dimensionless_spin (numpy.ndarray) – the dimensionless spin of the smaller object

Returns:

the radial momentum of a quasi-circular orbit for the given binary

Return type:

float

mayawaves.utils.postnewtonianutils.separation_from_orbital_frequency(orbital_frequency: float, mass_ratio: float, primary_dimensionless_spin: ndarray, secondary_dimensionless_spin: ndarray) → float

The separation at which a binary will have the given orbital frequency.

For a quasi-circular binary with the provided parameters, this returns the separation in M at which the binary will have the given orbital frequency. Uses equations from https://arxiv.org/pdf/1702.00872.pdf.

Parameters:

orbital_frequency (float) – the orbital frequency of the binary
mass_ratio (float) – the ratio of the masses of the two objects, \(q = m_1 / m_2 > 1\)
primary_dimensionless_spin (numpy.ndarray) – the dimensionless spin of the larger object
secondary_dimensionless_spin (numpy.ndarray) – the dimensionless spin of the smaller object

Returns:

the separation at which a quasi-circular binary will have the provided orbital frequency

Return type:

float

mayawaves.utils.postnewtonianutils.tangential_momentum_from_separation(separation: float, mass_ratio: float, primary_dimensionless_spin: ndarray, secondary_dimensionless_spin: ndarray) → float

The tangential momentum for a quasi-circular binary at the given separation.

For a binary of the provided parameters, this gives the tangential momentum to obtain a quasi-circular orbit. Uses equations from https://arxiv.org/pdf/1702.00872.pdf.

Parameters:

separation (float) – the separation between the two objects
mass_ratio (float) – the ratio of the masses of the two objects, \(q = m_1 / m_2 > 1\)
primary_dimensionless_spin (numpy.ndarray) – the dimensionless spin of the larger object
secondary_dimensionless_spin (numpy.ndarray) – the dimensionless spin of the smaller object

Returns:

the tangential momentum of a quasi-circular orbit for the given binary

Return type:

float