Package: gw-mbank
mbankmbankis a code for fast Gravitational Waves template bank generation. It creates a bank of binary black hole (BBH) systems. It is very handy for generating precessing and eccentric banks.If you want more details, you can take a look at thedocumentation.
Otherwise, you can keep reading and learn the essentials below.How it worksIn order to search for a Binary Black Hole (BBH) signal, one needs to come up with a set of templates (a.k.a. bank), signals that will be searched in the noisy data from the interferometers.
Generating abankis a tedious work, requiring to place huge number of templates so that their mutual distance is as constant as possible. Unfortunately the computation of such distance is highly expensive and, if we want to expand the parameter space covered by the searches, we areveryinterested to get a reliable bank covering an high dimensional space at a decent cost.This is exactly the purpose ofmbank: thanks to a cheap approximation to the distance between templates, it provides a very fast bank generation method, which can be successfully employed for high dimensional bank generation. The approximation consist in replacing the complicated distance with ametricdistance (i.e. a bilinear form).The bank generation algorithm works in 4+1 steps:Defining a metric approximationComputing the metric on a small set of points all around the space (a.k.a. tiling the space)Optional: training a normalizing flow to interpolate the metricPlacing the templates according to the tilingValidate the bank by means of injectionsmbankis the code that does all of this for you!How to installTo install the latestreleasedverion (no release has been done yet):pipinstallgw-mbankTo intall the latest version in the github repository, you can type:pipinstallgit+https://github.com/stefanoschmidt1995/mbankOtherwise, you can clone the repo, build a distribution and install the package:gitclonegit@github.com:stefanoschmidt1995/mbank.gitcdmbank
pythonsetup.pysdist
pipinstalldist/gw-mbank*.tar.gzThis will install the source code as well as some executables that makes the bank generation easier (plus the dependencies).How to useTo generate a bank you can use the executablembank_run. Make sure you have a PSD file (either in csv file either in ligo xml format).
You will need to choose:The BBH variables that you want to vary within the bank (--variable_formatparameter)The minimum match (--mm), that controls the average spacing between templatesThe range of physical parameters you want to include in the bank (note that the spins arealwaysexpressed in spherical coordinates)Low and high frequency for the match/metric computation (--f-minand--f-max)The WF FD approximant (it must be lal)Maximum number of templates in each tile: this tunes the hierarchical tiling (--template-in-tileargument)A coarse grid for tiling: the tiling can be parallelized and performed independently on each split (--grid-sizeargument)The placing method--placing-methodfor the templates in each tile ('geometric', 'stochastic', 'pure_stochastic', 'uniform', 'iterative', 'random'). The 'stochastic' method is recommended.If you don't have a favourite PSD, you can download one withwget https://dcc.ligo.org/public/0165/T2000012/002/aligo_O3actual_H1.txt.An example command to generate a simple non-precessing bank is:mbank_run\--run-namemyFirstBank\--variable-formatMq_s1z_s2z\--grid-size1,1,2,2\--mm0.97\--tile-tolerance0.5\--max-depth10\--psd./aligo_O3actual_H1.txt--asd\--f-min15--f-max1024\--mtot-range2075\--q-range15\--s1-range0.00.99\--s2-range-0.990.99\--plot\--placing-methodstochastic\--empty-iterations100\--approximantIMRPhenomPv2\--use-rayTo know more information about the available options type:mbank_run--helpThis is how the output bank look like:You can also use the metric to estimate the fitting factor for a bunch of injections:mbank_injections\--n-injs10000\--variable-formatMq_s1z_s2z\--tiling-fileout_myFirstBank/tiling_myFirstBank.npy\--bank-fileout_myFirstBank/bank_myFirstBank.xml.gz\--psd./aligo_O3actual_H1.txt--asd\--approximantIMRPhenomPv2\--f-min15--f-max1024\--plotIf you specify the--full-matchoption, the match will be recomputed without a metric approximation: in this case, you want to speed things up with something like--use-rayand--cache(if you have enough memory).
You can also throw some injection chosen from a file: you just need to set an input xml injection file with the--inj-fileoption.Here's the injection recovery:If you don't feel like typing all the options every time, you can add them to a text filemyFirstBank.iniand pass it to the command: it will figure out by itself. You can find some exampleini filesin the repo. To run them:mbank_runmy_first_eccentric_bank.ini
mbank_injectionsmy_first_eccentric_bank.iniAs you see, the same file can be used for different commands: each command will just ignore any option not relevant for it.TODO:finish to write the making bank by hand sectioncheck the READMEcheck the docs againsubmit to PyPIContactsFore more info, or just to say hello, you can contact me:stefanoschmidt1995@gmail.com.