The workflow injection generation module

Introduction

The injection generation module of pycbc’s workflow is responsible for generating or gathering the injection files that will be used to assess the performance of a pipeline to detect simulated signals. This can be run either by generating injection files at run time, by generating injection files within the workflow or by using pregenerated injection files.

The return of the injection generation module is a FileList of the injection files generated/supplied to this module. It is possible to call this module multiple times by using the tags key-word argument, but we have not foreseen a case where this would be needed.

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 the injection files (described below).
An initialized instance of the pycbc Workflow class, containing the ConfigParser.

The module is then called according to

pycbc.workflow.setup_injection_workflow(workflow, output_dir=None, inj_section_name='injections', tags=None)[source]

This function is the gateway for setting up injection-generation jobs in a workflow. It should be possible for this function to support a number of different ways/codes that could be used for doing this, however as this will presumably stay as a single call to a single code (which need not be inspinj) there are currently no subfunctions in this moudle.

Parameters:

workflow (pycbc.workflow.core.Workflow) – The Workflow instance that the coincidence jobs will be added to.
output_dir (path) – The directory in which injection files will be stored.
inj_section_name (string (optional, default='injections')) – The string that corresponds to the option describing the exe location in the [executables] section of the .ini file and that corresponds to the section (and sub-sections) giving the options that will be given to the code at run time.
tags (list of strings (optional, default = [])) – A list of the tagging strings that will be used for all jobs created by this call to the workflow. This will be used in output names.

Returns:

inj_files (pycbc.workflow.core.FileList) – The list of injection files created by this call.
inj_tags (list of strings) – The tag corresponding to each injection file and used to uniquely identify them. The FileList class contains functions to search based on tags.

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-injections] section

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

injections-method = VALUE

The choices here and their description are as described below

IN_WORKFLOW - The injection file generation will be added as jobs in the workflow and will be generated after submission of the workflow.
AT_RUNTIME - The injection jobs will be run directly within this module.
PREGENERATED - The injection files will be supplied as pregenerated files.

When using IN_WORKFLOW or AT_RUNTIME no additional options are required in the [workflow-injections] section.

When using PREGENERATED the additional option is needed:

injections-pregenerated-file = PATH - Specifies the location of the pregenerated injection file.

[executables]

PLEASE READ THIS EVEN IF USING method=PREGENERATED

In this section, if not using PREGENERATED, you need to supply the executable that will be used to generate the injection files. This is done in the [executables] section by adding something like:

injections = /path/to/lalapps_inspinj

The option, in this case ‘injections’, will be used to specify the constant command line options that are sent to all lalapps_inspinj jobs. The tag ‘injections’ can be changed, it is currently supplied as a key-word argument when calling the function. ‘injections’ is the default, and must be used if you want to use pipedown.

IMPORTANT this injSectionName tag, “injections” by default, is used to identify which injections are to be performed. The module will search for modules called [injections-XXXX] and generate one injection file for every sub-section using XXXX as a tag.

When using IN_WORKFLOW option, value pairs in [injections-XXXX] are also used to specify options specific to that particular injection set. These options will be directly supplied to the executable being used to generate the file.

PLEASE NOTE: When using PREGENERATED the injection names are still identified by looking in the “injections-XXXX” sections (a path in [executables] is not needed). These sections will be empty in this case. Also note that as XXXX is used as a tag you can use [workflow-injections-XXXX] section to supply unique pregenerated injection files.

Supported injection executables and instructions for using them

The following injection generation executables are currently supported

lalapps_inspinj

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.

lalapps_inspinj

lalapps_inspinj is the legacy C-code that has been used to generate injection files for gravitational-wave data analysis since the dawn of time. Documentation and command line options can be found at http://software.ligo.org/docs/lalsuite/lalapps/inspinj_8c.html

Of these options the workflow will automatically add the following. DO NOT ADD THESE OPTIONS IN THE CONFIGURATION FILE.

–gps-start-time
–gps-end-time
–output

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

lalapps_inspinj --gps-end-time 961671943 --i-distr uniform --max-mass1 3.1 --max-mass2 3.1 --m-distr componentMass --disable-spin  --min-mtotal 2.0 --output /home/spxiwh/lscsoft_git/src/pycbc/examples/ahope/weekly_ahope/961585543-961671943/inj_files/HL-INJECTIONS_BNSLININJ_2134-961585543-86400.xml --max-mtotal 6.2 --waveform TaylorT4threePointFivePN --time-interval 300 --time-step 837.155 --min-mass2 1.0 --f-lower 30 --l-distr random --min-mass1 1.0 --min-distance 1000 --gps-start-time 961585543 --d-distr uniform --max-distance 60000

`pycbc.workflow.injection` Module

This is complete documentation of this module’s code

This module is responsible for setting up the part of a pycbc workflow that will generate the injection files to be used for assessing the workflow’s ability to detect predicted signals. Full documentation for this module can be found here: https://ldas-jobs.ligo.caltech.edu/~cbc/docs/pycbc/NOTYETCREATED.html

class pycbc.workflow.injection.PyCBCMergeHDFExecutable(cp, name, ifos=None, out_dir=None, tags=None, reuse_executable=True, set_submit_subdir=True)[source]

Bases: Executable

Merge HDF injection files executable class

create_node(workflow, input_files)[source]

Default node constructor.

This is usually overridden by subclasses of Executable.

current_retention_level = 3

class pycbc.workflow.injection.PyCBCOptimalSNRExecutable(cp, name, ifos=None, out_dir=None, tags=None, reuse_executable=True, set_submit_subdir=True)[source]

Bases: Executable

Compute optimal SNR for injections

create_node(workflow, inj_file, precalc_psd_files, group_str)[source]