The workflow template bank generation module

Introduction

The template bank section of the pycbc workflow module is responsible for gathering/generating the banks of waveforms that will be used to matched-filter against the data.

It can run in a number of different modes

  • With a pre-generated template bank, which can be specified for all ifos, or as one bank for each ifo.
  • By generating unique and independent template banks for each ifo that are regenerated every approx. 2000s
  • Generating template banks that do not vary over the workflow, can be the same template bank in each ifo or different ones.

The template bank module, by default, is independent of other modules, though it is possible to ensure that there is a one-to-one correspondence between template banks and matched-filter outputs. Improvements over ihope:

  • The template bank analysis chunks may be longer or shorter than the inspiral chunks
  • Options sent to one job can be sent to the other or not, as desired. No hardcoding of options that are always sent to both the matched-filter and template bank stages.

Like other modules, the template bank module returns a pycbc FileList of the template bank files generated/supplied to this module. It is possible to make multiple calls to the template bank module in the same module by using the tags kwarg when calling this.

Usage

Using this module requires a number of things

  • A configuration file (or files) containing the information needed to tell this module how to generate (or gather) the template banks (described below).
  • An initialized instance of the pycbc Workflow class, containing the ConfigParser.
  • A list of segments to be analysed by this module.
  • A FileList returned by the datafind module containing the frames that contain the data that will be used to make the template banks. (If using a pre-supplied PSD, or some other use-case that does not require reading data this can be set to None).

The module is then called according to

pycbc.workflow.setup_tmpltbank_workflow(workflow, science_segs, datafind_outs, output_dir=None, psd_files=None, tags=None, return_format=None)[source]

Setup template bank section of CBC workflow. This function is responsible for deciding which of the various template bank workflow generation utilities should be used.

Parameters:
  • workflow (pycbc.workflow.core.Workflow) – An instanced class that manages the constructed workflow.
  • science_segs (Keyed dictionary of glue.segmentlist objects) – scienceSegs[ifo] holds the science segments to be analysed for each ifo.
  • datafind_outs (pycbc.workflow.core.FileList) – The file list containing the datafind files.
  • output_dir (path string) – The directory where data products will be placed.
  • psd_files (pycbc.workflow.core.FileList) – The file list containing predefined PSDs, if provided.
  • tags (list of strings) – If given these tags are used to uniquely name and identify output files that would be produced in multiple calls to this function.
Returns:

tmplt_banks – The FileList holding the details of all the template bank jobs.

Return type:

pycbc.workflow.core.FileList

Configuration file setup

Here we describe the options given in the configuration file used in the workflow that will be needed in this section

[workflow-tmpltbank] section

The configuration file must have a [workflow-tmpltbank] section, which is used to tell the workflow how to construct (or gather) the template banks. The first option to choose and provide is

  • tmpltbank-method = VALUE

The choices here and their description are as described below

  • PREGENERATED_BANK - A pregenerated template bank is supplied and this should be used when performing matched-filtering for all ifos and all times. This uses the setup_tmpltbank_pregenerated sub-module.
  • WORKFLOW_INDEPENDENT_IFOS - Template banks will be generated within the workflow. These banks will be made to cover only short (normally ~ 2000s) of data to reflect PSD changes over time and will be independent and distinct for each analysed interferometer. This uses the setup_tmpltbank_dax_generated sub-module.
  • WORKFLOW_INDEPENDENT_IFOS_NODATA - Template banks will be generated within the workflow. There will be one bank for each ifo, which will cover all times. No data frames will be used when constructing the workflow (ie. using a design PSD or similar). This uses the setup_tmpltbank_without_frames sub-module.
  • WORKFLOW_NO_IFO_VARIATION_NODATA - As WORKFLOW_INDEPENDENT_IFOS_NODATA except only one template bank will be generated that is valid for all ifos. This uses the setup_tmpltbank_without_frames sub-module.

Each of these options will describe which subfunction to use. These are described here

pycbc.workflow.setup_tmpltbank_pregenerated(workflow, tags=None)[source]

Setup CBC workflow to use a pregenerated template bank. The bank given in cp.get(‘workflow’,’pregenerated-template-bank’) will be used as the input file for all matched-filtering jobs. If this option is present, workflow will assume that it should be used and not generate template banks within the workflow.

