Utility Functions

Interpolation Utilities

class bbhx.waveformbuild.TemplateInterpFD(use_gpu=False)

Bases: object

Interpolate frequency domain template.

This class wraps CubicSplineInterpolant so that it fits into this specific waveform production method.

This class has GPU capabilities.

Parameters:

use_gpu (bool, optional) – If True, use GPU.

data_length

Length of data. This class interpolates to this length.

Type:

int

length

Length of original frequency array.

Type:

int

num_bin_all

Number of binaries.

Type:

int

num_channels

Number of channels in data.

Type:

int

num_modes

Number of harmonics.

Type:

int

template_carrier

Carrier for output templates. Templates can be accessed through the template_channels property.

Type:

complex128 xp.ndarray

use_gpu

If True, using GPU.

Type:

bool

property xp: object

Numpy or Cupy

property template_gen: callable

C/CUDA wrapped function for computing interpolated waveforms

property template_channels

Get template channels from self.template_carrier.

property citation

citations for this class

__call__(data_freqs, interp_container, t_start, t_end, length, num_modes, num_channels)

Generate frequency domain template via interpolation.

This class takes all waveform and response information as sparse arrays and then interpolates to the proper frequency array.

This class acts in a unique why by passing arrays of pointers from python into C++/CUDA.

Parameters:

  • data_freqs (double xp.ndarray) – Frequencies to interpolate to.

  • interp_container (obj) – container attribute from the interpolant class: CubicSplineInterpolant.

  • t_start (double xp.ndarray) – Array of start times (sec) for each binary.

  • t_end (double xp.ndarray) – Array of end times (sec) for each binary.

  • length (int) – Length of original frequency array.

  • num_modes (int) – Number of harmonics.

  • num_channels (int) – Number of channels in data.

Returns:

List of template arrays for all binaries.

shape of each array: (self.num_channels, self.data_length)

Return type:

list

class bbhx.utils.interpolate.CubicSplineInterpolant(x, y_all, num_interp_params=None, num_bin_all=None, num_modes=None, length=None, use_gpu=False)

Bases: object

GPU-accelerated Multiple Cubic Splines

This class produces multiple cubic splines. The cubic splines are produced with “not-a-knot” boundary conditions.

This class has GPU capability.

Parameters:

  • x (xp.ndarray) – f values as input for the spline. Can be 1D flattend array of total length (num_bin_all * length) or 2D array with shape: (num_bin_all, length).

  • y_all (xp.ndarray) – y values for the spline. This can be a 1D flattened array with length (num_interp_params * num_bin_all * num_modes * length) or 4D arrays of shape: (num_interp_params, num_bin_all, num_modes, length).

  • num_interp_params (int, optional) – If x and y_all are flattened, the user must provide the number of interpolation parameters. (Default: None)

  • num_bin_all (int, optional) – If x and y_all are flattened, the user must provide the number of total binaries. (Default: None)

  • num_modes (int, optional) – If x and y_all are flattened, the user must provide the number of modes. (Default: None)

  • length (int, optional) – If x and y_all are flattened, the user must provide the length of the frequency array for each binary. (Default: None)

  • use_gpu (bool, optional) – If True, prepare arrays for a GPU. Default is False.

Raises:

ValueError – If input arguments are not correct.

property use_gpu: bool

Whether to use a GPU.

property xp: object

Numpy or Cupy

property interpolate_arrays: callable

C/CUDA wrapped function for computing interpolation.

property x_shaped

Get shaped x array.

property y_shaped

Get shaped y array.

property c1_shaped

Get shaped c1 array.

property c2_shaped

Get shaped c2 array.

property c3_shaped

Get shaped c3 array.

property container

Container for easy transit of interpolation information.

__call__(x_new)

Call self as a function.

Useful Transformation Functions

When working with MBHBs, there are some useful transformations. Mainly to and from the LISA and SSB reference frames. Also, transforming to other probable sky locations during sampling.

bbhx.utils.transform.mT_q(mT, q)

Convert total mass and mass ratio to m1,m2

Parameters:

  • mT (scalar or np.ndarray) – Total mass of system.

  • q (scalar or np.ndarray) – Mass ratio of system with \(q<1\).

Returns:

First entry is m1. Second entry is m2.

Return type:

tuple

bbhx.utils.transform.modpi(phase)

Modulus with pi as the period

Originally from Sylvain Marsat.

Parameters:

phase (scalar or np.ndarray) – Phase angle.

Returns:

Phase angle modulus by pi.

Return type:

scalar or np.ndarray

bbhx.utils.transform.mod2pi(phase)

Modulus with 2pi as the period

Originally from Sylvain Marsat.

Parameters:

phase (scalar or np.ndarray) – Phase angle.

Returns:

Phase angle modulus by 2pi.

