mbank.bank

Module to implement a bank of gravitational waves signals. It implement the class cbc_bank which provides a large number of functionalities to generate a bank, perform I/O operations on files

class cbc_bank(variable_format, filename=None)[source]

The class implements a bank for compact binary coalescence signals (CBC). A bank is a collection of templates (saved in the method bank.templates). Each template is a row of the array; the columns are specified by a given variable format. To know more about the available variable formats, please refer to mbank.handlers.variable_handler.

A bank is generated from a tiling object (created internally) that speeds up the template placing. The tiling file is not part of a bank and lives as an independent object mbank.handlers.tiling_handler. A bank can be saved in txt or in the std ligo xml file.

Initialize the bank with a given variable format. If a filename is given, the bank is loaded from file.

Parameters:

  • variable_format (str) – How to handle the variables. See class variable_handler for more details

  • filename (str) – Optional filename to load the bank from (if None, the bank will be initialized empty)

property BBH_components

Returns the BBH components of the templates in the bank. They are: m1, m2, s1x, s1y, s1z, s2x, s2y, s2z, e, meanano iota, phi

Returns:

BBH_components – shape: (N,12) Array of BBH components of the templates in the bank. They have the same layout as mbank.handlers.variable_handler.get_BBH_components()

Return type:

ndarray

property D

The dimensionality of the space

Returns:

D – Keeps the dimensionality of the space

Return type:

float

add_templates(new_templates)[source]

Adds a bunch of templates to the bank. They must be of a shape suitable for the variable format

Parameters:

new_templates (ndarray) – shape: (N,D)/(D,) New templates to add. They need to be stored in an array of shape (N,D) or (D,), where D is the dimensionality of the bank

enforce_boundaries(boundaries)[source]

Remove from the bank the templates that do not lie within the given boundaries

Parameters:

boundaries (ndarray) – shape: (2,D) - An array with the boundaries for the model. Lower limit is boundaries[0,:] while upper limits is boundaries[1,:]

generate_bank(metric_obj, minimum_match, boundaries, tolerance, placing_method='random', metric_type='hessian', grid_list=None, train_flow=False, use_ray=False, N_livepoints=50, covering_fraction=0.01, empty_iterations=100, max_depth=6, n_layers=2, hidden_features=4, N_epochs=1000, verbose=True)[source]

DEPRECATED

Generates a bank using a hierarchical hypercube tesselation. The bank generation consists in two steps:

  1. Tiling generation by iterative splitting of the parameter space

  2. Template placing in each tile, according to the method given in placing_method

Parameters:

  • metric_obj (cbc_metric) – A cbc_metric object to compute the match with

  • minimum_match (float) – Average match between templates

  • boundaries (ndarray) – shape: (2,D) - An array with the boundaries for the model. Lower limit is boundaries[0,:] while upper limits is boundaries[1,:]

  • tolerance (float) – Threshold used for the tiling algorithm. It amounts to the maximum tolerated relative change between the metric determinant of the child and the parent |M|. For more information, see mbank.handlers.tiling_handler.create_tiling

  • placing_method (str) – The placing method to set templates in each tile. See place_templates for more information.

  • metric_type (str) – The method computation method to use. For more information, you can check metric.cbc_metric.get_metric.

  • train_flow (bool) – Whether to train a normalizing flow model after the tiling is generated. It will be used for metric interpolation during the template placing

  • grid_list (list) – A list of ints, each representing the number of coarse division of the space. If use ray option is set, the subtiling of each coarse division will run in parallel If None, no prior splitting will be made.

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

  • N_livepoints (float) – Only applies for random method or pruning method. For random (or related), it represents the number of livepoints to use for the estimation of the coverage fraction. For pruning, it amounts to the the ratio between the number of livepoints and the number of templates placed by uniform placing method.

  • covering_fraction (float) – Only applies for random method or pruning method. Fraction of livepoints to be covered before terminating the template placing

  • empty_iterations (int) – Number of consecutive proposal inside a tile to be rejected before the tile is considered full. It only applies to the stochastic placing method.

  • 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

  • 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

  • N_epochs (int) – Number of epochs for the training of the flow

  • verbose (bool) – Whether to print some output

Returns:

tiling – A list of tiles used for the bank generation

Return type:

tiling_handler

generate_bank_mcmc(metric_obj, N_templates, boundaries, n_walkers=100, use_ray=False, thin_factor=None, load_chain=None, save_chain=None, verbose=True)[source]