Parameters:
  • workflow (pycbc.workflow.core.Workflow) – An instanced class that manages the constructed workflow.
  • tags (list of strings) – If given these tags are used to uniquely name and identify output files that would be produced in multiple calls to this function.
Returns:

tmplt_banks – The FileList holding the details of the template bank.

Return type:

pycbc.workflow.core.FileList

pycbc.workflow.setup_tmpltbank_dax_generated(workflow, science_segs, datafind_outs, output_dir, tags=None, link_to_matchedfltr=True, compatibility_mode=False, psd_files=None)[source]

Setup template bank jobs that are generated as part of the CBC workflow. This function will add numerous jobs to the CBC workflow using configuration options from the .ini file. The following executables are currently supported:

  • lalapps_tmpltbank
  • pycbc_geom_nonspin_bank
Parameters:
  • workflow (pycbc.workflow.core.Workflow) – An instanced class that manages the constructed workflow.
  • science_segs (Keyed dictionary of glue.segmentlist objects) – scienceSegs[ifo] holds the science segments to be analysed for each ifo.
  • datafind_outs (pycbc.workflow.core.FileList) – The file list containing the datafind files.
  • output_dir (path string) – The directory where data products will be placed.
  • tags (list of strings) – If given these tags are used to uniquely name and identify output files that would be produced in multiple calls to this function.
  • link_to_matchedfltr (boolean, optional (default=True)) – If this option is given, the job valid_times will be altered so that there will be one inspiral file for every template bank and they will cover the same time span. Note that this option must also be given during matched-filter generation to be meaningful.
  • psd_file (pycbc.workflow.core.FileList) – The file list containing predefined PSDs, if provided.
Returns:

tmplt_banks – The FileList holding the details of all the template bank jobs.

Return type:

pycbc.workflow.core.FileList

pycbc.workflow.setup_tmpltbank_without_frames(workflow, output_dir, tags=None, independent_ifos=False, psd_files=None)[source]

Setup CBC workflow to use a template bank (or banks) that are generated in the workflow, but do not use the data to estimate a PSD, and therefore do not vary over the duration of the workflow. This can either generate one bank that is valid for all ifos at all times, or multiple banks that are valid only for a single ifo at all times (one bank per ifo).

Parameters:
  • workflow (pycbc.workflow.core.Workflow) – An instanced class that manages the constructed workflow.
  • output_dir (path string) – The directory where the template bank outputs will be placed.
  • tags (list of strings) – If given these tags are used to uniquely name and identify output files that would be produced in multiple calls to this function.
  • independent_ifos (Boolean, optional (default=False)) – If given this will produce one template bank per ifo. If not given there will be on template bank to cover all ifos.
  • psd_file (pycbc.workflow.core.FileList) – The file list containing predefined PSDs, if provided.
Returns:

tmplt_banks – The FileList holding the details of the template bank(s).

Return type:

pycbc.workflow.core.FileList

When using the setup_tmpltbank_pregenerated sub-module the following additional options apply in the [workflow-tmpltbank] section.

  • tmpltbank-pregenerated-bank = PATH - OPTIONAL. This is the location of the pre-generated bank that is to be used for all ifos.
  • tmpltbank-pregenerated-bank-[ifo] = PATH = OPTIONAL. This is the location of the pre-generated bank that is to be used for all ifos. Either this option must be given for all active ifos or tmpltbank-pregenerated-bank must be given. If both are supplied this option tmpltbank-pregenerated-bank-[ifo] will be ignored. [ifo] should be replaced by the name of each ifo in lower case. For example tmpltbank-pregenerated-bank-l1 or tmpltbank-pregenerated-bank-v1.

When using the setup_tmpltbank_without_frames sub-module the following additional options apply in the [workflow-tmpltbank] section:

  • tmpltbank-write-psd-file - OPTIONAL. If given the template bank code will also write a file containing the PSD. Currently only supported in pycbc template bank codes.