Return type:

scalar or np.ndarray

bbhx.utils.transform.tSSBfromLframe(tL, lambdaSSB, betaSSB, t0=0.0)

Get time in SSB frame from time in LISA-frame.

Compute Solar System Barycenter time tSSB from retarded time at the center of the LISA constellation tL. NOTE: depends on the sky position given in solar system barycenter (SSB) frame.

Originally from Sylvain Marsat. For more information and citation, see arXiv:2003.00357.

Parameters:

  • tL (scalar or np.ndarray) – Time in LISA constellation reference frame.

  • lambdaSSB (scalar or np.ndarray) – Ecliptic longitude in SSB reference frame.

  • betaSSB (scalar or np.ndarray) – Ecliptic latitude in SSB reference frame.

  • t0 (double, optional) – Initial start time point away from zero. (Default: 0.0)

Returns:

Time in the SSB frame.

Return type:

scalar or np.ndarray

bbhx.utils.transform.tLfromSSBframe(tSSB, lambdaSSB, betaSSB, t0=0.0)

Get time in LISA frame from time in SSB-frame.

Compute retarded time at the center of the LISA constellation frame tL from the time in the SSB frame tSSB. NOTE: depends on the sky position given in solar system barycenter (SSB) frame.

Originally from Sylvain Marsat. For more information and citation, see arXiv:2003.00357.

Parameters:

  • tSSB (scalar or np.ndarray) – Time in LISA constellation reference frame.

  • lambdaSSB (scalar or np.ndarray) – Ecliptic longitude in SSB reference frame.

  • betaSSB (scalar or np.ndarray) – Time in LISA constellation reference frame.

  • t0 (double, optional) – Initial start time point away from zero. (Default: 0.0)

Returns:

Time in the LISA frame.

Return type:

scalar or np.ndarray

bbhx.utils.transform.LISA_to_SSB(tL, lambdaL, betaL, psiL, t0=0.0)

Convert sky/orientation from LISA frame to SSB frame.

Convert the sky and orientation parameters from the center of the LISA constellation reference to the SSB reference frame.

The parameters that are converted are the reference time, ecliptic latitude, ecliptic longitude, and polarization angle.

Originally from Sylvain Marsat. For more information and citation, see arXiv:2003.00357.

Parameters:

  • tL (scalar or np.ndarray) – Time in LISA constellation reference frame.

  • lambdaL (scalar or np.ndarray) – Ecliptic longitude in LISA reference frame.

  • betaL (scalar or np.ndarray) – Ecliptic latitude in LISA reference frame.

  • psiL (scalar or np.ndarray) – Polarization angle in LISA reference frame.

  • t0 (double, optional) – Initial start time point away from zero. (Default: 0.0)

Returns:

(tSSB, lambdaSSB, betaSSB, psiSSB)

Return type:

Tuple

bbhx.utils.transform.SSB_to_LISA(tSSB, lambdaSSB, betaSSB, psiSSB, t0=0.0)

Convert sky/orientation from SSB frame to LISA frame.

Convert the sky and orientation parameters from the SSB reference frame to the center of the LISA constellation reference frame.

The parameters that are converted are the reference time, ecliptic latitude, ecliptic longitude, and polarization angle.

Originally from Sylvain Marsat. For more information and citation, see arXiv:2003.00357. Note: no transformation of the phase – approximant-dependence.

Parameters:

  • tSSB (scalar or np.ndarray) – Time in SSB reference frame.

  • lambdaSSB (scalar or np.ndarray) – Ecliptic longitude in SSB reference frame.

  • betaSSB (scalar or np.ndarray) – Ecliptic latitude in SSB reference frame.

  • psiSSB (scalar or np.ndarray) – Polarization angle in SSB reference frame.

  • t0 (double, optional) – Initial start time point away from zero in years. (Default: 0.0)

Returns:

(tL, lambdaL, betaL, psiL)

Return type:

Tuple

bbhx.utils.transform.mbh_sky_mode_transform(coords, ind_map=None, kind='both', inplace=False, cos_i=False)

Sky-mode transformation in the LISA reference frame

In the LISA constellation referenence frame, the sky localization for a source generally has 8 sky modes: 4 longitudinal and 2 latitudinal. Longitudinal modes involve \(\lambda + (0, 1, 2, 3)\times\pi/2\) and \(\psi + (0, 1, 2, 3)\times\pi/2\), where \(\lambda\) is the ecliptic longitude and \(\psi\) is the polarization angle. The latitudinal modes are at \((\pm\beta, \pm\cos{\iota}, \pm\cos{\psi})\) where \(\beta\) and \(\iota\) are the ecliptic latitude and inclination, respectively.

