Job Control¶

Pipeline: data → [jobs & segments] ← you are here → conditioning → WDM → pixels → clusters → likelihood → events → bkg → ranking → eff

This guide explains how pycWB defines and manages analysis jobs, including the lag/slag structure, trial indexing, segment construction from data-quality files, and parallelization strategies.

Why this matters ¶

Job control determines how your search is split across computing resources. Understanding segments, lags, and trials is essential for debugging failed jobs, estimating runtime, and optimizing cluster utilization. If jobs are failing or your run takes too long, this is the page to read.

Job Decomposition ¶

Overview ¶

A pycWB analysis run is decomposed into job segments—independent units of work that can be distributed across cluster nodes. Each job segment is a GPS time window containing detector data, processed across multiple lags (time-shift hypotheses) and optionally trials (injection groups).

The job structure is built by pycwb.modules.job_segment.job_segment.create_job_segment_from_config(), which reads the user parameter YAML and produces a list of WaveSegment objects.

Job Segment Construction ¶

pycWB supports five modes for defining job segment time windows:

Pure Simulation — no real data; segments defined solely by injection times. Used for waveform injection studies with synthetic noise.
gps_start / gps_end — a single explicit time interval:
```
gps_start: 1264060000
gps_end: 1264063600
```

gps_center + time_left/time_right — a centered window:

gps_center: 1264060000
time_left: 500
time_right: 500

superevent + time_left/time_right — queries GraceDB for the GPS time of a superevent (e.g., S190521g) and builds a window around it.
DQ Files — builds segments from science-quality data flags. This is the standard mode for production searches:
```
DQ_CAT1: input/H1_cat1.txt     # CAT1 veto segments
DQ_CAT2: input/H1_cat2.txt     # CAT2 veto segments (applied as windows)
DQ_CAT0: input/H1_cat0.txt     # Science-mode segments (CAT0)
```
The segment-building algorithm:
1. Read CAT1 segments and remove them from science time.
2. Merge remaining science segments that are separated by less than segTHR seconds.
3. Keep segments longer than segMLS seconds.
4. Apply CAT2 veto windows (not segments) around each veto edge.
5. Split long segments into chunks of segLen seconds with segOverlap overlap.
6. Add segEdge seconds of padding on each side for wavelet boundary effects.

Segment Sizing Parameters ¶

Parameter	Default	Description
`segLen`	600 s	Nominal segment (job) length
`segMLS`	300 s	Minimum segment length after CAT1 veto
`segTHR`	30 s	Minimum separation after CAT2 veto
`segEdge`	8 s	Wavelet boundary padding on each side
`segOverlap`	0 s	Overlap between consecutive job segments

Lag Structure ¶

Lags implement the time-shift analysis used to estimate the background (accidental coincidence rate). For an \(N\)-detector network, time-shifting one detector’s data relative to the others breaks any real gravitational-wave coincidence.

Regular Lags ¶

lagSize: 100       # Number of lags to generate
lagStep: 1.0       # Time step between lags [s]
lagOff: 6          # Offset: first N lags are skipped (0 = include zero-lag)
lagMax: 150        # Maximum time shift [s]

Lags are generated as:

\[\text{lag}[i] = (\text{lagOff} + i) \times \text{lagStep}, \quad i = 0, 1, \dots, \text{lagSize} - 1\]

subject to \(\text{lag}[i] \leq \text{lagMax}\).

Zero-lag (\(i\) such that \(\text{lagOff} + i = 0\)) represents the physical (unshifted) coincidence—where a real GW signal would appear.
Non-zero lags are used for background estimation.

You can also provide an explicit lag array or lag file:

lagMode: r                    # "r" = read from file, "w" = write to file
lagFile: input/lags.txt       # Path to lag list file
lagSite: 0                    # Site index for time-shift reference

When lagMode is r, lags are read from lagFile. When w, lags are written to lagFile for inspection or sharing.

Super Lags (Segments)¶

Super lags (slang) provide an additional layer of time shifts at the segment level, used for multi-detector networks:

slagSize: 10       # Number of super lags
slagMin: -5.0      # Minimum super lag [s]
slagMax: 5.0       # Maximum super lag [s]
slagOff: 0         # Super lag offset [s]

Super lags are generated as linearly spaced offsets between slagMin and slagMax or as explicit step/offset combinations.

Each super lag produces a new “shifted” version of the job segment, increasing the total number of analysis units by a factor of slagSize.

Trial Indexing ¶

For simulation (injection) studies, each job segment can contain multiple trials—groups of injections that share the same noise background:

\[\text{total\_jobs} = N_{segments} \times N_{slags} \times N_{trials}\]

trial_idx: identifies which trial an injection belongs to within a job segment.
sim_idx: unique identifier for each injection across all trials and jobs.
job_id: unique identifier for each analysis job (segment × slag × trial combination).

When parallel_injection_trail is enabled, job segments are flattened by trial via flatten_job_segments_by_trial(), so each trial becomes a separate job with a contiguous job_id. This enables trivial parallelization across trials.

Job Directory Structure ¶

Each job creates this directory layout:

<workdir>/
├── output/           # Waveform and trigger output files
├── log/              # Job log files
├── config/           # Copy of user_parameters.yaml
├── catalog/          # Parquet trigger catalogs
│   ├── catalog.parquet
│   └── progress.parquet
├── trigger/          # Per-event JSON trigger files
├── job_status/       # Job completion status files
├── public/           # Public-facing results
└── input/            # DQ files, frame lists, etc.

Frame File Selection ¶

Frame files (containing detector strain data) are selected in two ways:

Explicit file list via the frFiles parameter:

frFiles:
  - /path/to/H-H1_GWOSC-1264060000-4096.gwf
  - /path/to/L-L1_GWOSC-1264060000-4096.gwf

gwdatafind query via the gwdatafind config block:
```
gwdatafind:
  site: H1
  frametype: H1_GWOSC_O4_C01_4KHZ_R1
  host: datafind.ligo.org
```
This automatically queries the LIGO data-find server for frames covering each job segment’s time window.

Parallelization ¶

Jobs are parallelized at two levels:

Across lags — multiple lags within a segment can be processed concurrently (controlled by parallel_lag_workers, default 1).
Across segments — different job segments are independent and can run on different cluster nodes (see Run on Clusters).

For SLURM/HTCondor batch submission, jobs are bundled into workers via job_per_worker to balance scheduling overhead against parallelism.

Progress Tracking ¶

Each job writes a progress.parquet file containing per-lag processing status (start time, end time, success/failure, number of triggers). The pycwb progress CLI command summarizes this information:

pycwb progress --work-dir /path/to/run

Next: Injection Infrastructure — how to configure simulated signals