When using the setup_tmpltbank_dax_generated sub-module the following additional options apply in the [workflow-templtbank] section.

  • tmpltbank-link-to-matchedfltr - OPTIONAL. If this is given the workflow module will attempt to ensure a one-to-one correspondence between template banks and matched-filter outputs. This may not work in all cases and should be considered an option to be used for comparing with ihope output.
  • tmpltbank-compatibility-mode - OPTIONAL. If this is given the workflow module will tile the template bank jobs in the same way as inspiral_hipe used to. This requires the link option above and that the template bank and matched-filtering jobs are reading the same amount of data in each job.
  • tmpltbank-write-psd-file - OPTIONAL. If given the template bank code will also write a file containing the PSD. Currently only supported in pycbc template bank codes.

The following options apply only when using setup_tmpltbank_dax_generated and not using lalapps_tmpltbank

  • analysis-length = LENGTH_IN_SECONDS (not used when lalapps_tmpltbank is the executable) - REQUIRED. The amount of time in seconds that will be used for frames for PSD generation.

[executables]

If using setup_tmpltbank_pregenerated then no executables are needed, you have already generated the template bank.

If using setup_tmpltbank_dax_generated or setup_tmpltbank_without_frames then you need to supply the template bank executable. This is done in the [executables] section by adding something like:

tmpltbank = /path/to/lalapps_tmpltbank

the option, in this case ‘tmpltbank’, will be used to specify the constant command line options that are sent to all tmpltbank jobs. Currently this value is hardcoded to tmpltbank, but we plan to change this to allow multiple tmpltbank executables to be used in a single workflow. How to set up the [{exe_name}] section, and which executables are currently supported is discussed below.

If template banks are being generated separately for each ifo then sections named [tmpltbank-${ifo}] (for e.g. [tmpltbank-h1] or [tmpltbank-v1]) can be used to specify options that should only be supplied when running on that ifo.

Supported template bank exes and instructions for using them

The following template bank executables are currently supported in the workflow module

  • lalapps_tmpltbank
  • pycbc_geom_nonspinbank

Adding a new executable is not too hard, please ask a developer for some pointers on how to do this if you want to add a new code.

Also see Pycbc.Tmpltbank for a description/introduction to pycbc template bank code and papers describing these codes, lalapps_tmpltbank and sBank.

lalapps_tmpltbank_ahope

Lalapps_tmpltbank is the legacy C-code that has been used to generate template banks for gravitational-wave data analysis since the dawn of time. It is a little inflexible in terms of output file names. We recommend using the newer pycbc_geom_nonspinbank if possible.

lalapps_tmpltbank is supported in pycbc’s workflow module via a wrapper script lalapps_tmpltbank_ahope, this allows us to specify all the frame files and the output file name directly.

The help message for lalapps_tmpltbank is available at http://software.ligo.org/docs/lalsuite/lalapps/tmpltbank_8c.html

Of these options the workflow module and/or the wrapper script will automatically add the following, which are unique for each job. DO NOT ADD THESE OPTIONS IN THE CONFIGURATION FILE.

  • –gps-start-time
  • –gps-end-time
  • –frame-cache
  • –user-tag
  • –ifo-tag

All other options must be provided in the configuration file. Here is an example of a lalapps_tmpltbank call.

lalapps_tmpltbank --grid-spacing Hexagonal --dynamic-range-exponent 69.0 --minimal-match 0.97 --high-pass-order 8 --strain-high-pass-order 8 --maximum-mass 25.0 --gps-end-time 961587599 --calibrated-data real_8 --channel-name H1:LDAS-STRAIN --space Tau0Tau3 --number-of-segments 15 --enable-high-pass 30.0 --gps-start-time 961585551 --high-pass-attenuation 0.1 --num-freq-cutoffs 1 --segment-length 1048576 --low-frequency-cutoff 40.0 --pad-data 8 --min-high-freq-cutoff SchwarzISCO --sample-rate 4096 --high-frequency-cutoff 2048.0 --resample-filter ldas --strain-high-pass-atten 0.1 --strain-high-pass-freq 30 --max-total-mass 25.0 --frame-cache /home/spxiwh/lscsoft_git/src/pycbc/examples/ahope/weekly_ahope/961585543-961671943/datafind/H1-DATAFIND-961585543-86400.lcf --disable-compute-moments  --max-high-freq-cutoff SchwarzISCO --approximant TaylorF2 --write-compress  --minimum-mass 1.0 --order twoPN --spectrum-type median