It is generally wise to start MBH PE runs in all eight sky modes. Using a mode-hopping proposal is also a good idea and/or parallel tempering. For MBHBs at higher frequency, the 8 modes reduce only to the latitudinal modes located at the true ecliptic longitude.

Parameters:

  • coords (np.ndarray) – 2D array with shape: (num_bin_all, ndim). num_bin_all is the total number of binaries. ndim is the number of parameters given. If the inclination is given as \(\cos{\iota}\), that needs to be indicated with cos_i=True. It does not matter if \(\beta\) or \(\sin{\beta}\) is given because the transforms involve multiplying the input by -1.

  • ind_map (dict, optional) – Keys are parameter names and values are there index into the coords array. Must include the keys inc, lam, beta, psi. If None, it will be dict(inc=7, lam=8, beta=9, psi=10). (Default: None)

  • kind (str, optional) – String indicating which transform is needed. If kind=="both" (kind=="long") [``kind=="lat"], the transformation will be to all (longitudinal) [latitudinal] sky modes. If inplace==False, the output array 1st dimension will be a factor of 8 (4) [2] longer. (Default: "both")

  • inplace (bool, optional) – If True, adjust coords in place. In this case, the user needs to ensure the number of sets of binary Parameters is an integer multiple of the number of sky modes associated with the trasnformation. If kind=="both" (kind=="long") [``kind=="lat"], this must be a mutliple of 8 (4) [2]. (Default: False)

  • cos_i (bool, optional) – If True, the inclination is input as the cosine of the inclination. (Default: False)

Returns:

2D array with shape: (num_bin_all * factor, ndim).

The factor is 1 if inplace==False. The factor is 8 (4) [2] if kind=="both" (kind=="long") [``kind=="lat"].

Return type:

np.ndarray

Raises:

ValueError – Input arguments are not properly given.

Constants

The module bbhx.utils.constants houses the constants used throughout the package.

Constants list:

  • MSUN_SI = 1.98848e+30

  • YRSID_SI = 31558149.763545603

  • AU_SI = 149597870700.0

  • C_SI = 299792458.

  • G_SI = 6.674080e-11

  • GMSUN = 1.3271244210789466e+20

  • MTSUN_SI = 4.925491025873693e-06

  • MRSUN_SI = 1476.6250615036158

  • PC_SI = 3.0856775814913674e+16

  • PI = 3.141592653589793238462643383279502884

  • PI_2 = 1.570796326794896619231321691639751442

  • PI_3 = 1.047197551196597746154214461093167628

  • PI_4 = 0.785398163397448309615660845819875721

  • SQRTPI = 1.772453850905516027298167483341145183

  • SQRTTWOPI = 2.506628274631000502415765284811045253

  • INVSQRTPI = 0.564189583547756286948079451560772585

  • INVSQRTTWOPI = 0.398942280401432677939946059934381868

  • GAMMA = 0.577215664901532860606512090082402431

  • SQRT2 = 1.414213562373095048801688724209698079

  • SQRT3 = 1.732050807568877293527446341505872367

  • SQRT6 = 2.449489742783178098197284074705891392

  • INVSQRT2 = 0.707106781186547524400844362104849039

  • INVSQRT3 = 0.577350269189625764509148780501957455

  • INVSQRT6 = 0.408248290463863016366214012450981898

  • F0 = 3.168753578687779e-08

  • Omega0 = 1.9909865927683788e-07

  • L_SI = 2.5e9

  • eorbit = 0.004824185218078991

  • ConstOmega = 1.99098659277e-7

Citation Module

bbhx.utils.citations:

This module is used to collect citations for all modules in the package. This module is then imported to add citations to module classes using their citation attribute.

Cython GPU/CPU Agnostic Tools

bbhx.utils.utility:

This module contains tools used in the Cython CPU/GPU Agnostic framework.

bbhx.utils.utility.wrapper(*args, **kwargs)

Function to convert array and C/C++ class arguments to ptrs

This function checks the object type. If it is a cupy or numpy array, it will determine its pointer by calling the proper attributes. If you design a Cython class to be passed through python, it must have a ptr attribute.

If you use this function, you must convert input arrays to size_t data type in Cython and then properly cast the pointer as it enters the c++ function. See the Cython codes here for examples.

Parameters:

  • *args (list) – list of the arguments for a function.

  • **kwargs (dict) – dictionary of keyword arguments to be converted.

Returns:

(targs, tkwargs) where t indicates target (with pointer values

rather than python objects).

Return type:

Tuple

bbhx.utils.utility.pointer_adjust(func)

Decorator function for cupy/numpy agnostic cython

This decorator applies few.utils.utility.wrapper() to functions via the decorator construction.

If you use this decorator, you must convert input arrays to size_t data type in Cython and then properly cast the pointer as it enters the c++ function. See the Cython codes here for examples.