# pycbc.waveform package¶

## pycbc.waveform.bank module¶

This module provides classes that describe banks of waveforms

class pycbc.waveform.bank.FilterBank(filename, filter_length, delta_f, dtype, out=None, max_template_length=None, approximant=None, parameters=None, enable_compressed_waveforms=True, low_frequency_cutoff=None, waveform_decompression_method=None, **kwds)[source]
generate_with_delta_f_and_max_freq(t_num, max_freq, delta_f, low_frequency_cutoff=None, cached_mem=None)[source]

Generate the template with index t_num using custom length.

get_decompressed_waveform(tempout, index, f_lower=None, approximant=None, df=None)[source]

Returns a frequency domain decompressed waveform for the template in the bank corresponding to the index taken in as an argument. The decompressed waveform is obtained by interpolating in frequency space, the amplitude and phase points for the compressed template that are read in from the bank.

class pycbc.waveform.bank.FilterBankSkyMax(filename, filter_length, delta_f, dtype, out_plus=None, out_cross=None, max_template_length=None, parameters=None, low_frequency_cutoff=None, **kwds)[source]
class pycbc.waveform.bank.LIGOLWContentHandler(document, start_handlers={})[source]

Bases: glue.ligolw.ligolw.LIGOLWContentHandler

startColumn(parent, attrs)
startStream(parent, attrs, __orig_startStream=<function LIGOLWContentHandler.startStream>)
startTable(parent, attrs, __orig_startTable=<function use_in.<locals>.startTable>)
class pycbc.waveform.bank.LiveFilterBank(filename, sample_rate, minimum_buffer, approximant=None, increment=8, parameters=None, low_frequency_cutoff=None, **kwds)[source]
get_template(index, min_buffer=None)[source]
getslice(sindex)[source]
id_from_param(param_tuple)[source]

Get the index of this template based on its param tuple

Parameters: param_tuple (tuple) – Tuple of the parameters which uniquely identify this template index – The ordered index that this template has in the template bank. int
round_up(num)[source]

Determine the length to use for this waveform by rounding.

Parameters: num (int) – Proposed size of waveform in seconds size (int) – The rounded size to use for the waveform buffer in seconds. This is calculaed using an internal increment attribute, which determines the discreteness of the rounding.
class pycbc.waveform.bank.TemplateBank(filename, approximant=None, parameters=None, **kwds)[source]

Bases: object

Class to provide some basic helper functions and information about elements of a template bank.

Parameters: filename (string) – The name of the file to load. Must end in ‘.xml[.gz]’ or ‘.hdf’. If an hdf file, it should have a ‘parameters’ in its attrs which gives a list of the names of fields to load from the file. If no ‘parameters’ are found, all of the top-level groups in the file will assumed to be parameters (a warning will be printed to stdout in this case). If an xml file, it must have a SnglInspiral table. approximant ({None, (list of) string(s)}) – Specify the approximant(s) for each template in the bank. If None provided, will try to load the approximant from the file. The approximant may either be a single string (in which case the same approximant will be used for all templates) or a list of strings and conditionals specifying where to use the approximant. See boolargs_from_apprxstr for syntax. parameters ({None, (list of) sting(s)}) – Specify what parameters to load from the file. If None, all of the parameters in the file (if an xml file, this is all of the columns in the SnglInspiral table, if an hdf file, this is given by the parameters attribute in the file). The list may include parameters that are derived from the file’s parameters, or functions thereof. For a full list of possible parameters, see WaveformArray.default_fields. If a derived parameter is specified, only the parameters needed to compute that parameter will be loaded from the file. For example, if parameters=’mchirp’, then only mass1, mass2 will be loaded from the file. Note that derived parameters can only be used if the needed parameters are in the file; e.g., you cannot use chi_eff if spin1z, spin2z, mass1, and mass2 are in the input file. **kwds – Any additional keyword arguments are stored to the extra_args attribute.
table

An instance of a WaveformArray containing all of the information about the parameters of the bank.

Type: WaveformArray
has_compressed_waveforms

True if compressed waveforms are present in the the (hdf) file; False otherwise.

Type: {False, bool}
parameters

The parameters loaded from the input file. Same as table.fieldnames.

Type: tuple
indoc

If an xml file was provided, an in-memory representation of the xml. Otherwise, None.

Type: {None, xmldoc}
filehandler

If an hdf file was provided, the file handler pointing to the hdf file (left open after initialization). Otherwise, None.

Type: {None, h5py.File}
extra_args

Any extra keyword arguments that were provided on initialization.

Type: {None, dict}
approximant(index)[source]

Return the name of the approximant ot use at the given index

end_frequency(index)[source]

Return the end frequency of the waveform at the given index value

ensure_hash()[source]

Ensure that there is a correctly populated template_hash.

Check for a correctly populated template_hash and create if it doesn’t already exist.

ensure_standard_filter_columns(low_frequency_cutoff=None)[source]

Initialize FilterBank common fields

Parameters: low_frequency_cutoff ({float, None}, Optional) – A low frequency cutoff which overrides any given within the template bank file.
parameters
parse_approximant(approximant)[source]

Parses the given approximant argument, returning the approximant to use for each template in self. This is done by calling parse_approximant_arg using self’s table as the array; see that function for more details.

template_thinning(inj_filter_rejector)[source]

Remove templates from bank that are far from all injections.

write_to_hdf(filename, start_index=None, stop_index=None, force=False, skip_fields=None, write_compressed_waveforms=True)[source]

Writes self to the given hdf file.

Parameters: filename (str) – The name of the file to write to. Must end in ‘.hdf’. start_index (If a specific slice of the template bank is to be) – written to the hdf file, this would specify the index of the first template in the slice stop_index (If a specific slice of the template bank is to be) – written to the hdf file, this would specify the index of the last template in the slice force ({False, bool}) – If the file already exists, it will be overwritten if True. Otherwise, an OSError is raised if the file exists. skip_fields ({None, (list of) strings}) – Do not write the given fields to the hdf file. Default is None, in which case all fields in self.table.fieldnames are written. write_compressed_waveforms ({True, bool}) – Write compressed waveforms to the output (hdf) file if this is True, which is the default setting. If False, do not write the compressed waveforms group, but only the template parameters to the output file. The file handler to the output hdf file (left open). h5py.File

Adds an approximant argument to the given parser.

Parameters: parser (ArgumentParser) – The argument parser to add the argument to. default ({None, str}) – Specify a default for the approximant argument. Defaults to None. help ({None, str}) – Provide a custom help message. If None, will use a descriptive message on how to specify the approximant.
pycbc.waveform.bank.boolargs_from_apprxstr(approximant_strs)[source]

Parses a list of strings specifying an approximant and where that approximant should be used into a list that can be understood by FieldArray.parse_boolargs.

Parameters: apprxstr ((list of) string(s)) – The strings to parse. Each string should be formatted APPRX:COND, where APPRX is the approximant and COND is a string specifying where it should be applied (see FieldArgs.parse_boolargs for examples of conditional strings). The last string in the list may exclude a conditional argument, which is the same as specifying ‘:else’. boolargs – A list of tuples giving the approximant and where to apply them. This can be passed directly to FieldArray.parse_boolargs. list
pycbc.waveform.bank.find_variable_start_frequency(approximant, parameters, f_start, max_length, delta_f=1)[source]

Find a frequency value above the starting frequency that results in a waveform shorter than max_length.

pycbc.waveform.bank.parse_approximant_arg(approximant_arg, warray)[source]

Given an approximant arg (see add_approximant_arg) and a field array, figures out what approximant to use for each template in the array.

Parameters: approximant_arg (list) – The approximant argument to parse. Should be the thing returned by ArgumentParser when parsing the argument added by add_approximant_arg. warray (FieldArray) – The array to parse. Must be an instance of a FieldArray, or a class that inherits from FieldArray. A numpy array listing the approximants to use for each element in the warray. array
pycbc.waveform.bank.sigma_cached(self, psd)[source]

Cache sigma calculate for use in tandem with the FilterBank class

pycbc.waveform.bank.tuple_to_hash(tuple_to_be_hashed)[source]

Return a hash for a numpy array, avoids native (unsafe) python3 hash function

Parameters: tuple_to_be_hashed (tuple) – The tuple which is being hashed Must be convertible to a numpy array an integer representation of the hashed array int

## pycbc.waveform.compress module¶

Utilities for handling frequency compressed an unequally spaced frequency domain waveforms.

class pycbc.waveform.compress.CompressedWaveform(sample_points, amplitude, phase, interpolation=None, tolerance=None, mismatch=None, precision='double', load_to_memory=True)[source]

Bases: object

Class that stores information about a compressed waveform.

