PyCBC template bank generation documentation (pycbc.tmpltbank)

Introduction

This page gives details on how to use the various bank generation codes and bank generation workflows available in pyCBC and specifically the pyCBC.tmpltbank module. We also describe the sBank code, currently in lalinspiral. These codes currently consist of

Each of these codes and workflow generators is described in turn and is accompanied by some examples of how to run the code, some relevant background and references and the options described from the codes’ help messages.

The output of all these codes is currently a sngl_inspiral_table XML object. However, if people want to output in HDF or other formats it should be easy to write a back-end module to do this. The code may not fill every necessary column of the sngl_inspiral table, please let me know if something is missing and it will be added!

NOTE: Aligned-spin template generation is not at the point where it can be considered “plug and play”. Here we give some examples for distinct situations, but these options may not be suitable in other situations, for example if changing the mass ranges, or PSD, or frequency ranges etc. Template banks should always be checked (see :ref:`pycbc_banksim <banksim>`) and you should consider if you have placed too many templates (“overcovering” the parameter space), or if the placement has left gaps in the coverage (“undercovering” the parameter space). There are numerous things that can be tuned in the workflow generators, we try to describe them here, but it is often good to ask questions if you are unsure!

In some cases recommendations are given for which codes to use where. It should be noted that these are personal recommendations of the page maintainer (Ian), and there is always a strong possibility that Ian, and the recommendations he makes, are wrong. Where multiple methods exist, it is advised that the user try out the different methods and decide for themselves which method is best.

Non spin bank placement: pycbc_geom_nonspinbank

Overview

pycbc_geom_nonspinbank is designed as a drop in replacement for lalapps_tmpltbank. It uses a globally flat coordinate system, which enables it to easily place banks at 3.5PN order (and higher order as these become available).

Mapping back from the new coordinate system to masses and spins makes the bank placement slower than lalapps_tmpltbank. However, it doesn’t waste stupid amounts of time calculating the ethinca metric so it is faster than tmpltbank if the ethinca components are being computed.

A metric-based approach is not very reliable at high masses, but we have found that in general this just results in overcoverage, which is not normally a problem as most templates are found at lower masses. One might want to consider the stochastic code sbank if placing a high-mass only non-spinning template bank.

Ian’s recommendation: Use this code instead of lalapps_tmpltbank if you want a non-spinning bank. If only placing high-mass templates consider using lalapps_cbc_sbank, described below.

Background

The methods, specifically the metric and the lattice algorithm, used in lalapps_tmpltbank are described in:

  • Sathyaprakash, B. S. and Dhurandhar, S. V., Phys.Rev. D44 3819 (1991)
  • Poisson, Eric and Will, Clifford M., Phys.Rev. D52 848 (1995)
  • Balasubramanian, R. et al., Phys.Rev. D53 3033 (1996)
  • Owen, Benjamin J., Phys.Rev. D53 6749 (1996)
  • Owen, Benjamin J. and Sathyaprakash, B. S., Phys.Rev. D60 022002 (1998)
  • Babak, S. et al., Class.Quant.Grav. 23, 5477 (2006)
  • Cokelaer, Thomas Phys.Rev. D76 102004 (2007)
  • Babak, S. et al., Phys.Rev. D87 024033 (2013)

Our approach still uses the hexagonal lattice algorithm but instead of using the chirp times as coordinates uses the xi_i coordinate system described in:

  • Brown, Duncan A. et al. Phys.Rev. D86 084017 (2012)
  • Ohme, Frank et al. Phys.Rev. D88 024002 (2013)

This allows us to easily use higher order terms in the metric placement as we do not have to worry about correlations between tau 0 and 3 and the other coordinates. Our coordinates are independent.

The issue is that unlike in the lalapps_tmpltbank approach it is not trivial to map back from our coordinates to masses. Currently we use a monte-carlo approach to find mass positions fitting the desired coordinates. If we could implement some form of 2D interpolation this would probably be much faster. If anyone wants to investigate this I can provide lots of data!

Some examples

This first example computes a non-spinning template bank using a supplied ASD text file. It also calculates the ethinca metric components for a filter with ISCO cutoff

pycbc_geom_nonspinbank --pn-order twoPN --f0 40 --f-low 40 --f-upper 2048 --delta-f 0.01 --min-match 0.97 --min-mass1 2.0 --min-mass2 2.0 --max-mass1 3. --max-mass2 3. --verbose --output-file testNonSpin.xml --calculate-ethinca-metric --filter-cutoff SchwarzISCO --asd-file ZERO_DET_high_P.txt

Here is a second example that computes a non-spinning template bank from a frame cache file. This needs a bunch more options to read data and estimate the PSD from that.

pycbc_geom_nonspinbank --pn-order threePointFivePN --f0 40 --f-low 40 --f-upper 2048 --delta-f 0.01 --min-match 0.97 --min-mass1 2.0 --min-mass2 2.0 --max-mass1 3. --max-mass2 3. --verbose --output-file testNonSpin.xml --calculate-ethinca-metric --filter-cutoff SchwarzISCO --psd-estimation median --psd-segment-length 256 --psd-segment-stride 128 --psd-inverse-length 8 --gps-start-time 900000033 --gps-end-time 900002081 --strain-high-pass 30 --pad-data 8 --sample-rate 4096 --frame-cache cache/H-H1_NINJA2_G1000176_EARLY_RECOLORED_CACHE-900000024-10653.lcf --channel-name H1:LDAS-STRAIN --max-total-mass 5.5 --min-total-mass 4.5

Command line options

The command line options read as follows

$ pycbc_geom_nonspinbank --help
usage: pycbc_geom_nonspinbank [-h] [--version] [-V]
                              [--random-seed RANDOM_SEED] -m MIN_MATCH -O
                              OUTPUT_FILE [--f-low-column NAME] --pn-order
                              PN_ORDER [--f0 F0] --f-low F_LOW --f-upper
                              F_UPPER --delta-f DELTA_F [--write-metric]
                              --min-mass1 MIN_MASS1 --max-mass1 MAX_MASS1
                              --min-mass2 MIN_MASS2 --max-mass2 MAX_MASS2
                              [--max-total-mass MAX_TOTAL_MASS]
                              [--min-total-mass MIN_TOTAL_MASS]
                              [--max-chirp-mass MAX_CHIRP_MASS]
                              [--min-chirp-mass MIN_CHIRP_MASS]
                              [--max-eta MAX_ETA] [--min-eta MIN_ETA]
                              [--ns-eos NS_EOS]
                              [--remnant-mass-threshold REMNANT_MASS_THRESHOLD]
                              [--use-eos-max-ns-mass]
                              [--delta-bh-spin DELTA_BH_SPIN]
                              [--delta-ns-mass DELTA_NS_MASS]
                              [--psd-model {AdVBNSOptimizedSensitivityP1200087,AdVDesignSensitivityP1200087,AdVEarlyHighSensitivityP1200087,AdVEarlyLowSensitivityP1200087,AdVLateHighSensitivityP1200087,AdVLateLowSensitivityP1200087,AdVMidHighSensitivityP1200087,AdVMidLowSensitivityP1200087,AdvVirgo,CosmicExplorerP1600143,CosmicExplorerPessimisticP1600143,CosmicExplorerWidebandP1600143,EinsteinTelescopeP1600143,GEO,GEOHF,KAGRA,KAGRADesignSensitivityT1600593,KAGRAEarlySensitivityT1600593,KAGRALateSensitivityT1600593,KAGRAMidSensitivityT1600593,KAGRAOpeningSensitivityT1600593,TAMA,Virgo,aLIGOBHBH20Deg,aLIGOBHBH20DegGWINC,aLIGOBNSOptimizedSensitivityP1200087,aLIGODesignSensitivityP1200087,aLIGOEarlyHighSensitivityP1200087,aLIGOEarlyLowSensitivityP1200087,aLIGOHighFrequency,aLIGOHighFrequencyGWINC,aLIGOLateHighSensitivityP1200087,aLIGOLateLowSensitivityP1200087,aLIGOMidHighSensitivityP1200087,aLIGOMidLowSensitivityP1200087,aLIGONSNSOpt,aLIGONSNSOptGWINC,aLIGONoSRMHighPower,aLIGONoSRMLowPower,aLIGONoSRMLowPowerGWINC,aLIGOQuantumBHBH20Deg,aLIGOQuantumHighFrequency,aLIGOQuantumNSNSOpt,aLIGOQuantumNoSRMHighPower,aLIGOQuantumNoSRMLowPower,aLIGOQuantumZeroDetHighPower,aLIGOQuantumZeroDetLowPower,aLIGOThermal,aLIGOZeroDetHighPower,aLIGOZeroDetHighPowerGWINC,aLIGOZeroDetLowPower,aLIGOZeroDetLowPowerGWINC,eLIGOModel,eLIGOShot,iLIGOModel,iLIGOSRD,iLIGOSeismic,iLIGOShot,iLIGOThermal,flat_unity}]
                              [--psd-file PSD_FILE] [--asd-file ASD_FILE]
                              [--psd-inverse-length PSD_INVERSE_LENGTH]
                              [--psdvar_short_segment SECONDS]
                              [--psdvar_long_segment SECONDS]
                              [--psdvar_overlap SECONDS]
                              [--psdvar_low_freq HERTZ]
                              [--psdvar_high_freq HERTZ]
                              [--psd-estimation {mean,median,median-mean}]
                              [--psd-segment-length PSD_SEGMENT_LENGTH]
                              [--psd-segment-stride PSD_SEGMENT_STRIDE]
                              [--psd-num-segments PSD_NUM_SEGMENTS]
                              [--psd-output PSD_OUTPUT]
                              [--gps-start-time GPS_START_TIME]
                              [--gps-end-time GPS_END_TIME]
                              [--strain-high-pass STRAIN_HIGH_PASS]
                              [--pad-data PAD_DATA] [--taper-data TAPER_DATA]
                              [--sample-rate SAMPLE_RATE]
                              [--channel-name CHANNEL_NAME]
                              [--frame-cache FRAME_CACHE [FRAME_CACHE ...]]
                              [--frame-files FRAME_FILES [FRAME_FILES ...]]
                              [--frame-type FRAME_TYPE]
                              [--frame-sieve FRAME_SIEVE]
                              [--fake-strain {AdVBNSOptimizedSensitivityP1200087,AdVDesignSensitivityP1200087,AdVEarlyHighSensitivityP1200087,AdVEarlyLowSensitivityP1200087,AdVLateHighSensitivityP1200087,AdVLateLowSensitivityP1200087,AdVMidHighSensitivityP1200087,AdVMidLowSensitivityP1200087,AdvVirgo,CosmicExplorerP1600143,CosmicExplorerPessimisticP1600143,CosmicExplorerWidebandP1600143,EinsteinTelescopeP1600143,GEO,GEOHF,KAGRA,KAGRADesignSensitivityT1600593,KAGRAEarlySensitivityT1600593,KAGRALateSensitivityT1600593,KAGRAMidSensitivityT1600593,KAGRAOpeningSensitivityT1600593,TAMA,Virgo,aLIGOBHBH20Deg,aLIGOBHBH20DegGWINC,aLIGOBNSOptimizedSensitivityP1200087,aLIGODesignSensitivityP1200087,aLIGOEarlyHighSensitivityP1200087,aLIGOEarlyLowSensitivityP1200087,aLIGOHighFrequency,aLIGOHighFrequencyGWINC,aLIGOLateHighSensitivityP1200087,aLIGOLateLowSensitivityP1200087,aLIGOMidHighSensitivityP1200087,aLIGOMidLowSensitivityP1200087,aLIGONSNSOpt,aLIGONSNSOptGWINC,aLIGONoSRMHighPower,aLIGONoSRMLowPower,aLIGONoSRMLowPowerGWINC,aLIGOQuantumBHBH20Deg,aLIGOQuantumHighFrequency,aLIGOQuantumNSNSOpt,aLIGOQuantumNoSRMHighPower,aLIGOQuantumNoSRMLowPower,aLIGOQuantumZeroDetHighPower,aLIGOQuantumZeroDetLowPower,aLIGOThermal,aLIGOZeroDetHighPower,aLIGOZeroDetHighPowerGWINC,aLIGOZeroDetLowPower,aLIGOZeroDetLowPowerGWINC,eLIGOModel,eLIGOShot,iLIGOModel,iLIGOSRD,iLIGOSeismic,iLIGOShot,iLIGOThermal,zeroNoise}]
                              [--fake-strain-seed FAKE_STRAIN_SEED]
                              [--fake-strain-from-file FAKE_STRAIN_FROM_FILE]
                              [--injection-file INJECTION_FILE]
                              [--sgburst-injection-file SGBURST_INJECTION_FILE]
                              [--ringdown-injection-file RINGDOWN_INJECTION_FILE]
                              [--injection-scale-factor INJECTION_SCALE_FACTOR]
                              [--gating-file GATING_FILE]
                              [--autogating-threshold SIGMA]
                              [--autogating-cluster SECONDS]
                              [--autogating-width SECONDS]
                              [--autogating-taper SECONDS]
                              [--autogating-pad SECONDS]
                              [--normalize-strain NORMALIZE_STRAIN]
                              [--zpk-z ZPK_Z [ZPK_Z ...]]
                              [--zpk-p ZPK_P [ZPK_P ...]] [--zpk-k ZPK_K]
                              [--witness-frame-type WITNESS_FRAME_TYPE]
                              [--witness-tf-file WITNESS_TF_FILE]
                              [--witness-filter-length WITNESS_FILTER_LENGTH]
                              [--calculate-time-metric-components | --calculate-ethinca-metric]
                              [--ethinca-pn-order {threePointFivePN,twoPN,twoPointFivePN,threePN,onePointFivePN,onePN,zeroPN}]
                              [--filter-cutoff {HybridMECO,SEOBNRv1RD,LightRing,MECO,LRD,FRD,EOBNRv2RD,SEOBNRv2RD,BKLISCO,ERD,SEOBNRv4RD,EOBNRv2HMRD,SEOBNRv2Peak,IMRPhenomCFinal,IMRPhenomDPeak,SEOBNRv4Peak,SEOBNRv1Peak,IMRPhenomBFinal,SchwarzISCO}]
                              [--ethinca-frequency-step ETHINCA_FREQUENCY_STEP]

Template bank generator for placing a bank of non-spinning templates.

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  -V, --verbose         verbose output (default: False)
  --random-seed RANDOM_SEED
                        Random seed to use when calling numpy.random functions
                        used in obtaining the principal components and when
                        translating points back to physical space. If given,
                        the code should give the same output when run with the
                        same random seed. (default: None)
  -m MIN_MATCH, --min-match MIN_MATCH
                        Generate bank with specified minimum match. Required.
                        (default: None)
  -O OUTPUT_FILE, --output-file OUTPUT_FILE
                        Output file name. Required. (default: None)
  --f-low-column NAME   If given, store the lower frequency cutoff into column
                        NAME of the single-inspiral table. (default: None)

Options related to calculating the parameter space metric:
  --pn-order PN_ORDER   Determines the PN order to use. For a bank of non-
                        spinning templates, spin-related terms in the metric
                        will be zero. REQUIRED. Choices: * zeroPN: Will only
                        include the dominant term (proportional to chirp mass)
                        * onePN: Will only the leading orbit term and first
                        correction at 1PN * onePointFivePN: Will include orbit
                        and spin terms to 1.5PN. * twoPN: Will include orbit
                        and spin terms to 2PN. * twoPointFivePN: Will include
                        orbit and spin terms to 2.5PN. * threePN: Will include
                        orbit terms to 3PN and spin terms to 2.5PN. *
                        threePointFivePN: Include orbit terms to 3.5PN and
                        spin terms to 2.5PN (default: None)
  --f0 F0               f0 is used as a dynamic scaling factor when
                        calculating integrals used in metric construction.
                        I.e. instead of integrating F(f) we integrate F(f/f0)
                        then rescale by powers of f0. The default value 70Hz
                        should be fine for most applications. OPTIONAL.
                        UNITS=Hz. **WARNING: If the ethinca metric is to be
                        calculated, f0 must be set equal to f-low** (default:
                        70.0)
  --f-low F_LOW         Lower frequency cutoff used in computing the parameter
                        space metric. REQUIRED. UNITS=Hz (default: None)
  --f-upper F_UPPER     Upper frequency cutoff used in computing the parameter
                        space metric. REQUIRED. UNITS=Hz (default: None)
  --delta-f DELTA_F     Frequency spacing used in computing the parameter
                        space metric: integrals of the form \int F(f) df are
                        approximated as \sum F(f) delta_f. REQUIRED. UNITS=Hz
                        (default: None)
  --write-metric        If given write the metric components to disk as they
                        are calculated. (default: False)