pycbc_geom_nonspinbank

pycbc_geom_nonspinbank is pycbc’s non-spinning template bank generator. Designed as a replacement and improvement of lalapps_tmpltbank. See PyCBC template bank generation documentation (pycbc.tmpltbank) for documentation of this code. The help message of pycbc_geom_nonspinbank 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,aLIGOAPlusDesignSensitivityT1800042,aLIGOAdVO3LowT1800545,aLIGOAdVO4IntermediateT1800545,aLIGOAdVO4T1800545,aLIGOBHBH20Deg,aLIGOBHBH20DegGWINC,aLIGOBNSOptimizedSensitivityP1200087,aLIGODesignSensitivityP1200087,aLIGOEarlyHighSensitivityP1200087,aLIGOEarlyLowSensitivityP1200087,aLIGOHighFrequency,aLIGOHighFrequencyGWINC,aLIGOKAGRA128MpcT1800545,aLIGOKAGRA25MpcT1800545,aLIGOKAGRA80MpcT1800545,aLIGOLateHighSensitivityP1200087,aLIGOLateLowSensitivityP1200087,aLIGOMidHighSensitivityP1200087,aLIGOMidLowSensitivityP1200087,aLIGONSNSOpt,aLIGONSNSOptGWINC,aLIGONoSRMHighPower,aLIGONoSRMLowPower,aLIGONoSRMLowPowerGWINC,aLIGOQuantumBHBH20Deg,aLIGOQuantumHighFrequency,aLIGOQuantumNSNSOpt,aLIGOQuantumNoSRMHighPower,aLIGOQuantumNoSRMLowPower,aLIGOQuantumZeroDetHighPower,aLIGOQuantumZeroDetLowPower,aLIGOThermal,aLIGOZeroDetHighPower,aLIGOZeroDetHighPowerGWINC,aLIGOZeroDetLowPower,aLIGOZeroDetLowPowerGWINC,aLIGOaLIGO140MpcT1800545,aLIGOaLIGO175MpcT1800545,aLIGOaLIGODesignSensitivityT1800044,aLIGOaLIGOO3LowT1800545,eLIGOModel,eLIGOShot,iLIGOModel,iLIGOSRD,iLIGOSeismic,iLIGOShot,iLIGOThermal,flat_unity}]
                              [--psd-file PSD_FILE] [--asd-file ASD_FILE]
                              [--psd-inverse-length PSD_INVERSE_LENGTH]
                              [--psd-file-xml-ifo-string PSD_FILE_XML_IFO_STRING]
                              [--psd-file-xml-root-name PSD_FILE_XML_ROOT_NAME]
                              [--psdvar-segment SECONDS]
                              [--psdvar-short-segment SECONDS]
                              [--psdvar-long-segment SECONDS]
                              [--psdvar-psd-duration SECONDS]
                              [--psdvar-psd-stride 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 ...]]
                              [--hdf-store HDF_STORE]
                              [--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,aLIGOAPlusDesignSensitivityT1800042,aLIGOAdVO3LowT1800545,aLIGOAdVO4IntermediateT1800545,aLIGOAdVO4T1800545,aLIGOBHBH20Deg,aLIGOBHBH20DegGWINC,aLIGOBNSOptimizedSensitivityP1200087,aLIGODesignSensitivityP1200087,aLIGOEarlyHighSensitivityP1200087,aLIGOEarlyLowSensitivityP1200087,aLIGOHighFrequency,aLIGOHighFrequencyGWINC,aLIGOKAGRA128MpcT1800545,aLIGOKAGRA25MpcT1800545,aLIGOKAGRA80MpcT1800545,aLIGOLateHighSensitivityP1200087,aLIGOLateLowSensitivityP1200087,aLIGOMidHighSensitivityP1200087,aLIGOMidLowSensitivityP1200087,aLIGONSNSOpt,aLIGONSNSOptGWINC,aLIGONoSRMHighPower,aLIGONoSRMLowPower,aLIGONoSRMLowPowerGWINC,aLIGOQuantumBHBH20Deg,aLIGOQuantumHighFrequency,aLIGOQuantumNSNSOpt,aLIGOQuantumNoSRMHighPower,aLIGOQuantumNoSRMLowPower,aLIGOQuantumZeroDetHighPower,aLIGOQuantumZeroDetLowPower,aLIGOThermal,aLIGOZeroDetHighPower,aLIGOZeroDetHighPowerGWINC,aLIGOZeroDetLowPower,aLIGOZeroDetLowPowerGWINC,aLIGOaLIGO140MpcT1800545,aLIGOaLIGO175MpcT1800545,aLIGOaLIGODesignSensitivityT1800044,aLIGOaLIGOO3LowT1800545,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]
                              [--injection-scale-factor INJECTION_SCALE_FACTOR]
                              [--injection-f-ref INJECTION_F_REF]
                              [--injection-f-final INJECTION_F_FINAL]
                              [--gating-file GATING_FILE]
                              [--autogating-threshold SIGMA]
                              [--autogating-max-iterations 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 {zeroPN,onePN,onePointFivePN,twoPN,twoPointFivePN,threePN,threePointFivePN}]
                              [--filter-cutoff {SchwarzISCO,LightRing,ERD,BKLISCO,FRD,LRD,MECO,HybridMECO,IMRPhenomBFinal,IMRPhenomCFinal,IMRPhenomDPeak,EOBNRv2RD,EOBNRv2HMRD,SEOBNRv1RD,SEOBNRv1Peak,SEOBNRv2RD,SEOBNRv2Peak,SEOBNRv4RD,SEOBNRv4Peak}]
                              [--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,aLIGOAPlusDesignSensitivityT1800042,aLIGOAdVO3LowT1800545,aLIGOAdVO4IntermediateT1800545,aLIGOAdVO4T1800545,aLIGOBHBH20Deg,aLIGOBHBH20DegGWINC,aLIGOBNSOptimizedSensitivityP1200087,aLIGODesignSensitivityP1200087,aLIGOEarlyHighSensitivityP1200087,aLIGOEarlyLowSensitivityP1200087,aLIGOHighFrequency,aLIGOHighFrequencyGWINC,aLIGOKAGRA128MpcT1800545,aLIGOKAGRA25MpcT1800545,aLIGOKAGRA80MpcT1800545,aLIGOLateHighSensitivityP1200087,aLIGOLateLowSensitivityP1200087,aLIGOMidHighSensitivityP1200087,aLIGOMidLowSensitivityP1200087,aLIGONSNSOpt,aLIGONSNSOptGWINC,aLIGONoSRMHighPower,aLIGONoSRMLowPower,aLIGONoSRMLowPowerGWINC,aLIGOQuantumBHBH20Deg,aLIGOQuantumHighFrequency,aLIGOQuantumNSNSOpt,aLIGOQuantumNoSRMHighPower,aLIGOQuantumNoSRMLowPower,aLIGOQuantumZeroDetHighPower,aLIGOQuantumZeroDetLowPower,aLIGOThermal,aLIGOZeroDetHighPower,aLIGOZeroDetHighPowerGWINC,aLIGOZeroDetLowPower,aLIGOZeroDetLowPowerGWINC,aLIGOaLIGO140MpcT1800545,aLIGOaLIGO175MpcT1800545,aLIGOaLIGODesignSensitivityT1800044,aLIGOaLIGOO3LowT1800545,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)
  --psd-file-xml-ifo-string PSD_FILE_XML_IFO_STRING
                        If using an XML PSD file, use the PSD in the file's
                        PSD dictionary with this ifo string. If not given and
                        only one PSD present in the file return that, if not
                        given and multiple (or zero) PSDs present an exception
                        will be raised. (default: None)
  --psd-file-xml-root-name PSD_FILE_XML_ROOT_NAME
                        If given use this as the root name for the PSD XML
                        file. If this means nothing to you, then it is
                        probably safe to ignore this option. (default: psd)
  --psdvar-segment SECONDS
                        Length of segment for mean square calculation of PSD
                        variation. (default: None)
  --psdvar-short-segment SECONDS
                        Length of short segment for outliers removal in PSD
                        variability calculation. (default: None)
  --psdvar-long-segment SECONDS
                        Length of long segment when calculating the PSD
                        variability. (default: None)
  --psdvar-psd-duration SECONDS
                        Duration of short segments for PSD estimation.
                        (default: None)
  --psdvar-psd-stride SECONDS
                        Separation between PSD estimation segments. (default:
                        None)
  --psdvar-low-freq HERTZ
                        Minimum frequency to consider in strain bandpass.
                        (default: None)
  --psdvar-high-freq HERTZ
                        Maximum frequency to consider in strain bandpass.
                        (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: 8)
  --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)
  --hdf-store HDF_STORE
                        Store of time series data in hdf format (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,aLIGOAPlusDesignSensitivityT1800042,aLIGOAdVO3LowT1800545,aLIGOAdVO4IntermediateT1800545,aLIGOAdVO4T1800545,aLIGOBHBH20Deg,aLIGOBHBH20DegGWINC,aLIGOBNSOptimizedSensitivityP1200087,aLIGODesignSensitivityP1200087,aLIGOEarlyHighSensitivityP1200087,aLIGOEarlyLowSensitivityP1200087,aLIGOHighFrequency,aLIGOHighFrequencyGWINC,aLIGOKAGRA128MpcT1800545,aLIGOKAGRA25MpcT1800545,aLIGOKAGRA80MpcT1800545,aLIGOLateHighSensitivityP1200087,aLIGOLateLowSensitivityP1200087,aLIGOMidHighSensitivityP1200087,aLIGOMidLowSensitivityP1200087,aLIGONSNSOpt,aLIGONSNSOptGWINC,aLIGONoSRMHighPower,aLIGONoSRMLowPower,aLIGONoSRMLowPowerGWINC,aLIGOQuantumBHBH20Deg,aLIGOQuantumHighFrequency,aLIGOQuantumNSNSOpt,aLIGOQuantumNoSRMHighPower,aLIGOQuantumNoSRMLowPower,aLIGOQuantumZeroDetHighPower,aLIGOQuantumZeroDetLowPower,aLIGOThermal,aLIGOZeroDetHighPower,aLIGOZeroDetHighPowerGWINC,aLIGOZeroDetLowPower,aLIGOZeroDetLowPowerGWINC,aLIGOaLIGO140MpcT1800545,aLIGOaLIGO175MpcT1800545,aLIGOaLIGODesignSensitivityT1800044,aLIGOaLIGOO3LowT1800545,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)
  --injection-scale-factor INJECTION_SCALE_FACTOR
                        Divide injections by this factor before injecting into
                        the data. (default: 1)
  --injection-f-ref INJECTION_F_REF
                        Reference frequency in Hz for creating CBC injections
                        from an XML file. (default: None)
  --injection-f-final INJECTION_F_FINAL
                        Override the f_final field of a CBC XML injection
                        file. (default: None)
  --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-max-iterations SIGMA
                        If given, iteratively apply autogating (default: 1)
  --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 the
                        witness 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 {zeroPN,onePN,onePointFivePN,twoPN,twoPointFivePN,threePN,threePointFivePN}
                        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 {SchwarzISCO,LightRing,ERD,BKLISCO,FRD,LRD,MECO,HybridMECO,IMRPhenomBFinal,IMRPhenomCFinal,IMRPhenomDPeak,EOBNRv2RD,EOBNRv2HMRD,SEOBNRv1RD,SEOBNRv1Peak,SEOBNRv2RD,SEOBNRv2Peak,SEOBNRv4RD,SEOBNRv4Peak}
                        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)