Fills the bank with a Markov Chain Monte Carlo (MCMC) method. The MCMC sample from the probability distribution function induced by the metric:

\[p(\theta) \propto \sqrt{|M(\theta)|}\]

The function uses emcee package, not in the mbank dependencies.

Parameters:

  • metric_obj (cbc_metric) – A cbc_metric objec to compute the PDF to distribute the templates

  • N_templates (int) – Number of new templates to sample from the PDF

  • boundaries (ndarray) – shape: (2,D) - An array with the boundaries for the model. Lower limit is boundaries[0,:] while upper limits is boundaries[1,:]

  • n_walkers (int) – Number of independent walkers during the chain. If use_ray option is True, they will be run in parellel.

  • use_ray (bool) – Whether to use ray to parallelize the sampling. #DO THIS OPTION

  • thin_factor (int) – How many MC steps to discard before selecting one. If None it is computed authomatically based on the autocorrelation: this is the recommended behaviour

  • load_chain (str) – Path to a file where the position of each walker is stored, togheter with integrated aucorellation tau. The file must keep a np.array of dimensions (n_walkers, D). The first line of the file is intended to be the autocorrelation time for each variable. If it is not provided, a standard value of 4 (meaning a thin step of 2) is assumed. If set, the sampler will start from there and the burn-in phase will not be required.

  • save_chain (str) – If not None, it saves the path in which to save the status of the sampler. The file saved is ready to be loaded with option load_chain

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

load(filename)[source]

Load a template bank from file. They are added to the existing templates (if any).

Parameters:

filename (str) – Filename to load the bank from

place_templates(tiling, minimum_match, placing_method, N_livepoints=10000, covering_fraction=0.01, empty_iterations=100, verbose=True)[source]

Given a tiling, it places the templates according to the given method and adds them to the bank

Parameters:

  • tiling (tiling_handler) – A tiling handler with a non-empty tiling

  • minimum_match (float) – Minimum match for the bank: it controls the distance between templates as in utils.avg_dist()

  • placing_method (str) –

    The placing method to set templates in each tile. It can be:

    • uniform -> Uniform drawing in each hyper-rectangle, according to the volume

    • qmc -> Quasi Monte Carlo drawing in each hyper-rectangle, according to the volume

    • random -> Random points sampled from the tiling are added to the bank until only a fraction eta = 0.01 of the original volume is left uncovered

    • stochastic -> Stochastic placement: proposal are made and accepted only if they are more distant than sqrt(1-minimum_match) from the rest of the templates

    • random_stochastic -> Random placement, followed by a stochastic placement to “fill” the holes left by the random method

    • geometric -> Geometric placement: templates are placed on a lattice, with spacing computed according to the minimum match requirement

    • iterative -> Each tile is split iteratively until the number of templates in each subtile is equal to one

    • iterative_stochastic -> The outcome of the iterative method is given as input to the stochastic method

    • geo_stochastic -> Geometric placement + stochastic placement

    • tile_stochastic -> Stochastic placement performed for each tile separately

    • pruning -> The volume is covered with some point that are killed by placing the templates

    • tile_random -> Random placement for each tile separately

    Those methods are listed in cbc_bank.placing_methods

  • N_livepoints (float) – Only applies for random method or pruning method. For random (or related), it represents the number of livepoints to use for the estimation of the coverage fraction. For pruning, it amounts to the the ratio between the number of livepoints and the number of templates placed by uniform placing method.

  • covering_fraction (float) – Only applies for random method or pruning method. Fraction of livepoints to be covered before terminating the loop

  • empty_iterations (int) – Number of consecutive proposal inside a tile to be rejected before the tile is considered full. It only applies to the stochastic placing method (or related).

  • verbose (bool) – Whether to print the output

Returns:

new_templates – The templates generated (already added to the bank)

Return type:

ndarray

property placing_methods

List all the available placing methods

Returns:

placing_methods – The available methods for placing the templates

Return type:

list

save_bank(filename, f_max=1024.0, ifo='L1')[source]

Save the bank to file

WARNING: xml file format currently does not support eccentricity

Parameters:

  • filename (str) – Filename to save the bank at

  • f_max (float) – End frequency (in Hz) for the templates (applies only to xml format)

  • ifo (str) – Name of the interferometer the bank refers to (only applies to xml files)