Optical scattering

The gwdetchar.scattering module provides a suite of tools designed to look for evidence of optical scattering in the LIGO detectors. This tool finds the velocity of a set of optics as measured by optical position sensors and electromagnetic drivers (OSEMs), then compares against the wavelength of a carrier laser to estimate the fringe frequency. For more information about this method, please see Accadia et al. (2010).

The gwdetchar.scattering module provides the following functions:

get_fringe_frequency(series[, multiplier])

Predict scattering fringe frequency from the derivative of a timeseries

Note

OSEMs directly measure only the translational (linear) motion of optics, typically on the scale of microns. To measure velocity, gwdetchar.scattering uses a Savitzky-Golay filter to take smoothed time derivatives.

The gwdetchar.scattering.plot module also provides functions for comparing fringe frequency projections against high-resolution Q-transform spectrograms:

plot.spectral_comparison(gps, qspecgram, ...)

Compare a high-resolution spectrogram with projected fringe frequencies

plot.spectral_overlay(gps, qspecgram, ...[, ...])

Overlay scattering fringe projections on top of a high-resolution spectrogram

Command-line utilities

GWDetChar provides two command-line utilities for optical scattering; one is designed to identify time periods when scattering is likely, the other compares projected fringe frequencies against a high-resolution spectrogram of gravitational-wave strain.

Note

These utilities require authentication with LIGO.ORG credentials for archived frame data access.

gwdetchar.scattering

The gwdetchar.scattering command-line interface searches over a standard list of OSEM measurements within a user-specified time range for evidence of optical scattering. The simplest usage is as follows:

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

For example,

python -m gwdetchar.scattering -i H1 1126259442 1126259502

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

$ python -m gwdetchar.scattering --help
usage: python -m gwdetchar.scattering [-h] [-V] -i IFO [-a FLAG] [-z FMIN]
                                      [-t FREQUENCY_THRESHOLD] [-x {1,2,3,4}]
                                      [-m OPTIC] [-p SEGMENT_PADDING]
                                      [-s SEGMENT_START_PAD]
                                      [-e SEGMENT_END_PAD] [-L BANDPASS_FLOW]
                                      [-H BANDPASS_FHIGH] [-S SIGMA]
                                      [-c MAIN_CHANNEL] [-f FRAMETYPE]
                                      [-o OUTPUT_DIR] [-w NSCAN] [-v]
                                      [-j NPROC]
                                      gpsstart gpsend

Search for evidence of beam scattering based on optic velocity

This tool identifies broad time segments over which evidence for scattering is
strong. To compare projected fringes against spectrogram measurements for a
specific, narrow time range, please use the `simple` command-line module:

python -m gwdetchar.scattering.simple --help

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

optional arguments:
  -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
  -a FLAG, --state-flag FLAG
                        restrict search to times when FLAG was active
  -z FMIN, --fmin FMIN  minimum frequency (Hz) of triggers, default: 10.0
  -t FREQUENCY_THRESHOLD, --frequency-threshold FREQUENCY_THRESHOLD
                        critical fringe frequency threshold (Hz), default:
                        15.0
  -x {1,2,3,4}, --multiplier-for-threshold {1,2,3,4}
                        fringe frequency multiplier to use when applying
                        --frequency-threshold, default: 4
  -m OPTIC, --optic OPTIC
                        optic to search for scattering signal, can be given
                        multiple times, default: ['BS', 'ETMX', 'ETMY', 'IM1',
                        'IM2', 'IM3', 'IM4', 'ITMX', 'ITMY', 'MC1', 'MC2',
                        'MC3', 'OM1', 'OM2', 'OM3', 'OMC', 'PR2', 'PR3',
                        'PRM', 'RM1', 'RM2', 'ZM1', 'ZM2', 'OPO', 'OFI',
                        'SR2', 'SR3', 'SRM', 'TMSX', 'TMSY']
  -p SEGMENT_PADDING, --segment-padding SEGMENT_PADDING
                        time with which to pad scattering segments on either
                        side, default: 0.05
  -s SEGMENT_START_PAD, --segment-start-pad SEGMENT_START_PAD
                        amount of time to remove from the start of each
                        analysis segment
  -e SEGMENT_END_PAD, --segment-end-pad SEGMENT_END_PAD
                        amount of time to remove from the end of each analysis
                        segment
  -L BANDPASS_FLOW, --bandpass-flow BANDPASS_FLOW
                        lower-limit (Hz) of the passband for whitened BLRMS,
                        default: 4.0
  -H BANDPASS_FHIGH, --bandpass-fhigh BANDPASS_FHIGH
                        upper-limit (Hz) of the passband for whitened BLRMS,
                        default: 10.0
  -S SIGMA, --sigma SIGMA
                        significance threshold on whitened BLRMS, default: 2
  -c MAIN_CHANNEL, --main-channel MAIN_CHANNEL
                        name of main (h(t)) channel, default: {IFO}:GDS-
                        CALIB_STRAIN
  -f FRAMETYPE, --frametype FRAMETYPE
                        the frame type name
  -o OUTPUT_DIR, --output-dir OUTPUT_DIR
                        output directory for analysis, default: .
  -w NSCAN, --omega-scans NSCAN
                        generate a workflow of Omega scans for active
                        scattering, this will launch automatically to condor,
                        default: 0 (no Omega scans)
  -v, --verbose         log verbose output, default: False
  -j NPROC, --nproc NPROC
                        the number of processes to use when reading data,
                        default: 8