Of these options the workflow module will automatically add the following, which are unique fo r each job. DO NOT ADD THESE OPTIONS IN THE CONFIGURATION FILE.

  • –gps-start-time
  • –gps-end-time
  • –frame-cache
  • –output-file

All other options must be provided in the configuration file. Here is an example of a pycbc_geom_nonspinbank call.

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 --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

pycbc.workflow.tmpltbank Module

This is complete documentation of this module’s code

This module is responsible for setting up the template bank stage of CBC workflows. For details about this module and its capabilities see here: https://ldas-jobs.ligo.caltech.edu/~cbc/docs/pycbc/ahope/template_bank.html

pycbc.workflow.tmpltbank.setup_tmpltbank_dax_generated(workflow, science_segs, datafind_outs, output_dir, tags=None, link_to_matchedfltr=True, compatibility_mode=False, psd_files=None)[source]

Setup template bank jobs that are generated as part of the CBC workflow. This function will add numerous jobs to the CBC workflow using configuration options from the .ini file. The following executables are currently supported:

  • lalapps_tmpltbank
  • pycbc_geom_nonspin_bank
Parameters:
  • workflow (pycbc.workflow.core.Workflow) – An instanced class that manages the constructed workflow.
  • science_segs (Keyed dictionary of glue.segmentlist objects) – scienceSegs[ifo] holds the science segments to be analysed for each ifo.
  • datafind_outs (pycbc.workflow.core.FileList) – The file list containing the datafind files.
  • output_dir (path string) – The directory where data products will be placed.
  • tags (list of strings) – If given these tags are used to uniquely name and identify output files that would be produced in multiple calls to this function.
  • link_to_matchedfltr (boolean, optional (default=True)) – If this option is given, the job valid_times will be altered so that there will be one inspiral file for every template bank and they will cover the same time span. Note that this option must also be given during matched-filter generation to be meaningful.
  • psd_file (pycbc.workflow.core.FileList) – The file list containing predefined PSDs, if provided.
