waveformtools.waveforms

Classes for handling the waveform modes or data defined on spheres.

Classes

spherical_array: A 2D data-type.

Stores and manages two-dimensional data on surfaces of spherical topology.

modes_array: A data-type.

Handle and work with mode coefficients.

Functions

construct_mode_list(ell_max, spin_weight)

Construct a modes list in the form [[ell1, [emm1, emm2, ...], [ell2, [emm..]],..] given the \(\ell_{max}.\)

get_iteration_numbers_from_keys(keys_list)

Get the iteration number from keys.

sort_keys(modes_keys_list)

Sort the keys in a list based on

Classes

modes_array([data_dir, file_name, ...])

A class that holds mode array of waveforms

spherical_array([label, time_axis, ...])

A class for handling waveforms on a sphere.

waveformtools.waveforms.construct_mode_list(ell_max, spin_weight)[source]

Construct a modes list in the form [[ell1, [emm1, emm2, …], [ell2, [emm..]],..] given the \(\ell_{max}.\)

Parameters:
spin_weightint

The spin weight of the modes.

ell_maxint

The \(\ell_{max}\) of the modes list.

Returns:
modes_listlist

A list containg the mode indices lists.

Notes

The modes list is the form which the waveform object understands.

waveformtools.waveforms.get_iteration_numbers_from_keys(keys_list)[source]

Get the iteration number from keys.

Parameters:
keys_list: list

The list of keys.

Returns:
iteration_numbers: list

The list containing the iteration numbers.

class waveformtools.waveforms.modes_array(data_dir=None, file_name=None, modes_data=None, time_axis=None, frequency_axis=None, key_format=None, ell_max=None, modes_list=None, label=None, r_ext=500, out_file_name=None, maxtime=None, date=None, time=None, key_ex=None, spin_weight=- 2)[source]

A class that holds mode array of waveforms

Attributes:
label: str

The label of the modes array.

r_ext: float

The extraction radius.

modes_list: list

The list of available modes in the format [l1, [m values], [l2, [m values], …]]

ell_max: int

The maximum \(\ell\) mode available.

modes_data: 3d array

The three dimensional array containing modes in time/frequency space. The axis of the array is (\(\ell\), \(m\), time/freq).

base_dir: str

The base directory containing the modes data.

data_dir: str

The subdirectory in which to look for the data.

filename: str

The filename containg the modes data.

Methods

get_metadata:

Get the metadata associated with the modes_array.

mode:

Get the data for the given \(\ell, m\) mode.

create_modes_array:

A private method to create an empty modes_array of given shape.

delta_t:

Set the attribute delta_t and/ or return its value.

load_modes:

Load the waveform modes from a specified h5 file.

save_modes:

Save the waveform modes to a specified h5 file.

set_mode_data:

Set the mode data of specified modes.

to_frequency_basis:

Get the modes_array in frequency basis from its time basis representation.

to_time_basis:

Get the modes_array in temporal basis from its frequency basis representation.

extrap_to_inf:

Extrapolate the modes to infinity.

supertranslate:

Supertranslate the waveform modes.

boost:

Boost the waveform modes.

boost(conformal_factor, grid_info=None)[source]

Boost the waveform given the unboosted waveform and the boost conformal factor.

Parameters:
conformal_factor: 2d array

The conformal factor for the Lorentz transformation. It may be a single floating point number or an array on a spherical grid. The array will be of dimensions [ntheta, nphi]

Returns:
boosted_waveform: spherical_array

The class instance spherical_array that contains the boosted waveform.

create_modes_array(ell_max=None, data_len=None)[source]

Create a modes array and initialize it with zeros.

Parameters:
ell_max: int

The maximum \(\ell\) value of the modes.

data_len: int

The number of points along the third (time / frequency) axis.

Returns:
self.modes_array: modes_array

sets the self.modes_array attribute.

property data_len

Returns the length of the time/frequency axis.

Returns:
data_len: int

THe length of the time/frequency axis.

property delta_f

Sets and returns the value of frequency stepping \(df\).

Parameters:
valuefloat, optional

The value of \(df\) to set to the attribute.

Returns:
delta_f: float

Sets the attribute.

delta_t(value=None)[source]

Sets and returns the value of time stepping \(dt\).

Parameters:
valuefloat, optional

The value of \(dt\) to set to the attribute.

Returns
——-
self.delta_t: float

Sets the attribute.

extrap_to_inf(mass=1, spin=None, modes_list='all', method='SIO', r_ext_factor=1)[source]

Extrapolate the \(\Psi_4\) modes to infinity using the perturbative improved second order method.

Parameters:
mass: float

The effective total mass of the system.

spin: float

The effective spin of the system.

modes: modes array, optional

The modes to extrapolate. Defaults to all if not specified.

method: str

The method to use for extrapolation. The available methods are:

+————+————————————–+
| Method str | Name |
+————+————————————–+
|’FO’ | First order |
|’SO’ | Second order |
|’SIO’ | Second improved order |
|’NM’ | Numerical method (not ready yet) |
+————+————————————–+
Returns:
waveform_inf_modes: modes array

A new modes array that contains the extrapolated modes.

get_metadata()[source]

Get the metadata associated with the instance.

Returns:
metadata: dict

A dictionary of metedata.

get_news_from_psi4(omega0='auto')[source]

Get the News modes_array from \(\Psi_4\) by fixed frequency integration.

Parameters:
omega0: float, optional

The lower cutoff angular frequency for FFI. By default, it computes this as one tenth of the starting frequency of the mode data.

Returns:
news_waveform: modes_array

The computed strain modes.

get_strain_from_psi4(omega0='auto')[source]

Get the strain modes_array from \(\Psi_4\) by fixed frequency integration.

Parameters:
omega0: float, optional

The lower cutoff angular frequency for FFI. By default, it computes this from the mode data.

Returns:
strain_waveform: modes_array

The computed strain modes.

load_modes(label=None, data_dir=None, file_name=None, ftype='generic', var_type='Psi4', resam_type='finest', interp_kind='cubic', extrap_order=4, r_ext=None, ell_max=None, pre_key=None, modes_list=None, crop=False, centre=True, key_ex=None, save_as_ma=False, compression_opts=None, r_ext_factor=1, debug=False)[source]

Load the waveform mode data from an hdf file.

Parameters:
extrap_orderint, optional

For SpEC waveforms only. This is the order of extrapolation to use.

pre_key: str, optional

A string containing the key of the group in the HDF file in which the modes` dataset exists. It defaults to None.

mode_numbers: list

The mode numbers to load from the file. Each item in the list is a list that contains two integrer numbers, one for the mode index \(\ell\) and the other for the mode index \(m\).

crop: bool

Whether or not to crop the beginning of the input waveform. If yes, the first \(t=r_{ext}\) length of data will be discarded.

Returns:
waveform_obj: 3d array

Sets the three dimensional array waveform.modes that contains the required \(\ell, m\) modes.

Examples

# Note # Update this! #>>> from waveformtools.waveforms import waveform #>>> waveform.set_basedir(‘./’) #>>> waveform.set_datadir(‘data/’) #>>> mode_numbers = [[2, 2], [3, 3]] #>>> waveform.load_data(mode_numbers=mode_numbers)

low_cut(omega0=0.03, order=2)[source]

Apply the low cut filter from waveformtools.low_cut_filter

Parameters:
order: int, optional

The order of the butterworth filter.

omega0: float, optional

The cutoff frequency of the butterworth filter.

mode(ell, emm)[source]

The modes array data structure to hold waveform modes.

Parameters:
ell: int

The \(\ell\) index of the mode.

emm: int

The \(m\) index of the mode.

Returns:
mode_data: array

The array of the requested mode.

property modes_data

The modes array

save_modes(ell_max=None, pre_key=None, key_format=None, modes_to_save=None, out_file_name='mp_new_modes.h5', r_ext_factor=None, compression_opts=0, r_ext=None)[source]

Save the waveform mode data to an hdf file.

Parameters:
pre_key: str, optional

A string containing the key of the group in the HDF file in which the modes` dataset exists. It defaults to None.

mode_numbers: list

The mode numbers to load from the file. Each item in the list is a list that contains two integrer numbers, one for the mode index \(\ell\) and the other for the mode index \(m\).

Returns:
waveform_obj: 3d array

Sets the three dimensional array waveform.modes that contains the required \(\ell, m\) modes.

Examples

>>> from waveformtools.waveforms import waveform
>>> waveform.set_basedir('./')
>>> waveform.set_datadir('data/')
>>> mode_numbers = [[2, 2], [3, 3]]
>>> waveform.load_data(mode_numbers=mode_numbers)
set_mode_data(ell_value, emm_value, data)[source]

Set the mode array data for the respective \((\ell, m)\) mode.

Parameters:
ell_value: int

The \(\ell\) polar mode number.

emm_value: int

The \(emm\) azimuthal mode number.

data: 1d array

The array consisting of mode data for the requested mode.

Returns:
self.mode_data: modes_data

The updated modes data.

supertranslate(supertransl_alpha_modes, grid_info, order=4)[source]

Supertranslate the \(\Psi_{4\ell m}\) waveform modes, give the, the supertranslation parameter and the order.

Parameters:
supertransl_alpha_modesmodes_array

The modes_array containing the supertranslation mode coefficients.

grid_info: class instance

The class instance that contains the properties of the spherical grid using which the computations are carried out.

order: int

The number of terms to use to approximate the supertranslation.

Returns:
Psi4_supertransl: modes_array

A class instance containg the modes of the supertranslated waveform \(\Psi_4\).

taper(zeros='auto')[source]

Taper a waveform at both ends and insert zeros if needed

Parameters:
zeros: int

The number of zeros to add at rach end

Returns:
tapered_modes: modes_array

Modes array with tapered mode data.

taper_tanh(time_axis=None, zeros='auto', duration=10, sides='both')[source]

Taper a waveform at both ends and insert zeros if needed

Parameters:
zeros: int

The number of zeros to add at rach end

Returns:
tapered_modes: modes_array

Modes array with tapered mode data.

property time_axis

The time axis

to_frequency_basis()[source]

Compute the modes in frequency basis.

Returns:
waveform_tilde_modes: modes_array

A modes_array containing the modes in frequency basis.

to_spherical_array(grid_info, meth_info, spin_weight=None)[source]

Obtain the spherical array from the modes array.

Parameters:
grid_info: cls instance

An instance of the “spherical_grid” class to hold the grid info.

meth_infocls instance

An instance of the class waveformtools.diagnostics.method_info that provides information on what methods to use for integration.

Returns
——-
waveform_sp: spherical_array

A member of the “spherical_array” class constructed from the given “modes_rray”.

to_td_waveform(Mtotal=1, incl_angle=0, distance=1, delta_t=None)[source]

Get the plus and cross polarizations of of the waveform time series by summing the modes.

Parameters:
incl_anglefloat

The inclination angle.

distancefloat
Returns:
taxis, hp, hc1d arrays

The 1d arrays of the time axis and the polarizations of the waveforms.

to_time_basis()[source]

Compute the modes in time basis.

Returns:
waveform_modesmodes_array

A modes_array containing the modes in frequency basis.

trim(trim_upto_time=None)[source]
Trim the modes_array at the beginning and center about

the peak of the 2,2 mode.

Parameters:
time: float

The time unit upto which to discard.

Returns:
Re-sets the time_axis and modes_array data.
waveformtools.waveforms.sort_keys(modes_keys_list)[source]
Sort the keys in a list based on

its iteration number

Parameters:
modes_keys_list: str

The list of keys.

Returns:
sorted_modes_keys_list: str

The sorted list.

class waveformtools.waveforms.spherical_array(label=None, time_axis=None, frequency_axis=None, data=None, data_dir=None, file_name=None, grid_info=None, spin_weight=2)[source]

A class for handling waveforms on a sphere.

Attributes:
label: str

The label of the waveform data.

time_axis: 1d array

The time axis of the data.

frequency_axis: 1d array

The frequency axis if the data is represented in frequency domain.

grid_info: spherical_grid

An instance of the spherical_grid class.

data_len: int

The length of the data along the time axis.

Methods

delta_t:

Fetch the time stepping delta_t.

to_modes_array:

Find the waveform expressed in the SWSH basis.

boost:

Boost the waveform.

supertranslate:

Supertranslate the waveform.

boost(conformal_factor, grid_info=None)[source]

Boost the waveform given the unboosted waveform and the boost conformal factor.

Parameters:
self: spherical_array

A class instance of spherical array.

conformal_factor: 2d array

The conformal factor for the Lorentz transformation. It may be a single floating point number or an array on a spherical grid. The array will be of dimensions [ntheta, nphi]

grid_info: class instance

The class instance that contains the properties of the spherical grid.

Returns:
boosted_waveform: sp_array

The class instance sp_array that contains the boosted waveform.

property data_len

Returns the length of the time/frequency axis.

Returns:
data_len: int

The length of the time/frequency axis.

delta_t(value=None)[source]

Sets and returns the value of time stepping \(dt\).

Parameters:
valuefloat, optional

The value of \(dt\) to set to the attribute.

Returns:
delta_t: float

Sets the attribute.

load_qlm_data(data_dir=None, grid_info=None, bh=0, variable='sigma')[source]

Load the 2D shear data from h5 files.

Parameters:
file_name: str

The name of the file containing data.

data_dir: str

The name of the directory containing data.

grid_info: class instance

An instance of the grid_info class.

bh: int

The black hole number (0, 1 or 2)

supertranslate(supertransl_alpha_sp, order=1)[source]

Supertranslate the \(\Psi_{4\ell m}\) waveform modes, give the, the supertranslation parameter and the order.

Parameters:
supertransl_alpha_modesmodes_array

The modes_array containing the supertranslation mode coefficients.

grid_info: class instance

The class instance that contains the properties of the spherical grid using which the computations are carried out.

order: int

The number of terms to use to approximate the supertranslation.

Returns:
Psi4_supertransl: modes_array

A class instance containg the modes of the supertranslated waveform \(\Psi_4\).

to_modes_array(grid_info=None, spin_weight=None, ell_max=8)[source]

Decompose a given spherical array function on a sphere into Spin Weighted Spherical Harmonic modes.

Parameters:
spin_weight: int, optional

The spin weight of the waveform. It defaults to -2 for a gravitational waveform.

ell_max: int, optional

The maximum value of the \(\ell\) polar quantum number. Defaults to 8.

grid_info: class instance

The class instance that contains the properties of the spherical grid.

Returns:
waveforms_modes: modes_array

An instance of the modes_array class containing the decomposed modes.

Notes

  1. Assumes that the sphere on which this decomposition is carried out is so far out that the coordinate system is spherical polar on a round sphere.

  2. Assumes that the poper area is the same as its co-ordinate area.

  3. Ensure that the label of the input spherical array indicates whether it is a time domain data or frequency domain data.

to_shear_modes_array(grid_info=None, spin_weight=None, ell_max=8)[source]

Decompose a given spherical array function on a sphere into Spin Weighted Spherical Harmonic modes.

Parameters:
spin_weight: int, optional

The spin weight of the waveform. It defaults to -2 for a gravitational waveform.

ell_max: int, optional

The maximum value of the \(\ell\) polar quantum number. Defaults to 8.

grid_info: class instance

The class instance that contains the properties of the spherical grid.

Returns:
waveforms_modes: modes_array

An instance of the modes_array class containing the decomposed modes.

Notes

  1. Assumes that the sphere on which this decomposition is carried out is so far out that the coordinate system is spherical polar on a round sphere.

  2. Assumes that the poper area is the same as its co-ordinate area.

  3. Ensure that the label of the input spherical array indicates whether it is a time domain data or frequency domain data.