Options related to mass and spin limits for bank generation:
  --min-mass1 MIN_MASS1
                        Minimum mass1: must be >= min-mass2. REQUIRED.
                        UNITS=Solar mass (default: None)
  --max-mass1 MAX_MASS1
                        Maximum mass1: must be >= max-mass2. REQUIRED.
                        UNITS=Solar mass (default: None)
  --min-mass2 MIN_MASS2
                        Minimum mass2. REQUIRED. UNITS=Solar mass (default:
                        None)
  --max-mass2 MAX_MASS2
                        Maximum mass2. REQUIRED. UNITS=Solar mass (default:
                        None)
  --max-total-mass MAX_TOTAL_MASS
                        Maximum total mass. OPTIONAL, if not provided the max
                        total mass is determined by the component masses.
                        UNITS=Solar mass (default: None)
  --min-total-mass MIN_TOTAL_MASS
                        Minimum total mass. OPTIONAL, if not provided the min
                        total mass is determined by the component masses.
                        UNITS=Solar mass (default: None)
  --max-chirp-mass MAX_CHIRP_MASS
                        Maximum chirp mass. OPTIONAL, if not provided the max
                        chirp mass is determined by the component masses.
                        UNITS=Solar mass (default: None)
  --min-chirp-mass MIN_CHIRP_MASS
                        Minimum total mass. OPTIONAL, if not provided the min
                        chirp mass is determined by the component masses.
                        UNITS=Solar mass (default: None)
  --max-eta MAX_ETA     Maximum symmetric mass ratio. OPTIONAL, no upper bound
                        on eta will be imposed if not provided. UNITS=Solar
                        mass. (default: 0.25)
  --min-eta MIN_ETA     Minimum symmetric mass ratio. OPTIONAL, no lower bound
                        on eta will be imposed if not provided. UNITS=Solar
                        mass. (default: 0.0)
  --ns-eos NS_EOS       Select the EOS to be used for the NS when calculating
                        the remnant disk mass. Only 2H is currently supported.
                        OPTIONAL (default: None)
  --remnant-mass-threshold REMNANT_MASS_THRESHOLD
                        Setting this filters EM dim NS-BH binaries: if the
                        remnant disk mass does not exceed this value, the NS-
                        BH binary is dropped from the target parameter space.
                        When it is set to None (default value) the EM dim
                        filter is not activated. OPTIONAL (default: None)
  --use-eos-max-ns-mass
                        Cut the mass range of the smaller object to the
                        maximum mass allowed by EOS. OPTIONAL (default: False)
  --delta-bh-spin DELTA_BH_SPIN
                        Grid spacing used for the BH spin z component when
                        generating the surface of the minumum minimum
                        symmetric mass ratio as a function of BH spin and NS
                        mass required to produce a remnant disk mass that
                        exceeds the threshold specificed in --remnant-mass-
                        threshold. OPTIONAL (0.1 by default) (default: None)
  --delta-ns-mass DELTA_NS_MASS
                        Grid spacing used for the NS mass when generating the
                        surface of the minumum minimum symmetric mass ratio as
                        a function of BH spin and NS mass required to produce
                        a remnant disk mass that exceeds the thrsehold
                        specified in --remnant-mass-threshold. OPTIONAL (0.1
                        by default) (default: None)

Options to select the method of PSD generation:
  The options --psd-model, --psd-file, --asd-file, and --psd-estimation are
  mutually exclusive.

  --psd-model {AdVBNSOptimizedSensitivityP1200087,AdVDesignSensitivityP1200087,AdVEarlyHighSensitivityP1200087,AdVEarlyLowSensitivityP1200087,AdVLateHighSensitivityP1200087,AdVLateLowSensitivityP1200087,AdVMidHighSensitivityP1200087,AdVMidLowSensitivityP1200087,AdvVirgo,CosmicExplorerP1600143,CosmicExplorerPessimisticP1600143,CosmicExplorerWidebandP1600143,EinsteinTelescopeP1600143,GEO,GEOHF,KAGRA,KAGRADesignSensitivityT1600593,KAGRAEarlySensitivityT1600593,KAGRALateSensitivityT1600593,KAGRAMidSensitivityT1600593,KAGRAOpeningSensitivityT1600593,TAMA,Virgo,aLIGOBHBH20Deg,aLIGOBHBH20DegGWINC,aLIGOBNSOptimizedSensitivityP1200087,aLIGODesignSensitivityP1200087,aLIGOEarlyHighSensitivityP1200087,aLIGOEarlyLowSensitivityP1200087,aLIGOHighFrequency,aLIGOHighFrequencyGWINC,aLIGOLateHighSensitivityP1200087,aLIGOLateLowSensitivityP1200087,aLIGOMidHighSensitivityP1200087,aLIGOMidLowSensitivityP1200087,aLIGONSNSOpt,aLIGONSNSOptGWINC,aLIGONoSRMHighPower,aLIGONoSRMLowPower,aLIGONoSRMLowPowerGWINC,aLIGOQuantumBHBH20Deg,aLIGOQuantumHighFrequency,aLIGOQuantumNSNSOpt,aLIGOQuantumNoSRMHighPower,aLIGOQuantumNoSRMLowPower,aLIGOQuantumZeroDetHighPower,aLIGOQuantumZeroDetLowPower,aLIGOThermal,aLIGOZeroDetHighPower,aLIGOZeroDetHighPowerGWINC,aLIGOZeroDetLowPower,aLIGOZeroDetLowPowerGWINC,eLIGOModel,eLIGOShot,iLIGOModel,iLIGOSRD,iLIGOSeismic,iLIGOShot,iLIGOThermal,flat_unity}
                        Get PSD from given analytical model. (default: None)
  --psd-file PSD_FILE   Get PSD using given PSD ASCII file (default: None)
  --asd-file ASD_FILE   Get PSD using given ASD ASCII file (default: None)
  --psd-inverse-length PSD_INVERSE_LENGTH
                        (Optional) The maximum length of the impulse response
                        of the overwhitening filter (s) (default: None)
  --psdvar_short_segment SECONDS
                        Length of short segment when calculating the PSD
                        variability. (default: None)
  --psdvar_long_segment SECONDS
                        Length of long segment when calculating the PSD
                        variability. (default: None)
  --psdvar_overlap SECONDS
                        Sample length of the PSD. (default: None)
  --psdvar_low_freq HERTZ
                        Minimum frequency to consider in PSD comparison.
                        (default: None)
  --psdvar_high_freq HERTZ
                        Maximum frequency to consider in PSD comparison.
                        (default: None)
  --psd-estimation {mean,median,median-mean}
                        Measure PSD from the data, using given average method.
                        (default: None)
  --psd-segment-length PSD_SEGMENT_LENGTH
                        (Required for --psd-estimation) The segment length for
                        PSD estimation (s) (default: None)
  --psd-segment-stride PSD_SEGMENT_STRIDE
                        (Required for --psd-estimation) The separation between
                        consecutive segments (s) (default: None)
  --psd-num-segments PSD_NUM_SEGMENTS
                        (Optional, used only with --psd-estimation). If given,
                        PSDs will be estimated using only this number of
                        segments. If more data is given than needed to make
                        this number of segments then excess data will not be
                        used in the PSD estimate. If not enough data is given,
                        the code will fail. (default: None)
  --psd-output PSD_OUTPUT
                        (Optional) Write PSD to specified file (default: None)

Options for obtaining h(t):
  These options are used for generating h(t) either by reading from a file
  or by generating it. This is only needed if the PSD is to be estimated
  from the data, ie. if the --psd-estimation option is given.

  --gps-start-time GPS_START_TIME
                        The gps start time of the data (integer seconds)
                        (default: None)
  --gps-end-time GPS_END_TIME
                        The gps end time of the data (integer seconds)
                        (default: None)
  --strain-high-pass STRAIN_HIGH_PASS
                        High pass frequency (default: None)
  --pad-data PAD_DATA   Extra padding to remove highpass corruption (integer
                        seconds) (default: None)
  --taper-data TAPER_DATA
                        Taper ends of data to zero using the supplied length
                        as a window (integer seconds) (default: 0)
  --sample-rate SAMPLE_RATE
                        The sample rate to use for h(t) generation (integer
                        Hz). (default: None)
  --channel-name CHANNEL_NAME
                        The channel containing the gravitational strain data
                        (default: None)
  --frame-cache FRAME_CACHE [FRAME_CACHE ...]
                        Cache file containing the frame locations. (default:
                        None)
  --frame-files FRAME_FILES [FRAME_FILES ...]
                        list of frame files (default: None)
  --frame-type FRAME_TYPE
                        (optional), replaces frame-files. Use datafind to get
                        the needed frame file(s) of this type. (default: None)
  --frame-sieve FRAME_SIEVE
                        (optional), Only use frame files where the URL matches
                        the regular expression given. (default: None)
  --fake-strain {AdVBNSOptimizedSensitivityP1200087,AdVDesignSensitivityP1200087,AdVEarlyHighSensitivityP1200087,AdVEarlyLowSensitivityP1200087,AdVLateHighSensitivityP1200087,AdVLateLowSensitivityP1200087,AdVMidHighSensitivityP1200087,AdVMidLowSensitivityP1200087,AdvVirgo,CosmicExplorerP1600143,CosmicExplorerPessimisticP1600143,CosmicExplorerWidebandP1600143,EinsteinTelescopeP1600143,GEO,GEOHF,KAGRA,KAGRADesignSensitivityT1600593,KAGRAEarlySensitivityT1600593,KAGRALateSensitivityT1600593,KAGRAMidSensitivityT1600593,KAGRAOpeningSensitivityT1600593,TAMA,Virgo,aLIGOBHBH20Deg,aLIGOBHBH20DegGWINC,aLIGOBNSOptimizedSensitivityP1200087,aLIGODesignSensitivityP1200087,aLIGOEarlyHighSensitivityP1200087,aLIGOEarlyLowSensitivityP1200087,aLIGOHighFrequency,aLIGOHighFrequencyGWINC,aLIGOLateHighSensitivityP1200087,aLIGOLateLowSensitivityP1200087,aLIGOMidHighSensitivityP1200087,aLIGOMidLowSensitivityP1200087,aLIGONSNSOpt,aLIGONSNSOptGWINC,aLIGONoSRMHighPower,aLIGONoSRMLowPower,aLIGONoSRMLowPowerGWINC,aLIGOQuantumBHBH20Deg,aLIGOQuantumHighFrequency,aLIGOQuantumNSNSOpt,aLIGOQuantumNoSRMHighPower,aLIGOQuantumNoSRMLowPower,aLIGOQuantumZeroDetHighPower,aLIGOQuantumZeroDetLowPower,aLIGOThermal,aLIGOZeroDetHighPower,aLIGOZeroDetHighPowerGWINC,aLIGOZeroDetLowPower,aLIGOZeroDetLowPowerGWINC,eLIGOModel,eLIGOShot,iLIGOModel,iLIGOSRD,iLIGOSeismic,iLIGOShot,iLIGOThermal,zeroNoise}
                        Name of model PSD for generating fake gaussian noise.
                        (default: None)
  --fake-strain-seed FAKE_STRAIN_SEED
                        Seed value for the generation of fake colored gaussian
                        noise (default: 0)
  --fake-strain-from-file FAKE_STRAIN_FROM_FILE
                        File containing ASD for generating fake noise from it.
                        (default: None)
  --injection-file INJECTION_FILE
                        (optional) Injection file used to add waveforms into
                        the strain (default: None)
  --sgburst-injection-file SGBURST_INJECTION_FILE
                        (optional) Injection file used to add sine-Gaussian
                        burst waveforms into the strain (default: None)
  --ringdown-injection-file RINGDOWN_INJECTION_FILE
                        (optional) Injection file used to add ringdown-only
                        waveforms into the strain. (default: None)
  --injection-scale-factor INJECTION_SCALE_FACTOR
                        Divide injections by this factor before injecting into
                        the data. (default: 1)
  --gating-file GATING_FILE
                        (optional) Text file of gating segments to apply.
                        Format of each line is (all times in secs): gps_time
                        zeros_half_width pad_half_width (default: None)
  --autogating-threshold SIGMA
                        If given, find and gate glitches producing a deviation
                        larger than SIGMA in the whitened strain time series.
                        (default: None)
  --autogating-cluster SECONDS
                        Length of clustering window for detecting glitches for
                        autogating. (default: 5.0)
  --autogating-width SECONDS
                        Half-width of the gating window. (default: 0.25)
  --autogating-taper SECONDS
                        Taper the strain before and after each gating window
                        over a duration of SECONDS. (default: 0.25)
  --autogating-pad SECONDS
                        Ignore the given length of whitened strain at the ends
                        of a segment, to avoid filters ringing. (default: 16)
  --normalize-strain NORMALIZE_STRAIN
                        (optional) Divide frame data by constant. (default:
                        None)
  --zpk-z ZPK_Z [ZPK_Z ...]
                        (optional) Zero-pole-gain (zpk) filter strain. A list
                        of zeros for transfer function (default: None)
  --zpk-p ZPK_P [ZPK_P ...]
                        (optional) Zero-pole-gain (zpk) filter strain. A list
                        of poles for transfer function (default: None)
  --zpk-k ZPK_K         (optional) Zero-pole-gain (zpk) filter strain.
                        Transfer function gain (default: None)
  --witness-frame-type WITNESS_FRAME_TYPE
                        (optional), frame type which will be use to query
                        thewitness channel data. (default: None)
  --witness-tf-file WITNESS_TF_FILE
                        an hdf file containing the transfer functions and the
                        associated channel names (default: None)
  --witness-filter-length WITNESS_FILTER_LENGTH
                        filter length in seconds for the transfer function
                        (default: None)

Ethinca metric options:
  Options used in the calculation of Gamma metric components for the ethinca
  coincidence test and for assigning high-frequency cutoffs to templates.

  --calculate-time-metric-components
                        If given, the ethinca metric will be calculated for
                        only the time component, and stored in the Gamma0
                        entry of the sngl_inspiral table. OPTIONAL,
                        default=False (default: False)
  --calculate-ethinca-metric
                        If given, the ethinca metric will be calculated and
                        stored in the Gamma entries of the sngl_inspiral
                        table. OPTIONAL, default=False (default: False)
  --ethinca-pn-order {threePointFivePN,twoPN,twoPointFivePN,threePN,onePointFivePN,onePN,zeroPN}
                        Specify a PN order to be used in calculating the
                        ethinca metric. OPTIONAL: if not specified, the same
                        order will be used as for the bank metric. (default:
                        None)
  --filter-cutoff {HybridMECO,SEOBNRv1RD,LightRing,MECO,LRD,FRD,EOBNRv2RD,SEOBNRv2RD,BKLISCO,ERD,SEOBNRv4RD,EOBNRv2HMRD,SEOBNRv2Peak,IMRPhenomCFinal,IMRPhenomDPeak,SEOBNRv4Peak,SEOBNRv1Peak,IMRPhenomBFinal,SchwarzISCO}
                        Specify an upper frequency cutoff formula for the
                        ethinca metric calculation, and for the values of
                        f_final assigned to the templates. REQUIRED if the
                        calculate-ethinca-metric option is given. (default:
                        None)
  --ethinca-frequency-step ETHINCA_FREQUENCY_STEP
                        Control the precision of the upper frequency cutoff.
                        For speed, the metric is calculated only for discrete
                        f_max values with a spacing given by this option. Each
                        template is assigned the metric for the f_max closest
                        to its analytical cutoff formula. OPTIONAL,
                        default=10. UNITS=Hz (default: 10.0)

Some notes on these options:

  • The value of f0 generally doesn’t matter (so just use 70 if unsure). However if ethinca is being calculated f0 and f-low must be equal.
  • Choose f-upper wisely! If your signals coalesce at <1000Hz, you might want to use a lower value … although of course in this regime this inspiral-only metric will lose validity.
  • A delta-f value of 1/256 will certainly be accurate enough, a larger value will cause the code to run faster.
  • Using binary values for f-upper, delta-f and sample-rate is not needed for the metric calculation (which is a direct integral), but will provide a noticeable speed difference if reading data to compute a PSD.

Aligned-spin geometric placement: pycbc_geom_aligned_bank

Overview

pycbc_geom_aligned_bank is a code for placing of aligned-spin banks using the TaylorF2 metric.

This code will begin by generating a dax (a pegasus workflow, from which a DAG is created), which the user submits, that will generate the final template bank. This code will not calculate ethinca, as ethinca is not defined for spinning waveforms. However, if a new coincidence scheme is developed it could be used in that. This code forms part of the “uberbank”, described later, that is being used in Advanced LIGO searches.

Ian’s recommendation: This code will produce optimal template banks, if the metric can be trusted (ie. BNS). For NSBH and BBH the merger matters. Here the stochastic approaches described below could be more appropriate for your parameter space. It is recommended to try these, or a combination of the two as in the uberbank workflow. Note that the merger matters less in ZDHP than in O1, so this approach will work better for NSBH banks in 2018 than it does in 2015.

If any problems are encountered please email ian.harry@ligo.org.