Parameters: sample_points ({array, h5py.Dataset}) – The frequency points at which the compressed waveform is sampled. amplitude ({array, h5py.Dataset}) – The amplitude of the waveform at the given sample_points. phase ({array, h5py.Dataset}) – The phase of the waveform at the given sample_points. interpolation ({None, str}) – The interpolation that was used when compressing the waveform for computing tolerance. This is also the default interpolation used when decompressing; see decompress for details. tolerance ({None, float}) – The tolerance that was used when compressing the waveform. mismatch ({None, float}) – The actual mismatch between the decompressed waveform (using the given interpolation) and the full waveform. precision ({'double', str}) – The precision used to generate the compressed waveform’s amplitude and phase points. Default is ‘double’. load_to_memory ({True, bool}) – If sample_points, amplitude, and/or phase is an hdf dataset, they will be cached in memory the first time they are accessed. Default is True.
sample_points
amplitude
phase

Whether or not to load sample_points/amplitude/phase into memory the first time they are accessed, if they are hdf datasets. Can be set directly to toggle this behavior.

Type: bool
interpolation

The interpolation that was used when compressing the waveform, for checking the mismatch. Also the default interpolation used when decompressing.

Type: str
tolerance

The tolerance that was used when compressing the waveform.

Type: {None, float}
mismatch

The mismatch between the decompressed waveform and the original waveform.

Type: {None, float}
precision

The precision used to generate and store the compressed waveform points. Options are ‘double’ or ‘single’; default is ‘double

Type: {‘double’, str}
amplitude

The amplitude of the waveform at the sample_points.

This is always returned as an array; the same logic as for sample_points is used to determine whether or not to cache in memory.

Returns: amplitude Array
clear_cache()[source]

Clear self’s cache of amplitude, phase, and sample_points.

decompress(out=None, df=None, f_lower=None, interpolation=None)[source]

Decompress self.

Parameters: out ({None, FrequencySeries}) – Write the decompressed waveform to the given frequency series. The decompressed waveform will have the same delta_f as out. Either this or df must be provided. df ({None, float}) – Decompress the waveform such that its delta_f has the given value. Either this or out must be provided. f_lower ({None, float}) – The starting frequency at which to decompress the waveform. Cannot be less than the minimum frequency in sample_points. If None provided, will default to the minimum frequency in sample_points. interpolation ({None, str}) – The interpolation to use for decompressing the waveform. If None provided, will default to self.interpolation. The decompressed waveform. FrequencySeries

Load a compressed waveform from the given hdf file handler.

The waveform is retrieved from: fp[‘[{root}/]compressed_waveforms/{template_hash}/{param}’], where param is the sample_points, amplitude, and phase.

Parameters: fp (h5py.File) – An open hdf file to write the compressed waveform to. template_hash ({hash, int, str}) – The id of the waveform. root ({None, str}) – Retrieve the compressed_waveforms group from the given string. If None, compressed_waveforms will be assumed to be in the top level. load_to_memory ({True, bool}) – Set the load_to_memory attribute to the given value in the returned instance. load_now ({False, bool}) – Immediately load the sample_points/amplitude/phase to memory. An instance of this class with parameters loaded from the hdf file. CompressedWaveform
phase

The phase of the waveform as the sample_points.

This is always returned as an array; the same logic as for sample_points returned as an array; the same logic as for sample_points is used to determine whether or not to cache in memory.

Returns: phase Array
sample_points

The frequencies at which the compressed waveform is sampled.

This is always returned as an array, even if the stored sample_points is an hdf dataset. If load_to_memory is True and the stored points are an hdf dataset, the sample_points will cached in memory the first time this attribute is accessed.

Returns: sample_points Array
write_to_hdf(fp, template_hash, root=None, precision=None)[source]

Write the compressed waveform to the given hdf file handler.

The waveform is written to: fp[‘[{root}/]compressed_waveforms/{template_hash}/{param}’], where param is the sample_points, amplitude, and phase. The interpolation, tolerance, mismatch and precision are saved to the group’s attributes.

Parameters: fp (h5py.File) – An open hdf file to write the compressed waveform to. template_hash ({hash, int, str}) – A hash, int, or string to map the template to the waveform. root ({None, str}) – Put the compressed_waveforms group in the given directory in the hdf file. If None, compressed_waveforms will be the root directory. precision ({None, str}) – Cast the saved parameters to the given precision before saving. If None provided, will use whatever their current precision is. This will raise an error if the parameters have single precision but the requested precision is double.
pycbc.waveform.compress.compress_waveform(htilde, sample_points, tolerance, interpolation, precision, decomp_scratch=None, psd=None)[source]

Retrieves the amplitude and phase at the desired sample points, and adds frequency points in order to ensure that the interpolated waveform has a mismatch with the full waveform that is <= the desired tolerance. The mismatch is computed by finding 1-overlap between htilde and the decompressed waveform; no maximimization over phase/time is done, a PSD may be used.

Note

The decompressed waveform is only garaunteed to have a true mismatch <= the tolerance for the given interpolation and for no PSD. However, since no maximization over time/phase is performed when adding points, the actual mismatch between the decompressed waveform and htilde is better than the tolerance, using no PSD. Using a PSD does increase the mismatch, and can lead to mismatches > than the desired tolerance, but typically by only a factor of a few worse.

Parameters: htilde (FrequencySeries) – The waveform to compress. sample_points (array) – The frequencies at which to store the amplitude and phase. More points may be added to this, depending on the desired tolerance. tolerance (float) – The maximum mismatch to allow between a decompressed waveform and htilde. interpolation (str) – The interpolation to use for decompressing the waveform when computing overlaps. precision (str) – The precision being used to generate and store the compressed waveform points. decomp_scratch ({None, FrequencySeries}) – Optionally provide scratch space for decompressing the waveform. The provided frequency series must have the same delta_f and length as htilde. psd ({None, FrequencySeries}) – The psd to use for calculating the overlap between the decompressed waveform and the original full waveform. The compressed waveform data; see CompressedWaveform for details. CompressedWaveform
pycbc.waveform.compress.fd_decompress(amp, phase, sample_frequencies, out=None, df=None, f_lower=None, interpolation='inline_linear')[source]

Decompresses an FD waveform using the given amplitude, phase, and the frequencies at which they are sampled at.

Parameters: amp (array) – The amplitude of the waveform at the sample frequencies. phase (array) – The phase of the waveform at the sample frequencies. sample_frequencies (array) – The frequency (in Hz) of the waveform at the sample frequencies. out ({None, FrequencySeries}) – The output array to save the decompressed waveform to. If this contains slots for frequencies > the maximum frequency in sample_frequencies, the rest of the values are zeroed. If not provided, must provide a df. df ({None, float}) – The frequency step to use for the decompressed waveform. Must be provided if out is None. f_lower ({None, float}) – The frequency to start the decompression at. If None, will use whatever the lowest frequency is in sample_frequencies. All values at frequencies less than this will be 0 in the decompressed waveform. interpolation ({'inline_linear', str}) – The interpolation to use for the amplitude and phase. Default is ‘inline_linear’. If ‘inline_linear’ a custom interpolater is used. Otherwise, scipy.interpolate.interp1d is used; for other options, see possible values for that function’s kind argument. out – If out was provided, writes to that array. Otherwise, a new FrequencySeries with the decompressed waveform. FrequencySeries
pycbc.waveform.compress.inline_linear_interp(amp, phase, sample_frequencies, output, df, f_lower, imin, start_index)[source]

Generate a frequency-domain waveform via linear interpolation from sampled amplitude and phase. The sample frequency locations for the amplitude and phase must be the same. This function may be less accurate than scipy’s linear interpolation, but should be much faster. Additionally, it is ‘schemed’ and so may run under either CPU or GPU schemes.

This function is not ordinarily called directly, but rather by giving the argument ‘interpolation’ the value ‘inline_linear’ when calling the function ‘fd_decompress’ below.

Parameters: amp (array) – The amplitude of the waveform at the sample frequencies. phase (array) – The phase of the waveform at the sample frequencies. sample_frequencies (array) – The frequency (in Hz) of the waveform at the sample frequencies. output ({None, FrequencySeries}) – The output array to save the decompressed waveform to. If this contains slots for frequencies > the maximum frequency in sample_frequencies, the rest of the values are zeroed. If not provided, must provide a df. df ({None, float}) – The frequency step to use for the decompressed waveform. Must be provided if out is None. f_lower (float) – The frequency to start the decompression at. All values at frequencies less than this will be 0 in the decompressed waveform. imin (int) – The index at which to start in the sampled frequency series. Must therefore be 0 <= imin < len(sample_frequencies) start_index (int) – The index at which to start in the output frequency; i.e., ceil(f_lower/df). output – If out was provided, writes to that array. Otherwise, a new FrequencySeries with the decompressed waveform. FrequencySeries
pycbc.waveform.compress.mchirp_compression(m1, m2, fmin, fmax, min_seglen=0.02, df_multiple=None)[source]

