mbank.handlers

Two two important handlers class for mbank:

  • tile: represents a tile (i.e. a pair (Rectangle, Metric))

  • tiling_handler: provides an interface to the tiling (i.e. a set of tiles) of the space.

  • variable_handler: takes care of the BBH parametrization

The handlers are used extensively throughout the package

class tile(rectangle, metric=None)[source]

Class to represent a tile. A tile is a tuple

(Rectangle, Metric)

where rectangle is represented by a Rectangle object and metric is a square matrix, stored as a ndarray.

The rectangle and the metric can be accessed with attributes tile.rectangle and tile.metric. The volume and the center of the tile can be accessed with tile.center and tile.volume respectively.

Create a new tile.

Parameters:

  • rectangle (Rectangle/ndarray/tuple) – A scipy rectangle. If an np.ndarray is given, it must be of shape (2,D) and it is interpreted s.t. rectangle[0,:] is the minimum and rectangle[1,:] is the maximum. If metric is None, it can be initialized with a tuple: in this case it is understood that the tuple is (Rect, metric) and it will be unwrapped authomatically

  • metric (ndarray) – shape (D,D)

N_templates(avg_dist)[source]

Computes the approximate number of templates inside the tile, given the typical distance between templates

The number of templates \(N_\text{templates}\) is computed from the average distance avg_dist \(d_\text{avg}\) as:

\[N_\text{templates} = \frac{V_\text{T} \sqrt{|\text{det} M|}}{ d_{\text{avg}}^D}\]

where \(V_\text{T}\) is the coordinate volume of the tile and \(|\text{det} M|\) is the absolute value of the determinant of the metric.

Note that the quantity \(V_\text{T} \cdot \sqrt{|\text{det} M|}\) amounts to the volume of the tile, making also \(N_\text{templates}\) a measure of volume.

Parameters:

avg_dist (float) – Desidered average distance between templates

Returns:

N_templates – The number or templates that should lie inside the tile (i.e. the rectangle with the given metric)

Return type:

float

split(axis=None, n=2)[source]

Splits the tile along the given axis. It returns n split tiles (with the same metric) If axis is None, the axis is set to be along the direction of longest proper dimension.

Parameters:

axis (int) – Dimension along which the tile shall be split. If None, the dimension will be set to be the largest

Returns:

*split – The splitted

Return type:

tile

class tiling_handler(ini=None)[source]

Class for a tiling with I/O helpers. A tiling is a list of tiles that cover a larger space. Each tile, consists in:

  • an hypercubes (Rectangle object) that defines its boundaries

  • a metric that it’s used to compute distances between points of the tile. It is represented by a DxD matrix (ndarray object), where D is the dimensionality of the space.

Overall a tiling handler looks like:

[(rect_1, metric_1), (rect_2, metric_2), ..., (rect_N, metric_N)]

Initializes the tiling handler.

Parameters:

ini (str/list) – Optional initialization. If a string is given, it is understood as the file the tiling handler is loaded from. The file shall be the same format as produced by tiling_handler.save() If a list is given, it is understood as a list of tiles and the list will be initialized accordingly. Providing a single tile/tuple is also possible.

compute_volume(metric_func=None)[source]

Compute the volume of the space an the volume of each tile. The volume will be computed with the metric approximation by default. If metric_function is a function, the volume will be computed by means of an integration. It must returns a metric approximation given a point theta in D dimension.

The volume is computed as \(\int \text{d}\theta \sqrt{|M(\theta)|}\) over the D dimensional space covered by the tiling.

Using a metric function for the integration, may be veeeery slow!

Parameters:

metric_func (function) –

A function that accepts theta and returns the metric. A common usage would be:

metric_obj = mbank.metric.cbc_metric(**args)
metric_func = metric_obj.get_metric

Returns:

  • volume (float) – The volume of the space covered by the tiling

  • tiles_volume (list) – The volume covered by each tile

create_tiling(boundaries, tolerance, metric_func, max_depth=None, verbose=True, worker_id=None)[source]