Background

This code build upon the methods used to calculate the metric used in lalapps_tmpltbank. For details of how this code works see:

  • Brown et al., Phys.Rev. D86 (2012) 084017
  • Harry et al., Phys.Rev. D89 (2014) 024010

As with our non-spinning generator we place a lattice in the flat xi_i coordinate system and then map the points back to physical coordinates. In doing so we remove points that are too far away from the physical space, and push points that are outside the space, but overlap with it, back into the physical space.

This is all done with monte-carlo techniques, which is why this code requires a dag. If there were a more efficient way to map xi_i coordinates to physical values it will massively speed this code up. Please contact ian.harry@ligo.org if you want to play around with this.

Some examples

The command line arguments given to this code are very similar to those given to the non-spinning code (not surprising as they actually use the same modules).

Here is one example for making an aligned-spin template bank using a pre-generated ASD file.

pycbc_geom_aligned_bank --pn-order threePointFivePN --f0 70 --f-low 15 --f-upper 1000 --delta-f 0.01 --min-match 0.97 --min-mass1 2.5 --min-mass2 2.5 --max-mass1 3. --max-mass2 3. --verbose --max-ns-spin-mag 0.05 --max-bh-spin-mag 0.05 --output-file testAligned.xml --split-bank-num 5 --asd-file /home/spxiwh/aLIGO/BBH_template_banks/asd-T1200307v4.txt --intermediate-data-file intermediate.hdf --metadata-file metadata.xml

and then submitted with something like:

pycbc_submit_dax --dax bank_gen.dax --accounting-group ligo.dev.o2.cbc.bbh.pycbcoffline

run

pycbc_submit_dax --help

for more details on options for submitting an abstract workflow to condor.

Command line options

The command line options read as follows

$ pycbc_geom_aligned_bank --help
usage: pycbc_geom_aligned_bank [-h] [--version] [-V] [-s STACK_DISTANCE] [-3]
                               [-S SPLIT_BANK_NUM] [-F]
                               [--random-seed RANDOM_SEED]
                               [--print-chi-points FILENAME]
                               [--workflow-name WORKFLOW_NAME]
                               [--dax-filename DAX_FILENAME]
                               [--map-filename MAP_FILENAME]
                               --intermediate-data-file INTERMEDIATE_DATA_FILE
                               --metadata-file METADATA_FILE
                               [--is-sub-workflow]
                               [--storage-path-base STORAGE_PATH_BASE] -m
                               MIN_MATCH -O OUTPUT_FILE [--f-low-column NAME]
                               --pn-order PN_ORDER [--f0 F0] --f-low F_LOW
                               --f-upper F_UPPER --delta-f DELTA_F
                               [--write-metric] --min-mass1 MIN_MASS1
                               --max-mass1 MAX_MASS1 --min-mass2 MIN_MASS2
                               --max-mass2 MAX_MASS2
                               [--max-total-mass MAX_TOTAL_MASS]
                               [--min-total-mass MIN_TOTAL_MASS]
                               [--max-chirp-mass MAX_CHIRP_MASS]
                               [--min-chirp-mass MIN_CHIRP_MASS]
                               [--max-eta MAX_ETA] [--min-eta MIN_ETA]
                               [--ns-eos NS_EOS]
                               [--remnant-mass-threshold REMNANT_MASS_THRESHOLD]
                               [--use-eos-max-ns-mass]
                               [--delta-bh-spin DELTA_BH_SPIN]
                               [--delta-ns-mass DELTA_NS_MASS]
                               [--max-ns-spin-mag MAX_NS_SPIN_MAG]
                               [--max-bh-spin-mag MAX_BH_SPIN_MAG]
                               [--ns-bh-boundary-mass NS_BH_BOUNDARY_MASS | --nsbh-flag]
                               [--psd-model {AdVBNSOptimizedSensitivityP1200087,AdVDesignSensitivityP1200087,AdVEarlyHighSensitivityP1200087,AdVEarlyLowSensitivityP1200087,AdVLateHighSensitivityP1200087,AdVLateLowSensitivityP1200087,AdVMidHighSensitivityP1200087,AdVMidLowSensitivityP1200087,AdvVirgo,CosmicExplorerP1600143,CosmicExplorerPessimisticP1600143,CosmicExplorerWidebandP1600143,EinsteinTelescopeP1600143,GEO,GEOHF,KAGRA,KAGRADesignSensitivityT1600593,KAGRAEarlySensitivityT1600593,KAGRALateSensitivityT1600593,KAGRAMidSensitivityT1600593,KAGRAOpeningSensitivityT1600593,TAMA,Virgo,aLIGOBHBH20Deg,aLIGOBHBH20DegGWINC,aLIGOBNSOptimizedSensitivityP1200087,aLIGODesignSensitivityP1200087,aLIGOEarlyHighSensitivityP1200087,aLIGOEarlyLowSensitivityP1200087,aLIGOHighFrequency,aLIGOHighFrequencyGWINC,aLIGOLateHighSensitivityP1200087,aLIGOLateLowSensitivityP1200087,aLIGOMidHighSensitivityP1200087,aLIGOMidLowSensitivityP1200087,aLIGONSNSOpt,aLIGONSNSOptGWINC,aLIGONoSRMHighPower,aLIGONoSRMLowPower,aLIGONoSRMLowPowerGWINC,aLIGOQuantumBHBH20Deg,aLIGOQuantumHighFrequency,aLIGOQuantumNSNSOpt,aLIGOQuantumNoSRMHighPower,aLIGOQuantumNoSRMLowPower,aLIGOQuantumZeroDetHighPower,aLIGOQuantumZeroDetLowPower,aLIGOThermal,aLIGOZeroDetHighPower,aLIGOZeroDetHighPowerGWINC,aLIGOZeroDetLowPower,aLIGOZeroDetLowPowerGWINC,eLIGOModel,eLIGOShot,iLIGOModel,iLIGOSRD,iLIGOSeismic,iLIGOShot,iLIGOThermal,flat_unity}]
                               [--psd-file PSD_FILE] [--asd-file ASD_FILE]
                               [--psd-inverse-length PSD_INVERSE_LENGTH]
                               [--psdvar_short_segment SECONDS]
                               [--psdvar_long_segment SECONDS]
                               [--psdvar_overlap SECONDS]
                               [--psdvar_low_freq HERTZ]
                               [--psdvar_high_freq HERTZ]
                               [--psd-estimation {mean,median,median-mean}]
                               [--psd-segment-length PSD_SEGMENT_LENGTH]
                               [--psd-segment-stride PSD_SEGMENT_STRIDE]
                               [--psd-num-segments PSD_NUM_SEGMENTS]
                               [--psd-output PSD_OUTPUT]
                               [--gps-start-time GPS_START_TIME]
                               [--gps-end-time GPS_END_TIME]
                               [--strain-high-pass STRAIN_HIGH_PASS]
                               [--pad-data PAD_DATA] [--taper-data TAPER_DATA]
                               [--sample-rate SAMPLE_RATE]
                               [--channel-name CHANNEL_NAME]
                               [--frame-cache FRAME_CACHE [FRAME_CACHE ...]]
                               [--frame-files FRAME_FILES [FRAME_FILES ...]]
                               [--frame-type FRAME_TYPE]
                               [--frame-sieve FRAME_SIEVE]
                               [--fake-strain {AdVBNSOptimizedSensitivityP1200087,AdVDesignSensitivityP1200087,AdVEarlyHighSensitivityP1200087,AdVEarlyLowSensitivityP1200087,AdVLateHighSensitivityP1200087,AdVLateLowSensitivityP1200087,AdVMidHighSensitivityP1200087,AdVMidLowSensitivityP1200087,AdvVirgo,CosmicExplorerP1600143,CosmicExplorerPessimisticP1600143,CosmicExplorerWidebandP1600143,EinsteinTelescopeP1600143,GEO,GEOHF,KAGRA,KAGRADesignSensitivityT1600593,KAGRAEarlySensitivityT1600593,KAGRALateSensitivityT1600593,KAGRAMidSensitivityT1600593,KAGRAOpeningSensitivityT1600593,TAMA,Virgo,aLIGOBHBH20Deg,aLIGOBHBH20DegGWINC,aLIGOBNSOptimizedSensitivityP1200087,aLIGODesignSensitivityP1200087,aLIGOEarlyHighSensitivityP1200087,aLIGOEarlyLowSensitivityP1200087,aLIGOHighFrequency,aLIGOHighFrequencyGWINC,aLIGOLateHighSensitivityP1200087,aLIGOLateLowSensitivityP1200087,aLIGOMidHighSensitivityP1200087,aLIGOMidLowSensitivityP1200087,aLIGONSNSOpt,aLIGONSNSOptGWINC,aLIGONoSRMHighPower,aLIGONoSRMLowPower,aLIGONoSRMLowPowerGWINC,aLIGOQuantumBHBH20Deg,aLIGOQuantumHighFrequency,aLIGOQuantumNSNSOpt,aLIGOQuantumNoSRMHighPower,aLIGOQuantumNoSRMLowPower,aLIGOQuantumZeroDetHighPower,aLIGOQuantumZeroDetLowPower,aLIGOThermal,aLIGOZeroDetHighPower,aLIGOZeroDetHighPowerGWINC,aLIGOZeroDetLowPower,aLIGOZeroDetLowPowerGWINC,eLIGOModel,eLIGOShot,iLIGOModel,iLIGOSRD,iLIGOSeismic,iLIGOShot,iLIGOThermal,zeroNoise}]
                               [--fake-strain-seed FAKE_STRAIN_SEED]
                               [--fake-strain-from-file FAKE_STRAIN_FROM_FILE]
                               [--injection-file INJECTION_FILE]
                               [--sgburst-injection-file SGBURST_INJECTION_FILE]
                               [--ringdown-injection-file RINGDOWN_INJECTION_FILE]
                               [--injection-scale-factor INJECTION_SCALE_FACTOR]
                               [--gating-file GATING_FILE]
                               [--autogating-threshold SIGMA]
                               [--autogating-cluster SECONDS]
                               [--autogating-width SECONDS]
                               [--autogating-taper SECONDS]
                               [--autogating-pad SECONDS]
                               [--normalize-strain NORMALIZE_STRAIN]
                               [--zpk-z ZPK_Z [ZPK_Z ...]]
                               [--zpk-p ZPK_P [ZPK_P ...]] [--zpk-k ZPK_K]
                               [--witness-frame-type WITNESS_FRAME_TYPE]
                               [--witness-tf-file WITNESS_TF_FILE]
                               [--witness-filter-length WITNESS_FILTER_LENGTH]
                               [--calculate-time-metric-components | --calculate-ethinca-metric]
                               [--ethinca-pn-order {threePointFivePN,twoPN,twoPointFivePN,threePN,onePointFivePN,onePN,zeroPN}]
                               [--filter-cutoff {HybridMECO,SEOBNRv1RD,LightRing,MECO,LRD,FRD,EOBNRv2RD,SEOBNRv2RD,BKLISCO,ERD,SEOBNRv4RD,EOBNRv2HMRD,SEOBNRv2Peak,IMRPhenomCFinal,IMRPhenomDPeak,SEOBNRv4Peak,SEOBNRv1Peak,IMRPhenomBFinal,SchwarzISCO}]
                               [--ethinca-frequency-step ETHINCA_FREQUENCY_STEP]

Aligned spin bank generator. Initial placement of template points, and
rejection of "too far away" templates is done in the code, but the final
translation between points in the chirp parameters parameter space is done in
a workflow.

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  -V, --verbose         verbose output (default: False)
  -s STACK_DISTANCE, --stack-distance STACK_DISTANCE
                        Minimum metric spacing before we stack. (default: 0.2)
  -3, --threed-lattice  Set this to use a 3D lattice. OPTIONAL (default:
                        False)
  -S SPLIT_BANK_NUM, --split-bank-num SPLIT_BANK_NUM
                        Number of points per job in dag. OPTIONAL (default:
                        100)
  -F, --filter-points   Remove nearby points before generating the bank.
                        (default: False)
  --random-seed RANDOM_SEED
                        Random seed to use whenever the numpy random functions
                        are called when doing the monte-carlo for obtaining
                        the principal components and when translating all
                        points back to physical space. If this is used the
                        code should give the same output if run with the same
                        random seed. (default: None)
  --print-chi-points FILENAME
                        Add a node to print off an ASCII list of mass
                        parameters and corresponding location in the xi space
                        using pycbc_tmpltbank_to_chi_params. This will be
                        written to FILENAME. If this argument is not given, no
                        chi points file will be written. (default: None)
  --workflow-name WORKFLOW_NAME
                        Name to use for the produced .dax file. (default:
                        bank_gen)
  --dax-filename DAX_FILENAME
                        This can be used if running this job in a sub-workflow
                        to specify the dax filename. (default: None)
  --map-filename MAP_FILENAME
                        This can be used if running this job in a sub-workflow
                        to specify the output map filename. WARNING: Giving
                        this if not running as a sub-workflow will cause
                        pycbc_submit_dax to not work. (default: None)
  --intermediate-data-file INTERMEDIATE_DATA_FILE
                        The HDF file to be used to store data to pass down to
                        the various worker jobs. (default: None)
  --metadata-file METADATA_FILE
                        Location of the output file containing the metadata
                        that will be added to the final XML file. (default:
                        None)
  --is-sub-workflow     Only give this option if this code is being run as a
                        sub-workflow within pegasus. If this means nothing to
                        you, do not give this option. (default: False)
  --storage-path-base STORAGE_PATH_BASE
                        If running this code as a sub-workflow then this path
                        is pretended to all storage directories. (default:
                        None)
  -m MIN_MATCH, --min-match MIN_MATCH
                        Generate bank with specified minimum match. Required.
                        (default: None)
  -O OUTPUT_FILE, --output-file OUTPUT_FILE
                        Output file name. Required. (default: None)
  --f-low-column NAME   If given, store the lower frequency cutoff into column
                        NAME of the single-inspiral table. (default: None)

Options related to calculating the parameter space metric:
  --pn-order PN_ORDER   Determines the PN order to use. For a bank of non-
                        spinning templates, spin-related terms in the metric
                        will be zero. REQUIRED. Choices: * zeroPN: Will only
                        include the dominant term (proportional to chirp mass)
                        * onePN: Will only the leading orbit term and first
                        correction at 1PN * onePointFivePN: Will include orbit
                        and spin terms to 1.5PN. * twoPN: Will include orbit
                        and spin terms to 2PN. * twoPointFivePN: Will include
                        orbit and spin terms to 2.5PN. * threePN: Will include
                        orbit terms to 3PN and spin terms to 2.5PN. *
                        threePointFivePN: Include orbit terms to 3.5PN and
                        spin terms to 2.5PN (default: None)
  --f0 F0               f0 is used as a dynamic scaling factor when
                        calculating integrals used in metric construction.
                        I.e. instead of integrating F(f) we integrate F(f/f0)
                        then rescale by powers of f0. The default value 70Hz
                        should be fine for most applications. OPTIONAL.
                        UNITS=Hz. **WARNING: If the ethinca metric is to be
                        calculated, f0 must be set equal to f-low** (default:
                        70.0)
  --f-low F_LOW         Lower frequency cutoff used in computing the parameter
                        space metric. REQUIRED. UNITS=Hz (default: None)
  --f-upper F_UPPER     Upper frequency cutoff used in computing the parameter
                        space metric. REQUIRED. UNITS=Hz (default: None)
  --delta-f DELTA_F     Frequency spacing used in computing the parameter
                        space metric: integrals of the form \int F(f) df are
                        approximated as \sum F(f) delta_f. REQUIRED. UNITS=Hz
                        (default: None)
  --write-metric        If given write the metric components to disk as they
                        are calculated. (default: False)

