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 a modes list in the form [[ell1, [emm1, emm2, ...], [ell2, [emm..]],..] given the \(\ell_{max}.\) |
|
Get the iteration number from keys. |
|
Sort the keys in a list based on |
Classes
|
A class that holds mode array of waveforms |
|
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.
- 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
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.
Assumes that the poper area is the same as its co-ordinate area.
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
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.
Assumes that the poper area is the same as its co-ordinate area.
Ensure that the label of the input spherical array indicates whether it is a time domain data or frequency domain data.