PSLmon

The PSL monitor is a generic monitor program that was first written to monitor the performance of the Pre-Stabilized Laser (PSL). PSLmon performs three general functions and may be configured by way of a configuration file to perform the basic functions on an arbitrary channel set. The basic functions are the following:
  1. Collect and watch spectra: The monitor calculates the power spectra of one or more specified channel(s). The collected spectra will optionally be averaged over two or more time strides and recorded either as XML files or as meta-database records (not yet implemented). The spectra may be compared to a standard spectrum.
  2. Watch signal power in specified bands: The monitor calculates the power in a specified frequency band and compares it to absolute or relative limits. A trigger may be generated each time the in-band power exceeds specified limits.
  3. Identify and count glitches: The glitch tool finds time series containing samples lying outside of a specified envelope and optionally produces triggers describing the glitch, a trend of average glitch amplitude or snap-shot time series of the glitch. Glitch finding may be enabled by any condition defined by the OSC package e.g. when the IFO is locked.

Running PSLmon

The PSLmon command line syntax is as follows:

         PSLmon [-conf <cfile>] [-ndsindex [<index>]] [-exit] [-version]
     

Where:
-conf <cfile> Specifies an otional configuration file name.
-ndsindex [<index>] Indicates that PSLmon is to write out an NDS trend index file.
-exit Indicates that PSLmon is to stop immediately after initialization.
-version Write the cvs version header to stdout.

PSLmon Outputs

Status Reports

None defined yet.

Trend Files

Each instance of the PSL monitor produces a single minute trend frame file which receive all data channels. The trend files produced by PSLmon are named <site>-<name>_M-<GPS>-<time>.gwf where <site> is L for Livingston or H for Hanford frames, <name> is the monitor name specified by the MonName parameter, <GPS> is the start-time of the first frame in the file rounded down to the nearest hour, and <time> is the total time in the frame file (usually 3600). By default the trend frames are 60 minutes long and a single frame is stored in each file.

Triggers

Triggers are generated by the Glitch and Band tools upon request. Trigger generation is enabled or disabled for the entire monitor process by the TrigEnable parameter. The following triggers are generated by PSLmon tools:

ID Tool Meaning
Glitch Glitch A glitch was found in a monitored channel.
RMSBand Band A monitored Band exceeded the specified limit.

The contents and meaning of trigger record fields are summarized in individual tool descriptions below.

Configuring the PSL monitor

A configuration file is used to specify which tools are to be used on which channels and to set parameters and limit values needed by the process.

The configuration file consists of an arbitrary number of lines. Each line consists of one or more fields separated by blank space. The line terminates at a new line or at a pound sign('#'). The first field of each line is a command which may be any of the following:

The number of fields following the command differs among commands. Optional fields are preceded by a hyphen and a keyword/ The configuration command syntax is covered in the sections below and the descriptions of the appropriate tools.

Global parameters

Global parameters are set by the Parameter configuration command. The syntax of the Parameter command is:

Parameter <name> <value> [<name-2> <value-2> ...] 
     
The currently defined parameters are:

Parameter Default Meaning
MonName PSLmon Specify the monitor name. The monitor registers itself as a monitor data server with the given name, and uses the name in generating a default suffix for the Trend file name.
OSCFile none Specify an OperStateCond configuration file that defines the conditions used in the "-while" arguments.
StatFile $DMTHTMLOUT/PSLmon.txt Statistics output file.
StatMask 11 Decimal mask indicating which statistics to print: 1=configuration ; 10=Glitch Rates.
Stride 1.0 The number of seconds of data given to each tool. The time stride is used for all channels and tools.
TrigEnable 0 Global trigger enable flag. Any non-zero value will enable trigger writing.

Channel specification

All channels to be watched by the PSL monitor must be specified in configuration file with a "Channel" command. The channel alias is a short name that the user may use to avoid writing the entire channel name out each time it is used. If the alias is not specified, the channel name must be used. Each specified channel is read into a time series one stride at a time. The channel data may optionally be adjusted by an offset and a multiplicative constant specified by the -bias and -scale operands, respectively. An FFT is performed once if needed. Windowing may be specified on a channel-by-channel basis. If specified, the channel time series is passed through the window filter after scaling, but before the DFT is performed. The Channel data time series is not modified by the window.

The syntax of the Channel command is:

     Channel [<alias>] <channel> [-scale <scale>] [-bias <bias>] \
             [-window <filter>] [-overlap <ovlp-sec>]
Where:

<alias> is an optional channel alias which may be used in subsequent commands to specify a channel.
<channel> The full channel name to be read from the input frames.
<bias> A bias value which is added to the unscaled channel data before they are used by any of the tools.
<scale> A scale factor by which the biased channel data are multiplied before they are used by any of the tools.
<filter> A window or other filter to be applied to the channel time series before doing a DFT. The raw time series is unfiltered. <ovlp-sec> the number of seconds of data from the previous stride to be prepended to the current stride. The total stride length processed with each stride will then be <stride-len> + <ovlp-sec>. This should be used only with Band tools.

Filter Specification

PSLmon provides an arbitrary filter definition facility. Filters are used by the glitch tool for pre-conditioning the data channel and by the tools working in the frequency domain (e.g. Band) to window the data before performing the Fourier transform.

The syntax of the Filter command is:

     Filter <name> <type> [-settle <settle-time>] [<parameters>] 
Where:

<name> is a unique name by which the filter is referred.
<type> is the type of filter or window. The implemented types are listed in the table below.
<settle-time> is the filter settling time. This is described in the section on glitches.
<parameters> are filter type-dependent parameters.

The following filter types can be defined.