gwdetchar.scattering.simple

The gwdetchar.scattering.simple can also be run as a command-line module to compare fringe frequency projections against gravitational-wave strain at a specific time. The simplest usage is similar to gwdetchar.scattering, but with only a single time:

python -m gwdetchar.scattering.simple -i <interferometer> <gps-time>

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

$ python -m gwdetchar.scattering.simple --help
usage: python -m gwdetchar.scattering.simple [-h] [-V] -i IFO [-d DURATION]
                                             [-t FREQUENCY_THRESHOLD]
                                             [-m MULTIPLIERS]
                                             [-x MULTIPLIER_FOR_THRESHOLD]
                                             [-w PRIMARY_CHANNEL]
                                             [-W PRIMARY_FRAMETYPE]
                                             [-a AUX_FRAMETYPE]
                                             [-o OUTPUT_DIR] [-c COLORMAP]
                                             gpstime

Simple command-line interface to gwdetchar.scattering

Given a specific GPS time of interest, this module scans through records of
optic motion and projects fringe frequencies due to optical scattering. For
those channels with fringes above a user-specified threshold, a plot is
created comparing the fringes to a high-resolution Q-scan spectrogram.

To identify broader time segments when scattering is likely in the first
place, please use the main command-line module:

python -m gwdetchar.scattering --help

positional arguments:
  gpstime               GPS time or datestring to analyze

optional arguments:
  -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
  -d DURATION, --duration DURATION
                        Duration (seconds) of analysis, default: 60
  -t FREQUENCY_THRESHOLD, --frequency-threshold FREQUENCY_THRESHOLD
                        critical fringe frequency threshold (Hz), default: 15
  -m MULTIPLIERS, --multipliers MULTIPLIERS
                        harmonic numbers to plot projected motion for, should
                        be given as a comma-separated list of numbers,
                        default: 1,2,4,8
  -x MULTIPLIER_FOR_THRESHOLD, --multiplier-for-threshold MULTIPLIER_FOR_THRESHOLD
                        frequency multiplier to use when applying --frequency-
                        threshold, default: 4
  -w PRIMARY_CHANNEL, --primary-channel PRIMARY_CHANNEL
                        name of primary channel (without IFO prefix), default:
                        GDS-CALIB_STRAIN
  -W PRIMARY_FRAMETYPE, --primary-frametype PRIMARY_FRAMETYPE
                        frametype from which to read primary channel, default:
                        {IFO}_HOFT_C00
  -a AUX_FRAMETYPE, --aux-frametype AUX_FRAMETYPE
                        frametype from which to read auxiliary channels,
                        default: {IFO}_R
  -o OUTPUT_DIR, --output-dir OUTPUT_DIR
                        Output directory for analysis, default: .
  -c COLORMAP, --colormap COLORMAP
                        name of colormap to use, default: viridis