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 creates 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.

The snr grid generator: gwsnrcalc.generate_contour_data.py 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/tree/master/snr_calculator_folder/

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

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, h5py, and matplotlib. 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

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. 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. run setup.py to add the modules to your environment and compile the c codes.
python ./setup.py install

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.0.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).

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 all of the arXiv papers above if you use this code in a publication.

class gwsnrcalc.gw_snr_calculator.SNR(ecc=False, **kwargs)

Bases: gwsnrcalc.utils.sensitivity.SensitivityContainer, gwsnrcalc.utils.parallel.ParallelContainer, gwsnrcalc.utils.pyphenomd.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_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.pyphenomd.__call__().
  • sensitivity_kwargs (dict) – Dicitonary carrying signal_type info and
  • phases (list of str) – Phases from which SNR is desired. Generated by sensitivity module.
  • prefactor (float) – Prefactor to multiply SNR by (not SNR^2).
  • num_points (int) – Number of points in the generated waveforms. More points will asympotically converge to correct SNR value. The waveforms are log-spaced to conserve memory.
  • 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 need to have the same shape, either scalar or 1D array. Start time (st), end time (et), and/or chi values can be scalars while the rest of the binary parameters are arrays.

Parameters:
Returns:

Signal-to-Noise Ratio dictionary for requested phases.

Return type:

(dict or list of dict)

pyphenomd 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).

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). It wraps the accompanying c code, phenomd/phenomd.c, with ctypes. 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.

class gwsnrcalc.utils.pyphenomd.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', use_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.
  • use_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.

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. 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(par_num, val, name, unit)

Add the fixed parameters for SNR calculation.

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

# TODO: remove same spin

Parameters:
  • val (float) – Value of parameter.
  • name (str) – Name representing the axis. See GenerateContainer documentation for options for the name.
  • unit (str) – Unit for this axis quantity. See GenerateContainer documentation for options for the units.
set_x_grid_info(x_low, x_high, num_x, xscale, xval_name, xval_unit)

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.
  • xval_unit (str) – Unit for this axis quantity. See GenerateContainer documentation for options for the units.
set_y_grid_info(y_low, y_high, num_y, yscale, yval_name, yval_unit)

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.
  • yval_unit (str) – Unit for this axis quantity. See GenerateContainer documentation for options for the units.
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_overall_dictionary()

Output dictionary for generate_contour_data.py input.

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

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

Returns:Dicitonary for input into generate_contour_data.py.
Return type:
  • output_dict (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.
  • output_file_type (str, optional) – File extension. Choices are hdf5 or txt. Default is hdf5.
Raises:

ValueError – File type is not txt or hdf5.

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.
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_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.
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 ctypes. 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:
  • ValueErrorlen(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.
  • fixed_parameter_1/fixed_parameter_1/fixed_parameter_1/fixed_parameter_1 (float) – Value for each fixed parameter.
  • par_1_unit/par_2_unit/par_3_unit/par_4_unit (str) – Unit for fixed parameters.
  • par_1_name/par_2_name/par_3_name/par_4_name (str) – Name of fixed parameters.
  • fixed_parameter_5 (float) – Value of fixed parameter 5. This is only optional if xval_name or yval_name is ‘spin’.
  • par_5_name (str) – Name of fixed parameter 5. This is only optional if xval_name or yval_name is ‘spin’.
  • par_5_name – Unit of fixed parameter 5. This is only optional if xval_name or yval_name is ‘spin’.
  • sensitivty_input (dict) – kwargs for gwsnrcalc.utils.sensitivity.SensitivityContainer.
  • snr_input (dict) – kwargs for gwsnrcalc.gw_snr_calculator.SNR.
total_mass

Total mass of each binary.

Type:1D array of floats
mass_ratio

Mass ratio of each binary.

Type:1D array of floats
m1

Mass 1 of each binary.

Type:1D array of floats
m2

Mass 2 of each binary.

Type:1D array of floats
z_or_dist

Redshift or distance of each binary.

Type:1D array of floats
spin_1

Spin of mass 1 of each binary.

Type:1D array of floats
spin_2

Spin of mass 2 of each binary.

Type:1D array of floats
start_time

Start time in years before merger of each binary.

Type:1D array of floats
total_mass

End time in years before merger of each binary.

Type:1D array of floats
dist_type

Which type of distance measure is used. Options are redshift, luminosity_distance, or comoving_distance.

Type:str
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.

txt_read_out()

Read out an txt file.