Software saturations

The LIGO real-time controls system is a sophisticated collection of control loops designed to hold the arm cavities in resonance, each control loop typically featuring a large number of digital filters. To avoid instability by accidentally actuating too strongly, many of these filter banks are assigned a set of hard limits in the front-end control software. We can keep track of times when those limits are saturated by analyzing the readback channels from filter banks.

The gwdetchar.saturation module provides the following functions:

find_saturations(timeseries[, limit, ...])	Find the times of software saturations of the given TimeSeries
grouper(iterable, n[, fillvalue])	Separate an iterable into sub-sets of n elements
find_limit_channels(channels[, skip])	Find all 'LIMIT' channels that have a matching 'LIMEN' or 'SWSTAT'
is_saturated(channel, cache[, start, end, ...])	Check whether a channel has saturated its software limit

Command-line utility

Note

This utility requires authentication with LIGO.ORG credentials for archived frame data access.

gwdetchar.saturation

The gwdetchar.saturation command-line interface searches (typically several thousand) channels corresponding to control system filter banks, looking for times during which the OUTPUT channels match or exceed the LIMIT value set in control software. The simplest usage is as follows:

python -m gwdetchar.saturation -i `<interferometer>` `<gps-start-time>` `<gps-end-time>`

For example,

python -m gwdetchar.saturation -i L1 1126259442 1126259502

For a full explanation of the available command-line arguments and options, you can run

$ python -m gwdetchar.saturation --help
usage: python -m gwdetchar.saturation [-h] [-V] -i IFO -f FRAMETYPE [-j NPROC]
                                      [-c CHANNELS] [-s [SKIP ...]]
                                      [-g GROUP_SIZE] [-a FLAG] [-p PAD]
                                      [-m HTML] [-v]
                                      gpsstart gpsend

Find channels clipping their software saturation limits

positional arguments:
  gpsstart              GPS start time or datetime of analysis
  gpsend                GPS end time or datetime of analysis

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -i IFO, --ifo IFO     IFO prefix for this analysis, default: None
  -f FRAMETYPE, --frametype FRAMETYPE
                        the frame type name
  -j NPROC, --nproc NPROC
                        the number of processes to use when reading data,
                        default: 8
  -c CHANNELS, --channels CHANNELS
                        file containing columnar list of channels to process,
                        default is to find all relevant channels from frames
  -s [SKIP ...], --skip [SKIP ...]
                        skip channels matching this string
  -g GROUP_SIZE, --group-size GROUP_SIZE
                        number of channels to process in a single batch,
                        default: 1024
  -a FLAG, --state-flag FLAG
                        restrict search to times when FLAG was active
  -p PAD, --pad-state-end PAD
                        pad state segments inwards from the end by PAD
                        segments, default: 0
  -m HTML, --html HTML  path to write html output
  -v, --plot            make plots of all saturations, default: False