Options related to mass and spin limits for bank generation:
  --min-mass1 MIN_MASS1
                        Minimum mass1: must be >= min-mass2. REQUIRED.
                        UNITS=Solar mass (default: None)
  --max-mass1 MAX_MASS1
                        Maximum mass1: must be >= max-mass2. REQUIRED.
                        UNITS=Solar mass (default: None)
  --min-mass2 MIN_MASS2
                        Minimum mass2. REQUIRED. UNITS=Solar mass (default:
                        None)
  --max-mass2 MAX_MASS2
                        Maximum mass2. REQUIRED. UNITS=Solar mass (default:
                        None)
  --max-total-mass MAX_TOTAL_MASS
                        Maximum total mass. OPTIONAL, if not provided the max
                        total mass is determined by the component masses.
                        UNITS=Solar mass (default: None)
  --min-total-mass MIN_TOTAL_MASS
                        Minimum total mass. OPTIONAL, if not provided the min
                        total mass is determined by the component masses.
                        UNITS=Solar mass (default: None)
  --max-chirp-mass MAX_CHIRP_MASS
                        Maximum chirp mass. OPTIONAL, if not provided the max
                        chirp mass is determined by the component masses.
                        UNITS=Solar mass (default: None)
  --min-chirp-mass MIN_CHIRP_MASS
                        Minimum total mass. OPTIONAL, if not provided the min
                        chirp mass is determined by the component masses.
                        UNITS=Solar mass (default: None)
  --max-eta MAX_ETA     Maximum symmetric mass ratio. OPTIONAL, no upper bound
                        on eta will be imposed if not provided. UNITS=Solar
                        mass. (default: 0.25)
  --min-eta MIN_ETA     Minimum symmetric mass ratio. OPTIONAL, no lower bound
                        on eta will be imposed if not provided. UNITS=Solar
                        mass. (default: 0.0)
  --ns-eos NS_EOS       Select the EOS to be used for the NS when calculating
                        the remnant disk mass. Only 2H is currently supported.
                        OPTIONAL (default: None)
  --remnant-mass-threshold REMNANT_MASS_THRESHOLD
                        Setting this filters EM dim NS-BH binaries: if the
                        remnant disk mass does not exceed this value, the NS-
                        BH binary is dropped from the target parameter space.
                        When it is set to None (default value) the EM dim
                        filter is not activated. OPTIONAL (default: None)
  --use-eos-max-ns-mass
                        Cut the mass range of the smaller object to the
                        maximum mass allowed by EOS. OPTIONAL (default: False)
  --delta-bh-spin DELTA_BH_SPIN
                        Grid spacing used for the BH spin z component when
                        generating the surface of the minumum minimum
                        symmetric mass ratio as a function of BH spin and NS
                        mass required to produce a remnant disk mass that
                        exceeds the threshold specificed in --remnant-mass-
                        threshold. OPTIONAL (0.1 by default) (default: None)
  --delta-ns-mass DELTA_NS_MASS
                        Grid spacing used for the NS mass when generating the
                        surface of the minumum minimum symmetric mass ratio as
                        a function of BH spin and NS mass required to produce
                        a remnant disk mass that exceeds the thrsehold
                        specified in --remnant-mass-threshold. OPTIONAL (0.1
                        by default) (default: None)
  --max-ns-spin-mag MAX_NS_SPIN_MAG
                        Maximum neutron star spin magnitude. Neutron stars are
                        defined as components lighter than the NS-BH boundary
                        (3 Msun by default). REQUIRED if min-mass2 < ns-bh-
                        boundary-mass (default: None)
  --max-bh-spin-mag MAX_BH_SPIN_MAG
                        Maximum black hole spin magnitude. Black holes are
                        defined as components at or above the NS-BH boundary
                        (3 Msun by default). REQUIRED if max-mass1 >= ns-bh-
                        boundary-mass (default: None)
  --ns-bh-boundary-mass NS_BH_BOUNDARY_MASS
                        Mass boundary between neutron stars and black holes.
                        Components below this mass are considered neutron
                        stars and are subject to the neutron star spin limits.
                        Components at/above are subject to the black hole spin
                        limits. OPTIONAL, default=3.000000. UNITS=Solar mass
                        (default: None)
  --nsbh-flag           Set this flag if generating a bank that contains only
                        systems with 1 black hole and 1 neutron star. With
                        this flag set the heavier body will always be subject
                        to the black hole spin restriction and the lighter to
                        the neutron star spin restriction, regardless of mass.
                        OPTIONAL. If set, the value of --ns-bh-boundary-mass
                        will be ignored. (default: False)

Options to select the method of PSD generation:
  The options --psd-model, --psd-file, --asd-file, and --psd-estimation are
  mutually exclusive.

  --psd-model {AdVBNSOptimizedSensitivityP1200087,AdVDesignSensitivityP1200087,AdVEarlyHighSensitivityP1200087,AdVEarlyLowSensitivityP1200087,AdVLateHighSensitivityP1200087,AdVLateLowSensitivityP1200087,AdVMidHighSensitivityP1200087,AdVMidLowSensitivityP1200087,AdvVirgo,CosmicExplorerP1600143,CosmicExplorerPessimisticP1600143,CosmicExplorerWidebandP1600143,EinsteinTelescopeP1600143,GEO,GEOHF,KAGRA,KAGRADesignSensitivityT1600593,KAGRAEarlySensitivityT1600593,KAGRALateSensitivityT1600593,KAGRAMidSensitivityT1600593,KAGRAOpeningSensitivityT1600593,TAMA,Virgo,aLIGOBHBH20Deg,aLIGOBHBH20DegGWINC,aLIGOBNSOptimizedSensitivityP1200087,aLIGODesignSensitivityP1200087,aLIGOEarlyHighSensitivityP1200087,aLIGOEarlyLowSensitivityP1200087,aLIGOHighFrequency,aLIGOHighFrequencyGWINC,aLIGOLateHighSensitivityP1200087,aLIGOLateLowSensitivityP1200087,aLIGOMidHighSensitivityP1200087,aLIGOMidLowSensitivityP1200087,aLIGONSNSOpt,aLIGONSNSOptGWINC,aLIGONoSRMHighPower,aLIGONoSRMLowPower,aLIGONoSRMLowPowerGWINC,aLIGOQuantumBHBH20Deg,aLIGOQuantumHighFrequency,aLIGOQuantumNSNSOpt,aLIGOQuantumNoSRMHighPower,aLIGOQuantumNoSRMLowPower,aLIGOQuantumZeroDetHighPower,aLIGOQuantumZeroDetLowPower,aLIGOThermal,aLIGOZeroDetHighPower,aLIGOZeroDetHighPowerGWINC,aLIGOZeroDetLowPower,aLIGOZeroDetLowPowerGWINC,eLIGOModel,eLIGOShot,iLIGOModel,iLIGOSRD,iLIGOSeismic,iLIGOShot,iLIGOThermal,flat_unity}
                        Get PSD from given analytical model. (default: None)
  --psd-file PSD_FILE   Get PSD using given PSD ASCII file (default: None)
  --asd-file ASD_FILE   Get PSD using given ASD ASCII file (default: None)
  --psd-inverse-length PSD_INVERSE_LENGTH
                        (Optional) The maximum length of the impulse response
                        of the overwhitening filter (s) (default: None)
  --psdvar_short_segment SECONDS
                        Length of short segment when calculating the PSD
                        variability. (default: None)
  --psdvar_long_segment SECONDS
                        Length of long segment when calculating the PSD
                        variability. (default: None)
  --psdvar_overlap SECONDS
                        Sample length of the PSD. (default: None)
  --psdvar_low_freq HERTZ
                        Minimum frequency to consider in PSD comparison.
                        (default: None)
  --psdvar_high_freq HERTZ
                        Maximum frequency to consider in PSD comparison.
                        (default: None)
  --psd-estimation {mean,median,median-mean}
                        Measure PSD from the data, using given average method.
                        (default: None)
  --psd-segment-length PSD_SEGMENT_LENGTH
                        (Required for --psd-estimation) The segment length for
                        PSD estimation (s) (default: None)
  --psd-segment-stride PSD_SEGMENT_STRIDE
                        (Required for --psd-estimation) The separation between
                        consecutive segments (s) (default: None)
  --psd-num-segments PSD_NUM_SEGMENTS
                        (Optional, used only with --psd-estimation). If given,
                        PSDs will be estimated using only this number of
                        segments. If more data is given than needed to make
                        this number of segments then excess data will not be
                        used in the PSD estimate. If not enough data is given,
                        the code will fail. (default: None)
  --psd-output PSD_OUTPUT
                        (Optional) Write PSD to specified file (default: None)

Options for obtaining h(t):
  These options are used for generating h(t) either by reading from a file
  or by generating it. This is only needed if the PSD is to be estimated
  from the data, ie. if the --psd-estimation option is given.

  --gps-start-time GPS_START_TIME
                        The gps start time of the data (integer seconds)
                        (default: None)
  --gps-end-time GPS_END_TIME
                        The gps end time of the data (integer seconds)
                        (default: None)
  --strain-high-pass STRAIN_HIGH_PASS
                        High pass frequency (default: None)
  --pad-data PAD_DATA   Extra padding to remove highpass corruption (integer
                        seconds) (default: None)
  --taper-data TAPER_DATA
                        Taper ends of data to zero using the supplied length
                        as a window (integer seconds) (default: 0)
  --sample-rate SAMPLE_RATE
                        The sample rate to use for h(t) generation (integer
                        Hz). (default: None)
  --channel-name CHANNEL_NAME
                        The channel containing the gravitational strain data
                        (default: None)
  --frame-cache FRAME_CACHE [FRAME_CACHE ...]
                        Cache file containing the frame locations. (default:
                        None)
  --frame-files FRAME_FILES [FRAME_FILES ...]
                        list of frame files (default: None)
  --frame-type FRAME_TYPE
                        (optional), replaces frame-files. Use datafind to get
                        the needed frame file(s) of this type. (default: None)
  --frame-sieve FRAME_SIEVE
                        (optional), Only use frame files where the URL matches
                        the regular expression given. (default: None)
  --fake-strain {AdVBNSOptimizedSensitivityP1200087,AdVDesignSensitivityP1200087,AdVEarlyHighSensitivityP1200087,AdVEarlyLowSensitivityP1200087,AdVLateHighSensitivityP1200087,AdVLateLowSensitivityP1200087,AdVMidHighSensitivityP1200087,AdVMidLowSensitivityP1200087,AdvVirgo,CosmicExplorerP1600143,CosmicExplorerPessimisticP1600143,CosmicExplorerWidebandP1600143,EinsteinTelescopeP1600143,GEO,GEOHF,KAGRA,KAGRADesignSensitivityT1600593,KAGRAEarlySensitivityT1600593,KAGRALateSensitivityT1600593,KAGRAMidSensitivityT1600593,KAGRAOpeningSensitivityT1600593,TAMA,Virgo,aLIGOBHBH20Deg,aLIGOBHBH20DegGWINC,aLIGOBNSOptimizedSensitivityP1200087,aLIGODesignSensitivityP1200087,aLIGOEarlyHighSensitivityP1200087,aLIGOEarlyLowSensitivityP1200087,aLIGOHighFrequency,aLIGOHighFrequencyGWINC,aLIGOLateHighSensitivityP1200087,aLIGOLateLowSensitivityP1200087,aLIGOMidHighSensitivityP1200087,aLIGOMidLowSensitivityP1200087,aLIGONSNSOpt,aLIGONSNSOptGWINC,aLIGONoSRMHighPower,aLIGONoSRMLowPower,aLIGONoSRMLowPowerGWINC,aLIGOQuantumBHBH20Deg,aLIGOQuantumHighFrequency,aLIGOQuantumNSNSOpt,aLIGOQuantumNoSRMHighPower,aLIGOQuantumNoSRMLowPower,aLIGOQuantumZeroDetHighPower,aLIGOQuantumZeroDetLowPower,aLIGOThermal,aLIGOZeroDetHighPower,aLIGOZeroDetHighPowerGWINC,aLIGOZeroDetLowPower,aLIGOZeroDetLowPowerGWINC,eLIGOModel,eLIGOShot,iLIGOModel,iLIGOSRD,iLIGOSeismic,iLIGOShot,iLIGOThermal,zeroNoise}
                        Name of model PSD for generating fake gaussian noise.
                        (default: None)
  --fake-strain-seed FAKE_STRAIN_SEED
                        Seed value for the generation of fake colored gaussian
                        noise (default: 0)
  --fake-strain-from-file FAKE_STRAIN_FROM_FILE
                        File containing ASD for generating fake noise from it.
                        (default: None)
  --injection-file INJECTION_FILE
                        (optional) Injection file used to add waveforms into
                        the strain (default: None)
  --sgburst-injection-file SGBURST_INJECTION_FILE
                        (optional) Injection file used to add sine-Gaussian
                        burst waveforms into the strain (default: None)
  --ringdown-injection-file RINGDOWN_INJECTION_FILE
                        (optional) Injection file used to add ringdown-only
                        waveforms into the strain. (default: None)
  --injection-scale-factor INJECTION_SCALE_FACTOR
                        Divide injections by this factor before injecting into
                        the data. (default: 1)
  --gating-file GATING_FILE
                        (optional) Text file of gating segments to apply.
                        Format of each line is (all times in secs): gps_time
                        zeros_half_width pad_half_width (default: None)
  --autogating-threshold SIGMA
                        If given, find and gate glitches producing a deviation
                        larger than SIGMA in the whitened strain time series.
                        (default: None)
  --autogating-cluster SECONDS
                        Length of clustering window for detecting glitches for
                        autogating. (default: 5.0)
  --autogating-width SECONDS
                        Half-width of the gating window. (default: 0.25)
  --autogating-taper SECONDS
                        Taper the strain before and after each gating window
                        over a duration of SECONDS. (default: 0.25)
  --autogating-pad SECONDS
                        Ignore the given length of whitened strain at the ends
                        of a segment, to avoid filters ringing. (default: 16)
  --normalize-strain NORMALIZE_STRAIN
                        (optional) Divide frame data by constant. (default:
                        None)
  --zpk-z ZPK_Z [ZPK_Z ...]
                        (optional) Zero-pole-gain (zpk) filter strain. A list
                        of zeros for transfer function (default: None)
  --zpk-p ZPK_P [ZPK_P ...]
                        (optional) Zero-pole-gain (zpk) filter strain. A list
                        of poles for transfer function (default: None)
  --zpk-k ZPK_K         (optional) Zero-pole-gain (zpk) filter strain.
                        Transfer function gain (default: None)
  --witness-frame-type WITNESS_FRAME_TYPE
                        (optional), frame type which will be use to query
                        thewitness channel data. (default: None)
  --witness-tf-file WITNESS_TF_FILE
                        an hdf file containing the transfer functions and the
                        associated channel names (default: None)
  --witness-filter-length WITNESS_FILTER_LENGTH
                        filter length in seconds for the transfer function
                        (default: None)

Ethinca metric options:
  Options used in the calculation of Gamma metric components for the ethinca
  coincidence test and for assigning high-frequency cutoffs to templates.

  --calculate-time-metric-components
                        If given, the ethinca metric will be calculated for
                        only the time component, and stored in the Gamma0
                        entry of the sngl_inspiral table. OPTIONAL,
                        default=False (default: False)
  --calculate-ethinca-metric
                        If given, the ethinca metric will be calculated and
                        stored in the Gamma entries of the sngl_inspiral
                        table. OPTIONAL, default=False (default: False)
  --ethinca-pn-order {threePointFivePN,twoPN,twoPointFivePN,threePN,onePointFivePN,onePN,zeroPN}
                        Specify a PN order to be used in calculating the
                        ethinca metric. OPTIONAL: if not specified, the same
                        order will be used as for the bank metric. (default:
                        None)
  --filter-cutoff {HybridMECO,SEOBNRv1RD,LightRing,MECO,LRD,FRD,EOBNRv2RD,SEOBNRv2RD,BKLISCO,ERD,SEOBNRv4RD,EOBNRv2HMRD,SEOBNRv2Peak,IMRPhenomCFinal,IMRPhenomDPeak,SEOBNRv4Peak,SEOBNRv1Peak,IMRPhenomBFinal,SchwarzISCO}
                        Specify an upper frequency cutoff formula for the
                        ethinca metric calculation, and for the values of
                        f_final assigned to the templates. REQUIRED if the
                        calculate-ethinca-metric option is given. (default:
                        None)
  --ethinca-frequency-step ETHINCA_FREQUENCY_STEP
                        Control the precision of the upper frequency cutoff.
                        For speed, the metric is calculated only for discrete
                        f_max values with a spacing given by this option. Each
                        template is assigned the metric for the f_max closest
                        to its analytical cutoff formula. OPTIONAL,
                        default=10. UNITS=Hz (default: 10.0)

As before some notes on these options:

Some notes on these options:

  • The value of f0 generally doesn’t matter (so just use 70 if unsure). However if ethinca is being calculated f0 and f-low must be equal.
  • Choose f-upper wisely! If your signals coalesce at <1000Hz, you might want to use a lower value … although of course in this regime this inspiral-only metric will lose validity.
  • A delta-f value of 1/256 will certainly be accurate enough, a larger value will cause the code to run faster.
  • Using binary values for f-upper, delta-f and sample-rate is not needed for the metric calculation (which is a direct integral), but will provide a noticeable speed difference if reading data to compute a PSD.
  • For the purposes of spin calculations a NS is considered to be anything with mass < 3 solar masses and a BH is considered to be anything with mass > 3 solar masses. But this can be overridden with the –ns-bh-boundary-mass option.
  • To avoid generating a NSBH bank where you have a wall of triggers with NS mass = 3 and spins up to the black hole maximum use the nsbh-flag. This will ensure that only neutron-star–black-hole systems are generated.
  • If a remnant-mass-threshold is specified the code sets up the bank so that it does not target NS-BH systems that cannot produce a remnant disk mass that exceeds the threshold: this is used to remove EM dim NS-BH binaries from the target parameter space, as discussed in Pannarale and Ohme, ApJL 7, 5 (2014). Please contact francesco.pannarale@ligo.org if you want to know more about this.

