gwsnrcalc package

gwsnrcalc is a package designed for fast signal-to-noise ratio (SNR) calculations for single gravitational wave sources using a matched filtering SNR approach. It was originally designed to support BOWIE for Evaluating Black Hole Detectability with LISA (arXiv:1807.02511). It provides a fast SNR calculator, frequency-domain amplitude waveforms for binary black holes, and a SNR grid generator for binary black holes.

The main snr function is gwsnrcalc.gw_snr_calculator.snr. It has the capability to perform calculations in parallel across processors for faster calculation.

The waveform generator (gwsnrcalc.utils.waveforms) creates either circular or eccentric waveforms.

Circular waveforms are created with PhenomD amplitude waveforms for binary black hole inspiral, merger, and ringdown. PhenomD is from Husa et al 2016 (arXiv:1508.07250) and Khan et al 2016 (arXiv:1508.07253). The current waveforms returned are in units of characteristic strain.

Eccentric waveforms are generated according to Peters evolution only for the inspiral phase.

The snr grid generator: gwsnrcalc.generate_contour_data uses gwsnrcalc.gw_snr_calculator.snr to create SNR grids for contour plots (like those used in BOWIE).

Available via pip and on github: https://github.com/mikekatz04/BOWIE/

Getting Started

These instructions will get you a copy of the project up and running on your local machine for usage and testing purposes.

Prerequisites

It is best to run out of conda environment. It will handle the dependencies better. If you have issues with certain modules, try to update them.

Software installation/usage only requires a few specific libraries in python. All libraries are included with Anaconda. If you do not run python in an anaconda environment, you will need the following libraries and modules to run with all capabilities: Numpy, Scipy, collections, sys, json, multiprocessing, datetime, time, astropy, and h5py. All can be installed with pip. For example, within your python environment of choice:

pip install astropy

In order to properly create waveforms with ctypes, you will need complex, gsl, and math c libraries. For installing gsl, refer to https://www.gnu.org/software/gsl/ or install it through anaconda.

Installation

Begin with updating conda:

conda update conda

Create a conda environment (change the name as desired. Default: gwsnr_env):

conda create -n gwsnr_env numpy scipy astropy h5py gsl matplotlib jupyter ipython python=3.7

Installation is done two ways:

  1. using pip

pip install gwsnrcalc

This will download the all necessary packages to your current environment. It will not download the notebooks for testing and example usage.

  1. Clone the git repo on the command line, or downloading it from github. This is for all the modules, example jupyter notebooks, and extra files. This method will include BOWIE if pip install is used on the outer directory. To just download specific files that do not come with pip (e.g. jupyter notebook with examples), just download the files from the github.

  1. navigate to the directory of your choice.

  2. clone the git repo on the command line.

git clone https://github.com/mikekatz04/BOWIE.git

  1. pip install the local code to add the modules to your environment and compile the c codes.

pip install ./BOWIE/snr_calculator_folder/

Testing and Running an Example

To test the codes, you run the guide notebook.

jupyter notebook pyphenomd_guide.ipynb

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

Current version is 1.1.0.

We use SemVer for versioning.

Authors

Please email the author with any bugs or requests.

License

This project is licensed under the GNU License - see the LICENSE.md file for details.

Acknowledgments

  • Thanks to Michael Puerrer, Sebastian Khan, Frank Ohme, Ofek Birnholtz, Lionel London for authorship of the original c code for PhenomD within LALsuite.

gwsnrcalc pacakge documentation:

User interfacing modules:

gw_snr_calculator module

Calculate gravitational wave SNRs.