Return the frequencies needed to compress a waveform with the given chirp mass. This is based on the estimate in rough_time_estimate.

Parameters: m1 (float) – mass of first component object in solar masses m2 (float) – mass of second component object in solar masses fmin (float) – The starting frequency of the compressed waveform. fmax (float) – The ending frequency of the compressed waveform. min_seglen (float) – The inverse of this gives the maximum frequency step that is used. df_multiple ({None, float}) – Make the compressed sampling frequencies a multiple of the given value. If None provided, the returned sample points can have any floating point value. The frequencies at which to evaluate the compressed waveform. array
pycbc.waveform.compress.rough_time_estimate(m1, m2, flow, fudge_length=1.1, fudge_min=0.02)[source]

A very rough estimate of the duration of the waveform.

An estimate of the waveform duration starting from flow. This is intended to be fast but not necessarily accurate. It should be an overestimate of the length. It is derived from a simplification of the 0PN post-newtonian terms and includes a fudge factor for possible ringdown, etc.

Parameters: m1 (float) – mass of first component object in solar masses m2 (float) – mass of second component object in solar masses flow (float) – starting frequency of the waveform fudge_length (optional, {1.1, float}) – Factor to multiply length estimate by to ensure it is a convservative value fudge_min (optional, {0.2, float}) – Minimum signal duration that can be returned. This should be long enough to encompass the ringdown and errors in the precise end time. time – Time from flow untill the end of the waveform float
pycbc.waveform.compress.spa_compression(htilde, fmin, fmax, min_seglen=0.02, sample_frequencies=None)[source]

Returns the frequencies needed to compress the given frequency domain waveform. This is done by estimating t(f) of the waveform using the stationary phase approximation.

Parameters: htilde (FrequencySeries) – The waveform to compress. fmin (float) – The starting frequency of the compressed waveform. fmax (float) – The ending frequency of the compressed waveform. min_seglen (float) – The inverse of this gives the maximum frequency step that is used. sample_frequencies ({None, array}) – The frequencies that the waveform is evaluated at. If None, will retrieve the frequencies from the waveform’s sample_frequencies attribute. The frequencies at which to evaluate the compressed waveform. array
pycbc.waveform.compress.vecdiff(htilde, hinterp, sample_points, psd=None)[source]

Computes a statistic indicating between which sample points a waveform and the interpolated waveform differ the most.

## pycbc.waveform.decompress_cpu module¶

Utilities for handling frequency compressed an unequally spaced frequency domain waveforms.

pycbc.waveform.decompress_cpu.inline_linear_interp(amp, phase, sample_frequencies, output, df, f_lower, imin, start_index)[source]

## pycbc.waveform.decompress_cpu_cython module¶

pycbc.waveform.decompress_cpu_cython.decomp_ccode_double()
pycbc.waveform.decompress_cpu_cython.decomp_ccode_float()

## pycbc.waveform.generator module¶

This modules provides classes for generating waveforms.

class pycbc.waveform.generator.BaseCBCGenerator(generator, variable_args=(), **frozen_params)[source]

Adds ability to convert from various derived parameters to parameters needed by the waveform generators.

possible_args

The set of names of arguments that may be used in the variable_args or frozen_params.

Type: set
possible_args = {'amplitude_order', 'approximant', 'coa_phase', 'delta_f', 'delta_t', 'distance', 'dquad_mon1', 'dquad_mon2', 'eccentricity', 'eccentricity_order', 'f_final', 'f_final_func', 'f_lower', 'f_ref', 'frame_axis', 'inclination', 'lambda1', 'lambda2', 'lambda_octu1', 'lambda_octu2', 'long_asc_nodes', 'mass1', 'mass2', 'mean_per_ano', 'mode_array', 'modes_choice', 'numrel_data', 'octufmode1', 'octufmode2', 'phase_order', 'quadfmode1', 'quadfmode2', 'side_bands', 'spin1x', 'spin1y', 'spin1z', 'spin2x', 'spin2y', 'spin2z', 'spin_order', 'taper', 'tidal_order'}
class pycbc.waveform.generator.BaseGenerator(generator, variable_args=(), **frozen_params)[source]

Bases: object

A wrapper class to call a waveform generator with a set of frozen parameters and a set of variable parameters. The frozen parameters and values, along with a list of variable parameter names, are set at initialization. This way, repeated calls can be made to the underlying generator by simply passing a list of values for the variable parameters to this class’s generate function.

Parameters: generator (function) – The function that is called for waveform generation. variable_args ({(), list}) – A tuple or list of strings giving the names and order of variable parameters that will be passed to the waveform generator when the generate function is called. **frozen_params – These keyword arguments are the ones that will be frozen in the waveform generator. For a list of possible parameters, see pycbc.waveform.cbc_parameters.
generator

The function that is called for waveform generation.

Type: function
variable_args

The list of names of variable arguments.

Type: tuple
frozen_params

A dictionary of the frozen keyword arguments that are always passed to the waveform generator function.

Type: dict
current_params

A dictionary of the frozen keyword arguments and variable arguments that were last passed to the waveform generator.

Type: dict
generate(variable_values)[source]

Generates a waveform using the variable arguments and the frozen arguments.

generate(**kwargs)[source]

Generates a waveform from the keyword args. The current params are updated with the given kwargs, then the generator is called.

static_args

Returns a dictionary of the static arguments.

class pycbc.waveform.generator.FDomainCBCGenerator(variable_args=(), **frozen_params)[source]

Generates frequency-domain CBC waveforms in the radiation frame.

Uses waveform.get_fd_waveform as a generator function to create frequency- domain CBC waveforms in the radiation frame; i.e., with no detector response function applied. For more details, see BaseGenerator.

Derived parameters not understood by get_fd_waveform may be used as variable args and/or frozen parameters, as long as they can be converted into parameters that get_fd_waveform can use. For example, mchirp and eta (currently, the only supported derived parameters) may be used as variable/frozen params; these are converted to mass1 and mass2 prior to calling the waveform generator function.

Examples

Initialize a generator:

>>> from pycbc.waveform.generator import FDomainCBCGenerator
>>> generator = FDomainCBCGenerator(variable_args=['mass1', 'mass2'], delta_f=1./32, f_lower=30., approximant='TaylorF2')

Create a waveform with the variable arguments (in this case, mass1, mass2):

>>> generator.generate(mass1=1.4, mass2=1.4)
(<pycbc.types.frequencyseries.FrequencySeries at 0x1110c1450>,
<pycbc.types.frequencyseries.FrequencySeries at 0x1110c1510>)

Initialize a generator using mchirp, eta as the variable args, and generate a waveform:

>>> generator = FDomainCBCGenerator(variable_args=['mchirp', 'eta'], delta_f=1./32, f_lower=30., approximant='TaylorF2')
>>> generator.generate(mchirp=1.5, eta=0.25)
(<pycbc.types.frequencyseries.FrequencySeries at 0x109a104d0>,
<pycbc.types.frequencyseries.FrequencySeries at 0x109a10b50>)

Note that the current_params contains the mchirp and eta values, along with the mass1 and mass2 they were converted to:

>>> generator.current_params
{'approximant': 'TaylorF2',
'delta_f': 0.03125,
'eta': 0.25,
'f_lower': 30.0,
'mass1': 1.7230475324955525,
'mass2': 1.7230475324955525,
'mchirp': 1.5}
class pycbc.waveform.generator.FDomainDetFrameGenerator(rFrameGeneratorClass, epoch, detectors=None, variable_args=(), recalib=None, gates=None, **frozen_params)[source]

Bases: object

Generates frequency-domain waveform in a specific frame.

Generates a waveform using the given radiation frame generator class, and applies the detector response function and appropriate time offset.