Returns:

tmplt_banks – The FileList holding the details of all the template bank jobs.

Return type:

pycbc.workflow.core.FileList

pycbc.workflow.tmpltbank.setup_tmpltbank_pregenerated(workflow, tags=None)[source]

Setup CBC workflow to use a pregenerated template bank. The bank given in cp.get(‘workflow’,’pregenerated-template-bank’) will be used as the input file for all matched-filtering jobs. If this option is present, workflow will assume that it should be used and not generate template banks within the workflow.

Parameters:
  • workflow (pycbc.workflow.core.Workflow) – An instanced class that manages the constructed workflow.
  • tags (list of strings) – If given these tags are used to uniquely name and identify output files that would be produced in multiple calls to this function.
Returns:

tmplt_banks – The FileList holding the details of the template bank.

Return type:

pycbc.workflow.core.FileList

pycbc.workflow.tmpltbank.setup_tmpltbank_without_frames(workflow, output_dir, tags=None, independent_ifos=False, psd_files=None)[source]

Setup CBC workflow to use a template bank (or banks) that are generated in the workflow, but do not use the data to estimate a PSD, and therefore do not vary over the duration of the workflow. This can either generate one bank that is valid for all ifos at all times, or multiple banks that are valid only for a single ifo at all times (one bank per ifo).