Create a tiling within a rectangle using a hierarchical iterative splitting method. If there is already a tiling, the splitting will be continued.

Parameters:

  • boundaries (ndarray) – shape: (2,D) - Boundaries of the space to tile. Lower limit is boundaries[0,:] while upper limits is boundaries[1,:] If the tiling is non empty and not consistent with the boundaries, a warning will be raised but the boundaries will be ignored

  • tolerance (float) –

    Maximum tolerated relative change between the metric determinant of the child and the parent |M|. This means that a tile will be split if

    |log10(sqrt(M_p/M_c))| > tolerance

    If tolerance is greater than 10, no further tiling will be performed

  • metric_func (function) –

    A function that accepts theta and returns the metric. A common usage would be:

    metric_obj = mbank.metric.cbc_metric(**args)
metric_func = metric_obj.get_metric

  • max_depth (int) – Maximum number of splitting before quitting the iteration. If None, the iteration will go on until the volume condition is not met

  • verbose (bool) – Whether to print the progress of the computation

  • worker_id (int) – If given, it will print the worker id in the progress bar.

Returns:

self – Return this object filled with the desired tiling

Return type:

tiling_handler

create_tiling_from_list(boundaries_list, tolerance, metric_func, max_depth=None, use_ray=False, verbose=True)[source]