Parameters: rFrameGeneratorClass (class) – The class to use for generating the waveform in the radiation frame, e.g., FDomainCBCGenerator. This should be the class, not an instance of the class (the class will be initialized with the appropriate arguments internally). detectors ({None, list of strings}) – The names of the detectors to use. If provided, all location parameters must be included in either the variable args or the frozen params. If None, the generate function will just return the plus polarization returned by the rFrameGeneratorClass shifted by any desired time shift. epoch ({float, lal.LIGOTimeGPS) – The epoch start time to set the waveform to. A time shift = tc - epoch is applied to waveforms before returning. variable_args ({(), list or tuple}) – A list or tuple of strings giving the names and order of parameters that will be passed to the generate function. **frozen_params – Keyword arguments setting the parameters that will not be changed from call-to-call of the generate function.
location_args

The set of location parameters. These are not passed to the rFrame generator class; instead, they are used to apply the detector response function and/or shift the waveform in time. The parameters are:

• tc: The GPS time of coalescence (should be geocentric time).
• ra: Right ascension.
• dec: declination
• polarization: polarization.

All of these must be provided in either the variable args or the frozen params if detectors is not None. If detectors is None, tc may optionally be provided.

Type: set([‘tc’, ‘ra’, ‘dec’, ‘polarization’])
detectors

The dictionary of detectors that antenna patterns are calculated for on each call of generate. If no detectors were provided, will be {'RF': None}, where “RF” means “radiation frame”.

Type: dict
detector_names

The list of detector names. If no detectors were provided, then this will be [‘RF’] for “radiation frame”.

Type: list
epoch

The GPS start time of the frequency series returned by the generate function. A time shift is applied to the waveform equal to tc-epoch. Update by using set_epoch.

Type: lal.LIGOTimeGPS
current_params

A dictionary of name, value pairs of the arguments that were last used by the generate function.

Type: dict
rframe_generator

The instance of the radiation-frame generator that is used for waveform generation. All parameters in current_params except for the location params are passed to this class’s generate function.

Type: instance of rFrameGeneratorClass
frozen_location_args

Any location parameters that were included in the frozen_params.

Type: dict
variable_args

The list of names of arguments that are passed to the generate function.

Type: tuple

Examples

Initialize a generator:

>>> from pycbc.waveform.generator import FDomainDetFrameGenerator
>>> generator = FDomainDetFrameGenerator(waveform.FDomainCBCGenerator, 0., variable_args=['mass1', 'mass2', 'spin1z', 'spin2z', 'tc', 'ra', 'dec', 'polarization'], detectors=['H1', 'L1'], delta_f=1./64, f_lower=20., approximant='SEOBNRv2_ROM_DoubleSpin')

Generate a waveform:

>>> generator.generate(mass1=38.6, mass2=29.3, spin1z=0.33, spin2z=-0.94, tc=2.43, ra=1.37, dec=-1.26, polarization=2.76)
{'H1': <pycbc.types.frequencyseries.FrequencySeries at 0x116637350>,
'L1': <pycbc.types.frequencyseries.FrequencySeries at 0x116637a50>}
epoch
generate(**kwargs)[source]

Generates a waveform, applies a time shift and the detector response function from the given kwargs.

location_args = {'dec', 'polarization', 'ra', 'tc'}
set_epoch(epoch)[source]

Sets the epoch; epoch should be a float or a LIGOTimeGPS.

static_args

Returns a dictionary of the static arguments.

class pycbc.waveform.generator.FDomainFreqTauRingdownGenerator(variable_args=(), **frozen_params)[source]

Uses ringdown.get_fd_from_freqtau as a generator function to create frequency-domain ringdown waveforms with higher modes in the radiation frame; i.e., with no detector response function applied. For more details, see BaseGenerator.

Examples

Initialize a generator:

>>> from pycbc.waveform.generator import FDomainFreqTauRingdownGenerator
>>> generator = FDomainFreqTauRingdownGenerator(variable_args=['f_220',
'tau_220','f_210','tau_210','amp220','amp210','phi220','phi210'],
lmns=['221','211'], delta_f=1./32, f_lower=30., f_final=500)

Create a ringdown with the variable arguments:

>>> generator.generate(f_220=317., tau_220=0.003, f_210=274., tau_210=0.003,
amp220=1e-21, amp210=1./10, phi220=0., phi210=0.)
(<pycbc.types.frequencyseries.FrequencySeries at 0x51614d0>,
<pycbc.types.frequencyseries.FrequencySeries at 0x5161550>)
class pycbc.waveform.generator.FDomainMassSpinRingdownGenerator(variable_args=(), **frozen_params)[source]

Uses ringdown.get_fd_from_final_mass_spin as a generator function to create frequency-domain ringdown waveforms with higher modes in the radiation frame; i.e., with no detector response function applied. For more details, see BaseGenerator.

Examples

Initialize a generator:

>>> from pycbc.waveform.generator import FDomainMassSpinRingdownGenerator
>>> generator = FDomainMassSpinRingdownGenerator(variable_args=['final_mass',
'final_spin','amp220','amp210','phi220','phi210'], lmns=['221','211'],
delta_f=1./32, f_lower=30., f_final=500)

Create a ringdown with the variable arguments:

>>> generator.generate(final_mass=65., final_spin=0.7,
amp220=1e-21, amp210=1./10, phi220=0., phi210=0.)
(<pycbc.types.frequencyseries.FrequencySeries at 0x51614d0>,
<pycbc.types.frequencyseries.FrequencySeries at 0x5161550>)
class pycbc.waveform.generator.TDomainCBCGenerator(variable_args=(), **frozen_params)[source]

Create time domain CBC waveforms in the radiation frame.

Uses waveform.get_td_waveform as a generator function to create time- domain CBC waveforms in the radiation frame; i.e., with no detector response function applied. For more details, see BaseGenerator.

Derived parameters not understood by get_td_waveform may be used as variable args and/or frozen parameters, as long as they can be converted into parameters that get_td_waveform can use. For example, mchirp and eta (currently, the only supported derived parameters) may be used as variable/frozen params; these are converted to mass1 and mass2 prior to calling the waveform generator function.

Examples

Initialize a generator:

>>> from pycbc.waveform.generator import TDomainCBCGenerator
>>> generator = TDomainCBCGenerator(variable_args=['mass1', 'mass2'], delta_t=1./4096, f_lower=30., approximant='TaylorT4')

Create a waveform with the variable arguments (in this case, mass1, mass2):

>>> generator.generate(mass1=2., mass2=1.3)
(<pycbc.types.timeseries.TimeSeries at 0x10e546710>,
<pycbc.types.timeseries.TimeSeries at 0x115f37690>)

Initialize a generator using mchirp, eta as the variable args, and generate a waveform:

>>> generator = TDomainCBCGenerator(variable_args=['mchirp', 'eta'], delta_t=1./4096, f_lower=30., approximant='TaylorT4')
>>> generator.generate(mchirp=1.75, eta=0.2)
(<pycbc.types.timeseries.TimeSeries at 0x116ac6050>,
<pycbc.types.timeseries.TimeSeries at 0x116ac6950>)
class pycbc.waveform.generator.TDomainFreqTauRingdownGenerator(variable_args=(), **frozen_params)[source]

Uses ringdown.get_td_from_freqtau as a generator function to create time-domain ringdown waveforms with higher modes in the radiation frame; i.e., with no detector response function applied. For more details, see BaseGenerator.

Examples

Initialize a generator:

>>> from pycbc.waveform.generator import FDomainFreqTauRingdownGenerator
>>> generator = TDomainFreqTauRingdownGenerator(variable_args=['f_220',
'tau_220','f_210','tau_210','amp220','amp210','phi220','phi210'],
lmns=['221','211'], delta_t=1./2048)

Create a ringdown with the variable arguments:

>>> generator.generate(f_220=317., tau_220=0.003, f_210=274., tau_210=0.003,
amp220=1e-21, amp210=1./10, phi220=0., phi210=0.)
(<pycbc.types.frequencyseries.FrequencySeries at 0x51614d0>,
<pycbc.types.frequencyseries.FrequencySeries at 0x5161550>)
class pycbc.waveform.generator.TDomainMassSpinRingdownGenerator(variable_args=(), **frozen_params)[source]

Uses ringdown.get_td_from_final_mass_spin as a generator function to create time-domain ringdown waveforms with higher modes in the radiation frame; i.e., with no detector response function applied. For more details, see BaseGenerator.

Examples

Initialize a generator:

>>> from pycbc.waveform.generator import TDomainMassSpinRingdownGenerator
>>> generator = TDomainMassSpinRingdownGenerator(variable_args=['final_mass',
'final_spin','amp220','amp210','phi220','phi210'], lmns=['221','211'],
delta_t=1./2048)

Create a ringdown with the variable arguments:

>>> generator.generate(final_mass=65., final_spin=0.7,
amp220=1e-21, amp210=1./10, phi220=0., phi210=0.)
(<pycbc.types.frequencyseries.FrequencySeries at 0x51614d0>,
<pycbc.types.frequencyseries.FrequencySeries at 0x5161550>)
pycbc.waveform.generator.select_waveform_generator(approximant)[source]

Returns the single-IFO generator for the approximant.

Parameters: approximant (str) – Name of waveform approximant. Valid names can be found using pycbc.waveform methods. generator – A waveform generator object. (PyCBC generator instance)

Examples

Get a list of available approximants: >>> from pycbc import waveform >>> waveform.fd_approximants() >>> waveform.td_approximants() >>> from pycbc.waveform import ringdown >>> ringdown.ringdown_fd_approximants.keys()

Get generator object: >>> from pycbc.waveform.generator import select_waveform_generator >>> select_waveform_generator(waveform.fd_approximants()[0])

## pycbc.waveform.nltides module¶

Utilities for introducing nonlinear tidal effects into waveform approximants

pycbc.waveform.nltides.nltides_fourier_phase_difference(f, delta_f, f0, amplitude, n, m1, m2)[source]

Calculate the change to the Fourier phase change due to non-linear tides. Note that the Fourier phase Psi(f) is not the same as the gravitational-wave phase phi(f) and is computed by Delta Psi(f) = 2 pi f Delta t(f) - Delta phi(f)

Parameters: f (numpy.array) – Array of frequency values to calculate the fourier phase difference delta_f (float) – Frequency resolution of f array f0 (float) – Frequency that NL effects switch on amplitude (float) – Amplitude of effect n (float) – Growth dependence of effect m1 (float) – Mass of component 1 m2 (float) – Mass of component 2 delta_psi – Fourier phase as a function of frequency numpy.array
pycbc.waveform.nltides.nonlinear_tidal_spa(**kwds)[source]

Generates a frequency-domain waveform that implements the TaylorF2+NL tide model described in https://arxiv.org/abs/1808.07013

## pycbc.waveform.parameters module¶

Classes to define common parameters used for waveform generation.

class pycbc.waveform.parameters.Parameter[source]

Bases: str

A class that stores information about a parameter. This is done by sub-classing string, adding additional attributes.

docstr(prefix='', include_label=True)[source]

Returns a string summarizing the parameter. Format is: <prefix>name : {default, dtype} <prefix> description Label: label.

class pycbc.waveform.parameters.ParameterList(initlist=None)[source]

Bases: collections.UserList

A list of parameters. Each element in the list is expected to be a Parameter instance.

asdict

Returns a dictionary of the parameters keyed by the parameters.

aslist

Cast to basic list.

default_dict()[source]

Returns a dictionary of the name and default value of each parameter.

defaults()[source]

Returns a list of the name and default value of each parameter, as tuples.

description_dict

Return a dictionary of the name and description of each parameter.

descriptions

Returns a list of the name and description of each parameter, as tuples.

docstr(prefix='', include_label=True)[source]

Returns the docstr of each parameter joined together.

dtype_dict

Returns a dictionary of the name and dtype of each parameter.

dtypes

Returns a list of the name and dtype of each parameter, as tuples.

label_dict

Return a dictionary of the name and label of each parameter.

labels

Returns a list of each parameter and its label, as tuples.

names

Returns a list of the names of each parameter.

nodefaults

Returns a ParameterList of the parameters that have None for defaults.

## pycbc.waveform.plugin module¶

Utilities for handling waveform plugins

Make custom waveform available to pycbc

Parameters: approximant (str) – The name of the waveform function (function) – The function to generate the waveform domain : str Either ‘frequency’ or ‘time’ to indicate the domain of the waveform.

Add length estimator for an approximant

Parameters: approximant (str) – Name of approximant function (function) – A function which takes kwargs and returns the waveform length
pycbc.waveform.plugin.retrieve_waveform_plugins()[source]

Process external waveform plugins

## pycbc.waveform.premerger module¶

Waveform approximants for the pre-merger detection of gravitational waves

pycbc.waveform.premerger.premerger_taylorf2(**p)[source]

Generate time-shifted TaylorF2

## pycbc.waveform.ringdown module¶

Generate ringdown templates in the time and frequency domain.

pycbc.waveform.ringdown.Kerr_factor(final_mass, distance)[source]

Return the factor final_mass/distance (in dimensionless units) for Kerr ringdowns

pycbc.waveform.ringdown.apply_taper(tau, amp, phi, delta_t, l=2, m=2, inclination=None)[source]

Return a tapering window of the form exp(10*t/tau).

pycbc.waveform.ringdown.fd_damped_sinusoid(f_0, tau, amp, phi, delta_f, f_lower, f_final, t_0=0.0, l=2, m=2, inclination=None)[source]

Return a frequency domain damped sinusoid (plus and cross polarizations) with central frequency f_0, damping time tau, amplitude amp and phase phi. The l, m, and inclination parameters are used for the spherical harmonics.

pycbc.waveform.ringdown.fd_output_vector(freqs, damping_times, delta_f=None, f_final=None)[source]

Return an empty FrequencySeries with the appropriate size to fit all the quasi-normal modes present in freqs, damping_times

pycbc.waveform.ringdown.format_lmns(lmns)[source]

Checks if the format of the parameter lmns is correct, returning the appropriate format if not, and raise an error if nmodes=0. The required format for the ringdown approximants is a list of lmn modes as strings, with n the number of overtones desired. For instance, lmns = [‘223’,’331’] are the modes 220, 221, 222, and 330. The ConfigParser of a workflow might convert that to a single string (case 1 below) or a list with a single string (case 2), and this function will return the appropriate list of strings. If a different format is given, raise an error.

pycbc.waveform.ringdown.get_fd_from_final_mass_spin(template=None, **kwargs)[source]

Return frequency domain ringdown with all the modes specified.

Parameters: template (object) – An object that has attached properties. This can be used to substitute for keyword arguments. A common example would be a row in an xml table. distance ({None, float}, optional) – Luminosity distance of the system. If specified, the returned ringdown will include the Kerr factor (final_mass/distance). final_mass (float) – Mass of the final black hole in solar masses. final_spin (float) – Dimensionless spin of the final black hole. lmns (list) – Desired lmn modes as strings (lm modes available: 22, 21, 33, 44, 55). The n specifies the number of overtones desired for the corresponding lm pair (maximum n=8). Example: lmns = [‘223’,’331’] are the modes 220, 221, 222, and 330 amp220 (float) – Amplitude of the fundamental 220 mode. Always required, even if 220 mode has not been selected. Note that if distance is given, this parameter will have a completely different order of magnitude. See table II in https://arxiv.org/abs/1107.0854 for an estimate. amplmn (float) – Fraction of the amplitude of the lmn overtone relative to the fundamental mode, i.e. amplmn/amp220. Provide as many as the number of selected subdominant modes. philmn (float) – Phase of the lmn overtone, as many as the number of modes. Should also include the information from the azimuthal angle, philmn=(phi + m*Phi). inclination (float) – Inclination of the system in radians (for the spherical harmonics). delta_f ({None, float}, optional) – The frequency step used to generate the ringdown. If None, it will be set to the inverse of the time at which the amplitude is 1/1000 of the peak amplitude (the minimum of all modes). f_lower ({None, float}, optional) – The starting frequency of the output frequency series. If None, it will be set to delta_f. f_final ({None, float}, optional) – The ending frequency of the output frequency series. If None, it will be set to the frequency at which the amplitude is 1/1000 of the peak amplitude (the maximum of all modes). hplustile (FrequencySeries) – The plus phase of a ringdown with the lm modes specified and n overtones in frequency domain. hcrosstilde (FrequencySeries) – The cross phase of a ringdown with the lm modes specified and n overtones in frequency domain.
pycbc.waveform.ringdown.get_fd_from_freqtau(template=None, **kwargs)[source]

Return frequency domain ringdown with all the modes specified.

Parameters: template (object) – An object that has attached properties. This can be used to substitute for keyword arguments. A common example would be a row in an xml table. lmns (list) – Desired lmn modes as strings (lm modes available: 22, 21, 33, 44, 55). The n specifies the number of overtones desired for the corresponding lm pair (maximum n=8). Example: lmns = [‘223’,’331’] are the modes 220, 221, 222, and 330 f_lmn (float) – Central frequency of the lmn overtone, as many as number of modes. tau_lmn (float) – Damping time of the lmn overtone, as many as number of modes. amp220 (float) – Amplitude of the fundamental 220 mode. Always required, even if 220 mode has not been selected. amplmn (float) – Fraction of the amplitude of the lmn overtone relative to the fundamental mode, i.e. amplmn/amp220. Provide as many as the number of selected subdominant modes. philmn (float) – Phase of the lmn overtone, as many as the number of modes. Should also include the information from the azimuthal angle (phi + m*Phi). inclination ({None, float}, optional) – Inclination of the system in radians. If None, the spherical harmonics will be set to 1. delta_f ({None, float}, optional) – The frequency step used to generate the ringdown. If None, it will be set to the inverse of the time at which the amplitude is 1/1000 of the peak amplitude (the minimum of all modes). f_lower ({None, float}, optional) – The starting frequency of the output frequency series. If None, it will be set to delta_f. f_final ({None, float}, optional) – The ending frequency of the output frequency series. If None, it will be set to the frequency at which the amplitude is 1/1000 of the peak amplitude (the maximum of all modes). hplustilde (FrequencySeries) – The plus phase of a ringdown with the lm modes specified and n overtones in frequency domain. hcrosstilde (FrequencySeries) – The cross phase of a ringdown with the lm modes specified and n overtones in frequency domain.
pycbc.waveform.ringdown.get_td_from_final_mass_spin(template=None, **kwargs)[source]

Return time domain ringdown with all the modes specified.

Parameters: template (object) – An object that has attached properties. This can be used to substitute for keyword arguments. A common example would be a row in an xml table. taper ({False, bool}, optional) – Add a rapid ringup with timescale tau/10 at the beginning of the waveform to avoid the abrupt turn on of the ringdown. Each mode and overtone will have a different taper depending on its tau, the final taper being the superposition of all the tapers. distance ({None, float}, optional) – Luminosity distance of the system. If specified, the returned ringdown will include the Kerr factor (final_mass/distance). final_mass (float) – Mass of the final black hole in solar masses. final_spin (float) – Dimensionless spin of the final black hole. lmns (list) – Desired lmn modes as strings (lm modes available: 22, 21, 33, 44, 55). The n specifies the number of overtones desired for the corresponding lm pair (maximum n=8). Example: lmns = [‘223’,’331’] are the modes 220, 221, 222, and 330 amp220 (float) – Amplitude of the fundamental 220 mode. Always required, even if 220 mode has not been selected. Note that if distance is given, this parameter will have a completely different order of magnitude. See table II in https://arxiv.org/abs/1107.0854 for an estimate. amplmn (float) – Fraction of the amplitude of the lmn overtone relative to the fundamental mode, i.e. amplmn/amp220. Provide as many as the number of selected subdominant modes. philmn (float) – Phase of the lmn overtone, as many as the number of modes. Should also include the information from the azimuthal angle, philmn=(phi + m*Phi). inclination (float) – Inclination of the system in radians (for the spherical harmonics). delta_t ({None, float}, optional) – The time step used to generate the ringdown. If None, it will be set to the inverse of the frequency at which the amplitude is 1/1000 of the peak amplitude (the minimum of all modes). t_final ({None, float}, optional) – The ending time of the output frequency series. If None, it will be set to the time at which the amplitude is 1/1000 of the peak amplitude (the maximum of all modes). hplus (TimeSeries) – The plus phase of a ringdown with the lm modes specified and n overtones in time domain. hcross (TimeSeries) – The cross phase of a ringdown with the lm modes specified and n overtones in time domain.
pycbc.waveform.ringdown.get_td_from_freqtau(template=None, **kwargs)[source]

Return time domain ringdown with all the modes specified.

Parameters: template (object) – An object that has attached properties. This can be used to substitute for keyword arguments. A common example would be a row in an xml table. taper ({False, bool}, optional) – Add a rapid ringup with timescale tau/10 at the beginning of the waveform to avoid the abrupt turn on of the ringdown. Each mode and overtone will have a different taper depending on its tau, the final taper being the superposition of all the tapers. lmns (list) – Desired lmn modes as strings (lm modes available: 22, 21, 33, 44, 55). The n specifies the number of overtones desired for the corresponding lm pair (maximum n=8). Example: lmns = [‘223’,’331’] are the modes 220, 221, 222, and 330 f_lmn (float) – Central frequency of the lmn overtone, as many as number of modes. tau_lmn (float) – Damping time of the lmn overtone, as many as number of modes. amp220 (float) – Amplitude of the fundamental 220 mode. Note that if distance is given, this parameter will have a completely different order of magnitude. See table II in https://arxiv.org/abs/1107.0854 for an estimate. Always required, even if 220 mode has not been selected. amplmn (float) – Fraction of the amplitude of the lmn overtone relative to the fundamental mode, i.e. amplmn/amp220. Provide as many as the number of selected subdominant modes. philmn (float) – Phase of the lmn overtone, as many as the number of modes. Should also include the information from the azimuthal angle, philmn=(phi + m*Phi). inclination (float) – Inclination of the system in radians (for the spherical harmonics). If None, the spherical harmonics will be set to 1. delta_t ({None, float}, optional) – The time step used to generate the ringdown. If None, it will be set to the inverse of the frequency at which the amplitude is 1/1000 of the peak amplitude (the minimum of all modes). t_final ({None, float}, optional) – The ending time of the output frequency series. If None, it will be set to the time at which the amplitude is 1/1000 of the peak amplitude (the maximum of all modes). hplus (TimeSeries) – The plus phase of a ringdown with the lm modes specified and n overtones in time domain. hcross (TimeSeries) – The cross phase of a ringdown with the lm modes specified and n overtones in time domain.
pycbc.waveform.ringdown.lm_amps_phases(**kwargs)[source]

Take input_params and return dictionaries with amplitudes and phases of each overtone of a specific lm mode, checking that all of them are given.

pycbc.waveform.ringdown.lm_deltaf(damping_times)[source]

Return the minimum delta_f of all the modes given, with delta_f given by the inverse of the time at which the amplitude of the ringdown falls to 1/1000 of the peak amplitude.

pycbc.waveform.ringdown.lm_deltat(freqs, damping_times)[source]

Return the minimum delta_t of all the modes given, with delta_t given by the inverse of the frequency at which the amplitude of the ringdown falls to 1/1000 of the peak amplitude.

pycbc.waveform.ringdown.lm_ffinal(freqs, damping_times)[source]

Return the maximum f_final of the modes given, with f_final the frequency at which the amplitude falls to 1/1000 of the peak amplitude

pycbc.waveform.ringdown.lm_freqs_taus(**kwargs)[source]

Take input_params and return dictionaries with frequencies and damping times of each overtone of a specific lm mode, checking that all of them are given.

pycbc.waveform.ringdown.lm_tfinal(damping_times)[source]

Return the maximum t_final of the modes given, with t_final the time at which the amplitude falls to 1/1000 of the peak amplitude

pycbc.waveform.ringdown.multimode_base(input_params)[source]

Return a superposition of damped sinusoids in either time or frequency domains with parameters set by input_params.

pycbc.waveform.ringdown.props(obj, required, domain_args, **kwargs)[source]

Return a dictionary built from the combination of defaults, kwargs, and the attributes of the given object.

pycbc.waveform.ringdown.qnm_freq_decay(f_0, tau, decay)[source]

Return the frequency at which the amplitude of the ringdown falls to decay of the peak amplitude.

Parameters: f_0 (float) – The ringdown-frequency, which gives the peak amplitude. tau (float) – The damping time of the sinusoid. decay (float) – The fraction of the peak amplitude. f_decay – The frequency at which the amplitude of the frequency-domain ringdown falls to decay of the peak amplitude. float
pycbc.waveform.ringdown.qnm_time_decay(tau, decay)[source]

Return the time at which the amplitude of the ringdown falls to decay of the peak amplitude.

Parameters: tau (float) – The damping time of the sinusoid. decay (float) – The fraction of the peak amplitude. t_decay – The time at which the amplitude of the time-domain ringdown falls to decay of the peak amplitude. float
pycbc.waveform.ringdown.spher_harms(l, m, inclination)[source]

Return spherical harmonic polarizations

pycbc.waveform.ringdown.td_damped_sinusoid(f_0, tau, amp, phi, delta_t, t_final, l=2, m=2, inclination=None)[source]

Return a time domain damped sinusoid (plus and cross polarizations) with central frequency f_0, damping time tau, amplitude amp and phase phi. The l, m, and inclination parameters are used for the spherical harmonics.

pycbc.waveform.ringdown.td_output_vector(freqs, damping_times, taper=False, delta_t=None, t_final=None)[source]

Return an empty TimeSeries with the appropriate size to fit all the quasi-normal modes present in freqs, damping_times

## pycbc.waveform.sinegauss module¶

Generation of sine-Gaussian bursty type things

pycbc.waveform.sinegauss.fd_sine_gaussian(amp, quality, central_frequency, fmin, fmax, delta_f)[source]

Generate a Fourier domain sine-Gaussian

Parameters: amp (float) – Amplitude of the sine-Gaussian quality (float) – The quality factor central_frequency (float) – The central frequency of the sine-Gaussian fmin (float) – The minimum frequency to generate the sine-Gaussian. This determines the length of the output vector. fmax (float) – The maximum frequency to generate the sine-Gaussian delta_f (float) – The size of the frequency step sg – A Fourier domain sine-Gaussian pycbc.types.Frequencyseries

## pycbc.waveform.spa_tmplt module¶

This module contains functions for generating common SPA template precalculated vectors.

pycbc.waveform.spa_tmplt.findchirp_chirptime(m1, m2, fLower, porder)[source]
pycbc.waveform.spa_tmplt.spa_amplitude_factor(**kwds)[source]
pycbc.waveform.spa_tmplt.spa_distance(psd, mass1, mass2, lower_frequency_cutoff, snr=8)[source]

Return the distance at a given snr (default=8) of the SPA TaylorF2 template.

pycbc.waveform.spa_tmplt.spa_length_in_time(**kwds)[source]

Returns the length in time of the template, based on the masses, PN order, and low-frequency cut-off.

pycbc.waveform.spa_tmplt.spa_tmplt(**kwds)[source]

Generate a minimal TaylorF2 approximant with optimizations for the sin/cos

pycbc.waveform.spa_tmplt.spa_tmplt_end(**kwds)[source]
pycbc.waveform.spa_tmplt.spa_tmplt_engine(htilde, kmin, phase_order, delta_f, piM, pfaN, pfa2, pfa3, pfa4, pfa5, pfl5, pfa6, pfl6, pfa7, amp_factor)[source]

Calculate the spa tmplt phase

pycbc.waveform.spa_tmplt.spa_tmplt_norm(psd, length, delta_f, f_lower)[source]
pycbc.waveform.spa_tmplt.spa_tmplt_precondition(length, delta_f, kmin=0)[source]

Return the amplitude portion of the TaylorF2 approximant, used to precondition the strain data. The result is cached, and so should not be modified only read.

## pycbc.waveform.spa_tmplt_cpu module¶

pycbc.waveform.spa_tmplt_cpu.cbrt_lookup()
pycbc.waveform.spa_tmplt_cpu.get_cbrt()
pycbc.waveform.spa_tmplt_cpu.get_log()
pycbc.waveform.spa_tmplt_cpu.logv_lookup()
pycbc.waveform.spa_tmplt_cpu.spa_tmplt_engine()

Calculate the spa tmplt phase

pycbc.waveform.spa_tmplt_cpu.spa_tmplt_inline_sequence()

## pycbc.waveform.utils module¶

This module contains convenience utilities for manipulating waveforms

pycbc.waveform.utils.amplitude_from_frequencyseries(htilde)[source]

Returns the amplitude of the given frequency-domain waveform as a FrequencySeries.

Parameters: htilde (FrequencySeries) – The waveform to get the amplitude of. The amplitude of the waveform as a function of frequency. FrequencySeries
pycbc.waveform.utils.amplitude_from_polarizations(h_plus, h_cross)[source]

Return gravitational wave amplitude

Return the gravitation-wave amplitude from the h_plus and h_cross polarizations of the waveform.

Parameters: h_plus (TimeSeries) – An PyCBC TmeSeries vector that contains the plus polarization of the gravitational waveform. h_cross (TimeSeries) – A PyCBC TmeSeries vector that contains the cross polarization of the gravitational waveform. GWAmplitude – A TimeSeries containing the gravitational wave amplitude. TimeSeries

Examples

>>> from pycbc.waveform import get_td_waveform, phase_from_polarizations
>>> hp, hc = get_td_waveform(approximant="TaylorT4", mass1=10, mass2=10,
f_lower=30, delta_t=1.0/4096)
>>> amp = amplitude_from_polarizations(hp, hc)
pycbc.waveform.utils.apply_fd_time_shift(htilde, shifttime, kmin=0, fseries=None, copy=True)[source]

Shifts a frequency domain waveform in time. The shift applied is shiftime - htilde.epoch.

Parameters: htilde (FrequencySeries) – The waveform frequency series. shifttime (float) – The time to shift the frequency series to. kmin ({0, int}) – The starting index of htilde to apply the time shift. Default is 0. fseries ({None, numpy array}) – The frequencies of each element in htilde. This is only needed if htilde is not sampled at equal frequency steps. copy ({True, bool}) – Make a copy of htilde before applying the time shift. If False, the time shift will be applied to htilde’s data. A frequency series with the waveform shifted to the new time. If makecopy is True, will be a new frequency series; if makecopy is False, will be the same as htilde. FrequencySeries
pycbc.waveform.utils.apply_fseries_time_shift(htilde, dt, kmin=0, copy=True)[source]

Shifts a frequency domain waveform in time. The waveform is assumed to be sampled at equal frequency intervals.

pycbc.waveform.utils.ceilpow2(n)[source]

convenience function to determine a power-of-2 upper frequency limit

pycbc.waveform.utils.coalign_waveforms(h1, h2, psd=None, low_frequency_cutoff=None, high_frequency_cutoff=None, resize=True)[source]

Return two time series which are aligned in time and phase.

The alignment is only to the nearest sample point and all changes to the phase are made to the first input waveform. Waveforms should not be split accross the vector boundary. If it is, please use roll or cyclic time shift to ensure that the entire signal is contiguous in the time series.

Parameters: h1 (pycbc.types.TimeSeries) – The first waveform to align. h2 (pycbc.types.TimeSeries) – The second waveform to align. psd ({None, pycbc.types.FrequencySeries}) – A psd to weight the alignment low_frequency_cutoff ({None, float}) – The low frequency cutoff to weight the matching in Hz. high_frequency_cutoff ({None, float}) – The high frequency cutoff to weight the matching in Hz. resize (Optional, {True, boolean}) – If true, the vectors will be resized to match each other. If false, they must be the same length and even in length h1 (pycbc.types.TimeSeries) – The shifted waveform to align with h2 h2 (pycbc.type.TimeSeries) – The resized (if necessary) waveform to align with h1.
pycbc.waveform.utils.fd_taper(out, start, end, beta=8, side='left')[source]

Applies a taper to the given FrequencySeries.

A half-kaiser window is used for the roll-off.

Parameters: out (FrequencySeries) – The FrequencySeries to taper. start (float) – The frequency (in Hz) to start the taper window. end (float) – The frequency (in Hz) to end the taper window. beta (int, optional) – The beta parameter to use for the Kaiser window. See scipy.signal.kaiser for details. Default is 8. side ({'left', 'right'}) – The side to apply the taper to. If 'left' ('right'), the taper will roll up (down) between start and end, with all values before start (after end) set to zero. Default is 'left'. The tapered frequency series. FrequencySeries
pycbc.waveform.utils.fd_to_td(htilde, delta_t=None, left_window=None, right_window=None, left_beta=8, right_beta=8)[source]

Converts a FD waveform to TD.

A window can optionally be applied using fd_taper to the left or right side of the waveform before being converted to the time domain.

Parameters: htilde (FrequencySeries) – The waveform to convert. delta_t (float, optional) – Make the returned time series have the given delta_t. left_window (tuple of float, optional) – A tuple giving the start and end frequency of the FD taper to apply on the left side. If None, no taper will be applied on the left. right_window (tuple of float, optional) – A tuple giving the start and end frequency of the FD taper to apply on the right side. If None, no taper will be applied on the right. left_beta (int, optional) – The beta parameter to use for the left taper. See fd_taper for details. Default is 8. right_beta (int, optional) – The beta parameter to use for the right taper. Default is 8. The time-series representation of htilde. TimeSeries
pycbc.waveform.utils.frequency_from_polarizations(h_plus, h_cross)[source]

Return gravitational wave frequency

Return the gravitation-wave frequency as a function of time from the h_plus and h_cross polarizations of the waveform. It is 1 bin shorter than the input vectors and the sample times are advanced half a bin.

Parameters: h_plus (TimeSeries) – A PyCBC TimeSeries vector that contains the plus polarization of the gravitational waveform. h_cross (TimeSeries) – A PyCBC TimeSeries vector that contains the cross polarization of the gravitational waveform. GWFrequency – A TimeSeries containing the gravitational wave frequency as a function of time. TimeSeries

Examples

>>> from pycbc.waveform import get_td_waveform, phase_from_polarizations
>>> hp, hc = get_td_waveform(approximant="TaylorT4", mass1=10, mass2=10,
f_lower=30, delta_t=1.0/4096)
>>> freq = frequency_from_polarizations(hp, hc)
pycbc.waveform.utils.phase_from_frequencyseries(htilde, remove_start_phase=True)[source]

Returns the phase from the given frequency-domain waveform. This assumes that the waveform has been sampled finely enough that the phase cannot change by more than pi radians between each step.

Parameters: htilde (FrequencySeries) – The waveform to get the phase for; must be a complex frequency series. remove_start_phase ({True, bool}) – Subtract the initial phase before returning. The phase of the waveform as a function of frequency. FrequencySeries
pycbc.waveform.utils.phase_from_polarizations(h_plus, h_cross, remove_start_phase=True)[source]

Return gravitational wave phase

Return the gravitation-wave phase from the h_plus and h_cross polarizations of the waveform. The returned phase is always positive and increasing with an initial phase of 0.

Parameters: h_plus (TimeSeries) – An PyCBC TmeSeries vector that contains the plus polarization of the gravitational waveform. h_cross (TimeSeries) – A PyCBC TmeSeries vector that contains the cross polarization of the gravitational waveform. GWPhase (TimeSeries) – A TimeSeries containing the gravitational wave phase. Examples ——–s >>> from pycbc.waveform import get_td_waveform, phase_from_polarizations >>> hp, hc = get_td_waveform(approximant=”TaylorT4”, mass1=10, mass2=10, – f_lower=30, delta_t=1.0/4096) >>> phase = phase_from_polarizations(hp, hc)
pycbc.waveform.utils.taper_timeseries(tsdata, tapermethod=None, return_lal=False)[source]

Taper either or both ends of a time series using wrapped LALSimulation functions

Parameters: tsdata (TimeSeries) – Series to be tapered, dtype must be either float32 or float64 tapermethod (string) – Should be one of (‘TAPER_NONE’, ‘TAPER_START’, ‘TAPER_END’, ‘TAPER_STARTEND’, ‘start’, ‘end’, ‘startend’) - NB ‘TAPER_NONE’ will not change the series! return_lal (Boolean) – If True, return a wrapped LAL time series object, else return a PyCBC time series.
pycbc.waveform.utils.td_taper(out, start, end, beta=8, side='left')[source]

Applies a taper to the given TimeSeries.

A half-kaiser window is used for the roll-off.

Parameters: out (TimeSeries) – The TimeSeries to taper. start (float) – The time (in s) to start the taper window. end (float) – The time (in s) to end the taper window. beta (int, optional) – The beta parameter to use for the Kaiser window. See scipy.signal.kaiser for details. Default is 8. side ({'left', 'right'}) – The side to apply the taper to. If 'left' ('right'), the taper will roll up (down) between start and end, with all values before start (after end) set to zero. Default is 'left'. The tapered time series. TimeSeries
pycbc.waveform.utils.time_from_frequencyseries(htilde, sample_frequencies=None, discont_threshold=3.1101767270538954)[source]

Computes time as a function of frequency from the given frequency-domain waveform. This assumes the stationary phase approximation. Any frequencies lower than the first non-zero value in htilde are assigned the time at the first non-zero value. Times for any frequencies above the next-to-last non-zero value in htilde will be assigned the time of the next-to-last non-zero value.

Note

Some waveform models (e.g., SEOBNRv2_ROM_DoubleSpin) can have discontinuities in the phase towards the end of the waveform due to numerical error. We therefore exclude any points that occur after a discontinuity in the phase, as the time estimate becomes untrustworthy beyond that point. What determines a discontinuity in the phase is set by the discont_threshold. To turn this feature off, just set discont_threshold to a value larger than pi (due to the unwrapping of the phase, no two points can have a difference > pi).

Parameters: htilde (FrequencySeries) – The waveform to get the time evolution of; must be complex. sample_frequencies ({None, array}) – The frequencies at which the waveform is sampled. If None, will retrieve from htilde.sample_frequencies. discont_threshold ({0.99*pi, float}) – If the difference in the phase changes by more than this threshold, it is considered to be a discontinuity. Default is 0.99*pi. The time evolution of the waveform as a function of frequency. FrequencySeries

## pycbc.waveform.utils_cpu module¶

This module contains the CPU-specific code for convenience utilities for manipulating waveforms

pycbc.waveform.utils_cpu.apply_fseries_time_shift()

Shifts a frequency domain waveform in time. The waveform is assumed to be sampled at equal frequency intervals.

pycbc.waveform.utils_cpu.fstimeshift()
pycbc.waveform.utils_cpu.fstimeshift32()

## pycbc.waveform.waveform module¶

Convenience functions to genenerate gravitational wave templates and waveforms.

pycbc.waveform.waveform.get_td_waveform(template=None, **kwargs)[source]

Return the plus and cross polarizations of a time domain waveform.

Parameters: template (object) – An object that has attached properties. This can be used to subsitute for keyword arguments. A common example would be a row in an xml table. mass1 ({None,
pycbc.waveform.waveform.get_fd_waveform(template=None, **kwargs)[source]

Return a frequency domain gravitational waveform.

Parameters: template (object) – An object that has attached properties. This can be used to substitute for keyword arguments. A common example would be a row in an xml table. mass1 ({None,
pycbc.waveform.waveform.get_fd_waveform_sequence(template=None, **kwds)[source]

Return values of the waveform evaluated at the sequence of frequency points.

Parameters: template (object) – An object that has attached properties. This can be used to substitute for keyword arguments. A common example would be a row in an xml table. mass1 ({None,
pycbc.waveform.waveform.get_fd_waveform_from_td(**params)[source]

Return time domain version of fourier domain approximant.

This returns a frequency domain version of a fourier domain approximant, with padding and tapering at the start of the waveform.

Parameters: params (dict) – The parameters defining the waveform to generator. See get_td_waveform. hp (pycbc.types.FrequencySeries) – Plus polarization time series hc (pycbc.types.FrequencySeries) – Cross polarization time series
pycbc.waveform.waveform.print_td_approximants()[source]
pycbc.waveform.waveform.print_fd_approximants()[source]
pycbc.waveform.waveform.td_approximants(scheme=<pycbc.scheme.DefaultScheme object>)[source]

Return a list containing the available time domain approximants for the given processing scheme.

pycbc.waveform.waveform.fd_approximants(scheme=<pycbc.scheme.DefaultScheme object>)[source]

Return a list containing the available fourier domain approximants for the given processing scheme.

pycbc.waveform.waveform.get_waveform_filter(out, template=None, **kwargs)[source]

Return a frequency domain waveform filter for the specified approximant

pycbc.waveform.waveform.filter_approximants(scheme=<pycbc.scheme.DefaultScheme object>)[source]

Return a list of fourier domain approximants including those written specifically as templates.

pycbc.waveform.waveform.get_waveform_filter_norm(approximant, psd, length, delta_f, f_lower)[source]

Return the normalization vector for the approximant

pycbc.waveform.waveform.get_waveform_end_frequency(template=None, **kwargs)[source]

Return the stop frequency of a template

pycbc.waveform.waveform.waveform_norm_exists(approximant)[source]
pycbc.waveform.waveform.get_template_amplitude_norm(template=None, **kwargs)[source]

Return additional constant template normalization. This only affects the effective distance calculation. Returns None for all templates with a physically meaningful amplitude.

pycbc.waveform.waveform.get_waveform_filter_length_in_time(approximant, template=None, **kwargs)[source]

For filter templates, return the length in time of the template.

pycbc.waveform.waveform.get_sgburst_waveform(template=None, **kwargs)[source]

Return the plus and cross polarizations of a time domain sine-Gaussian burst waveform.

Parameters: template (object) – An object that has attached properties. This can be used to subsitute for keyword arguments. A common example would be a row in an xml table. approximant (string) – A string that indicates the chosen approximant. See td_approximants for available options. q (float) – The quality factor of a sine-Gaussian burst frequency (float) – The centre-frequency of a sine-Gaussian burst delta_t (float) – The time step used to generate the waveform hrss (float) – The strain rss amplitude (float) – The strain amplitude hplus (TimeSeries) – The plus polarization of the waveform. hcross (TimeSeries) – The cross polarization of the waveform.
pycbc.waveform.waveform.print_sgburst_approximants()[source]
pycbc.waveform.waveform.sgburst_approximants(scheme=<pycbc.scheme.DefaultScheme object>)[source]

Return a list containing the available time domain sgbursts for the given processing scheme.

pycbc.waveform.waveform.td_waveform_to_fd_waveform(waveform, out=None, length=None, buffer_length=100)[source]

Convert a time domain into a frequency domain waveform by FFT. As a waveform is assumed to “wrap” in the time domain one must be careful to ensure the waveform goes to 0 at both “boundaries”. To ensure this is done correctly the waveform must have the epoch set such the merger time is at t=0 and the length of the waveform should be shorter than the desired length of the FrequencySeries (times 2 - 1) so that zeroes can be suitably pre- and post-pended before FFTing. If given, out is a memory array to be used as the output of the FFT. If not given memory is allocated internally. If present the length of the returned FrequencySeries is determined from the length out. If out is not given the length can be provided expicitly, or it will be chosen as the nearest power of 2. If choosing length explicitly the waveform length + buffer_length is used when choosing the nearest binary number so that some zero padding is always added.

pycbc.waveform.waveform.get_two_pol_waveform_filter(outplus, outcross, template, **kwargs)[source]

Return a frequency domain waveform filter for the specified approximant. Unlike get_waveform_filter this function returns both h_plus and h_cross components of the waveform, which are needed for searches where h_plus and h_cross are not related by a simple phase shift.

exception pycbc.waveform.waveform.NoWaveformError[source]

Bases: Exception

This should be raised if generating a waveform would just result in all zeros being returned, e.g., if a requested f_final is <= f_lower.

exception pycbc.waveform.waveform.FailedWaveformError[source]

Bases: Exception

This should be raised if a waveform fails to generate.

pycbc.waveform.waveform.get_td_waveform_from_fd(rwrap=0.2, **params)[source]

Return time domain version of fourier domain approximant.

This returns a time domain version of a fourier domain approximant, with padding and tapering at the start of the waveform.

Parameters: rwrap (float) – Cyclic time shift parameter in seconds. A fudge factor to ensure that the entire time series is contiguous in the array and not wrapped around the end. params (dict) – The parameters defining the waveform to generator. See get_fd_waveform. hp (pycbc.types.TimeSeries) – Plus polarization time series hc (pycbc.types.TimeSeries) – Cross polarization time series