DMT Background Monitors 

A few sample background monitors have been developed already. They are:
  • BitTest: Check for stuck bits and repeated words in the raw data.
  • DQual:Measure some steady state signal quantities, such as average, standard deviation, power into specific frequency bands and number of  excursions of 3 sigma.
  • FrTest: Utility to test internal consistency of frame files and to dump selected structures.
  • FrWrite: Utility to write designer frames to one or more date-stamped files.

  • BitTest



    BitTest monitors specified channels for bits that remain in one state and for channels that repeat a value twice or more in succession. The channels to be monitored may produce either integer or floating point data, but the bit checking facility functions only for the integer channels. BitTest accumulates statistics on all requested channels for a fixed number of frames, until a specified time or until an external interrupt is received. Any detected problems are reported at the end of the period and the accumulation cycle is restarted.

    The BitTest error reports are produced in two sections with each section written to a separate file. The first section lists the channels found to be missing or to have data errors. The second section gives detailed statistics on each channel. In the future, the detection of an erroneous channel will cause a trigger to be generated. Note: At present, triggers are not generated pending the finalization of the trigger mechanism and stabilization of the channel list (Aug 13, 1999).

    The BitTest Configuration File

    The BitTest configuration file specifies the channels to be monitored and parameters affecting the generation of triggers for each channel. Each line of the configuration file specifies the parameters for a single channel and contains the following fields:

        <channel-name>  <bit-range>  <max-repetition>

    The meaning of each field is as follows:

        <channel-name>    Name of the channel to be monitored.
        <bit-range>      Mask of bits to be monitored.
        <max-repetition>  Maximum number of of time a given value may be repeated.

    The bits in the mask need not be adjacent. If the bit mask is zero, an automatic error detection algorithm is used that requires that any stuck bits be adjacent high-order bits. Thus, any bit that is stuck in one state, is not the most significant bit and is not adjacent to a higher order stuck bit will generate a trigger. This will give the desired result in cases where the channel measures a signal that varies smoothly over a given range. This condition is satisfied by most LIGO signals.

    Repetition count triggers may be disabled by setting the maximum repetition count to zero.

    The configuration file is reread each time a SIGUSR1 signal is received. This means that the monitor process need not be restarted in order to change the configuration. Instead, the configuration file can be modified, and the process reconfigured with a "kill -USR1 <pid>" command.

    Running BitTest

    The syntax of the BitTestcommand is as follows:

    BitTest [-partition <part-name>] [-infile <file>] \
            [-debug <dbg-level>] [cfile <conf-file>] \
            [reset <nsec>] [synch hh[:mm[:ss]]] \
            [ofile <out-file>]

    Where the arguments have the following meaning:

        <part-name>    Shared memory partition name with data to be read
        <file>        Input frame file (exclusive of <part-name>)
        <dbg-level>    Debug level
        <conf-file>    Configuration file name.
                <nsec>         Accumulation time in seconds
        hh:mm:ss      Time (in current UTC day) for first report to be generated
        <out-file>     Root output file name (defaults to "BitTest.junk")

    The partition name is mutually exclusive with the input frame file name. If both are specified, data are read from the specified shared memory partition. The debug level defaults to 0 (no debug messages). Any other value for <dbg-level> will cause debugging messages to be printed to cout/cerr. Reports are produced at hh:mm:ss and every <nsec> seconds after that. If <nsec> is not specified, BitTest will continue to accumulate statistics until it catches either a SIGTERM or SIGUSR1 signal. If hh:mm:ss is not specified, BitTest will produce a report after <nsec> frames have been received.

    BitTest Reports and Other Output

     The BitTest reports are divided into two sections. The first section is a list all channels that were found to have errors. This list is stored in the file named by "<out-file>.Errors" where the file root name is specified on the command line. The error list is further divided into categories containing channels with the following errors:
  • Channels with errors: this is a list of channels that either have one or more stuck bits or have a repetition count greater than the maximum specified.
  • Channels with all one value: this lists channels that never changed value during the accumulation period. Channels are listed here even if the repetition count test is disabled by setting the maximum to zero.
  • Channels not read out: this is a list of channels that were requested in the configuration file, but never found in the data frames.
  • The second section is a table with statistics and status information for all configured channels.  The table  is written to a file named "<out-file>.Statistics" and contains the following information for each channel:
  • Error Flag: A flag (****) is printed for Channels failing the bit or repetition test.
  • Channel Name: Obvious
  • Frames: The number of frames in which the channel was seen.
  • On Bits: A hex mask containing a 1 in each bit position in which the data was always 1.
  • Off Bits: A hex mask containing a 1 in each bit position in which the data was always 0.
  • Repeat Count: Largest number of consecutive samples containing the same data value.
  • Average value: Average of all samples during the accumulation period.
  • Sigma: Standard deviation from the mean of all samples during the accumulation period.
  • Minimum: The smallest (signed) value found during the accumulation period.
  • Maximum: The largest (signed) value found during the accumulation period.

  • DQual



    DQual monitors and records the following parameters of each configured ADC channel:
  • Average value
  • Variance
  • Number of excursions greater than 3-6 sigma.
  • Power into several bands over the GW frequency range.
  • These parameters were chosen because they will be of use in scanning data for variations in running conditions.
    Note: No trigger are currently generated pending the finalization of the trigger mechanism  (Aug 13, 1999).

    The DQual Configuration File

    The DQual configuration file specifies the channels to be monitored and parameters affecting the generation of triggers for each channel. Each line of the configuration file specifies the parameters for a single channel and contains the following fields:

        <channel-name>  <bit-range>  <max-repetition>

    The meaning of each fields is as follows:

        <channel-name>    Name of the channel to be monitored.
        <bit-range>      Mask of bits to be monitored.
        <max-repetition>  Maximum number of of time a given value may be repeated.

    The bits in the mask need not be adjacent. If the bit mask is zero, an automatic error detection algorithm is used that requires that any stuck bits be adjacent high-order bits. Thus, any bit that is stuck in one state, is not the most significant bit and is not adjacent to a higher order stuck bit will generate a trigger. This will give the desired result in cases where the channel measures a signal that varies smoothly over a given range. This condition is satisfied by most LIGO signals.

    Repetition count triggers may be disabled by setting the maximum repetition count to zero
     

     Running DQual

    The syntax of the DQualcommand is as follows:

        DQual [-partition <part-name>] [-infile <file>] \
              [-debug <dbg-level>] [cfile <conf-file>]

    Where the arguments have the following meaning:

        <part-name>    Shared memory partition name with data to be read
        <file>        Input frame file (exclusive of <part-name>)
        <dbg-level>    Debug level
        <conf-file>    Configuration file name.

    The partition name is mutually exclusive with the input frame file name. If both are specified, the data are read from the specified shared memory partition. The debug level defaults to 0 (no debug messages). Any other value for <dbg-level> will cause debugging message to be printed.
     

    Triggers generated by  DQual

    A trigger is generated for each monitored channel after each time interval expires.
     


    FrTest



    FrTest tests frames internal consistency and optionally dumps selected structures of the frame. The input data source may be either an online shared memory partition or a frame file. Selected structure types are dumped in hex to the standard output stream.

    Running FrTest

    The syntax of the FrTestcommand is as follows:

    FrTest [-partition <part-name>] [-infile <file>] \
           [-debug <dbg-level>] [-dumpid <struct-id>]

    Where the arguments have the following meaning:

        <part-name>    Shared memory partition name with data to be read
        <file>        Input frame file (exclusive of <part-name>)
        <dbg-level>    Debug level
        <struct-id>    Identifier of structure type to be dumped.

    The partition name is mutually exclusive with the input frame file name. If both are specified, data are read from the specified shared memory partition. The debug level defaults to 0 (no debug messages). Any other value for <dbg-level> will cause debugging messages to be printed to cout. If a structure ID is specified, all instances of the specified structure will be dumped out in hexadecimal. Several structure types may be dumped at the same time by specifying multiple "-dumpid <struct-id>" arguments.


    FrWrite



    FrWrite writes frames consisting of a user-defined subset of the channels. The input data source may be either an online shared memory partition or one or more frame files. The data are written to one or more frame files, the names of which may include a time stamp generated from the GPS time of the first frame in the file. The list of channels to be written is specified in an optional configuration file. If no configuration file is specified, all available channels are written.
    Note: At present, no pre-processing is performed on the data. Filtering, decimation, time deskewing and trigging capabilities are expected to be added at some time in the future. (January 27, 2000).

    The FrWrite Configuration File

    The FrWrite configuration file specifies which channels are to be written to the output file. Each line of the configuration file specifies a single channel name. Comment lines may be interspersed throughout the file and must have a '#' in the first column. No error is generated is a requested channel doesn't exist in a given frame, although a message will be printed each time a channel is not found if the debug flag is non-zero.
     

    Running FrWrite

    The syntax of the FrWrite command is as follows:

    FrWrite [-partition <part-name>] [-infile <file>] \
            [-debug <dbg-level>] [-cfile <conf-file>] \
            [-nframe <nFrame>] [-repeat <nFile>] \
            [-ofile <out-file>] [-sequence <nSeq>] \
            [-trigger <osc-file>]

    Where the arguments have the following meaning:

        <part-name>   Shared memory partition with data to be read
        <file>        Input frame file (exclusive of <part-name>)
        <dbg-level>   Debug level
        <conf-file>   Configuration file name.
                <nFrame>      Number of frames to write in each file [default 1].
        <nFile>       The number of files to be written [default 1].
        <out-file>    Output file name template (defaults to
                                                        "FrWrite-%Y.%m.%d-%H.%N.%S.F")
        <nSeq>        The number of output file in a sequence [default 0].
        <osc-file>    OperStateCond configuration file defining "Trigger".

    The partition name is mutually exclusive with the input frame file name. If both are specified,data are read from the specified shared memory partition. Multiple input files may be specified either by specifying several "-infile <file>"  arguments or with wild-cards (e.g. "-infile '*.F' "). The debug level defaults to 0 (no debug messages). Any other value for <dbg-level> will cause debugging messages to be printed to cout. The <out-file> argument is treated as a template for generating file names. The name is generated with TimeStr() using the template and the GPS start-time of the first frame as arguments. You can thus include the GPS time in seconds by using a file name template of e.g. "MyFrame-%s.F". If <nFile> is zero, FrWrite will continue to write frame files until it is terminated with a ctrl/c or a kill command. Output files may be devided into sequences of <nSeq> files. This is most useful for limiting the number of files in a single directory. The sequence number may be incorporated into the output file name with a "%q" token. The <osc-file> defines an optional condition that the input frame must satisfy for the data to be written to the output.



    Last modified: July 18, 2000
    Please address questions and comments to: John Zweizig