# 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)

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

  Parameters:
    spin_weight int

      The spin weight of the modes.

    ell_max int

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

  Returns:
    modes_list list

      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)

  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)

  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)

    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)

    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:
      value float, optional

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

    Returns:
      delta_f: float

        Sets the attribute.

  delta_t(value=None)

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

    Parameters:
      value float, 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)

    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()

    Get the metadata associated with the instance.

    Returns:
      metadata: dict

        A dictionary of metedata.

  get_news_from_psi4(omega0='auto')

    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')

    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)

    Load the waveform mode data from an hdf file.

    Parameters:
      extrap_order int, 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)

    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)

    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)

    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)

    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)

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

    Parameters:
      supertransl_alpha_modes modes_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')

    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')

    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()

    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)

    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_info cls 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)

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

    Parameters:
      incl_angle float

        The inclination angle.

      distance float
    Returns:
      taxis, hp, hc 1d arrays

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

  to_time_basis()

    Compute the modes in time basis.

    Returns:
      waveform_modes modes_array

        A modes_array containing the modes in frequency basis.

  trim(trim_upto_time=None)
    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)
  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)

  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)

    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)

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

    Parameters:
      value float, 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')

    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)

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

    Parameters:
      supertransl_alpha_modes modes_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)

    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)

    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.