Aligned-spin stochastic placement

lalapps_cbc_sbank and pycbc_aligned_stoch_bank

Introduction

pycbc_aligned_stoch_bank is an aligned-spin bank generator that uses a stochastic algorithm and the TaylorF2 (or TaylorR2F4) metric to create a bank of templates.

lalapps_cbc_sbank is an aligned-spin bank generator that uses a stochastic algorithm to create a bank of templates. It can use a metric to approximate distances (currently available metrics: TaylorF2 single spin approximation). It can also compute banks using direct matches between waveforms instead of a metric. It can also be used to generate precessing banks (and of course non-spin banks), although computational cost of precessing banks makes this difficult; here the workflow code is necessary and one must spend some time constructing a good configuration file.

Comparisons, advantages and disadvantages of the two codes are discussed below.

When using a metric these codes do not require the processing power of the geometric lattice algorithm and do not produce a dag. Run the command, wait, get bank. When using the direct match method in sbank computational cost is much higher. For this purpose a workflow generator is also supplied to parallelize generation.

NOTE: The question “Do I need to use the sbank workflow or just call sbank directly?” is an important one. As a rough rule of thumb if your template bank will result in less than 20000 templates (assuming quick-to-generate waveforms) and you use the optimization options, then a single sbank job should be sufficient. If expecting more than this then expect to need the workflow generator. Many of the optimizations used to speed up sbank do not work with time-domain waveforms, which are often much slower to generate than frequency-domain ones. sbank can run with time-domain waveforms, but it will generally be too slow to generate anything but the smallest template banks (approximately 1000 templates). We strongly recommend not using time-domain waveforms for bank generation!

Background

As opposed to geometric algorithms where the metric is used to determine a lattice of equally placed points, a stochastic algorithm works by creating a large set of randomly placed points and then using the metric or actually computing overlaps to remove points that are too close to each other.

This algorithm has the benefit that it can work in any parameter space, you do not require a flat metric. However, it does require more templates to cover a space than a geometric approach. Additionally the computational cost will increase as a factor of the number of points in the bank to a power between 2 and 3 - the exact number depends on how well you are able to optimize the parameter space and not match every point in the bank with every seed point. Nevertheless it has been found that the computational cost of generating aligned-spin banks for Advanced LIGO, using direct-match algorithms is not too large, and this approach forms a large part of the “uberbank” construction described below.

The stochastic bank code can calculate the ethinca metric, but only if both component maximum spins are set to 0.0, i.e. a stochastic non-spinning bank. One can also generate only the time component of the metric if doing exact-match coincidence.

Stochastic placement was first proposed in terms of LISA searches in

  • Harry et al. Class.Quant.Grav. 25 (2008) 184027
  • Babak Class.Quant.Grav. 25 (2008) 195011

(the former using a metric, and the latter using direct match). Then described in more detail in

  • Harry et al. Phys.Rev. D80 (2009) 104014
  • Manca and Vallisneri Phys.Rev. D81 (2010) 024004

Recently stochastic placement has been explored for LIGO searches in

  • Ajith et al., Phys.Rev. D89 (2014) 084041
  • Privitera et al., Phys.Rev. D89 (2014) 024003
  • Harry et al., Phys.Rev. D89 (2014) 024010
  • Capano et al., Phys.Rev. D93 (2016) 124007

pycbc_aligned_stoch_bank follows the method described in Harry et al. (2009) and calculates matches using a metric (in this case the F2 metric). lalapps_cbc_sbank can do stochastic template bank generation with or without a metric. In the absence of a metric it uses the method introduced in Babak (2008) and used in Privitera (2013) to compute distances between points by generating both waveforms and calculating an explicit overlap.

Ian’s recommendation: Which stochastic code should I use?

Okay so there are two stochastic codes, and a lot of overlap between the two codes. We are aware that this is not optimal and hope to combine the features of these two codes into a single front-end to get the best of both worlds.

In the mean-time here is how I see the breakdown of the two codes:

I want to use the F2 metric

