gstlal_inspiral_bank_splitter
=============================

This program splits template banks into sub banks suitable for singular value decomposition; see gstlal_bank_splitter for more information

Usage examples
--------------

1. split up bank file for H1; sort by mchirp; add final frequency and specify a maximum frequency::

	gstlal_bank_splitter --overlap 10 --instrument H1 --n 100 --sort-by mchirp --add-f-final --max-f-final 2048 H1-TMPLTBANK-871147516-2048.xml

2. Please add more!

Review status
-------------

Compared original bank with the split banks.  Verified that they are the same, e.g., add sub bank files into test.xml.gz and run (except that lalapps_tmpltbank adds redundant templates)::

	ligolw_print -t sngl_inspiral -c mass1 -c mass2 ../H1-TMPLTBANK-871147516-2048.xml | sort -u | wc
	ligolw_print -t sngl_inspiral -c mass1 -c mass2 test.xml.gz | sort -u | wc

+-------------------------------------------------+------------------------------------------+------------+
| Names                                           | Hash                                     |            |
+=================================================+==========================================+============+
| Florent, Sathya, Duncan Me., Jolien, Kipp, Chad | 7536db9d496be9a014559f4e273e1e856047bf71 | 2014-04-28 |
+-------------------------------------------------+------------------------------------------+------------+
| Sathya, Duncan Me., Jolien, Kipp, Chad          | 72875f5cb241e8d297cd9b3f9fe309a6cfe3f716 | 2015-11-06 |
+-------------------------------------------------+------------------------------------------+------------+

Command line options
--------------------



.. code-block:: none

   Usage: gstlal_inspiral_bank_splitter [options]
   
   Options:
     -h, --help            show this help message and exit
     --output-path=path    Set the path to the directory where output files will
                           be written.  Default is ".".
     --stats-file=file     Set the path where the SVD metadata (stats) file will
                           be written.  Required
     --bank-name=name      If specified, set the name of the template bank being
                           split. Used to track metadata when splitting multiple
                           template banks, and when providing the same SVD
                           metadata file across multiple template banks, will
                           create unique SVD bin numbers across all template
                           banks.
     --output-full-bank-file=path
                           Set the path to output the bank.
     --n=count             Set the number of templates per output file
                           (required). It will be rounded to make all sub banks
                           approximately the same size.
     --overlap=count       overlap the templates in each file by this amount,
                           must be even
     --sort-by=column      Select the template sort column, default mchirp
     --f-final=float       f_final to populate table with
     --instrument=ifo      override the instrument, required
     -v, --verbose         Be verbose.
     --psd-xml=PSD_XML     Specify a PSD to use for computing template bandwidth.
                           Required if --sort-by=bandwidth or needing bandwidth
                           and/or horizon distance metadata.
     --approximant=APPROXIMANT
                           Must specify an approximant given as
                           mchirp_min:mchirp_max:string
     --f-low=frequency     Lower frequency cutoff. Required
     --group-by-chi=N      group templates into N groups of chi - helps with SVD.
                           Default 1
     --group-by-mu=N       group templates into N groups of mu2, one of the
                           orthogonalized PN-phase coefficients, to help with
                           SVD. Default 20
     --num-banks=str       The number of parallel subbanks per SVD bank. More
                           than 2 sub-banks is not recommended and return an
                           error. Setting --num-banks-force forces the program to
                           run through. can be given as a list like 1,2,3,4 then
                           it will split up the bank into N groups with M banks
                           each. (required)
     --num-banks-force     Set if you intentially set --num-banks larger than 2.