gstlal_inspiral =============== A program to analyze gravitational wave data for compact binary coalescence in real time or in an offline mode .. graphviz:: digraph llpipe { labeljust = "r"; label="gstlal_inspiral" rankdir=LR; graph [fontname="Roman", fontsize=24]; edge [ fontname="Roman", fontsize=10 ]; node [fontname="Roman", shape=box, fontsize=11]; gracedb [label="GW\nCandidate\nDatabase", shape=oval, color=tomato3, style=filled]; subgraph clusterNodeN { style=rounded; label="gstreamer pipeline"; labeljust = "r"; fontsize = 14; H1src [label="H1 data source:\n mkbasicsrc()", color=red4]; L1src [label="L1 data source:\n mkbasicsrc()", color=green4]; V1src [label="V1 data source:\n mkbasicsrc()", color=magenta4]; H1multirate [label="H1 whitening and downsampling:\nmkwhitened_multirate_src()", color=red4]; L1multirate [label="L1 whitening and downsampling:\nmkwhitened_multirate_src()", color=green4]; V1multirate [label="V1 whitening and downsampling:\nmkwhitened_multirate_src()", color=magenta4]; H1LLOID [label="H1 LLOID filtering engine:\nmkLLOIDmulti()", color=red4]; L1LLOID [label="L1 LLOID filtering engine:\nmkLLOIDmulti()", color=green4]; V1LLOID [label="V1 LLOID filtering engine:\nmkLLOIDmulti()", color=magenta4]; H1Trig1 [label="H1 Triggering:\nsub bank 1", color=red4]; L1Trig1 [label="L1 Triggering:\nsub bank 1", color=green4]; V1Trig1 [label="V1 Triggering:\nsub bank 1", color=magenta4]; H1Trig2 [label="H1 Triggering:\nsub bank 2", color=red4]; L1Trig2 [label="L1 Triggering:\nsub bank 2", color=green4]; V1Trig2 [label="V1 Triggering:\nsub bank 2", color=magenta4]; H1TrigN [label="H1 Triggering:\nsub bank N", color=red4]; L1TrigN [label="L1 Triggering:\nsub bank N", color=green4]; V1TrigN [label="V1 Triggering:\nsub bank N", color=magenta4]; H1src -> H1multirate; L1src -> L1multirate; V1src -> V1multirate; H1multirate -> H1LLOID [label="h(t) 4096Hz"]; L1multirate -> L1LLOID [label="h(t) 4096Hz"]; V1multirate -> V1LLOID [label="h(t) 4096Hz"]; H1multirate -> H1LLOID [label="h(t) 2048Hz"]; L1multirate -> L1LLOID [label="h(t) 2048Hz"]; V1multirate -> V1LLOID [label="h(t) 2048Hz"]; H1multirate -> H1LLOID [label="h(t) Nth-pow-of-2 Hz"]; L1multirate -> L1LLOID [label="h(t) Nth-pow-of-2 Hz"]; V1multirate -> V1LLOID [label="h(t) Nth-pow-of-2 Hz"]; H1LLOID -> H1Trig1 [label="SNRs sub bank 1"]; L1LLOID -> L1Trig1 [label="SNRs sub bank 1"]; V1LLOID -> V1Trig1 [label="SNRs sub bank 1"]; H1LLOID -> H1Trig2 [label="SNRs sub bank 2"]; L1LLOID -> L1Trig2 [label="SNRs sub bank 2"]; V1LLOID -> V1Trig2 [label="SNRs sub bank 2"]; H1LLOID -> H1TrigN [label="SNRs sub bank N"]; L1LLOID -> L1TrigN [label="SNRs sub bank N"]; V1LLOID -> V1TrigN [label="SNRs sub bank N"]; } Coincidence [label="Coincidence\nO(1)s latency"]; SigEst [label="Significance\nEstimation\nO(1)s latency"]; Thresh [label="Thresholding\nO(1)s latency"]; EventGen [label="Event\nGeneration\nO(1)s latency"]; H1Trig1 -> Coincidence [label="Trigs sub bank 1"]; L1Trig1 -> Coincidence [label="Trigs sub bank 1"]; V1Trig1 -> Coincidence [label="Trigs sub bank 1"]; H1Trig2 -> Coincidence [label="Trigs sub bank 2"]; L1Trig2 -> Coincidence [label="Trigs sub bank 2"]; V1Trig2 -> Coincidence [label="Trigs sub bank 2"]; H1TrigN -> Coincidence [label="Trigs sub bank N"]; L1TrigN -> Coincidence [label="Trigs sub bank N"]; V1TrigN -> Coincidence [label="Trigs sub bank N"]; Coincidence -> SigEst -> Thresh -> EventGen; EventGen -> gracedb; } Review Status ------------- +------------------------------------------------+---------------------------------------------+------------+ | Names | Hash | Date | +================================================+=============================================+============+ | Florent, Sathya, Duncan Me, Jolien, Kipp, Chad | 9074294d6b57f43651143b5f93210751de1fe55a | 2014-05-02 | +------------------------------------------------+---------------------------------------------+------------+ Command line options -------------------- .. code-block:: none Usage: gstlal_inspiral [options] Stream-based inspiral analysis tool Options: -h, --help show this help message and exit Data source options: Use these options to set up the appropriate data source --data-source=source Set the data source from [frames|framexmit|lvshm|nds|silence|white]. Required. --block-size=bytes Data block size to read in bytes. Default 16384 * 8 * 512 (512 seconds of double precision data at 16384 Hz. This parameter is only used if --data-source is one of white, silence, AdvVirgo, LIGO, AdvLIGO, nds. --frame-cache=filename Set the name of the LAL cache listing the LIGO-Virgo .gwf frame files (optional). --frame-type=name Set the frame type for a given instrument. Can be given multiple times as --frame-type=IFO=FRAME-TYPE. Used with --data-source=frames --data-find-server=url Set the data find server for LIGO data discovery. Used with --data-source=frames --gps-start-time=seconds Set the start time of the segment to analyze in GPS seconds. Required unless --data-source=lvshm --gps-end-time=seconds Set the end time of the segment to analyze in GPS seconds. Required unless --data-source=lvshm --injection-file=filename Set the name of the LIGO light-weight XML file from which to load injections (optional). --channel-name=name Set the name of the channels to process. Can be given multiple times as --channel-name=IFO=CHANNEL-NAME --idq-channel-name=idqname iDQ channel names to process. Must also provide idq- state-channel-name. Can be given multiple times as --idq-channel-name=IFO=IDQ-CHANNEL-NAME --idq-state-channel-name=idqstatename iDQ state channel names to process. Can be given multiple times as --idq-state-channel-name=IFO=IDQ- STATE-CHANNEL-NAME --nds-host=hostname Set the remote host or IP address that serves nds data. This is required iff --data-source=nds --nds-port=portnumber Set the port of the remote host that serves nds data. This is required iff --data-source=nds --nds-channel-type=type Set the port of the remote host that serves nds data. This is required only if --data-source=nds. default==online --framexmit-addr=name Set the address of the framexmit service. Can be given multiple times as --framexmit- addr=IFO=xxx.xxx.xxx.xxx:port --framexmit-iface=name Set the multicast interface address of the framexmit service. --state-channel-name=name Set the name of the state vector channel. This channel will be used to control the flow of data via the on/off bits. Can be given multiple times as --channel-name=IFO=CHANNEL-NAME --dq-channel-name=name Set the name of the data quality channel. This channel will be used to control the flow of data via the on/off bits. Can be given multiple times as --channel-name=IFO=CHANNEL-NAME --shared-memory-partition=name Set the name of the shared memory partition for a given instrument. Can be given multiple times as --shared-memory-partition=IFO=PARTITION-NAME --shared-memory-dir=name Set the name of the shared memory directory for a given instrument. Can be given multiple times as --shared-memory-dir=IFO=DIR-NAME --shared-memory-assumed-duration=SHARED_MEMORY_ASSUMED_DURATION Set the assumed span of files in seconds. Default = 4. --shared-memory-block-size=SHARED_MEMORY_BLOCK_SIZE Set the byte size to read per buffer. Default = 4096. --frame-segments-file=filename Set the name of the LIGO light-weight XML file from which to load frame segments. Optional iff --data- source=frames --frame-segments-name=name Set the name of the segments to extract from the segment tables. Required iff --frame-segments-file is given --state-vector-on-bits=bits Set the state vector on bits to process (optional). The default is 0x7 for all detectors. Override with IFO=bits can be given multiple times. Only currently has meaning for online (lvshm) data. --state-vector-off-bits=bits Set the state vector off bits to process (optional). The default is 0x160 for all detectors. Override with IFO=bits can be given multiple times. Only currently has meaning for online (lvshm) data. --dq-vector-on-bits=bits Set the DQ vector on bits to process (optional). The default is 0x7 for all detectors. Override with IFO=bits can be given multiple times. Only currently has meaning for online (lvshm) data. --dq-vector-off-bits=bits Set the DQ vector off bits to process (optional). The default is 0x160 for all detectors. Override with IFO=bits can be given multiple times. Only currently has meaning for online (lvshm) data. PSD Options: Adjust noise spectrum estimation parameters --psd-fft-length=seconds The length of the FFT used to used to whiten the data (default is 32 s). --reference-psd=filename Instead of measuring the noise spectrum, load the spectrum from this LIGO light-weight XML file (optional). --track-psd Enable dynamic PSD tracking. Always enabled if --reference-psd is not given. Data Qualtiy: Adjust data quality handling --ht-gate-threshold=sigma Set the threshold on whitened h(t) to excise a glitches in units of standard deviations (optional). If given, exactly as many h(t) thresholds must be set as svd-bank files will be processed (see --svd-bank). --idq-gate-threshold=IDQ_GATE_THRESHOLD Set the threshold on idq to excise glitches from whitened h(t) (optional). --veto-segments-file=filename Set the name of the LIGO light-weight XML file from which to load vetoes (optional). --veto-segments-name=name Set the name of the segments to extract from the segment tables and use as the veto list. Trigger Generator: Adjust trigger generator behaviour --control-peak-time=seconds Set a time window in seconds to find peaks in the control signal (optional, default is to disable composite detection statistic). --output=filename Set the name of the LIGO light-weight XML output file *.{xml,xml.gz} or an SQLite database *.sqlite (required). Can be given multiple times. Exactly as many output files must be specified as svd-bank files will be processed (see --svd-bank). --output-cache=filename Provide a cache of output files. This can be used instead of giving multiple --output options. Cannot be combined with --output. --svd-bank=filename Set the name of the LIGO light-weight XML file from which to load the svd bank for a given instrument. To analyze multiple instruments, --svd-bank can be called multiple times for svd banks corresponding to different instruments. If --data-source is lvshm or framexmit, then only svd banks corresponding to a single bin must be given. If given multiple times, the banks will be processed one-by-one, in order. At least one svd bank for at least 2 detectors is required, but see also --svd-bank-cache. --svd-bank-cache=filename Provide a cache file of svd-bank files. This can be used instead of giving multiple --svd-bank options. Cannot be combined with --svd-bank options. --singles-threshold=SNR Set the SNR threshold at which to record single- instrument events in the output (default = +inf, i.e. don't retain singles). Ranking Statistic Options: Adjust ranking statistic behaviour --cap-singles Cap singles to 1 / livetime if computing FAR. No effect otherwise --far-trials-factor=trials Add trials factor to FAR before uploading to gracedb --chisq-type=type Choose the type of chisq computation to perform. Must be one of (autochisq|timeslicechisq). The default is autochisq. --coincidence-threshold=seconds Set the coincidence window in seconds (default = 0.005 s). The light-travel time between instruments will be added automatically in the coincidence test. --min-instruments=count Set the minimum number of instruments that must contribute triggers to form a candidate (default = 2). --ranking-stat-input=url Set the URL from which to load a ranking statistic definition. When this is enabled, signal candidates will have ranking statistic values assigned on-the- fly. Required when --data-source is lvshm or framexmit; must also set --likelihood-snapshot- interval. --ranking-stat-output=filename Set the name of the file to which to write ranking statistic data collected from triggers (optional). Can be given more than once. If given, exactly as many must be provided as there are --svd-bank options and they will be writen to in order. --ranking-stat-output-cache=filename Provide a cache of ranking statistic output files. This can be used instead of giving multiple --ranking- stat-output options. Cannot be combined with --ranking-stat-output. --compress-ranking-stat Choose whether to compress the ranking stat upon start up. Only used when --ranking-stat-input is set. --compress-ranking-stat-threshold=COMPRESS_RANKING_STAT_THRESHOLD Only keep horizon distance values that differ by this much, fractionally, from their neighbours (default = 0.03). --likelihood-snapshot-interval=seconds How often to snapshot candidate and ranking statistic data to disk when running online. --ranking-stat-pdf=url Set the URL from which to load the ranking statistic PDF. This is used to compute false-alarm probabilities and false-alarm rates and is required for online operation (when --data-source is framexmit or lvshm). It is forbidden for offline operation (all other data sources) --time-slide-file=filename Set the name of the xml file to get time slide offsets (required). --zerolag-rankingstat-pdf=url Record a histogram of the likelihood ratio ranking statistic values assigned to zero-lag candidates in this XML file. This is used to construct the extinction model and set the overall false-alarm rate normalization during online running. If it does not exist at start-up, a new file will be initialized, otherwise the counts will be added to the file's contents. Required when --data-source is lvshm or framexmit; optional otherwise. If given, exactly as many must be provided as there are --svd-bank options and they will be used in order. --activation-counts-file=filename Set the name of the h5 file containing activation counts for multicomponent p-astro. GracedB Options: Adjust GracedB interaction --gracedb-far-threshold=Hertz False-alarm rate threshold for gracedb uploads in Hertz (default = do not upload to gracedb). --gracedb-group=name Gracedb group to which to upload events (default is Test). --gracedb-pipeline=name Name of pipeline to provide in GracedB uploads (default is gstlal). --gracedb-search=name Name of search to provide in GracedB uploads (default is LowMass). --gracedb-label=GRACEDB_LABEL Labels to apply to gracedb uploads. Can be applied multiple times. --gracedb-service-url=url Override default GracedB service url (optional, default is https://gracedb.ligo.org/api/). --delay-uploads Choose whether to delay uploads to allow aggregation of events downstream from many gstlal_inspiral jobs (default is False). --upload-time-before-merger If stored in SVD banks, option to upload the time before merger at which each filter terminates in process params table Program Behaviour: --injections Whether to run this as an injection job. In this case, --injection-file may optionally also be specified in order to process injections from disk. --ranking-stat- output must not be specified when --injections is set. --blind-injections=filename Set the name of an injection file that will be added to the data without saving the sim_inspiral_table or otherwise processing the data differently. Has the effect of having hidden signals in the input data. --injections and --injection-file must not be specified in this case --comment=message Set the string to be recorded in comment and tag columns in various places in the output file (optional). --fir-stride=seconds Set the length of the fir filter stride in seconds. default = 8 --analysis-tag=tag Set the string to identify the analysis in which this job is part of. Used when --output-kafka-server is set. May not contain "." nor "-". Default is test. --job-tag=tag Set the string to identify this job and register the resources it provides on a node. Should be 4 digits of the form 0001, 0002, etc.; may not contain "." nor "-". --local-frame-caching Pre-reads frame data, performs downsampling, and stores to local filespace. --nxydump-segment=start:stop Set the time interval to dump from nxydump elments (optional). The default is ":", i.e. dump all time. --reconstruction-segment=start:stop Only reconstruct the SNRs for this time interval (optional). Can be provided multiple times. -t path, --tmp-space=path Path to a directory suitable for use as a work area while manipulating the database file. The database file will be worked on in this directory, and then moved to the final location when complete. This option is intended to improve performance when running in a networked environment, where there might be a local disk with higher bandwidth than is available to the filesystem on which the final output will reside. -v, --verbose Be verbose (optional). --write-pipeline=filename Write a DOT graph description of the as-built pipeline to this file (optional). The environment variable GST_DEBUG_DUMP_DOT_DIR must be set for this option to work. --output-kafka-server=addr Set the server address and port number for output data. Optional, e.g., 10.14.0.112:9092 --disable-service-discovery Disable service discovery. This disables gstlal_inspiral jobs from being able to advertise the location of the services it provides.