Parameters:
  • workflow (pycbc.workflow.core.Workflow) – An instanced class that manages the constructed workflow.
  • output_dir (path string) – The directory where the template bank outputs will be placed.
  • tags (list of strings) – If given these tags are used to uniquely name and identify output files that would be produced in multiple calls to this function.
  • independent_ifos (Boolean, optional (default=False)) – If given this will produce one template bank per ifo. If not given there will be on template bank to cover all ifos.
  • psd_file (pycbc.workflow.core.FileList) – The file list containing predefined PSDs, if provided.
Returns:

tmplt_banks – The FileList holding the details of the template bank(s).

Return type:

pycbc.workflow.core.FileList

pycbc.workflow.tmpltbank.setup_tmpltbank_workflow(workflow, science_segs, datafind_outs, output_dir=None, psd_files=None, tags=None, return_format=None)[source]

Setup template bank section of CBC workflow. This function is responsible for deciding which of the various template bank workflow generation utilities should be used.

Parameters:
  • workflow (pycbc.workflow.core.Workflow) – An instanced class that manages the constructed workflow.
  • science_segs (Keyed dictionary of glue.segmentlist objects) – scienceSegs[ifo] holds the science segments to be analysed for each ifo.
  • datafind_outs (pycbc.workflow.core.FileList) – The file list containing the datafind files.
  • output_dir (path string) – The directory where data products will be placed.
  • psd_files (pycbc.workflow.core.FileList) – The file list containing predefined PSDs, if provided.
  • tags (list of strings) – If given these tags are used to uniquely name and identify output files that would be produced in multiple calls to this function.
Returns:

tmplt_banks – The FileList holding the details of all the template bank jobs.

Return type:

pycbc.workflow.core.FileList