BaseLine A baseline restore filter. The first argument is a time constant.
Blackman A Blackman window.
Design Use the FilterDesign class to define a filter. The parameters are the sampling rate and a filter specification string.
Difference A differencing filter (i.e. a FIR filter with coefficients of {-1, 1}.
Hamming A Hamming window.
Hanning A Hanning window.
IIRFilter IIR filter are defined by a sampling rate followed by a list of poles and a list of zeros in the complex s-plane.
MultiPipe A compound filter composed of an arbitrary number of component filters.

The PSLmon Tools

Band limited RMS

The power in the specified frequency band is calculated for each time stride. The power can then be recorded in a trend frame or a trigger can be generated when the power changes by a specified absolute or fractional amount. Band powers are calculated by summing the squares of the appropriate bins from an FFT of the specified channel. By default, no windowing is performed on the time series before calculating the Fourier transform. This may be specified as a channel option. The trigger conditions are based on the the difference between the power measured in a given stride and the power measured in the previous stride. An exponential weighted average may optionally be used instead of the previous stride.

The syntax of the Band command is:

Band <name> <channel> -fmin <flo> -fmax <fhi> [-abslow <amin> -abshi <amax>] \
     [-fraclow <xmin> -frachi <xmax>] [-delt <delta>] [-while <osc-cond>] \
     [-alarm] [-atime <avg-time>] [-notrend | -trend <tname>] [-suffix <sfx>] \
     [-viewer <vname>] [-trigger]
Where:
<name> The name of the band tool.
<channel> The channel name or channel alias.
<flo> Lower edge of the frequency band.
<fhi> Upper edge of the frequency band.
<sfx> A suffix to append to the (mangled) input channel name to produce the default trend channel name. The suffix defaults to _BAND_<flo>_<fhi>.
<tname> The name of the trend channel. The band power is trended unless -notrend argument is specified. If <tname> is not specified or a null string, the trend is constructed from the input channel name.
<vname> The dmtviewer channel name. If neither <tname> or <vname> are specified,<vname> is derived from the generated channel name. If the trend name is specified without the viewer name, <vname> is set to the tool name (<name>).
<amin> Minimum absolute limit for the band power.
<amax> Maximum absolute limit for the band power.
<xmin> Minimum fractional decrease for the band power.
<xmax> Maximum fractional increase for the band power.
<delta> Maximum absolute change in the band power.
<osc-cond> OSC condition that must be satisfied by the data stride.
<-alarm> Generate an alarm if the band exceeds the specified limits.
<avg-time> Average time for an exponential weighted average.

Spectra

The spectrum tool calculates the power spectrum of the channel and averages the spectra over a specified time. The resulting averaged power spectra are served via the Monitor Data Service protocol. No windowing is performed when calculating the spectrum. The averaged spectra may be recorded to a file at regular intervals. The syntax of the Spectrum configuration file command is:

     Spectrum <spect> <channel> [-avtime <atime>] [-svtime <stime>] \
                      [-svfile <file>] [-while <osc-condition>]
Where:
<spect> The name of the spectrum tool.
<channel> The channel name or channel alias.
<atime> The time (seconds) over which the spectrum is averaged
<stime> Time (seconds) between saving spectra
<file> Name of file into which the spectrum will be saved.
<osc-condition> OSC condition that must be satisfied before taking a spectrum

Glitches

A glitch is defined to be a deviation from the average signal value that is greater than a specified number of sigma. The signal average and sigma are calculated for each time stride (as specified by the Stride global parameter). The glitch is assumed to start at the first sample that the signal exceeds the limit and to last until no samples have been found outside the limits for the typical glitch time. The two parameters used to control the glitch finding algorithm: a minimum deviation in sigma and the typical glitch time (1 ms by default), can be set with the Glitch configuration command described below. A filter may be used to pre-condition the data before passing it through the glitch finding tool. This is specified with the -filter argument and the Filter definition command. If a settling time is specified in the filter definition, the glitch finder will ignore all data from any interruption in the input data stream for the specified settling time. A snippet is taken of the largest glitch in a time stride and is served to the Monitor Data Viewer for online perusal. Only a single glitch trigger or snapshot is recorded per input stride, although all glitches found during the stride are counted in the rate summaries. If more than one glitch is found in the same time stride of the same channel, the largest amplitude glitch will be recorded and used to generate a trigger. The average glitch rate (in Hz) is served as time series and may be summarized in the trend frames by specifying a trend channel name. Note that because a maximum of one trigger is recorded per time stride, the trigger rate may be less than the trended glitch rate.

The Syntax of the Glitch configuration file command is:

     Glitch <glitch> <channel> [-sigma <nSig>] [-snip <time>] [-trigger] \
                               [-trend <name>] [-while <osc-condition>] \
			       [-filter <filter>] [-alarm <rate>] \
			       [-atime <avg-time>]
Where:

<glitch> The name of the glitch tool.
<channel> The channel name or channel alias.
<nSig> The minimum number of sigma for a glitch. [4]
<time> Typical glitch time. [1 ms]
<name> Channel name for a glitch rate trend.
-trigger If set, generate a trigger when a glitch is found
<osc-condition> OSC condition that must be satisfied before looking for glitches
<filter> is the filter used to precondition the data.
<rate> Rate threshold for generating an alarm.
<avg-time> Time span for alarm rate averaging.

The triggers generated by the Glitch tool have the following content:

ID "Glitch"
SubID The glitch tool name specified in the configuration command.
Start The time of the first sample found outside the limits.
Duration The time in seconds from the first sample outside the limits to the last sample in the glitch.
Significance The number of sigma of the sample with the largest deviation from the mean.
Intensity The largest single sample deviation in the glitch.
Priority Error

alphabetic index hierarchy of classes


generated by doc++