Creates a tiling of the space, starting from a list of rectangles. Each rectangle in boundaries_list is treated separately and if use_ray is set to `True they run in parallel.

This function is useful to create a new tiling which covers disconnected regions or to heavily parallelize the computation.

The generated tiling will overwrite any previous tiling (i.e. the tiling will be emptied before executing).

Parameters:

  • boundaries_list (list) – A list of boundaries for a coarse tiling. Each box will have its own independent hierarchical tiling Each element of the list must be (max, min), where max, min are array with the upper and lower point of the hypercube. Each element can also be a (2,D) np.ndarray. If a single np.ndarray is given

  • tolerance (float) –

    Maximum tolerated relative change between the metric determinant of the child and the parent \(|M|\). This means that a tile will be split if

    \[0.5 \bigg\rvert{\log_{10}\frac{|M_{\text{parent}}|}{|M_{\text{child}}|}} \bigg\rvert > tolerance\]

    If tolerance is greater than 10, no further tiling will be performed

  • metric_func (function) –

    A function that accepts theta and returns the metric. A common usage would be:

    metric_obj = mbank.metric.cbc_metric(**args)
metric_func = metric_obj.get_metric

  • max_depth (int) – Maximum number of splitting before quitting the iteration. If None, the iteration will go on until the volume condition is not met

  • use_ray (bool) – Whether to use ray to parallelize

  • verbose (bool) – whether to print to screen the output

Returns:

self – A list of tiles ready to be used for the bank generation

Return type:

tiling_handler

get_centers()[source]

Returns an array with the centers of the tiling

Returns:

centers – shape (N,D) - All the centers of the tiles

Return type:

ndarray

get_metric(theta, flow=False, kdtree=False)[source]

Computes the approximation to the metric evaluated at points theta, as provided by the tiling. If flow is true, a normalizing flow model will be used to interpolate the metric.

Givent the metric \(M_{\text{T}}\) in a given tile with center \(\theta_{\text{T}}\), the interpolated determinant is

\[|M|(\theta) = \left( \frac{p_{\text{NF}}(\theta)}{p_{\text{NF}}(\theta_{\text{T}})} \right)^2 |M_{\text{T}}| = f(\theta; \theta_{\text{T}}) |M_{\text{T}}|\]

where \(p_{\text{NF}}(\theta)\) is the probability distribution function defined by the normalizing flow model. \(p_{\text{NF}}\) is proportional by construction to the square root of the metric determinant.

The interpolated metric then becomes:

\[M_{ij}(\theta) = f^{2/D}(\theta; \theta_{\text{T}}) {M_{\text{T}}}_{ij}\]
Parameters:

  • theta (ndarray) – shape: (N, D)/(D,) - Points of the parameter space to evaluate the metric at.

  • flow (bool) – Whether to use the normalizing flow model. The flow model must be trained in advance using tiling_handler.train_flow.

  • kdtree (bool) – Whether to use a kdtree method to compute the tile. This method is much faster but it may be less accurate as it relies on euclidean distance rather than on the rectangles of the tiling. Argument is passed to get_tile

Returns:

metric – shape: (N, D, D)/(D, D) - The metric evaluated according to the tiling

Return type:

ndarray

get_metric_distance(theta1, theta2, flow=False)[source]

Computes the squared metric distance between theta1 and theta2, using the metric provided by tiling. The distance between to points is related to the match \(\mathcal{M}(\theta_1, \theta_2)\) as follow:

\[d(\theta_1, \theta_2) = e^{M_{ij}\Delta\theta_i \Delta\theta_j} - 1 \simeq 1 - \mathcal{M}(\theta_1, \theta_2)\]

where \(M_{ij}\Delta\theta_i \Delta\theta_j\) is the metric approximation to the distance. The exponential is required to constrain the distance between 0 and 1.

If the option flow is True, the distance is computed with an integration of the flow PDF (this may be quite expensive). See mbank.handlers.tiling_handler.compute_integral() for more details.

Parameters:

  • theta1 (ndarray) – shape: (N, D)/(D,) - First point

  • theta2 (ndarray) – shape: (N, D)/(D,) - Second point

  • flow (bool) – Whether to use the flow to compute the distance. Default is False

Returns:

dist – shape: (N, )/(,) - Distance between theta1 and theta2 computed according to the tiling

Return type:

ndarray

get_tile(points, kdtree=True)[source]

Given a set points, it computes the tile each point is closest to.

Parameters:

  • points (ndarray) – shape (N,D)/(D,) - A set of points

  • kdtree (bool) – Whether to use a kdtree method to compute the tile. This method is much faster but it may be less accurate as it relies on euclidean distance rather than on the rectangles of the tiling.

Returns:

id_tile – A list of length N of the indices of the closest tile for each point.

Return type:

list

integrate_flow(theta1, theta2, thetac, N_steps=100)[source]

It performs the following integral:

\[\int_{0}^{1} \text{d}t \, \left(\frac{|M_{\text{flow}}(\theta(t))|}{|M_{\text{flow}}(\theta_C)|} \right)^{2/D}\]

where D is the dimensionality of the space and

\[\theta(t) = \theta_1 + (\theta_2 -\theta_1) t\]

and where \(|M_{\text{flow}}(\theta)|\) is estimated by the flow.

It is useful to weigth the metric distance obtained by assuming a constant metric (i.e. the standard way).

Parameters:

  • theta1 (torch.tensor) – shape (D,)/(N,D) - Starting point of the line integral

  • theta2 (torch.tensor) – shape (D,)/(N,D) - Ending point of the line integral

  • thetac (torch.tensor) – shape (D,)/(N,D) - Center which the metric is compared at

  • N_steps (int) – The number of points to be used for integral estimation

Returns:

integral – shape (1,)/(N,) - The result of the integral

Return type:

torch.tensor

is_inside(points)[source]

Returns whether each point is inside the tiling.

Parameters:

points (ndarray) – shape (N,D)/(D,) - A set of points

Returns:

  • is_inside (ndarray) – shape (N,)/() - Bool array stating whether each of the input is inside the tiling

  • ids_inside ndarray – shape (N’,) - Indices of the points inside the tiling

  • ids_outside ndarray – shape (N’,) - Indices of the points outside the tiling

load(filename)[source]

Loads the tiling from a file in npy format. The file should be the same layout as produced by tiling_handler.load()

Parameters:

filename (str) – File to load the tiling from (in npy format)

load_flow(filename)[source]

Loads the flow from file. The architecture of the flow must be specified at input.

Parameters:

  • filename (str) – File to load the tiling from (in npy format)

  • n_layers (int) – Number of layers of the flow See mbank.flow.STD_GW_flow for more information

  • hidden_features (int) – Number of hidden features for the masked autoregressive flow in use. See mbank.flow.STD_GW_flow for more information

sample_from_flow(N_samples)[source]

Samples random points from the normalizing flow model defined on the tiling. It makes sure that the sampled points are inside the tiling. The flow must be trained in advance using tiling_handler.train_flow.

Parameters:

N_samples (int) – Number of samples to draw from the normalizing flow

Returns:

samples – shape: (N_samples, D) - N_samples samples drawn from the normalizing flow inside the tiling

Return type:

ndarray

sample_from_tiling(N_samples, seed=None, qmc=False, dtype=<class 'numpy.float64'>, tile_id=False, p_equal=False)[source]

Samples random points from the tiling. It uses Gibb’s sampling.

Parameters:

  • N_samples (int) – Number of samples to draw from the tiling

  • seed (int) – Seed for the random points. If None no seed will be set

  • qmc (int) – Whether to use a quasi-Monte carlo method to sample points inside a tile. It uses scipy.stats.qmc

  • dtype (type) – Data type for the sampling (default np.float64)

  • tile_id (bool) – Whether to output the id of the tile each random point belongs to. Default is False

  • p_equal (bool) – Whether all the tiles should be chosen with equal probability. If False, the probability of having a point in each tile is proportional to its volume

Returns:

samples – shape: (N_samples, D) - N_samples samples drawn from the tiling

Return type:

ndarray

save(filename, flowfilename=None)[source]

Save the tiling to a file in npy format

Parameters:

  • filename (str) – File to save the tiling to (in npy format)

  • flowfilename (str) – File to save the flow to. If None, the flow will not be saved

split_tiling(d, split)[source]

Produce two tilings by splitting the parameter space along dimension d. The splitting is done by the threshold split. It is roughly the equivalent for a tiling to the split method of Rectangle.

Parameters:

  • d (int) – Axis to split the tiling along.

  • split (float) – Threshold value for the splitting along axis d

Returns:

  • left (tiling_handler) – Tiling covering the space <threshold the given axis

  • right (tiling_handler) – Tiling covering the space >threshold the given axis

train_flow(N_epochs=1000, N_train_data=10000, n_layers=2, hidden_features=4, batch_size=None, lr=0.001, verbose=False)[source]

Train a normalizing flow model on the space covered by the tiling, using points sampled from the tiling. The flow can be useful for smooth sampling from the tiling and to interpolate the metric within each tiles.

It uses the architecture defined in mbank.flow.STD_GW_flow.

Parameters:

  • N_epochs (int) – Number of training epochs

  • N_train_data (int) – Number of training samples from the tiling to be used for training. The validation will be performed with 10% of the training data

  • n_layers (int) – Number of layers of the flow See mbank.flow.STD_GW_flow for more information

  • hidden_features (int) – Number of hidden features for the masked autoregressive flow in use. See mbank.flow.STD_GW_flow for more information

  • batch_size (int) – Amount of training data to be used for each iteration. If None, all the training data will be used.

  • lr (float) – Learning rate for the training

  • verbose (bool) – Whether to print the training output

Returns:

history – A dict with the training history. See mbank.flow.GW_flow.train_flow for more information

Return type:

dict

update_KDTree()[source]

Updates the lookup table to compute the tile each point falls in. It should be called if you update the tiling and you want to compute the tile each point falls in.

class variable_handler[source]

Class to handle a large number of variable layouts. The full BBH space is characterized by the following variables

m1, m2, s1x, s1y, s1z, s2x, s2y, s2z, e, meanano, iota, phi

These are standard quantities in gravitational waves and the ligo waveform infrastructure can accept all these paramters.

A variable layout is a set of variables that parametrize a subspace of such 12 dimensional BBH parameter space. The conversion between a the full space and the chosen subspace is made by means of a projection, where any variable not used in the paramterization is set to a default value of 0. For instance, (m1, m2, s1x, s1y, s1z, s2x, s2y, s2z, e, meanano, iota, phi) can be mapped to (m1, m2, s1x, 0, s1z, 0, 0, s2z, iota, 0, e, 0) with a suitable variable format. The variable parametrizing the projected BBH will alway be labeled as theta and has a variable dimension D, depending on the chosen variable format.

The variable layout is specified by a string variable_format, that can be passed to any function of this class.

The general variable format can be built as any of the follwing:

MassFormat_SpinFormat
MassFormat_SpinFormat_AnglesFormat
MassFormat_SpinFormat_EccentricityFormat
MassFormat_SpinFormat_EccentricityFormat_AnglesFormat

Valid format for the two masses are:

  • Mq: Total mass and q

  • logMq: Log10 of total mass and q

  • mceta: chirp mass and eta

  • m1m2: mass1 and mass2

  • logm1logm2: Log 10 of mass1 and mass2

Valid formats for spins are:

  • nonspinning: no spins are considered (only two masses), D = 0

  • chi: only chi_eff is considered. That means that s1z=s2z=chi

  • s1z: only the z spin component of most massive BH is considered, D = 3

  • s1z_s2z: only the z components of the spins are considered (no precession), D = 2

  • s1xz: spin components assigned to one BH in plane xz, D = 2

  • s1xyz: spin components assigned to one BH, D = 3

  • s1xz_s2z: the two z components are assigned as well as s1x, D = 3

  • s1xyz_s2z: the two z components are assigned as well as s1x, s1y, D = 4

  • fullspins: all the 6 dimensional spin parameter is assigned, D = 6

Regarding the spins, we stick to the following conventions:

  • If a spin is aligned to the z axis the spin variable is the value of the z component of the spin (with sign): s1z or s2z.

  • If a generic spin is assigned to a BH, the spin is always* expressed in sperical coordinates s1, theta1, phi. s1 (or s2) represents the spin magnitude (between 0 and 1). The angle theta1 (theta2) corresponds to the polar angle of the spin, which controls the magnitude of in-plane spin. The angle phi1``(``phi2) is the aximuthal angle (if set), which controls the mixing between x and y components.

On top of the spins, the user can optionally specify a format for Angles and for the Eccentricity

Valid formats for the angles are:

  • iota: the inclination angle is included

  • iotaphi: the inclination angle and reference phase are included

Valid formats for the eccentricity are:

  • e: to include the orbital eccentricity

  • emeanano: to include the orbital eccentricity and mean periastron anomaly

Note that some waveform approximants do not support all these paramters. Using a format that sets them to be non zero will likely fail.

For example, valid formats are: mceta_s1xz_s2z_e_iotaphi, m1m2_nonspinning_e, Mq_s1xz_s2z_iotaphi, m1m2_s1z_s2z

Initialization. Creates a dict of dict with all the info for each format

D(variable_format)[source]

Returns the dimensionality of the parameter space required

Parameters:

variable_format (str) – How to handle the BBH variables.

Returns:

D – Dimensionality of the BBH parameter vector

Return type:

int

convert_theta(theta, in_format, out_format)[source]

Converts the input theta in the in_format to the chosen out_format.

This is equivalent to:

from mbank import variable_handler
vh = variable_handler()
vh.get_theta(vh.get_BBH_components(theta, in_format), out_format)
Parameters:

  • theta (ndarray) – shape: (N,D) - Parameters of the BBHs. The dimensionality depends on in_format

  • in_format (str) – Variable format of the input theta

  • out_format (str) – Variable format for the output theta

Returns:

theta – shape: (N,D)/(D,) - Components of the BBH in the chosen out_format

Return type:

ndarray

format_info(variable_format)[source]

Returns the a dict with some information about the format. The dict has the following entries:

  • mass_format : format for the masses

  • spin_format : format for the spins

  • eccentricity_format : format for the eccentricities

  • angle_format : format for the angles

  • D : dimensionality of the BBH space

  • e : whether the variables include the eccentricity e

  • meanano : whether the variables include the mean periastron anomaly meanano

  • iota : whether the variables include the inclination iota

  • phi : whether the variables include the reference phase phi

Parameters:

variable_format (str) – How to handle the BBH variables.

Returns:

format_info – Dictionary with the info for the format

Return type:

int

get_BBH_components(theta, variable_format)[source]

Given theta, it returns the components of the BBH suitable for lal

Parameters:

  • theta (ndarray) – shape: (N,12) - Parameters of the BBHs. The dimensionality depends on variable_format

  • variable_format (str) – How to handle the BBH variables.

Returns:

BBH_components – shape: (N,12) - Components of the BBH. Columns of the array are m1, m2, s1x, s1y, s1z, s2x, s2y, s2z, e, meanano iota, phi.

Return type:

ndarray

get_BBH_components_from_table(table)[source]

Given the BBH components, it returns the components suitable for the bank. Currently it doesn’t support eccentricity

Parameters:

table (ligolw.table) – A lsctable to load the parameters from. It has to be either a SimInspiral or a SnglInspiral table

Returns:

BBH_components – shape: (N,12) - Components of the BBH. Columns of the array are m1, m2, s1x, s1y, s1z, s2x, s2y, s2z, e, meanano iota, phi.

Return type:

ndarray

get_chiP(m1, m2, s1x, s1y, s1z, s2x, s2y)[source]

Computes the precessing spin parameter (one dimensional) as in 1408.1810 Also described in 2012.02209

Parameters:

  • m1 (ndarray) – shape: (N,)/() - Masses of the two BHs It assumes m1>=m2

  • m2 (ndarray) – shape: (N,)/() - Masses of the two BHs It assumes m1>=m2

  • s1x (ndarray) – shape: (N,)/() - In-plane spins of the primary black hole

  • s1y (ndarray) – shape: (N,)/() - In-plane spins of the primary black hole

  • s1z (ndarray) – shape: (N,)/() - Aligned spin for the primary black hole. Used to enforce Kerr limit in the spin parameter

  • s2x (ndarray) – shape: (N,)/() - In-plane spins of the secondary black hole

  • s2y (ndarray) – shape: (N,)/() - In-plane spins of the secondary black hole

Returns:

chiP – shape: (N,)/() - The precessing spin parameter

Return type:

ndarray

get_chiP_2D(m1, m2, s1x, s1y, s1z, s2x, s2y, s2z, only_spin1=False)[source]

Computes the two dimensional precessing spin parameter as in 2012.02209 The approximantion assigns a two dimensional in-plane spin to one of the two BHs. If the option only_spin1 is set, the in-plane spin will be always assigned to the primary BH (as in (7) in 2012.02209).

Parameters:

  • m1 (ndarray) – shape: (N,)/() - Masses of the two BHs

  • m2 (ndarray) – shape: (N,)/() - Masses of the two BHs

  • s1x (ndarray) – shape: (N,)/() - In-plane spins of the primary black hole

  • s1y (ndarray) – shape: (N,)/() - In-plane spins of the primary black hole

  • s1z (ndarray) – shape: (N,)/() - Aligned spin for the primary black hole. Used to enforce Kerr limit in the spin parameter (if it is the case)

  • s2x (ndarray) – shape: (N,)/() - In-plane spins of the secondary black hole

  • s2y (ndarray) – shape: (N,)/() - In-plane spins of the secondary black hole

  • s2z (ndarray) – shape: (N,)/() - Aligned spin for the secondary black hole. Used to enforce Kerr limit in the spin parameter (if it is the case)

  • only_spin1 (bool) – Whether to assign the precessing spin only always to the primary BH. The default is False, as 2012.02209 suggests.

Returns:

  • chiP_2D_1 (ndarray) – shape: (N,2)/(2,) - In-plane (x and y) components of the two dimensional precessing spin parameter on the primary BH

  • chiP_2D_2 (ndarray) – shape: (N,2)/(2,) - In-plane (x and y) components of the two dimensional precessing spin parameter on the secondary BH

get_chiP_BBH_components(BBH_components, chiP_type='chiP')[source]

Given a set of BBH components (in the output format of get_BBH_components()) it returns the components of the same BBH in the precessing spin parameter approximation. This implements a mapping between the 4 dimensional in-plane spin parameter (s1x, s1y, s2x, s2y) onto a smaller space. Several options are available:

  • chiP: performs the mapping described in eq (4.1) of arxiv/1408.1810, where the only non-zero componennt is s1x

  • chiP_2D: performs the mapping described in eq (10-11) of arxiv/2012.02209. It consist in assigning a two dimensional in-plane spin to the BH which exibit more precession

  • chiP_2D_BH1: performs the mapping described in eq (7) of arxiv/2012.02209. The spin parameter is the same as above but it is always assigned to the primary BH

Parameters:

  • BBH_components (ndarray) – shape: (N,12) - Parameters of the BBHs. Each row should keep: m1, m2, s1x, s1y, s1z, s2x, s2y, s2z, e, meanano, iota, phi

  • chiP_type (str) –

    A string to determine which precessing spin approximation to set

    • chiP: one dimensional spin parameter eq (5-6) of 2012.02209

    • chiP_2D: two dimensional spin parameter eq (10-11) of 2012.02209

    • chiP_2D_BH1: two dimensional spin parameter, always placed on BH1, as in eq (7) of 2012.02209

Returns:

m1, m2, s1x, s1y, s1z, s2x, s2y, s2z, e, meanano iota, phi – Components of the BBH in the std parametrization after the spin parameter mapping has been applied. Each has shape (N,)

Return type:

ndarray

get_massratio(theta, variable_format)[source]

Given theta, it returns the mass ratio.

Parameters:

  • theta (ndarray) – shape: (N,D) - Parameters of the BBHs. The dimensionality depends on variable_format

  • variable_format (str) – How to handle the BBH variables.

Returns:

q – Chirp mass of each BBH

Return type:

ndarray

get_mchirp(theta, variable_format)[source]

Given theta, it returns the chirp mass

Parameters:

  • theta (ndarray) – shape: (N,D)/(D,) - Parameters of the BBHs. The dimensionality depends on variable_format

  • variable_format (str) – How to handle the BBH variables.

Returns:

mchirp – Chirp mass of each BBH

Return type:

ndarray

get_theta(BBH_components, variable_format)[source]

Given the BBH components, it returns the components suitable for the bank.

Parameters:

  • BBH_components (ndarray) – shape: (N,12)/(12,) - Parameters of the BBHs. The columns of the array should be: m1, m2, s1x, s1y, s1z, s2x, s2y, s2z, e, meanano, iota, phi

  • variable_format (str) – How to handle the BBH variables.

Returns:

theta – shape: (N,D)/(D,) - Components of the BBH in the format suitable for the bank. The dimensionality depends on variable_format

Return type:

ndarray

is_theta_ok(theta, variable_format, raise_error=False)[source]

Given a value of theta, it checks whether it is an acceptable value for the given spin format. It calls get_BBH_components() internally.

Parameters:

  • theta (ndarray) – shape: (N,D) - Parameters of the BBHs. The dimensionality depends on variable_format

  • variable_format (str) – How to handle the BBH variables.

  • raise_error (bool) – Whether to raise a ValueError if theta is not acceptable

Returns:

is_ok – True if theta is an acceptable value. False otherwise

Return type:

bool

labels(variable_format, latex=False)[source]

List the names of the variables for each entry of the BBH parameter vector

Parameters:

variable_format (str) – How to handle the BBH variables.

Returns:

  • labels (list) – List of labels for the parmams in the BBH (each a str)

  • latex (bool) – Whether the labels should be in latex

switch_BBH(theta, variable_format)[source]

Given theta, it returns the theta components of the system with switched BBH masses (so that m1>m2) If only BH1 has an in-plane component, only the z components of the spins will be switched: this is equivalent to assume that the in-plane spin of BH1 is a collective spin.

Parameters:

  • theta (ndarray) – shape: (N,D) - Parameters of the BBHs. The dimensionality depends on variable_format

  • variable_format (str) – How to handle the BBH variables.