This was used in “Evaluating Black Hole Detectability with LISA” (arXiv:1508.07253), as a part of the BOWIE package (https://github.com/mikekatz04/BOWIE). Please cite this when using this code.

This code is licensed with the GNU public license.

This python code impliments PhenomD waveforms from Husa et al 2016 (arXiv:1508.07250) and Khan et al 2016 (arXiv:1508.07253). Please cite these papers if PhenomD waveforms are used.

It can also generate eccentric inspirals according to Peters evolution.

class gwsnrcalc.gw_snr_calculator.SNR(**kwargs)

Bases: gwsnrcalc.utils.sensitivity.SensitivityContainer, gwsnrcalc.utils.parallel.ParallelContainer, gwsnrcalc.utils.waveforms.PhenomDWaveforms

Main class for SNR calculations.

This class performs gravitational wave SNR calculations with a matched filtering approach. It can generate SNRs for single sources or arrays of sources. It can run in parallel or on a single processor.

Parameters

  • ecc (bool, optional) – If True, use the eccentric SNR calculator. If False, use PhenomDWaveforms. (For future usage.) Default is False.

  • **kwargs (dict) – kwargs to be added to ParallelContainer, PhenomDWaveforms, and SensitivityContainer.

Keyworkd Arguments:
signal_type (scalar or list of str, optional): Phase of snr.

Options are ‘all’ for all phases; ‘ins’ for inspiral; ‘mrg’ for merger; or ‘rd’ for ringdown. Default is ‘all’.

prefactor (float, optional): Factor to multiply snr (not snr^2) integral values by.

Default is 1.0.

snr_function

Function object representing the snr function to use. This is form future use with other snr calculations.

Type

obj

phenomdwave

gwsnrcalc.utils.pyphenomd.PhenomDWaveforms object for storing initial kwargs and passing to snr function.

Type

obj

Note

All kwargs are stored as attributes.

Note

Attributes are inherited from inherited classes.

__call__(*binary_args)

Input binary parameters and calculate the SNR

Binary parameters are read in and adjusted based on shapes. They are then fed into run for calculation of the snr.

Parameters

*args – Arguments for binary parameters (see :meth:gwsnrcalc.utils.pyphenomd.__call__)

Returns

Dictionary with the SNR output from the calculation.

Return type

(dict)

gwsnrcalc.gw_snr_calculator.parallel_ecc_snr_func(num, binary_args, eccwave, signal_type, noise_interpolants, prefactor, verbose)

SNR calulation with eccentric waveforms

Generate PhenomDWaveforms and calculate their SNR against sensitivity curves.

Parameters
Returns

Dictionary with the SNR output from the calculation.

Return type

(dict)

gwsnrcalc.gw_snr_calculator.parallel_snr_func(num, binary_args, phenomdwave, signal_type, noise_interpolants, prefactor, verbose)

SNR calulation with PhenomDWaveforms

Generate PhenomDWaveforms and calculate their SNR against sensitivity curves.

Parameters

  • num (int) – Process number. If only a single process, num=0.

  • binary_args (tuple) – Binary arguments for gwsnrcalc.utils.waveforms.EccentricBinaries.__call__().

  • phenomdwave (obj) – Initialized class of gwsnrcalc.utils.waveforms.PhenomDWaveforms.

  • signal_type (list of str) – List with types of SNR to calculate. Options are all for full wavefrom, ins for inspiral, mrg for merger, and/or rd for ringdown.

  • noise_interpolants (dict) – All the noise noise interpolants generated by gwsnrcalc.utils.sensitivity.

  • prefactor (float) – Prefactor to multiply SNR by (not SNR^2).

  • verbose (int) – Notify each time verbose processes finish. If -1, then no notification.

Returns

Dictionary with the SNR output from the calculation.

Return type

(dict)

gwsnrcalc.gw_snr_calculator.snr(*args, **kwargs)

Compute the SNR of binaries.

snr is a function that takes binary parameters and sensitivity curves as inputs, and returns snr for chosen phases.

Warning: All binary parameters must be either scalar, len-1 arrays, or arrays of the same length. All of these can be used at once. However, you cannot input multiple arrays of different lengths.

Parameters

  • *args – Arguments for gwsnrcalc.utils.pyphenomd.PhenomDWaveforms.__call__()

  • **kwargs – Keyword arguments related to parallel generation (see gwsnrcalc.utils.parallel), waveforms (see gwsnrcalc.utils.pyphenomd), or sensitivity information (see gwsnrcalc.utils.sensitivity).

Returns

Signal-to-Noise Ratio dictionary for requested phases.

Return type

(dict or list of dict)

waveforms module

Author: Michael Katz guided by lal implimentation of PhenomD. This was used in “Evaluating Black Hole Detectability with LISA” (arXiv:1508.07253), as a part of the BOWIE package (https://github.com/mikekatz04/BOWIE). Please cite this paper when using this code.

This code is licensed with the GNU public license.

This python code impliments circular PhenomD waveforms from Husa et al 2016 (arXiv:1508.07250) and Khan et al 2016 (arXiv:1508.07253). It wraps the accompanying c code, phenomd/phenomd.c, with cython. phenomd/phenomd.c is mostly from LALsuite. See phenomd/phenomd.c for specifics. Please cite these papers if circular waveforms are generated.

It also implements eccentric inpspiral waveforms according to Peters (1964).

class gwsnrcalc.utils.waveforms.EccentricBinaries(**kwargs)

Bases: object

Generate eccentric inspiral waveforms

EccentricBinaries is a class that takes binary parameters as inputs, and adds characteristic strain waveforms as attributes to self.

Keyword Arguments

  • dist_type (str, optional) – Which type of distance is used. Default is ‘redshift’. This is stored as an attributed.

  • num_points (int, optional) – Number of points to use in the waveform. The frequency points are log-spaced. Default is 8192. This is stored as an attributed.

  • initial_cond_type (str, optional) – Initial value representing the start of evolution. Options are time, frequency, or separation. Default is time.

  • n_max (int, optional) – Maximum number of higher order harmonics to analyze in the SNR. Default is 100.

freqs

Frequencies corresponding to the waveforms. Shape is (num binaries, num_points) if 2D. Shape is (num_points,) if 1D for one binary.

Type

1D or 2D array of floats

hc

Characteristic strain of the waveforms. Shape is (num binaries, num_points) if 2D. Shape is (num_points,) if 1D for one binary.

Type

1D or 2D array of floats

z

Redshift equivalent of the z_or_dist given.

Type

float or 1D array of floats

dist

Luminosity distance equivalent of the z_or_dist given.

Type

float or 1D array of floats

f0

Initial orbital frequencies. If initial_cond_type == 'frequency', initial values are stored here. Optional. Default is None.

Type

float, 1D array of floats, or None

a0

Initial orbital semi-major axes. If initial_cond_type == 'separation', initial values are stored here. Optional. Default is None.

Type

float, 1D array of floats, or None

t_start

Initial times before merger. If initial_cond_type == 'time', initial values are stored here. Optional. Default is None.

Type

float, 1D array of floats, or None

e_vals

Eccentricity values over time.

Type

2D array of floats

a_vals

Semi-major axis values over time.

Type

2D array of floats

t_vals

Time values corresponding to e_vals and a_vals.

Type

2D array of floats

freqs_orb

Orbital frequencies over time.

Type

2D array of floats

n

Radiation mode values.

Type

2D array of ints

ef

Final eccentricity for each binary.

Type

1D array of floats

remove_axis

Remove axis based on if it is one or more than one binary.

Type

bool

length

Number of binaries.

Type

int

Note

All args from gwsnrcalc.utils.pyphenomd.PhenomDWaveforms.__call__() are stored as attributes.

Note

All kwargs from above are stored as attributes.

Raises

  • ValueError – dist_type is not one of the three options.

  • ValueError – initial_cond_type is not one of the three options.

__call__(m1, m2, z_or_dist, initial_point, e0, t_obs)

Run the waveform creator.

Create eccentric inspiral waveforms in the amplitude frequency domain.

Warning: Binary parameters have to one of three shapes: scalar, len-1 array, or array of len MAX. All scalar quantities or len-1 arrays are cast to len-MAX arrays. If arrays of different lengths (len>1) are given, a ValueError will be raised.

Parameters

  • m1 (float or 1D array of floats) – Mass 1 in Solar Masses. (>0.0)

  • m2 (float or 1D array of floats) – Mass 2 in Solar Masses. (>0.0)

  • z_or_dist (float or 1D array of floats) – Distance measure to the binary. This can take three forms: redshift (dimensionless, default), luminosity distance (Mpc), comoving_distance (Mpc). The type used must be specified in ‘dist_type’ parameter. (>0.0)

  • initial_point (float or 1D array of floats) – Initial description point of binary. This can either be the start time, frequency, separation. This must be the same quantity as initial_cond_type. (>0.0)

  • e0 (float or 1D array of floats) – Inital eccentricity of binary. (0<e<1)

  • t_obs (float or 1D array of floats) – Observation time of binary. (>0.0)

class gwsnrcalc.utils.waveforms.PhenomDWaveforms(**kwargs)

Bases: object

Generate phenomd waveforms

PhenomDWaveforms is a class that takes binary parameters as inputs, and adds characteristic strain waveforms as attributes to self.

Keyword Arguments

  • dist_type (str, optional) – Which type of distance is used. Default is ‘redshift’. This is stored as an attributed.

  • num_points (int, optional) – Number of points to use in the waveform. The frequency points are log-spaced. Default is 8192. This is stored as an attributed.

freqs

Frequencies corresponding to the waveforms. Shape is (num binaries, num_points) if 2D. Shape is (num_points,) if 1D for one binary.

Type

1D or 2D array of floats

hc

Characteristic strain of the waveforms. Shape is (num binaries, num_points) if 2D. Shape is (num_points,) if 1D for one binary.

Type

1D or 2D array of floats

fmrg

(scalar float or 1D array of floats): Merger frequency of each binary separating inspiral from merger phase. (0.014/M) Shape is (num binaries,) if more than one binary.

fpeak

(scalar float or 1D array of floats): Peak frequency of each binary separating merger from ringdown phase. (0.014/M) Shape is (num binaries,) if more than one binary.

z

Redshift equivalent of the z_or_dist given.

Type

float or 1D array of floats

dist

Luminosity distance equivalent of the z_or_dist given.

Type

float or 1D array of floats

remove_axis

Remove axis based on if it is one or more than one binary.

Type

bool

length

Number of binaries.

Type

int

Note

All args from gwsnrcalc.utils.pyphenomd.PhenomDWaveforms.__call__() are stored as attributes.

Note

All kwargs from above are stored as attributes.

Raises

ValueError – dist_type is not one of the three options.

__call__(m1, m2, chi_1, chi_2, z_or_dist, st, et)

Run the waveform creator.

Create phenomd waveforms in the amplitude frequency domain.

Warning: Binary parameters have to one of three shapes: scalar, len-1 array, or array of len MAX. All scalar quantities or len-1 arrays are cast to len-MAX arrays. If arrays of different lengths (len>1) are given, a ValueError will be raised.

Parameters

  • m1 (float or 1D array of floats) – Mass 1 in Solar Masses. (>0.0)

  • m2 (float or 1D array of floats) – Mass 2 in Solar Masses. (>0.0)

  • chi_1 (float or 1D array of floats) – dimensionless spin of mass 1 aligned to orbital angular momentum. Default is None (not 0.0). [-1.0, 1.0]

  • chi_2 (float or 1D array of floats) – dimensionless spin of mass 2 aligned to orbital angular momentum. Default is None (not 0.0). [-1.0, 1.0]

  • z_or_dist (float or 1D array of floats) – Distance measure to the binary. This can take three forms: redshift (dimensionless, default), luminosity distance (Mpc), comoving_distance (Mpc). The type used must be specified in ‘dist_type’ parameter. (>0.0)

  • st (float or 1D array of floats) – Start time of waveform in years before end of the merger phase. This is determined using 1 PN order. (>0.0)

  • et (float or 1D array of floats) – End time of waveform in years before end of the merger phase. This is determined using 1 PN order. (>0.0)

readnoisecurves module

Author: Michael Katz. This code is a simple auxillary function that returns sensitivity curvesself. This was used in “Evaluating Black Hole Detectability with LISA” (arXiv:1508.07253), as a part of the BOWIE package (https://github.com/mikekatz04/BOWIE).

Please cite this paper if you use this code in a publication.

This code is licensed with the GNU public license.

gwsnrcalc.utils.readnoisecurves.asd_to_char_strain(f, amp)

Convert asd to char_strain

Parameters

  • f (float array) – Frequencies.

  • amp (float array) – Amplitude Spectral Density values.

Returns

Characteristic strain values.

Return type

(float array)

gwsnrcalc.utils.readnoisecurves.asd_to_psd(f, amp)

Convert asd to psd

Parameters

  • f (float array) – Frequencies.

  • amp (float array) – Amplitude Spectral Density values.

Returns

Power Spectral Density values.

Return type

(float array)

gwsnrcalc.utils.readnoisecurves.char_strain_to_asd(f, amp)

Convert char_strain to asd

Parameters

  • f (float array) – Frequencies.

  • amp (float array) – Characteristic strain values.

Returns

Amplitude Spectral Density values.

Return type

(float array)

gwsnrcalc.utils.readnoisecurves.char_strain_to_psd(f, amp)

Convert char_strain to psd

Parameters

  • f (float array) – Frequencies.

  • amp (float array) – Characteristic strain values.

Returns

Power Spectral Density values.

Return type

(float array)

gwsnrcalc.utils.readnoisecurves.combine_with_wd_noise(f_n, amp_n, f_n_wd, amp_n_wd)

Combine noise with wd noise.

Combines noise and white dwarf background noise based on greater amplitude value at each noise curve step.

Parameters

  • f_n (float array) – Frequencies of noise curve.

  • amp_n (float array) – Amplitude values of noise curve.

  • f_n_wd (float array) – Frequencies of wd noise.

  • amp_n_wd (float array) – Amplitude values of wd noise.

Returns

Amplitude values of combined noise curve.

Return type

(tuple of float arrays)

gwsnrcalc.utils.readnoisecurves.psd_to_asd(f, amp)

Convert psd to asd

Parameters

  • f (float array) – Frequencies.

  • amp (float array) – Power Spectral Density values.

Returns

Amplitude Spectral Density values.

Return type

(float array)

gwsnrcalc.utils.readnoisecurves.psd_to_char_strain(f, amp)

Convert psd to char_strain

Parameters

  • f (float array) – Frequencies.

  • amp (float array) – Power Spectral Density values.

Returns

Characteristic strain values.

Return type

(float array)

gwsnrcalc.utils.readnoisecurves.read_noise_curve(noise_curve, noise_type_in='ASD', noise_type_out='ASD', add_wd_noise=False, wd_noise='HB_wd_noise', wd_noise_type_in='ASD')

Simple auxillary function that can read noise curves in.

This function can read in noise curves from a provided file or those that are preinstalled with this installation. All pre-installed noise curves are in the form of an amplitude spectral density. Information on each one is found in each specific file. These are located in the noise_curves folder.

Pre-installed really just means in the noise_curves folder. Therefore, curves can be added and called with only a string.

Parameters

  • noise_curve (str) – Either a file path to a noise curve or a str represented pre-loaded sensitivity curve. If using pre-loaded curve, choices are LPA (LISA Phase A), PL (Proposed LISA), CL (Classic LISA), CLLF (Classic LISA Low Frequency), PLCS (Proposed LISA Constant Slope), or PLHB (Proposed LISA Higher Break). See the arXiv paper above for the meaning behind each choice and a plot with each curve.

  • noise_type_in/noise_type_out (str, optional) – Type of noise input/output. Choices are ASD, PSD, or char_strain. Default for both is ASD.

  • add_wd_noise (bool, optional) – If True, include wd noise.

  • wd_noise (str, optional) – File path to wd background noise or string representing those in the noise curves folder. Default is the Hiscock et al 2000 approximation of the Hils & Bender 1997 white dwarf background (HB_wd_noise).

  • wd_noise_type_in (str, optional) – Type of wd noise input. The output will be the same as noise_type_out. Choices are ASD, PSD, or char_strain. Default for both is ASD.

  • Returns – (tuple of arrays): Frequency and amplitude arrays of type noise_type_out.

gwsnrcalc.utils.readnoisecurves.show_available_noise_curves(return_curves=True, print_curves=False)

List available sensitivity curves

This function lists the available sensitivity curve strings in noise_curves folder.

Parameters

  • return_curves (bool, optional) – If True, return a list of curve options.

  • print_curves (bool, optional) – If True, print each curve option.

Returns

List of curve options.

Return type

(optional list of str)

Raises

ValueError – Both args are False.

generate_contour_data module

Generate gridded data for contour plots with PhenomD waveform. It is part of the BOWIE analysis tool. Author: Michael Katz. Please cite “Evaluating Black Hole Detectability with LISA” (arXiv:1807.02511) for usage of this code.

PhenomD waveforms are generated according to Husa et al 2016 (arXiv:1508.07250) and Khan et al 2016 (arXiv:1508.07253). Please cite these papers if the PhenomD waveform is used.

Eccentric inspiral waveforms are also possible according to Peters evolution.

generate_contour_data produces gridded data sets based on an input class or dictionary. It can take any basic set of parameters for binary black holes and produce waveforms and SNR calculations for each phase of binary black hole coalescence (only inspiral for eccentric binaries). It reads in sensitivity curves from .txt files. The outputs can either be .txt or .hdf5. It can run in parallel or on a single processor. See the example notebooks for usage of this module.

This code is licensed under the GNU public license.

gwsnrcalc.generate_contour_data.generate_contour_data(pid)

Main function for this program.

This will read in sensitivity_curves and binary parameters; calculate snrs with a matched filtering approach; and then read the contour data out to a file.

Parameters

pid (obj or dict) – GenInput class or dictionary containing all of the input information for the generation. See BOWIE documentation and example notebooks for usage of this class.

forminput module

Documentation is provided for creating the main input dictionary for make_plot.py. A dictionary is passed into the main function of the code, providing the preferences of the user. A dictionary in python is contained within {} (see 5.5 Dictionaries at https://docs.python.org/3/tutorial/datastructures.html).

This documentation will direct the user to all choices related to this dictionary included required and optional parameters.

These dictionaries can be used in a python code or jupyter notebook by importing the main functions from each script. They can also be implemented with .json files similar to those included in the repository. If .json is used, the function call is python make_plot.py make_plot_config.json.

This code is part of the BOWIE analysis tool. Author: Michael Katz. Please see “Evaluating Black Hole Detectability with LISA” (arXiv:1807.02511) for example usage. Please cite arXiv:1807.02511 for its usage.

This code is shared under the GNU Public License.

NOTE: This code associates classes with a name (e.g. Label) and a Container

class for storing its information (e.g. LabelContainer). This is due to the need to inherit methods in a separate way from where the information is actually stored.

Therefore, when reading the documentation, the main classes (without Container) will describe the methods for adding information for plotting. This includes required values and default values for optional Args related to the methods themselves and not the defaults and required values within the actual plotting module code.

The Container classes have descriptions of their attributes. Their attributes involve the same requirements and default/optional Args as the plotting code itself.

class gwsnrcalc.genconutils.forminput.GeneralContainer

Bases: object

Holds all of the attributes related to the general dictionary.

This class is used to store the information when methods are called by the MainContainer class.

WORKING_DIRECTORY

Working directory for file export and retrieval. Default is '.'.

Type

str, optional

class gwsnrcalc.genconutils.forminput.Generate

Bases: object

Generate contains the methods inherited by MainContainer.

These methods are used by MainContainer class to add generation specific information to the generate_info dict.

All attributes are appended to the GenerateContainer class. The GenerateContainer class is contained in the generate_info attribute in the MainContainer class.

add_fixed_parameter(val, name)

Add the fixed parameters for SNR calculation.

The fixed parameters represent those that a fixed for the entire 2D grid.

Parameters

  • val (float) – Value of parameter.

  • name (str) – Name representing the axis. See GenerateContainer documentation for options for the name.

set_x_grid_info(x_low, x_high, num_x, xscale, xval_name)

Set the grid values for x.

Create information for the grid of x values.

Parameters

  • num_x (int) – Number of points on axis.

  • x_low/x_high (float) – Lowest/highest value for the axis.

  • xscale (str) – Scale of the axis. Choices are ‘log’ or ‘lin’.

  • xval_name (str) – Name representing the axis. See GenerateContainer documentation for options for the name.

set_y_grid_info(y_low, y_high, num_y, yscale, yval_name)

Set the grid values for y.

Create information for the grid of y values.

Parameters

  • num_y (int) – Number of points on axis.

  • y_low/y_high (float) – Lowest/highest value for the axis.

  • yscale (str) – Scale of the axis. Choices are ‘log’ or ‘lin’.

  • yval_name (str) – Name representing the axis. See GenerateContainer documentation for options for the name.

class gwsnrcalc.genconutils.forminput.GenerateContainer

Bases: object

Holds all of the attributes related to the generate_info dictionary.

This class is used to store the information when methods from Generate class are called by the MainContainer class.

Note

Attributes represent the kwargs from gwsnrcalc.genconutils.genprocess.GenProcess.

class gwsnrcalc.genconutils.forminput.MainContainer(print_input=False)

Bases: gwsnrcalc.genconutils.forminput.Generate, gwsnrcalc.genconutils.forminput.SensitivityInput, gwsnrcalc.genconutils.forminput.SNRInput, gwsnrcalc.genconutils.forminput.ParallelInput, gwsnrcalc.genconutils.forminput.Output

Main class for creating input dictionary to generate_contour_data.py.

This class creates a pythonic way to add information to the input dictionary to generate_contour_data.py. It creates and can read out this dictionary.

MainContainer inherits methods from Generate, SensitivityInput, SNRInput, ParallelInput, and Output classes so that it can add respective dictionary information to MainContainer class.

Parameters

print_input (bool, optional) – If True, print the dictionary created by MainContainer class after it is completed.

general

GeneralContainer class for holding information for general dictionary.

Type

obj

generate_info

GenerateContainer class for holding information for generate_info dictionary.

Type

obj

sensitivity_input

InputContainer class for holding information for sensitivty_input dictionary.

Type

obj

snr_input

SNRInputContainer class for holding information for snr_input dictionary.

Type

obj

parallel_input

ParallelInputContainer class for holding information for parallel_input dictionary.

Type

obj

output_info

OutputContainer class for holding information for output_info dictionary.

Type

obj

print_input

If True, print the dictionary created by MainContainer class after it is completed.

Type

bool, optional

return_dict()

Output dictionary for gwsnrcalc.generate_contour_data input.

Iterates through the entire MainContainer class turning its contents into dictionary form. This dictionary becomes the input for gwsnrcalc.generate_contour_data.

If print_input attribute is True, the entire dictionary will be printed prior to returning the dicitonary.

Returns

Dicitonary for input into

gwsnrcalc.generate_contour_data.

Return type

  • output_dict

set_working_directory(wd)

Set the WORKING_DIRECTORY variable.

Sets the WORKING_DIRECTORY. The code will then use all paths as relative paths to the WORKING_DIRECTORY. In code default is current directory.

Parameters

wd (str) – Absolute or relative path to working directory.

class gwsnrcalc.genconutils.forminput.Output

Bases: object

Output contains the methods inherited by MainContainer.

These methods are used by MainContainer class to add information pertaining to the output of the grid creation.

All attributes are appended to the OutputContainer class. The OutputContainer class is contained in the output_info attribute in the SinglePlot class.

add_note(note)

Add a note to output file.

This will add a note of user input to the output file.

Parameters

note (str) – Note to be added.

set_output_file(output_file_name)

Add information for the ouput file.

Take information on the output file name, type, and folder.

Parameters

output_file_name (str) – String representing the name of the file without the file extension.

set_x_col_name(x_col_name)

Set x column name.

Sets the x column name in the output file.

Parameters

x_col_name (str) – x column name to be added.

set_y_col_name(y_col_name)

Set y column name.

Sets the y column name in the output file.

Parameters

y_col_name (str) – y column name to be added.

class gwsnrcalc.genconutils.forminput.OutputContainer

Bases: object

Holds all of the attributes related to the output_info dictionary.

This class is used to store the information when methods from Output class are called by the MainContainer class.

Note

Attributes represent the kwargs from gwsnrcalc.genconutils.readout.FileReadOut.

class gwsnrcalc.genconutils.forminput.ParallelInput

Bases: object

General contains the methods inherited by MainContainer.

These methods are used by MainContainer class to add information that applies to parallel generation. This information is stored in a ParallelInputContainer class object.

set_generation_type(num_processors=-1, num_splits=1000, verbose=-1)

Change generation type.

Choose weather to generate the data in parallel or on a single processor.

Parameters

  • num_processors (int or None, optional) – Number of parallel processors to use. If num_processors==-1, this will use multiprocessing module and use available cpus. If single generation is desired, num_processors is set to None. Default is -1.

  • num_splits (int, optional) – Number of binaries to run during each process. Default is 1000.

  • verbose (int, optional) – Describes the notification of when parallel processes are finished. Value describes cadence of process completion notifications. If verbose == -1, no notifications are given. Default is -1.

class gwsnrcalc.genconutils.forminput.ParallelInputContainer

Bases: object

Holds all of the attributes related to the parallel_input dictionary.

This class is used to store the information when methods from ParallelInput class are called by the MainContainer class.

Note

Attributes represent the kwargs from gwsnrcalc.utils.parallel.ParallelContainer.

class gwsnrcalc.genconutils.forminput.SNRInput

Bases: object

General contains the methods inherited by MainContainer.

These methods are used by MainContainer class to add information that applies to all plots or the figure as a whole. Many of its settings pertaining to plots can be overriden with methods in SinglePlot.

set_n_max(n_max)

Maximium modes for eccentric signal.

The number of modes to be considered when calculating the SNR for an eccentric signal. This will only matter when calculating eccentric signals.

Parameters

n_max (int) – Maximium modes for eccentric signal.

set_num_waveform_points(num_wave_points)

Number of log-spaced points for waveforms.

The number of points of the waveforms with asymptotically increase the accuracy, but will lower the speed of generation.

Parameters

num_wave_points (int) – Number of log-spaced points for the waveforms.

set_signal_type(sig_type)

Set the signal type of interest.

Sets the signal type for which the SNR is calculated. This means inspiral, merger, and/or ringdown.

Parameters

sig_type (str or list of str) – Signal type desired by user. Choices are ins, mrg, rd, all for circular waveforms created with PhenomD. If eccentric waveforms are used, must be all.

set_snr_prefactor(factor)

Set the SNR multiplicative factor.

This factor will be multpilied by the SNR, not SNR^2. This involves orientation, sky, and polarization averaging, as well as any factors for the configuration.

For example, for LISA, this would be sqrt(2*16/5). The sqrt(2) is for a six-link configuration and the 16/5 represents the averaging factors.

Parameters

factor (float) – Factor to multiply SNR by for averaging.

class gwsnrcalc.genconutils.forminput.SNRInputContainer

Bases: object

Holds all of the attributes related to the snr_input dictionary.

This class is used to store the information when methods from SNRInput class are called by the MainContainer class.

Note

Attributes represent the kwargs from gwsnrcalc.gw_snr_calculator.SNR.

class gwsnrcalc.genconutils.forminput.SensitivityInput

Bases: object

Input contains the methods inherited by MainContainer.

These methods are used by MainContainer class to add noise curve information.

All attributes are appended to the SensitivityInputContainer class. The SensitivityInputContainer class is contained in the sensitivty_input attribute in the MainContainer class.

add_noise_curve(name, noise_type='ASD', is_wd_background=False)

Add a noise curve for generation.

This will add a noise curve for an SNR calculation by appending to the sensitivity_curves list within the sensitivity_input dictionary.

The name of the noise curve prior to the file extension will appear as its label in the final output dataset. Therefore, it is recommended prior to running the generator that file names are renamed to simple names for later reference.

Parameters

  • name (str) – Name of noise curve including file extension inside input_folder.

  • noise_type (str, optional) – Type of noise. Choices are ASD, PSD, or char_strain. Default is ASD.

  • is_wd_background (bool, optional) – If True, this sensitivity is used as the white dwarf background noise. Default is False.

set_wd_noise(wd_noise)

Add White Dwarf Background Noise

This adds the White Dwarf (WD) Background noise. This can either do calculations with, without, or with and without WD noise.

Parameters

wd_noise (bool or str, optional) – Add or remove WD background noise. First option is to have only calculations with the wd_noise. For this, use yes or True. Second option is no WD noise. For this, use no or False. For both calculations with and without WD noise, use both.

Raises

ValueError – Input value is not one of the options.

class gwsnrcalc.genconutils.forminput.SensitivityInputContainer

Bases: object

Holds all of the attributes related to the sensitivity_input dictionary.

This class is used to store the information when methods from Input class are called by the MainContainer class.

Note

Attributes represent the kwargs from gwsnrcalc.utils.sensitivity.SensitivityContainer.

Background documentation:

utils package

csnr module

Author: Michael Katz This was used in “Evaluating Black Hole Detectability with LISA” (arXiv:1508.07253), as a part of the BOWIE package (https://github.com/mikekatz04/BOWIE).

This code is licensed with the GNU public license.

This python code impliments a fast SNR calculator for binary black hole waveforms in c. It wraps the accompanying c code, phenomd/phenomd.c, with cython. phenomd/phenomd.c is mostly from LALsuite. See phenomd/phenomd.c for specifics.

Please cite all of the arXiv papers above if you use this code in a publication.

gwsnrcalc.utils.csnr.csnr(freqs, hc, hn, fmrg, fpeak, prefactor=1.0)

Calculate the SNR of a frequency domain waveform.

SNRCalculation is a function that takes waveforms (frequencies and hcs) and a noise curve, and returns SNRs for all binary phases and the whole waveform.

Parameters

  • freqs (1D or 2D array of floats) – Frequencies corresponding to the waveforms. Shape is (num binaries, num_points) if 2D. Shape is (num_points,) if 1D for one binary.

  • hc (1D or 2D array of floats) – Characteristic strain of the waveforms. Shape is (num binaries, num_points) if 2D. Shape is (num_points,) if 1D for one binary.

  • fmrg – (scalar float or 1D array of floats): Merger frequency of each binary separating inspiral from merger phase. (0.014/M) Shape is (num binaries,) if more than one binary.

  • fpeak – (scalar float or 1D array of floats): Peak frequency of each binary separating merger from ringdown phase. (0.014/M) Shape is (num binaries,) if more than one binary.

  • hn – (1D or 2D array of floats): Characteristic strain of the noise. Shape is (num binaries, num_points) if 2D. Shape is (num_points,) if 1D for one binary.

  • prefactor (float, optional) – Factor to multiply snr (not snr^2) integral values by. Default is 1.0.

Returns

Dictionary with SNRs from each phase.

Return type

(dict)

sensitivity module
class gwsnrcalc.utils.sensitivity.SensitivityContainer(**kwargs)

Bases: object

Sensitivity curve analysis

This prepares the sensitivity side of the SNR calculation. It takes all the inputs and converts them to characterstic strain.

Keyword Arguments

  • sensitivity_curves (scalar or list of str or single or list of lists, optional) – String that starts the .txt file containing the sensitivity curve in folder ‘noise_curves/’ or list of [f_n, asd_n] in terms of an amplitude spectral density. It can be a single one of these values or a list of these values. A folder string with absolute path to a sensitivity curve .txt file can also be input. Default is [LPA] (LISA Phase A).

  • add_wd_noise (str or bool, optional) – Options are yes, no, True, False, Both, True, or False. yes, True, or True will exclusively calculate with the wd noise. no, False, or False will exclusively calculate without the wd noise. Both will calculate with and without wd noise. Default is Both.

  • wd_noise (str or list, optional) – If string, read the wd noise from noise_curves folder or absolute path to file. If list, must be [f_n_wd, asd_n_wd]. Default is Hils-Bender estimation (Bender & Hils 1997) by Hiscock et al. 2000.

  • noise_type_in (str, optional) – Type of noise curve passed in. Options are ASD, PSD, or char_strain. All sensitivity curves must have same noise type. Also, their amplitude column must have this same string as its label. Default is ASD.

  • wd_noise_type_in (str, optional) – Type of wd noise curve passed in. Options are ASD, PSD, or char_strain. Amplitude column must have this same string as its label. Default is ASD.

noise_interpolants

Dictionary carrying scipy.interpolate.interp1d objects. These are the interpolations used to calculate the SNR.

Type

dict

Note

All Keyword Arguments are added as attributes.

_prep_noise_interpolants()

Construct interpolated sensitivity curves

This will construct the interpolated sensitivity curves using scipy.interpolate.interp1d. It will add wd noise if that is requested.

Raises

  • ValueError – len(noise_type_in) != len(sensitivity_curves)

  • ValueError – Issue with sensitivity curve type provided.

parallel module
class gwsnrcalc.utils.parallel.ParallelContainer(**kwargs)

Bases: object

Run SNR calculation in parallel.

Calculate in parallel using multiprocessing module. This can be easily adaptable to other parallel functions.

Keyword Arguments

  • length (int) – Number of binaries to process.

  • num_processors (int or None, optional) – If None, run on single processor. If -1, use `multiprocessing.cpu_count() to determine cpus to use. Otherwise, this is the number of processors to use. Default is -1.

  • num_splits (int, optional) – Number of binaries to run for each process. Default is 1000.

  • verbose (int, optional) – Notify each time verbose processes finish. If -1, then no notification. Default is -1.

  • timer (bool, optional) – If True, time the parallel process. Default is False.

args

List of arguments to passes to the parallel function.

Type

list of tuple

Note

All kwargs above are stored as attributes.

prep_parallel(binary_args, other_args)

Prepare the parallel calculations

Prepares the arguments to be run in parallel. It will divide up arrays according to num_splits.

Parameters

  • binary_args (list) – List of binary arguments for input into the SNR function.

  • other_args (tuple of obj) – tuple of other args for input into parallel snr function.

run_parallel(para_func)

Run parallel calulation

This will run the parallel calculation on self.num_processors.

Parameters

para_func (obj) – Function object to be used in parallel.

Returns

Dictionary with parallel results.

Return type

(dict)

genconutils package

genprocess module

Generate gridded data for contour plots with PhenomD waveform.

This module provides the main process class which the main part of the code is run out of. It is part of the BOWIE analysis tool.

Author: Michael Katz. Please cite “Evaluating Black Hole Detectability with LISA” (arXiv:1807.02511) for usage of this code.

PhenomD waveforms are generated according to Husa et al 2016 (arXiv:1508.07250) and Khan et al 2016 (arXiv:1508.07253). Please cite these papers if the PhenomD waveform is used.

It can take any basic set of parameters for binary black holes and produce waveforms and SNR calculations for each phase of binary black hole coalescence. It reads in sensitivity curves from .txt files. The outputs can either be .txt or .hdf5. It can run in parallel or on a single processor.

This code is licensed under the GNU public license.

class gwsnrcalc.genconutils.genprocess.GenProcess(**kwargs)

Bases: object

Direct the contour generation process.

Class that carries the input information and directs the program to accomplish generation tasks.

Parameters

**kwargs (dict) – Combination of all input dictionaries to have their information stored as attributes.

Keyword Arguments

  • xscale/yscale (str) – lin for linear scale or log for log10 scaling.

  • xlow/xhigh/ylow/yhigh (float) – Low/high value for x/y.

  • num_x/num_y (int) – Number of x/y points in contour.

  • xval_name/yval_name (str) – Name of the x/y quantity.

  • xval_unit/yval_unit (str) – Units for x/y quantity.

  • parameters – All the parameters (args) for the specific waveform generator. For both circular and eccentric, this will include start_time, m1, m2, redshift (or luminosity_distance or comoving_distance). For circular with will also include spin_1, spin_2, and end_time. For eccentric this will additionally include eccentricity and observation time.

  • sensitivty_input (dict) – kwargs for gwsnrcalc.utils.sensitivity.SensitivityContainer.

  • snr_input (dict) – kwargs for gwsnrcalc.gw_snr_calculator.SNR.

final_dict

Dictionary with SNR results.

Type

dict

Note

All kwargs above are added as attributes.

run_snr()

Run the snr calculation.

Takes results from self.set_parameters and other inputs and inputs these into the snr calculator.

set_parameters()

Setup all the parameters for the binaries to be evaluated.

Grid values and store necessary parameters for input into the SNR function.

readout module

Read out contour data. It is part of the BOWIE analysis tool. Author: Michael Katz. Please cite “Evaluating Black Hole Detectability with LISA” (arXiv:1807.02511) for usage of this code.

This code is licensed under the GNU public license.

class gwsnrcalc.genconutils.readout.FileReadOut(xvals, yvals, output_dict, **kwargs)

Bases: object

Class designed for reading out files in .txt files or hdf5 compressed files.

FileReadOut will export all of the contour data to a file and file type of the user’s choice. It will include all supplemental information for reference back to the file at a later point in time.

Parameters

  • xvals/yvals (1D array) – The x/y values for the contour data.

  • output_dict (dict) – The output of the SNR calculations. This is the dictionary returned by gwsnrcalc.gw_snr_calculator.snr.

  • **kwargs (dict) – Combination of the general, output_info, and generate_info dictionaries from pid. These kwargs are stored as attributes.

Keyword Arguments

  • output_file_name (str) – Path and name of output file in relation to working directory.

  • x_col_name (str, optional) – Column label for x column in output file. Default is x.

  • y_col_name (str, optional) – Column label for y column in output file. Default is y.

  • added_note (str, optional) – Add note to output file. Default is ‘’.

output_file_type

Type of file. Must be hdf5 or txt.

Type

str

Note

All args above are added as attributes.

Note

All kwargs above are added as attributes.

Note

kwargs from gwsnrcalc.genconutils.genprocess.GenProcess are also included for readout information. These are stored as attributes.

hdf5_read_out()

Read out an hdf5 file.

Takes the output of gwsnrcalc.genconutils.genprocess.GenProcess and reads it out to an HDF5 file.

txt_read_out()

Read out txt file.

Takes the output of gwsnrcalc.genconutils.genprocess.GenProcess and reads it out to a txt file.