If you want to use the F2 metric used in the geometric code then I recommend to use pycbc_aligned_stoch_bank. Here I have found the code to be faster than lalapps_cbc_sbank using the F2 reduced spin metric because the pycbc code is using a Cartesian parameter space and is therefore able to greatly reduce the number of matches that are calculated. (Effectively lalapps_cbc_sbank only limits the number of matches calculated by chirp mass differences, pycbc_aligned_stoch_bank also uses the second direction (some combination of mass ratio and the spins). The pycbc metric also incorporates the effect of both spins.

I want to use another metric, ie. an IMR metric

If you have and want to use a different metric, such as the IMRPhenomX metric, where the approach used in the geometric bank cannot be used to create a Cartesian coordinate system, then use lalapps_cbc_sbank.

This code is more flexible, and is not dependent on the assumptions that are used in the geometric code. If your metric is not already added then please contact a developer for help in integrating this.

I want to use direct match

Use lalapps_cbc_sbank. Be aware though that this is often difficult to run in a single process and may require the dag generator described below.

Some examples

The command line arguments given to this code are very similar to those given to the non-spinning code and the aligned-spin geometric code (they use the same modules).

Here is one example reading data from a frame cache, as in the non-spinning example

pycbc_aligned_stoch_bank --pn-order threePointFivePN --f0 60 --f-low 30 -V --delta-f 0.01 --min-match 0.97 --min-mass1 2.5 --max-mass1 3 --min-mass2 2.5 --max-mass2 3 --max-ns-spin-mag 0.05 --max-bh-spin-mag 0.05 --nsbh-flag --psd-estimation median --psd-segment-length 256 --psd-segment-stride 128 --psd-inverse-length 8 --gps-start-time 900000033 --gps-end-time 900002081 --strain-high-pass 30 --pad-data 8 --sample-rate 4096 --frame-cache cache/H-H1_NINJA2_G1000176_EARLY_RECOLORED_CACHE-900000024-10653.lcf --channel-name H1:LDAS-STRAIN --verbose --output-file testStoch.xml --num-seeds 2000000 --f-upper 2000

Another example where we read the PSD from a supplied ASD file:

pycbc_aligned_stoch_bank --pn-order threePointFivePN --f0 60 --f-low 30 --delta-f 0.1 --min-match 0.97 --min-mass1 2.5 --max-mass1 3 --min-mass2 2.5 --max-mass2 3 --max-ns-spin-mag 0.05 --max-bh-spin-mag 0.05 --nsbh-flag --verbose --asd-file ZERO_DET_high_P.txt --num-seeds 10000 --output-file "testStoch.xml" --f-upper 2000

And a third example where we use a batshit PN order.

pycbc_aligned_stoch_bank --pn-order onePN --f0 60 --f-low 30 --delta-f 0.1 --min-match 0.97 --min-mass1 2.5 --max-mass1 3 --min-mass2 2.5 --max-mass2 3 --max-ns-spin-mag 0.05 --max-bh-spin-mag 0.05 --nsbh-flag --verbose --asd-file ZERO_DET_high_P.txt --num-seeds 10000 --output-file "testStoch.xml" --f-upper 2000

lalapps_cbc_sbank provides example in the help text, see below.

Command line options: pycbc_aligned_stoch_bank

The command line options read as follows

$ pycbc_aligned_stoch_bank --help
usage: pycbc_aligned_stoch_bank [-h] [--version] [--verbose] [-V]
                                [--bank-fupper-step BANK_FUPPER_STEP]
                                [--bank-fupper-formula {HybridMECO,SEOBNRv1RD,LightRing,MECO,LRD,FRD,EOBNRv2RD,SEOBNRv2RD,BKLISCO,ERD,SEOBNRv4RD,EOBNRv2HMRD,SEOBNRv2Peak,IMRPhenomCFinal,IMRPhenomDPeak,SEOBNRv4Peak,SEOBNRv1Peak,IMRPhenomBFinal,SchwarzISCO}]
                                [-N NUM_SEEDS] [-n NUM_FAILED_CUTOFF]
                                [--random-seed RANDOM_SEED] -m MIN_MATCH -O
                                OUTPUT_FILE [--f-low-column NAME] --pn-order
                                PN_ORDER [--f0 F0] --f-low F_LOW --f-upper
                                F_UPPER --delta-f DELTA_F [--write-metric]
                                --min-mass1 MIN_MASS1 --max-mass1 MAX_MASS1
                                --min-mass2 MIN_MASS2 --max-mass2 MAX_MASS2
                                [--max-total-mass MAX_TOTAL_MASS]
                                [--min-total-mass MIN_TOTAL_MASS]
                                [--max-chirp-mass MAX_CHIRP_MASS]
                                [--min-chirp-mass MIN_CHIRP_MASS]
                                [--max-eta MAX_ETA] [--min-eta MIN_ETA]
                                [--ns-eos NS_EOS]
                                [--remnant-mass-threshold REMNANT_MASS_THRESHOLD]
                                [--use-eos-max-ns-mass]
                                [--delta-bh-spin DELTA_BH_SPIN]
                                [--delta-ns-mass DELTA_NS_MASS]
                                [--max-ns-spin-mag MAX_NS_SPIN_MAG]
                                [--max-bh-spin-mag MAX_BH_SPIN_MAG]
                                [--ns-bh-boundary-mass NS_BH_BOUNDARY_MASS | --nsbh-flag]
                                [--psd-model {AdVBNSOptimizedSensitivityP1200087,AdVDesignSensitivityP1200087,AdVEarlyHighSensitivityP1200087,AdVEarlyLowSensitivityP1200087,AdVLateHighSensitivityP1200087,AdVLateLowSensitivityP1200087,AdVMidHighSensitivityP1200087,AdVMidLowSensitivityP1200087,AdvVirgo,CosmicExplorerP1600143,CosmicExplorerPessimisticP1600143,CosmicExplorerWidebandP1600143,EinsteinTelescopeP1600143,GEO,GEOHF,KAGRA,KAGRADesignSensitivityT1600593,KAGRAEarlySensitivityT1600593,KAGRALateSensitivityT1600593,KAGRAMidSensitivityT1600593,KAGRAOpeningSensitivityT1600593,TAMA,Virgo,aLIGOBHBH20Deg,aLIGOBHBH20DegGWINC,aLIGOBNSOptimizedSensitivityP1200087,aLIGODesignSensitivityP1200087,aLIGOEarlyHighSensitivityP1200087,aLIGOEarlyLowSensitivityP1200087,aLIGOHighFrequency,aLIGOHighFrequencyGWINC,aLIGOLateHighSensitivityP1200087,aLIGOLateLowSensitivityP1200087,aLIGOMidHighSensitivityP1200087,aLIGOMidLowSensitivityP1200087,aLIGONSNSOpt,aLIGONSNSOptGWINC,aLIGONoSRMHighPower,aLIGONoSRMLowPower,aLIGONoSRMLowPowerGWINC,aLIGOQuantumBHBH20Deg,aLIGOQuantumHighFrequency,aLIGOQuantumNSNSOpt,aLIGOQuantumNoSRMHighPower,aLIGOQuantumNoSRMLowPower,aLIGOQuantumZeroDetHighPower,aLIGOQuantumZeroDetLowPower,aLIGOThermal,aLIGOZeroDetHighPower,aLIGOZeroDetHighPowerGWINC,aLIGOZeroDetLowPower,aLIGOZeroDetLowPowerGWINC,eLIGOModel,eLIGOShot,iLIGOModel,iLIGOSRD,iLIGOSeismic,iLIGOShot,iLIGOThermal,flat_unity}]
                                [--psd-file PSD_FILE] [--asd-file ASD_FILE]
                                [--psd-inverse-length PSD_INVERSE_LENGTH]
                                [--psdvar_short_segment SECONDS]
                                [--psdvar_long_segment SECONDS]
                                [--psdvar_overlap SECONDS]
                                [--psdvar_low_freq HERTZ]
                                [--psdvar_high_freq HERTZ]
                                [--psd-estimation {mean,median,median-mean}]
                                [--psd-segment-length PSD_SEGMENT_LENGTH]
                                [--psd-segment-stride PSD_SEGMENT_STRIDE]
                                [--psd-num-segments PSD_NUM_SEGMENTS]
                                [--psd-output PSD_OUTPUT]
                                [--gps-start-time GPS_START_TIME]
                                [--gps-end-time GPS_END_TIME]
                                [--strain-high-pass STRAIN_HIGH_PASS]
                                [--pad-data PAD_DATA]
                                [--taper-data TAPER_DATA]
                                [--sample-rate SAMPLE_RATE]
                                [--channel-name CHANNEL_NAME]
                                [--frame-cache FRAME_CACHE [FRAME_CACHE ...]]
                                [--frame-files FRAME_FILES [FRAME_FILES ...]]
                                [--frame-type FRAME_TYPE]
                                [--frame-sieve FRAME_SIEVE]
                                [--fake-strain {AdVBNSOptimizedSensitivityP1200087,AdVDesignSensitivityP1200087,AdVEarlyHighSensitivityP1200087,AdVEarlyLowSensitivityP1200087,AdVLateHighSensitivityP1200087,AdVLateLowSensitivityP1200087,AdVMidHighSensitivityP1200087,AdVMidLowSensitivityP1200087,AdvVirgo,CosmicExplorerP1600143,CosmicExplorerPessimisticP1600143,CosmicExplorerWidebandP1600143,EinsteinTelescopeP1600143,GEO,GEOHF,KAGRA,KAGRADesignSensitivityT1600593,KAGRAEarlySensitivityT1600593,KAGRALateSensitivityT1600593,KAGRAMidSensitivityT1600593,KAGRAOpeningSensitivityT1600593,TAMA,Virgo,aLIGOBHBH20Deg,aLIGOBHBH20DegGWINC,aLIGOBNSOptimizedSensitivityP1200087,aLIGODesignSensitivityP1200087,aLIGOEarlyHighSensitivityP1200087,aLIGOEarlyLowSensitivityP1200087,aLIGOHighFrequency,aLIGOHighFrequencyGWINC,aLIGOLateHighSensitivityP1200087,aLIGOLateLowSensitivityP1200087,aLIGOMidHighSensitivityP1200087,aLIGOMidLowSensitivityP1200087,aLIGONSNSOpt,aLIGONSNSOptGWINC,aLIGONoSRMHighPower,aLIGONoSRMLowPower,aLIGONoSRMLowPowerGWINC,aLIGOQuantumBHBH20Deg,aLIGOQuantumHighFrequency,aLIGOQuantumNSNSOpt,aLIGOQuantumNoSRMHighPower,aLIGOQuantumNoSRMLowPower,aLIGOQuantumZeroDetHighPower,aLIGOQuantumZeroDetLowPower,aLIGOThermal,aLIGOZeroDetHighPower,aLIGOZeroDetHighPowerGWINC,aLIGOZeroDetLowPower,aLIGOZeroDetLowPowerGWINC,eLIGOModel,eLIGOShot,iLIGOModel,iLIGOSRD,iLIGOSeismic,iLIGOShot,iLIGOThermal,zeroNoise}]
                                [--fake-strain-seed FAKE_STRAIN_SEED]
                                [--fake-strain-from-file FAKE_STRAIN_FROM_FILE]
                                [--injection-file INJECTION_FILE]
                                [--sgburst-injection-file SGBURST_INJECTION_FILE]
                                [--ringdown-injection-file RINGDOWN_INJECTION_FILE]
                                [--injection-scale-factor INJECTION_SCALE_FACTOR]
                                [--gating-file GATING_FILE]
                                [--autogating-threshold SIGMA]
                                [--autogating-cluster SECONDS]
                                [--autogating-width SECONDS]
                                [--autogating-taper SECONDS]
                                [--autogating-pad SECONDS]
                                [--normalize-strain NORMALIZE_STRAIN]
                                [--zpk-z ZPK_Z [ZPK_Z ...]]
                                [--zpk-p ZPK_P [ZPK_P ...]] [--zpk-k ZPK_K]
                                [--witness-frame-type WITNESS_FRAME_TYPE]
                                [--witness-tf-file WITNESS_TF_FILE]
                                [--witness-filter-length WITNESS_FILTER_LENGTH]
                                [--calculate-time-metric-components | --calculate-ethinca-metric]
                                [--ethinca-pn-order {threePointFivePN,twoPN,twoPointFivePN,threePN,onePointFivePN,onePN,zeroPN}]
                                [--filter-cutoff {HybridMECO,SEOBNRv1RD,LightRing,MECO,LRD,FRD,EOBNRv2RD,SEOBNRv2RD,BKLISCO,ERD,SEOBNRv4RD,EOBNRv2HMRD,SEOBNRv2Peak,IMRPhenomCFinal,IMRPhenomDPeak,SEOBNRv4Peak,SEOBNRv1Peak,IMRPhenomBFinal,SchwarzISCO}]
                                [--ethinca-frequency-step ETHINCA_FREQUENCY_STEP]

Stochastic aligned spin bank generator.

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --verbose             verbose output (default: False)
  -V, --vary-fupper     Use a variable upper frequency cutoff in laying out
                        the bank. OPTIONAL. (default: False)
  --bank-fupper-step BANK_FUPPER_STEP
                        Size of discrete frequency steps used when varying the
                        fupper. If --calculate-ethinca-metric and --ethinca-
                        freq-step are also given, the code will use the
                        smaller of the two step values. OPTIONAL. Units=Hz
                        (default: 10.0)
  --bank-fupper-formula {HybridMECO,SEOBNRv1RD,LightRing,MECO,LRD,FRD,EOBNRv2RD,SEOBNRv2RD,BKLISCO,ERD,SEOBNRv4RD,EOBNRv2HMRD,SEOBNRv2Peak,IMRPhenomCFinal,IMRPhenomDPeak,SEOBNRv4Peak,SEOBNRv1Peak,IMRPhenomBFinal,SchwarzISCO}
                        Frequency cutoff formula for varying fupper.
                        Frequencies will be rounded to the nearest discrete
                        step. OPTIONAL. (default: SchwarzISCO)
  -N NUM_SEEDS, --num-seeds NUM_SEEDS
                        Number of seed points used in bank construction.
                        OPTIONAL. (default: 5000000)
  -n NUM_FAILED_CUTOFF, --num-failed-cutoff NUM_FAILED_CUTOFF
                        Maximum number of consecutive, not-accepted test
                        points after which bank generation will be stopped.
                        OPTIONAL. Default value is really large as --num-seeds
                        is intended to provide the termination condition.
                        (default: 1000000000)
  --random-seed RANDOM_SEED
                        Random seed to use when calling numpy.random functions
                        used in obtaining the principal components in
                        parameter space and when translating points back to
                        physical space. If given, the code should give the
                        same output when run with the same random seed.
                        (default: None)
  -m MIN_MATCH, --min-match MIN_MATCH
                        Generate bank with specified minimum match. Required.
                        (default: None)
  -O OUTPUT_FILE, --output-file OUTPUT_FILE
                        Output file name. Required. (default: None)
  --f-low-column NAME   If given, store the lower frequency cutoff into column
                        NAME of the single-inspiral table. (default: None)

Options related to calculating the parameter space metric:
  --pn-order PN_ORDER   Determines the PN order to use. For a bank of non-
                        spinning templates, spin-related terms in the metric
                        will be zero. REQUIRED. Choices: * zeroPN: Will only
                        include the dominant term (proportional to chirp mass)
                        * onePN: Will only the leading orbit term and first
                        correction at 1PN * onePointFivePN: Will include orbit
                        and spin terms to 1.5PN. * twoPN: Will include orbit
                        and spin terms to 2PN. * twoPointFivePN: Will include
                        orbit and spin terms to 2.5PN. * threePN: Will include
                        orbit terms to 3PN and spin terms to 2.5PN. *
                        threePointFivePN: Include orbit terms to 3.5PN and
                        spin terms to 2.5PN (default: None)
  --f0 F0               f0 is used as a dynamic scaling factor when
                        calculating integrals used in metric construction.
                        I.e. instead of integrating F(f) we integrate F(f/f0)
                        then rescale by powers of f0. The default value 70Hz
                        should be fine for most applications. OPTIONAL.
                        UNITS=Hz. **WARNING: If the ethinca metric is to be
                        calculated, f0 must be set equal to f-low** (default:
                        70.0)
  --f-low F_LOW         Lower frequency cutoff used in computing the parameter
                        space metric. REQUIRED. UNITS=Hz (default: None)
  --f-upper F_UPPER     Upper frequency cutoff used in computing the parameter
                        space metric. REQUIRED. UNITS=Hz (default: None)
  --delta-f DELTA_F     Frequency spacing used in computing the parameter
                        space metric: integrals of the form \int F(f) df are
                        approximated as \sum F(f) delta_f. REQUIRED. UNITS=Hz
                        (default: None)
  --write-metric        If given write the metric components to disk as they
                        are calculated. (default: False)

Options related to mass and spin limits for bank generation:
  --min-mass1 MIN_MASS1
                        Minimum mass1: must be >= min-mass2. REQUIRED.
                        UNITS=Solar mass (default: None)
  --max-mass1 MAX_MASS1
                        Maximum mass1: must be >= max-mass2. REQUIRED.
                        UNITS=Solar mass (default: None)
  --min-mass2 MIN_MASS2
                        Minimum mass2. REQUIRED. UNITS=Solar mass (default:
                        None)
  --max-mass2 MAX_MASS2
                        Maximum mass2. REQUIRED. UNITS=Solar mass (default:
                        None)
  --max-total-mass MAX_TOTAL_MASS
                        Maximum total mass. OPTIONAL, if not provided the max
                        total mass is determined by the component masses.
                        UNITS=Solar mass (default: None)
  --min-total-mass MIN_TOTAL_MASS
                        Minimum total mass. OPTIONAL, if not provided the min
                        total mass is determined by the component masses.
                        UNITS=Solar mass (default: None)
  --max-chirp-mass MAX_CHIRP_MASS
                        Maximum chirp mass. OPTIONAL, if not provided the max
                        chirp mass is determined by the component masses.
                        UNITS=Solar mass (default: None)
  --min-chirp-mass MIN_CHIRP_MASS
                        Minimum total mass. OPTIONAL, if not provided the min
                        chirp mass is determined by the component masses.
                        UNITS=Solar mass (default: None)
  --max-eta MAX_ETA     Maximum symmetric mass ratio. OPTIONAL, no upper bound
                        on eta will be imposed if not provided. UNITS=Solar
                        mass. (default: 0.25)
  --min-eta MIN_ETA     Minimum symmetric mass ratio. OPTIONAL, no lower bound
                        on eta will be imposed if not provided. UNITS=Solar
                        mass. (default: 0.0)
  --ns-eos NS_EOS       Select the EOS to be used for the NS when calculating
                        the remnant disk mass. Only 2H is currently supported.
                        OPTIONAL (default: None)
  --remnant-mass-threshold REMNANT_MASS_THRESHOLD
                        Setting this filters EM dim NS-BH binaries: if the
                        remnant disk mass does not exceed this value, the NS-
                        BH binary is dropped from the target parameter space.
                        When it is set to None (default value) the EM dim
                        filter is not activated. OPTIONAL (default: None)
  --use-eos-max-ns-mass
                        Cut the mass range of the smaller object to the
                        maximum mass allowed by EOS. OPTIONAL (default: False)
  --delta-bh-spin DELTA_BH_SPIN
                        Grid spacing used for the BH spin z component when
                        generating the surface of the minumum minimum
                        symmetric mass ratio as a function of BH spin and NS
                        mass required to produce a remnant disk mass that
                        exceeds the threshold specificed in --remnant-mass-
                        threshold. OPTIONAL (0.1 by default) (default: None)
  --delta-ns-mass DELTA_NS_MASS
                        Grid spacing used for the NS mass when generating the
                        surface of the minumum minimum symmetric mass ratio as
                        a function of BH spin and NS mass required to produce
                        a remnant disk mass that exceeds the thrsehold
                        specified in --remnant-mass-threshold. OPTIONAL (0.1
                        by default) (default: None)
  --max-ns-spin-mag MAX_NS_SPIN_MAG
                        Maximum neutron star spin magnitude. Neutron stars are
                        defined as components lighter than the NS-BH boundary
                        (3 Msun by default). REQUIRED if min-mass2 < ns-bh-
                        boundary-mass (default: None)
  --max-bh-spin-mag MAX_BH_SPIN_MAG
                        Maximum black hole spin magnitude. Black holes are
                        defined as components at or above the NS-BH boundary
                        (3 Msun by default). REQUIRED if max-mass1 >= ns-bh-
                        boundary-mass (default: None)
  --ns-bh-boundary-mass NS_BH_BOUNDARY_MASS
                        Mass boundary between neutron stars and black holes.
                        Components below this mass are considered neutron
                        stars and are subject to the neutron star spin limits.
                        Components at/above are subject to the black hole spin
                        limits. OPTIONAL, default=3.000000. UNITS=Solar mass
                        (default: None)
  --nsbh-flag           Set this flag if generating a bank that contains only
                        systems with 1 black hole and 1 neutron star. With
                        this flag set the heavier body will always be subject
                        to the black hole spin restriction and the lighter to
                        the neutron star spin restriction, regardless of mass.
                        OPTIONAL. If set, the value of --ns-bh-boundary-mass
                        will be ignored. (default: False)

Options to select the method of PSD generation:
  The options --psd-model, --psd-file, --asd-file, and --psd-estimation are
  mutually exclusive.

  --psd-model {AdVBNSOptimizedSensitivityP1200087,AdVDesignSensitivityP1200087,AdVEarlyHighSensitivityP1200087,AdVEarlyLowSensitivityP1200087,AdVLateHighSensitivityP1200087,AdVLateLowSensitivityP1200087,AdVMidHighSensitivityP1200087,AdVMidLowSensitivityP1200087,AdvVirgo,CosmicExplorerP1600143,CosmicExplorerPessimisticP1600143,CosmicExplorerWidebandP1600143,EinsteinTelescopeP1600143,GEO,GEOHF,KAGRA,KAGRADesignSensitivityT1600593,KAGRAEarlySensitivityT1600593,KAGRALateSensitivityT1600593,KAGRAMidSensitivityT1600593,KAGRAOpeningSensitivityT1600593,TAMA,Virgo,aLIGOBHBH20Deg,aLIGOBHBH20DegGWINC,aLIGOBNSOptimizedSensitivityP1200087,aLIGODesignSensitivityP1200087,aLIGOEarlyHighSensitivityP1200087,aLIGOEarlyLowSensitivityP1200087,aLIGOHighFrequency,aLIGOHighFrequencyGWINC,aLIGOLateHighSensitivityP1200087,aLIGOLateLowSensitivityP1200087,aLIGOMidHighSensitivityP1200087,aLIGOMidLowSensitivityP1200087,aLIGONSNSOpt,aLIGONSNSOptGWINC,aLIGONoSRMHighPower,aLIGONoSRMLowPower,aLIGONoSRMLowPowerGWINC,aLIGOQuantumBHBH20Deg,aLIGOQuantumHighFrequency,aLIGOQuantumNSNSOpt,aLIGOQuantumNoSRMHighPower,aLIGOQuantumNoSRMLowPower,aLIGOQuantumZeroDetHighPower,aLIGOQuantumZeroDetLowPower,aLIGOThermal,aLIGOZeroDetHighPower,aLIGOZeroDetHighPowerGWINC,aLIGOZeroDetLowPower,aLIGOZeroDetLowPowerGWINC,eLIGOModel,eLIGOShot,iLIGOModel,iLIGOSRD,iLIGOSeismic,iLIGOShot,iLIGOThermal,flat_unity}
                        Get PSD from given analytical model. (default: None)
  --psd-file PSD_FILE   Get PSD using given PSD ASCII file (default: None)
  --asd-file ASD_FILE   Get PSD using given ASD ASCII file (default: None)
  --psd-inverse-length PSD_INVERSE_LENGTH
                        (Optional) The maximum length of the impulse response
                        of the overwhitening filter (s) (default: None)
  --psdvar_short_segment SECONDS
                        Length of short segment when calculating the PSD
                        variability. (default: None)
  --psdvar_long_segment SECONDS
                        Length of long segment when calculating the PSD
                        variability. (default: None)
  --psdvar_overlap SECONDS
                        Sample length of the PSD. (default: None)
  --psdvar_low_freq HERTZ
                        Minimum frequency to consider in PSD comparison.
                        (default: None)
  --psdvar_high_freq HERTZ
                        Maximum frequency to consider in PSD comparison.
                        (default: None)
  --psd-estimation {mean,median,median-mean}
                        Measure PSD from the data, using given average method.
                        (default: None)
  --psd-segment-length PSD_SEGMENT_LENGTH
                        (Required for --psd-estimation) The segment length for
                        PSD estimation (s) (default: None)
  --psd-segment-stride PSD_SEGMENT_STRIDE
                        (Required for --psd-estimation) The separation between
                        consecutive segments (s) (default: None)
  --psd-num-segments PSD_NUM_SEGMENTS
                        (Optional, used only with --psd-estimation). If given,
                        PSDs will be estimated using only this number of
                        segments. If more data is given than needed to make
                        this number of segments then excess data will not be
                        used in the PSD estimate. If not enough data is given,
                        the code will fail. (default: None)
  --psd-output PSD_OUTPUT
                        (Optional) Write PSD to specified file (default: None)

Options for obtaining h(t):
  These options are used for generating h(t) either by reading from a file
  or by generating it. This is only needed if the PSD is to be estimated
  from the data, ie. if the --psd-estimation option is given.

  --gps-start-time GPS_START_TIME
                        The gps start time of the data (integer seconds)
                        (default: None)
  --gps-end-time GPS_END_TIME
                        The gps end time of the data (integer seconds)
                        (default: None)
  --strain-high-pass STRAIN_HIGH_PASS
                        High pass frequency (default: None)
  --pad-data PAD_DATA   Extra padding to remove highpass corruption (integer
                        seconds) (default: None)
  --taper-data TAPER_DATA
                        Taper ends of data to zero using the supplied length
                        as a window (integer seconds) (default: 0)
  --sample-rate SAMPLE_RATE
                        The sample rate to use for h(t) generation (integer
                        Hz). (default: None)
  --channel-name CHANNEL_NAME
                        The channel containing the gravitational strain data
                        (default: None)
  --frame-cache FRAME_CACHE [FRAME_CACHE ...]
                        Cache file containing the frame locations. (default:
                        None)
  --frame-files FRAME_FILES [FRAME_FILES ...]
                        list of frame files (default: None)
  --frame-type FRAME_TYPE
                        (optional), replaces frame-files. Use datafind to get
                        the needed frame file(s) of this type. (default: None)
  --frame-sieve FRAME_SIEVE
                        (optional), Only use frame files where the URL matches
                        the regular expression given. (default: None)
  --fake-strain {AdVBNSOptimizedSensitivityP1200087,AdVDesignSensitivityP1200087,AdVEarlyHighSensitivityP1200087,AdVEarlyLowSensitivityP1200087,AdVLateHighSensitivityP1200087,AdVLateLowSensitivityP1200087,AdVMidHighSensitivityP1200087,AdVMidLowSensitivityP1200087,AdvVirgo,CosmicExplorerP1600143,CosmicExplorerPessimisticP1600143,CosmicExplorerWidebandP1600143,EinsteinTelescopeP1600143,GEO,GEOHF,KAGRA,KAGRADesignSensitivityT1600593,KAGRAEarlySensitivityT1600593,KAGRALateSensitivityT1600593,KAGRAMidSensitivityT1600593,KAGRAOpeningSensitivityT1600593,TAMA,Virgo,aLIGOBHBH20Deg,aLIGOBHBH20DegGWINC,aLIGOBNSOptimizedSensitivityP1200087,aLIGODesignSensitivityP1200087,aLIGOEarlyHighSensitivityP1200087,aLIGOEarlyLowSensitivityP1200087,aLIGOHighFrequency,aLIGOHighFrequencyGWINC,aLIGOLateHighSensitivityP1200087,aLIGOLateLowSensitivityP1200087,aLIGOMidHighSensitivityP1200087,aLIGOMidLowSensitivityP1200087,aLIGONSNSOpt,aLIGONSNSOptGWINC,aLIGONoSRMHighPower,aLIGONoSRMLowPower,aLIGONoSRMLowPowerGWINC,aLIGOQuantumBHBH20Deg,aLIGOQuantumHighFrequency,aLIGOQuantumNSNSOpt,aLIGOQuantumNoSRMHighPower,aLIGOQuantumNoSRMLowPower,aLIGOQuantumZeroDetHighPower,aLIGOQuantumZeroDetLowPower,aLIGOThermal,aLIGOZeroDetHighPower,aLIGOZeroDetHighPowerGWINC,aLIGOZeroDetLowPower,aLIGOZeroDetLowPowerGWINC,eLIGOModel,eLIGOShot,iLIGOModel,iLIGOSRD,iLIGOSeismic,iLIGOShot,iLIGOThermal,zeroNoise}
                        Name of model PSD for generating fake gaussian noise.
                        (default: None)
  --fake-strain-seed FAKE_STRAIN_SEED
                        Seed value for the generation of fake colored gaussian
                        noise (default: 0)
  --fake-strain-from-file FAKE_STRAIN_FROM_FILE
                        File containing ASD for generating fake noise from it.
                        (default: None)
  --injection-file INJECTION_FILE
                        (optional) Injection file used to add waveforms into
                        the strain (default: None)
  --sgburst-injection-file SGBURST_INJECTION_FILE
                        (optional) Injection file used to add sine-Gaussian
                        burst waveforms into the strain (default: None)
  --ringdown-injection-file RINGDOWN_INJECTION_FILE
                        (optional) Injection file used to add ringdown-only
                        waveforms into the strain. (default: None)
  --injection-scale-factor INJECTION_SCALE_FACTOR
                        Divide injections by this factor before injecting into
                        the data. (default: 1)
  --gating-file GATING_FILE
                        (optional) Text file of gating segments to apply.
                        Format of each line is (all times in secs): gps_time
                        zeros_half_width pad_half_width (default: None)
  --autogating-threshold SIGMA
                        If given, find and gate glitches producing a deviation
                        larger than SIGMA in the whitened strain time series.
                        (default: None)
  --autogating-cluster SECONDS
                        Length of clustering window for detecting glitches for
                        autogating. (default: 5.0)
  --autogating-width SECONDS
                        Half-width of the gating window. (default: 0.25)
  --autogating-taper SECONDS
                        Taper the strain before and after each gating window
                        over a duration of SECONDS. (default: 0.25)
  --autogating-pad SECONDS
                        Ignore the given length of whitened strain at the ends
                        of a segment, to avoid filters ringing. (default: 16)
  --normalize-strain NORMALIZE_STRAIN
                        (optional) Divide frame data by constant. (default:
                        None)
  --zpk-z ZPK_Z [ZPK_Z ...]
                        (optional) Zero-pole-gain (zpk) filter strain. A list
                        of zeros for transfer function (default: None)
  --zpk-p ZPK_P [ZPK_P ...]
                        (optional) Zero-pole-gain (zpk) filter strain. A list
                        of poles for transfer function (default: None)
  --zpk-k ZPK_K         (optional) Zero-pole-gain (zpk) filter strain.
                        Transfer function gain (default: None)
  --witness-frame-type WITNESS_FRAME_TYPE
                        (optional), frame type which will be use to query
                        thewitness channel data. (default: None)
  --witness-tf-file WITNESS_TF_FILE
                        an hdf file containing the transfer functions and the
                        associated channel names (default: None)
  --witness-filter-length WITNESS_FILTER_LENGTH
                        filter length in seconds for the transfer function
                        (default: None)

Ethinca metric options:
  Options used in the calculation of Gamma metric components for the ethinca
  coincidence test and for assigning high-frequency cutoffs to templates.

  --calculate-time-metric-components
                        If given, the ethinca metric will be calculated for
                        only the time component, and stored in the Gamma0
                        entry of the sngl_inspiral table. OPTIONAL,
                        default=False (default: False)
  --calculate-ethinca-metric
                        If given, the ethinca metric will be calculated and
                        stored in the Gamma entries of the sngl_inspiral
                        table. OPTIONAL, default=False (default: False)
  --ethinca-pn-order {threePointFivePN,twoPN,twoPointFivePN,threePN,onePointFivePN,onePN,zeroPN}
                        Specify a PN order to be used in calculating the
                        ethinca metric. OPTIONAL: if not specified, the same
                        order will be used as for the bank metric. (default:
                        None)
  --filter-cutoff {HybridMECO,SEOBNRv1RD,LightRing,MECO,LRD,FRD,EOBNRv2RD,SEOBNRv2RD,BKLISCO,ERD,SEOBNRv4RD,EOBNRv2HMRD,SEOBNRv2Peak,IMRPhenomCFinal,IMRPhenomDPeak,SEOBNRv4Peak,SEOBNRv1Peak,IMRPhenomBFinal,SchwarzISCO}
                        Specify an upper frequency cutoff formula for the
                        ethinca metric calculation, and for the values of
                        f_final assigned to the templates. REQUIRED if the
                        calculate-ethinca-metric option is given. (default:
                        None)
  --ethinca-frequency-step ETHINCA_FREQUENCY_STEP
                        Control the precision of the upper frequency cutoff.
                        For speed, the metric is calculated only for discrete
                        f_max values with a spacing given by this option. Each
                        template is assigned the metric for the f_max closest
                        to its analytical cutoff formula. OPTIONAL,
                        default=10. UNITS=Hz (default: 10.0)

As before some notes on these options:

Some notes on these options:

  • The value of f0 generally doesn’t matter (so just use 70 if unsure). However if ethinca is being calculated f0 and f-low must be equal.
  • Choose f-upper wisely! If your signals coalesce at <1000Hz, you might want to use a lower value … although of course in this regime this inspiral-only metric will lose validity.
  • A delta-f value of 1/256 will certainly be accurate enough, a larger value will cause the code to run faster.
  • For the purposes of spin calculations a NS is considered to be anything with mass < 3 solar masses and a BH is considered to be anything with mass > 3 solar masses. But this can be overridden with the –ns-bh-boundary-mass option.
  • To avoid generating a NSBH bank where you have a wall of triggers with NS mass = 3 and spins up to the black hole maximum use the nsbh-flag. This will ensure that only neutron-star–black-hole systems are generated.
  • –num-seeds is the termination condition. The code will throw NUM_SEEDS points at the parameter space, and then filter out those that are too close to each other. If this value is too low, the bank will not converge, if it is too high, the code will take longer to run.
  • –num-failed-cutoff can be used as an alternative termination condition. Here the code runs until NUM_FAILED_CUTOFF points have been consecutively rejected and will then stop.
  • –vary-fupper will allow the code to vary the upper frequency cutoff across the parameter space. Currently this feature is only available in the stochastic code.
  • If a remnant-mass-threshold is specified the code sets up the bank so that it does not target NS-BH systems that cannot produce a remnant disk mass that exceeds the threshold: this is used to remove EM dim NS-BH binaries from the target parameter space, as discussed in Pannarale and Ohme, ApJL 7, 5 (2014). Please contact francesco.pannarale@ligo.org if you want to know more about this.

Command line options: lalapps_cbc_sbank

The program lalapps_cbc_sbank is part of lalsuite and documentation and command line options are described in the documentation at http://software.ligo.org/docs/lalsuite/lalapps/lalapps__cbc__sbank_8py_source.html

Some notes on the command line options:

  • Using the –iterative-match-df-max 8 option will greatly speed up the code by generating waveforms with a large frequency step and then iteratively lowering it until the calculated matches converge.
  • Using the –cache-waveforms option will greatly speed up the code by avoiding generating a waveform more than once. With this enabled memory usage can become a concern. If memory usage becomes high consider using the workflow generator.

Sbank workflow generator

In the case where one sbank job will not do the job you can use pycbc_create_sbank_workflow to parallelize your template bank placement needs.

The command line options for this code read as follows

$ pycbc_create_sbank_workflow --help
usage: pycbc_create_sbank_workflow [-h] [--version]
                                   [--workflow-name WORKFLOW_NAME]
                                   [-d OUTPUT_DIR] [--output-file OUTPUT_FILE]
                                   [--dax-filename DAX_FILENAME]
                                   [--map-filename MAP_FILENAME]
                                   [--is-sub-workflow]
                                   [--tags [TAGS [TAGS ...]]]
                                   [--config-files CONFIGFILE [CONFIGFILE ...]]
                                   [--config-overrides [SECTION:OPTION:VALUE [SECTION:OPTION:VALUE ...]]]
                                   [--config-delete [SECTION:OPTION [SECTION:OPTION ...]]]

Workflow generator for the lalapps_cbc_sbank template bank generation. This is
intended to be standalone, without putting things like the SbankExecutable
class in the pycbc.workflow module, to give an illustration of how a simple
workflow is constructed with pycbc.workflow.

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --workflow-name WORKFLOW_NAME
                        Descriptive name of the analysis.
  -d OUTPUT_DIR, --output-dir OUTPUT_DIR
                        Path to output directory.
  --output-file OUTPUT_FILE
                        Specify the output file name. Either a name can be
                        provided or a full path to file. Is this is not given
                        a filename and location is chosen automatically.
  --dax-filename DAX_FILENAME
                        This can be used if running this job in a sub-workflow
                        to specify the dax filename.
  --map-filename MAP_FILENAME
                        This can be used if running this job in a sub-workflow
                        to specify the output map filename. WARNING: Giving
                        this if not running as a sub-workflow will cause
                        pycbc_submit_dax to not work.
  --is-sub-workflow     Only give this option if this code is being run as a
                        sub-workflow within pegasus. If this means nothing to
                        you, do not give this option.
  --tags [TAGS [TAGS ...]]
                        If this option is given all jobs, and all workflow
                        configuration options, will use the tags given here.
                        This can be used if running this as a sub-workflow to
                        give two sets of options to two different invocations
                        of the sbank workflow.

workflow:
  Options needed for workflow setup.

  --config-files CONFIGFILE [CONFIGFILE ...]
                        List of config files to be used in analysis.
  --config-overrides [SECTION:OPTION:VALUE [SECTION:OPTION:VALUE ...]]
                        List of section,option,value combinations to add into
                        the configuration file. Normally the gps start and end
                        times might be provided this way, and user specific
                        locations (ie. output directories). This can also be
                        provided as SECTION:OPTION or SECTION:OPTION: both of
                        which indicate that the corresponding value is left
                        blank.
  --config-delete [SECTION:OPTION [SECTION:OPTION ...]]
                        List of section,option combinations to delete from the
                        configuration file. This can also be provided as
                        SECTION which deletes the enture section from the
                        configuration file or SECTION:OPTION which deletes a
                        specific option from a given section.

The main thing here is that a configuration file is supplied. This configuration file supplies basically all options about the template bank generation. One can read about the general setup of such files at the following page, but we provide some examples here. First we give a simple example, with some options commented out, but still shown and explained.

; Configuration file for pycbc_create_sbank_workflow
;
; Template bank documentation can be found here:
;
;    http://pycbc.org/pycbc/latest/html/tmpltbank.html
;
; Documentation for the PyCBC workflow module is here:
;
;    http://pycbc.org/pycbc/latest/html/workflow.html


[workflow]
; http://pycbc.org/pycbc/latest/html/workflow/initialization.html

; What files to store? If this is set to "results" then only the final template
; bank will exist after the workflow completes.
; If set to "merged_triggers" then a template bank will be placed in the output
; directory after each "cycle" of the workflow generation completes.
; If set to "all_triggers" you will get some more files from within each cycle,
; but not the output of each of the parallel jobs.
; if set to "all_files" you will get everything.
file-retention-level = merged_triggers

; Start and end times are needed to obey LIGO file naming conventions. Actual
; values are irrelevant. This can be overriden on the command line.
start-time = 900000000
end-time = 900010000

; These are the sbank-specific options.
; num-cycles is how many repetitions of the sbank parallelization -> recombine
; process will be done
num-cycles = 5

; nbanks is how many parallel jobs to use each cycle
nbanks = 100

; seed-bank can be used to provide an input to sbank jobs
; seed-bank = /path/to/file

; If using seed-bank, this will instruct sbank to use this to determine the
; initial chirp-mass bins. In this case a coarse job is not run
; use-seed-bank-for-chirp-bins=

; If not giving a seed-bank the coarse job will be used as a seed for the first
; parallel stage. Give this option and the coarse job will not be used as a
; seed. Then it is only used to determine initial chirp-mass bins
; do-not-use-coarse-job-as-seed =


[workflow-ifos]
; Need to specify the active ifos for file naming.
h1 =
l1 =
v1=

[executables]
; http://pycbc.org/pycbc/latest/html/workflow/initialization.html

; All executables are listed here
sbank = ${which:lalapps_cbc_sbank}
sbank_mchirp_bins = ${which:lalapps_cbc_sbank_hdf5_choose_mchirp_boundaries}
h5add = ${which:lalapps_cbc_sbank_hdf5_bankcombiner}

; Then options for all executables are added. These are added directly to the
; jobs as described here:
;    http://pycbc.org/pycbc/latest/html/workflow/initialization.html
[sbank]
; Options for *all* sbank jobs

; PSD-related options
reference-psd = /home/spxiwh/aLIGO/BBH_template_banks/psd-T1200307v4_H1.xml
; This refers to the instrument in the reference-psd file.
instrument = H1
; F-high is lower than this if the waveform power doesn't get this high
fhigh-max = 2048.
flow = 30.

; Waveform
approximant = SEOBNRv2_ROM_DoubleSpin

; Mass/spin parameter options
mass1-min = 5.0
mass1-max = 100.0
mass2-min = 5.0
mass2-max = 100.0
mtotal-min = 10.0
mtotal-max = 100.0
mratio-min = 1.0
mratio-max = 3.0
aligned-spin =
spin1-max = 0.9899
spin1-min = -0.9899
spin2-max = 0.9899
spin2-min = -0.9899

;minimal match
match-min = 0.97

; Optimization choices
iterative-match-df-max = 8.0
cache-waveforms =

[sbank-coarse]
; These options are sent only to the initial sbank-coarse job. There must not
; be duplication between this section and [sbank]

; When you accept a point after rejecting, on average, more than
; convergence-threshold points, the job will terminate.
convergence-threshold = 50
; Do not accept more templates than this. Once this limit is reached the job
; will terminate
max-new-templates = 20000

[sbank-parallel]
; These options are sent to *all* sbank parallel jobs
convergence-threshold = 5000
max-new-templates = 20000000

[sbank-readder]
; These options are sent to *all* sbank readder jobs. The readder jobs takes
; all points accepted in the parallel stage and tests them against each other.
; This avoids the situation where two separate parallel jobs place a template
; in essentially the same point.

; Jobs should not terminate until all potential points are tried
convergence-threshold = 500000000
max-new-templates = 20000000000

[sbank_mchirp_bins]
; These options are sent to the sbank_mchirp_bins jobs
template-weight = equal

[llwadd]
; Global llwadd options, if any, go here

Then a more complex example, where we exercise more fine-grained control over the parallel job and use different settings during each cycle of the generator.

; Configuration file for pycbc_create_sbank_workflow
;
; Template bank documentation can be found here:
;
;    http://pycbc.org/pycbc/latest/html/tmpltbank.html
;
; Documentation for the PyCBC workflow module is here:
;
;    http://pycbc.org/pycbc/latest/html/workflow.html


[workflow]
; http://pycbc.org/pycbc/latest/html/workflow/initialization.html

; What files to store? If this is set to "results" then only the final template
; bank will exist after the workflow completes.
; If set to "merged_triggers" then a template bank will be placed in the output
; directory after each "cycle" of the workflow generation completes.
; If set to "all_triggers" you will get some more files from within each cycle,
; but not the output of each of the parallel jobs.
; if set to "all_files" you will get everything.
file-retention-level = merged_triggers

; Start and end times are needed to obey LIGO file naming conventions. Actual
; values are irrelevant. This can be overriden on the command line.
start-time = 900000000
end-time = 900010000

; These are the sbank-specific options.
; num-cycles is how many repetitions of the sbank parallelization -> recombine
; process will be done
num-cycles = 13

; nbanks is how many parallel jobs to use each cycle
nbanks = 100

; seed-bank can be used to provide an input to sbank jobs
; seed-bank = /path/to/file

; If using seed-bank, this will instruct sbank to use this to determine the
; initial chirp-mass bins. In this case a coarse job is not run
; use-seed-bank-for-chirp-bins=

; If not giving a seed-bank the coarse job will be used as a seed for the first
; parallel stage. Give this option and the coarse job will not be used as a
; seed. Then it is only used to determine initial chirp-mass bins
; do-not-use-coarse-job-as-seed =


[workflow-ifos]
; Need to specify the active ifos for file naming.
h1 =
l1 =
v1=

[executables]
; http://pycbc.org/pycbc/latest/html/workflow/initialization.html

; All executables are listed here
sbank = ${which:lalapps_cbc_sbank}
sbank_mchirp_bins = ${which:lalapps_cbc_sbank_hdf5_choose_mchirp_boundaries}
h5add = ${which:lalapps_cbc_sbank_hdf5_bankcombiner}

; Then options for all executables are added. These are added directly to the
; jobs as described here:
;    http://pycbc.org/pycbc/latest/html/workflow/initialization.html
[sbank]
; Options for *all* sbank jobs

; PSD-related options
reference-psd = /home/spxiwh/aLIGO/BBH_template_banks/psd-T1200307v4_H1.xml
; This refers to the instrument in the reference-psd file.
instrument = H1
; F-high is lower than this if the waveform power doesn't get this high
fhigh-max = 2048.
flow = 30.

; Waveform
approximant = SEOBNRv2_ROM_DoubleSpin

; Mass/spin parameter options
mass1-min = 5.0
mass1-max = 100.0
mass2-min = 5.0
mass2-max = 100.0
mtotal-min = 10.0
mtotal-max = 100.0
mratio-min = 1.0
mratio-max = 3.0
aligned-spin =
spin1-max = 0.9899
spin1-min = -0.9899
spin2-max = 0.9899
spin2-min = -0.9899

;minimal match
match-min = 0.97

; Optimization choices
iterative-match-df-max = 8.0
cache-waveforms =

[sbank-coarse]
; These options are sent only to the initial sbank-coarse job. There must not
; be duplication between this section and [sbank]

; When you accept a point after rejecting, on average, more than
; convergence-threshold points, the job will terminate.
convergence-threshold = 50
; Do not accept more templates than this. Once this limit is reached the job
; will terminate
max-new-templates = 20000

[pegasus_profile-sbank-coarse]
; These are pegasus specific options for sbank jobs with the coarse tag.
; One main example of this section is to specify options to go into the 
; submit file. For example:

condor|request_memory = 10000
; This can take a lot of RAM! Other options for condor sub files can be
; specified in the same way. Things like accounting group are automatically
; added, as is get_env = True.

[sbank-parallel-cycle0]
; parallel jobs, cycle0
convergence-threshold = 10
max-new-templates = 100

[sbank-parallel-cycle1]
; parallel jobs, cycle1
convergence-threshold = 10
max-new-templates = 100

[sbank-parallel-cycle2]
; parallel jobs, cycle2
convergence-threshold = 10
max-new-templates = 100

[sbank-parallel-cycle3]
; parallel jobs, cycle3
convergence-threshold = 10
max-new-templates = 200

[sbank-parallel-cycle4]
; parallel jobs, cycle4
convergence-threshold = 10
max-new-templates = 1000

[sbank-parallel-cycle5]
; parallel jobs, cycle5
convergence-threshold = 100
max-new-templates = 100

[sbank-parallel-cycle6]
; parallel jobs, cycle6
convergence-threshold = 100
max-new-templates = 100

[sbank-parallel-cycle7]
; parallel jobs, cycle7
convergence-threshold = 100
max-new-templates = 1000

[sbank-parallel-cycle8]
; parallel jobs, cycle8
convergence-threshold = 500
max-new-templates = 100

[sbank-parallel-cycle9]
; parallel jobs, cycle9
convergence-threshold = 500
max-new-templates = 1000

[sbank-parallel-cycle10]
; parallel jobs, cycle10
convergence-threshold = 1000
max-new-templates = 1000

[sbank-parallel-cycle11]
; parallel jobs, cycle11
convergence-threshold = 1000
; Don't expect templates-max to be reached here
max-new-templates = 1000000

[sbank-parallel-cycle12]
; parallel jobs, cycle12
convergence-threshold = 1000
max-new-templates = 1000000


[sbank-readder]
; These options are sent to *all* sbank readder jobs. The readder jobs takes
; all points accepted in the parallel stage and tests them against each other.
; This avoids the situation where two separate parallel jobs place a template
; in essentially the same point.

; Jobs should not terminate until all potential points are tried
convergence-threshold = 500000000
max-new-templates = 20000000000

[sbank_mchirp_bins]
; These options are sent to the sbank_mchirp_bins jobs
template-weight = equal

[llwadd]
; Global llwadd options, if any, go here

PLEASE NOTE: These examples are intended to be illustrative of the workflow generator and not intended to be used verbatim, expecting this to work for all examples. You will want to tune these options based around whatever examples you are running. When doing that you want to balance job run time, memory usage, wall-clock time, avoiding too many templates at the readder stage. Please ask for help if you have a specific example and want some help to optimize.

Hybrid approaches: the best of both worlds

We have found that in many cases it makes sense to combine the techniques of sbank with the geometric lattic algorithm to produce a template bank. This technique was used in Advanced LIGO’s first observing run to produce what was called the “uberbank”. The references for this are the following:

  • Abbott et al., Phys.Rev. D93 (2016) 122003
  • Capano et al., Phys.Rev. D93 (2016) 124007

The uberbank construction process is now written up in a single workflow, pycbc_create_uberbank_workflow. The current setup of this workflow is as follows:

  • Run in parallel one sbank workflow and one geometric workflow
  • Combine the two outputs together (this assumes the two do not overlap)
  • Run a further sbank workflow to fill in the remaining space and any holes

The idea to this 3-part workflow is it allows us to first focus on covering well both the BNS and BBH regions of parameter space, before filling in the rest with potentially different settings. There is a lot of scope for editing and reordering this workflow, potentially adding, or removing various of the stages.

The command-line help for the workflow generator is as follows:

$ pycbc_create_uberbank_workflow --help
usage: pycbc_create_uberbank_workflow [-h] [--version]
                                      [--workflow-name WORKFLOW_NAME]
                                      [-d OUTPUT_DIR]
                                      [--config-files CONFIGFILE [CONFIGFILE ...]]
                                      [--config-overrides [SECTION:OPTION:VALUE [SECTION:OPTION:VALUE ...]]]
                                      [--config-delete [SECTION:OPTION [SECTION:OPTION ...]]]

Workflow generator for the 'uberbank' template bank construction. The script
as written runs one configurable example of sbank, and one of
pycbc_geom_aligned_bank independently. It then combines these two banks
together and runs a second example of sbank and the resulting output. It is
foreseen that this script would be altered to generate workflows in slightly
different configurations to the one described, so hopefully the script is
clear enough to allow someone to do that.

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --workflow-name WORKFLOW_NAME
                        Descriptive name of the analysis.
  -d OUTPUT_DIR, --output-dir OUTPUT_DIR
                        Path to output directory.

workflow:
  Options needed for workflow setup.

  --config-files CONFIGFILE [CONFIGFILE ...]
                        List of config files to be used in analysis.
  --config-overrides [SECTION:OPTION:VALUE [SECTION:OPTION:VALUE ...]]
                        List of section,option,value combinations to add into
                        the configuration file. Normally the gps start and end
                        times might be provided this way, and user specific
                        locations (ie. output directories). This can also be
                        provided as SECTION:OPTION or SECTION:OPTION: both of
                        which indicate that the corresponding value is left
                        blank.
  --config-delete [SECTION:OPTION [SECTION:OPTION ...]]
                        List of section,option combinations to delete from the
                        configuration file. This can also be provided as
                        SECTION which deletes the enture section from the
                        configuration file or SECTION:OPTION which deletes a
                        specific option from a given section.

As with the sbank workflow generator the main bulk of the configuration is the configuration file, which is provided on the command line. This configuration file contains options for all 3 stages of the workflow, and so is a little more involved than the sbank example given above. Here we provide a particularly detailed configuration for generating a bank equivalent to the uberbank on O1-like data.

; Configuration file for pycbc_create_uberbank_workflow
;
; Tests and decisions for the choices made here are documented here:
;
;    https://www.lsc-group.phys.uwm.edu/ligovirgo/cbcnote/PyCBC/O2TemplateBank
;
; Template bank documentation can be found here:
;
;    http://pycbc.org/pycbc/latest/html/tmpltbank.html
;
; Documentation for the PyCBC workflow module is here:
;
;    http://pycbc.org/pycbc/latest/html/workflow.html

[common]
; Main options shared by different sections are gathered here

; Noise PSDs for geometric and sbank jobs
psd-txt = /home/tito/o1/psds/all_O1_C02_estimation/output/psds/H1L1-AVERAGE_PSD-1126051217-11203200.txt
psd-xml = /home/tito/o1/psds/all_O1_C02_estimation/output/psds/H1L1-AVERAGE_PSD-1126051217-11203200.xml.gz

low-frequency-cutoff = 30

; Spin bounds
max-bh-spin = 0.9899
max-ns-spin = 0.05
nsbh-boundary = 2

[workflow]
; http://pycbc.org/pycbc/latest/html/workflow/initialization.html

; Store only "merged_triggers" this means only final result files, and all key
; intermediate products.
file-retention-level = merged_triggers

; Start and end times are needed to obey LIGO file naming conventions. Actual
; values are irrelevant. This can be overriden on the command line.
; Here we use the times matching the estimated PSD so we have an immediate
; reference on the resulting bank file name
start-time = 1126051217
end-time = 1137254417

[workflow-bbh]
; Options in here go only to the first sbank workflow (currently tagged BBH)

; num-cycles is how many repetitions of the sbank parallelization -> recombine
; process will be done
num-cycles = 13

; nbanks is how many parallel jobs to use, setting this large no longer causes
; overcoverage *but* be careful that the templates generated by all nbanks is
; not that large that it causes memory issues when readding. You can limit the
; number of templates added by each job and then run more total cycles. For
; weird parameter space (e.g. precession) set number of cycles to a large
; value, use a good number of nbanks, but accept only 10-100 templates per job
; This let's the bank slowly converge while you can monitor the periodic
; output!
nbanks = 200

; seed-bank can be used to provide an input to sbank jobs
; seed-bank = /path/to/file

; If using seed-bank, this will instruct sbank to use this to determine the
; initial chirp-mass bins. In this case a coarse job is not run
; use-seed-bank-for-chirp-bins=

; If not giving a seed-bank the coarse job will be used as a seed for the first
; parallel stage. Give this option and the coarse job will not be used as a
; seed. Then it is only used to determine initial chirp-mass bins
; do-not-use-coarse-job-as-seed =

[workflow-final]
; Options in here go only to the second sbank workflow (currently tagged FINAL)

; See above for option descriptions
num-cycles = 17
nbanks = 500

; Here the seed-bank is set automatically by the workflow generator.

; Not using seed bank for the chirp-mass bins as it does not cover the full
; space
; use-seed-bank-for-chirp-bins=

[workflow-ifos]
; Need to specify the active ifos for file naming.
h1 =
l1 =

[executables]
; http://pycbc.org/pycbc/latest/html/workflow/initialization.html

; All executables are listed here, will be equivalent to `which exe`
sbank = ${which:lalapps_cbc_sbank}
sbank_workflow = ${which:pycbc_create_sbank_workflow}
sbank_mchirp_bins = ${which:lalapps_cbc_sbank_hdf5_choose_mchirp_boundaries}
h5add = ${which:lalapps_cbc_sbank_hdf5_bankcombiner}
geom_aligned_bank = ${which:pycbc_geom_aligned_bank}

; Then options for all executables are added. These are added directly to the
; jobs as described here:
;    http://pycbc.org/pycbc/latest/html/workflow/initialization.html

[sbank_workflow]
; Options to the workflow generator

[llwadd]
; Global llwadd options, if any, go here

[geom_aligned_bank]
min-match = 0.97
random-seed = 1915
pn-order = threePointFivePN
f-low = ${common|low-frequency-cutoff}
f-upper = 1000
delta-f = 0.01
min-mass1 = 1.
max-mass1 = 5.
min-mass2 = 1.
max-mass2 = 3.
min-total-mass = 2.
max-total-mass = 6.
max-bh-spin-mag = ${common|max-bh-spin}
max-ns-spin-mag = ${common|max-ns-spin}
ns-bh-boundary-mass = ${common|nsbh-boundary}
psd-file = ${common|psd-txt}
split-bank-num = 75

[sbank_mchirp_bins]
; These options are sent to the sbank_mchirp_bins jobs
template-weight = equal

[sbank]
; These options are sent to *all* sbank jobs
; Options sent to specific sbank jobs are give below. There must be *no*
; conflicts here. Ie. if an option appears here it *cannot* be overridden in
; any of the sub-sections below.

; PSD-related options
reference-psd = ${common|psd-xml}
; This refers to the instrument in the reference-psd file.
instrument = H1L1
; F-high is lower than this if the waveform power doesn't get this high
fhigh-max = 2048.
flow = ${common|low-frequency-cutoff}
; Waveform
approximant = SEOBNRv2_ROM_DoubleSpin_HI
; Optimization choices
iterative-match-df-max = 8.0
cache-waveforms =

; Mass options common to sbank jobs
mass1-max = 99
mass2-max = 99
mtotal-max = 100
mratio-min = 1

; Spin options common to sbank jobs
aligned-spin =
bh-spin-min = -${common|max-bh-spin}
bh-spin-max = ${common|max-bh-spin}
ns-spin-min = -${common|max-ns-spin}
ns-spin-max = ${common|max-ns-spin}
ns-bh-boundary-mass = ${common|nsbh-boundary}

[sbank-bbh]
; These options are sent to all sbank "BBH" jobs

; Mass/spin parameter options
mass1-min = 5.0
mass2-min = 5.0
mtotal-min = 10.0
mratio-max = 3.0

[sbank-final]
; These options are sent to all sbank "FINAL" jobs

; Mass/spin parameter options
mass1-min = 1.0
mass2-min = 1.0
; SEOBNRv2's eta = 0.01 limit
mratio-max = 97.989

[sbank-bbh-coarse]
; These options are sent only to the initial sbank-coarse job for "FINAL".
match-min = 0.98
convergence-threshold = 50
max-new-templates = 100000

[pegasus_profile-sbank-bbh-coarse]
; These are pegasus specific options for sbank jobs with the coarse tag.
; These will appear in the .sub files.
; FIXME: Need to verify this works with tags!

; This can take a lot of RAM! Other options for condor sub files can be
; specified in the same way. Things like accounting group are automatically
; added, as is get_env = True.
condor|request_memory = 10000

[sbank-final-coarse]
; These options are sent only to the initial sbank-coarse job for "BBH".
; This one is not a seed!!!
match-min = 0.90
convergence-threshold = 200
max-new-templates = 20000

[sbank-readder]
; These options are sent to all readder jobs

; Jobs should not terminate until all potential points are tried
convergence-threshold = 500000000
max-new-templates = 20000000000

[sbank-bbh-readder]
; These options are sent to all readder jobs for "BBH"
match-min = 0.98

[sbank-parallel-cycle0]
; parallel jobs, cycle0
convergence-threshold = 10
max-new-templates = 100

[sbank-parallel-cycle1]
; parallel jobs, cycle1
convergence-threshold = 10
max-new-templates = 100

[sbank-parallel-cycle2]
; parallel jobs, cycle2
convergence-threshold = 10
max-new-templates = 100

[sbank-parallel-cycle3]
; parallel jobs, cycle3
convergence-threshold = 10
max-new-templates = 200

[sbank-parallel-cycle4]
; parallel jobs, cycle4
convergence-threshold = 10
max-new-templates = 1000

[sbank-parallel-cycle5]
; parallel jobs, cycle5
convergence-threshold = 100
max-new-templates = 100

[sbank-parallel-cycle6]
; parallel jobs, cycle6
convergence-threshold = 100
max-new-templates = 100

[sbank-parallel-cycle7]
; parallel jobs, cycle7
convergence-threshold = 100
max-new-templates = 1000

[sbank-parallel-cycle8]
; parallel jobs, cycle8
convergence-threshold = 500
max-new-templates = 100

[sbank-parallel-cycle9]
; parallel jobs, cycle9
convergence-threshold = 500
max-new-templates = 1000

[sbank-parallel-cycle10]
; parallel jobs, cycle10
convergence-threshold = 1000
max-new-templates = 1000

[sbank-parallel-cycle11]
; parallel jobs, cycle11
convergence-threshold = 1000
; Don't expect max-new-templates to be reached here
max-new-templates = 1000000

[sbank-parallel-cycle12]
; parallel jobs, cycle12
convergence-threshold = 1000
max-new-templates = 1000000

[sbank-parallel-bbh]
; BBH parallel jobs

; All use the same match-min
match-min = 0.98

[sbank-final-cycle0&sbank-final-cycle1]
; BBH parallel and readder jobs, cycles 0 and 1
match-min = 0.965

[sbank-final-cycle2&sbank-final-cycle3]
; BBH parallel and readder jobs, cycles 2 and 3
match-min = 0.965

[sbank-final-cycle4&sbank-final-cycle5]
; BBH parallel and readder jobs, cycles 4 and 5
match-min = 0.965

[sbank-final-cycle6&sbank-final-cycle7]
; BBH parallel and readder jobs, cycles 6 and 7
match-min = 0.965

[sbank-final-cycle8&sbank-final-cycle9]
; BBH parallel and readder jobs, cycles 8 and 9
match-min = 0.965

[sbank-final-cycle10&sbank-final-cycle11&sbank-final-cycle12]
; BBH parallel and readder jobs, cycles 10 and 11 and 12
match-min = 0.965

[sbank-final-parallel-cycle13]
; These last cycles only used by "FINAL" intended to avoid any large holes
convergence-threshold = 5000
max-new-templates = 20000000
match-min = 0.95

[sbank-final-readder-cycle13&sbank-final-readder-cycle14&sbank-final-readder-cycle15&sbank-final-readder-cycle16]
; "FINAL" readder jobs at cycles 13 - 16
match-min = 0.95

[sbank-final-parallel-cycle14]
; These last cycles only used by "FINAL" intended to avoid any large holes
convergence-threshold = 5000
max-new-templates = 20000000
match-min = 0.95

[sbank-final-parallel-cycle15]
; These last cycles only used by "FINAL" intended to avoid any large holes
convergence-threshold = 50000
max-new-templates = 20000000
match-min = 0.95

[sbank-final-parallel-cycle16]
; These last cycles only used by "FINAL" intended to avoid any large holes
convergence-threshold = 50000
max-new-templates = 20000000
match-min = 0.95