# Earthworm Modules:
CarlStaTrig Configuration File

(last revised March 9, 2007)
Page Index:
1. Functional command listing
2. Alphabetic command listing & description
3. Sample Configuration File
4. Sample Station File

On startup, carlstatrig reads the configuration file named on the command line. Commands in this file set all the parameters used for computing Carl Johnson triggers for individual stations. In the control file, lines may begin with a valid carlstatrig command (listed below) or with one of 2 special characters:

>     #  marks the line as a comment (example: # This is a comment).

>     @  allows control files to be nested; one control file can be
>        accessed from another with the command "@" followed by
>        a string representing the path name of the next control file
>        (example: @model.d).

Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!).

## 1. FUNCTIONAL COMMAND LISTING

Below are the commands recognized by carlstatrig, grouped by the function they influence. Most of the commands are required; they may be specified in any order in the control file.

    	Earthworm system setup:
    		MyModuleId		required
    		RingNameIn		required
    		RingNameOut		required
    		HeartBeatInterval	required
    		Debug

    	Station file and trigger parameters:
    		StationFile		required
    		MaxGap
    		Startup			required
    		STAtime
    		LTAtime
    		Ratio			required
    		Quiet			required
    		Decimation
    		GetWavesFrom		optional

## 2. ALPHABETIC COMMAND LISTING & DESCRIPTION

In the following section, all configuration file commands are listed in alphabetical order. Listed along with the command (bold-type) are its arguments (in red), the name of the subroutine that processes the command, and the function within the module that the command influences. A detailed description of the command and is also given. Default values and example commands are listed after each command description.

    command arg1		processed by		function

    Debug level		ReadConfig		Earthworm setup

> Sets the debug logging level for CarlStaTrig. With level set to zero minimal logging is done. Very verbose logging is obtained with level set to 4.

>     Default:  0
>     Example:  Debug  3

    Decimation count		ReadConfig		Trigger parameter

> Sets the decimation count for CarlStaTrig. Normally, every sample is used for computing averages; this is the default decimation of 1. To reduce CPU load, the decimation may be set to 2 or 3 without significantly affecting the trigger results. Then CarlStaTrig will use every second or third sample for averaging.

>     Default:  1
>     Example:  Decimation  3

    GetWavesFrom Inst Mod		ReadConfig		Earthworm Setup

> Defines the waveform logos to retrieve, Inst and Mod module for processing.
> Example: GetWavesFrom INST_WILDCARD MOD_WILDCARD

    HeartBeatInterval nsec	ReadConfig		Earthworm Setup

> Defines the number of seconds, nsec between TYPE_HEARTBEAT messages issued by carlstatrig. Example: HeartBeatInterval 30

    MaxGap nlevel		ReadConfig		Trigger parameter

> Sets the gap size, in sample periods, above which the station averages are restarted. For smaller gaps, data is interpolated to the sample period for that station. The sample period is specified in TRACE_BUF messages from the source module for that station. The default is 1; that is, reset the station averages for any gap larger than the sample period.

>     Default:  1
>     Example:  MaxGap  15

    MyModuleId mod_id	ReadConfig		Earthworm setup

> Sets the module id for labeling all outgoing trigger, heartbeat, and error messages. mod_id is a character string (valid strings are listed in earthworm.d) that relates to a unique single-byte number.

>     Default:  none
>     Example:  MyModuleId MOD_CARLSTATRIG

    Quiet equiet		ReadConfig		Trigger parameter

> Sets the value of Carl Johnson's equiet parameter for the station trigger calculation. This parameter is a trigger level adjustment.

>     Default:  none
>     Example:  Quiet 4.0

    Ratio ratio		ReadConfig		Trigger parameter

> Sets the value of the trigger ratio. In Carl Johnson's original formulation, this was enumer / edenom.

>     Default:  none
>     Example:  Ratio 2.3

    RingNameIn ring		ReadConfig		Earthworm setup

> Tells carlstatrig which shared memory region to use for input. ring is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique number for the key to the shared memory region.

>     Default:  none
>     Example:  RingNameIn  WAVE_RING

    RingNameOut ring		ReadConfig		Earthworm setup

> Tells carlstatrig which shared memory region to use for output. ring is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique number for the key to the shared memory region.

>     Default:  none
>     Example:  RingNameOut PICK_RING

    StartUp nsec		ReadConfig		Trigger parameter

> Sets the startup time for stations averages to nsec seconds. Carlstatrig waits this number of seconds after startup and reset before it calculates station triggers. This allows long-term averages to stabilize; otherwise false triggers would be sent on startup.

>     Default:  none
>     Example:  StartUp  7

    STAtime nsec		ReadConfig		Trigger parameter

> Sets the time for the short-term average (STA) to nsec seconds.

>     Default:  1
>     Example:  STAtime  3

    LTAtime nsta		ReadConfig		Trigger parameter

> Sets the nominal time for the long-term average (LTA) time to nsta STAtimes. This is the time over which the time-dependent weighting factor used in the averaging decreases by a factor of approximately 1/e.

>     Default:  8
>     Example:  LTAtime  20

    StationFile sta_file	ReadConfig		Station File

> Specifes sta_file as the file of stations to be monitored by carlstatrig. This file can be the same station file as the one for CarlSubTrig. CarlStaTrig uses all TRACEBUF messages it gets from its input ring which are listed in the station file. Any other TRACEBUF messages, and stations in the file for which there are no TRACEBUF messages, are ignored. In the following sample station file, the Trigger Time To Live value is not used by carlstaTrig.

>     Default:  none
>     Example:  StationFile  pnsn_trig.sta

> ##
> 3. Sample Configuration File

>     # $Id: carlstatrig_cmd.html,v 1.6 2007/03/09 15:46:13 paulf Exp $
>     #
>     # CarlStaTrig's Parameter File
>     #

>     #
>     #  Basic Earthworm Setup
>     #
>     MyModuleId      MOD_CARLSTATRIG # Module id for this instance of CarlStaTrig
>                                     # - REQUIRED
>     RingNameIn      WAVE_RING       # Name of ring from which trace data will be
>                                     #   read - REQUIRED.
>     RingNameOut     PICK_RING       # Name of ring to which triggers will be
>                                     #   written - REQUIRED.
>     HeartBeatInterval       0       # Heartbeat Interval (seconds). REQUIRED

>     # Set debug log message level: OPTIONAL (default: 0)
>     #   0  log transport errors, changes in datatype, samplerate, failure to flush
>     #   1  above plus large gaps and overlaps
>     #   2  above plus small gaps and overlaps, station trigger changes -
>     #      best for beginning installations
>     #   3  above plus station trigger values and messages
>     #   4  above plus "unable to find station..."
>     #   5  above plus many details of message handling - very verbose.

>     Debug 1

>     #
>     # CarlTrig Specific Setup
>     #
>     StationFile     "pnsn_trig.sta" # Name of file containing station information -
>                                     #   REQUIRED.
>     MaxGap          1.5             # Maximum gap between trace data points that
>                                     #   can be interpolated (otherwise restart the
>                                     #   station). OPTIONAL (default MaxGap = 1)
>     StartUp         60              # Minimum seconds of trace data needed to
>                                     #   before using LTAs REQUIRED. Recommended
>                                     #   value is 2.5 * LTAtime * STAtime.
>     STAtime		3		# Number of seconds for short term average
>     				# OPTIONAL (integer; default STAtime = 1)
>     LTAtime         8               # Long-term average time (time to 1/e weight)
>     				#   in units of STAtime.
>                                     # OPTIONAL (default LTAtime = 8)
>     Decimation      1               # Decimation factor used in averages
>                                     # OPTIONAL (default Decimation = 1)
>     Ratio           2.3             # Carl Trigger parameter: enumer / edenom
>                                     # REQUIRED
>     Quiet           4.0             # Carl Trigger equiet parameter - REQUIRED

>     GetWavesFrom INST_WILDCARD MOD_WILDCARD # optional way to specify which trace logos to get

> ##
> 4. Sample Station File

>     #
>     #   carlsta/subtrig.sta  FOR PNSN
>     #
>     #   PNSN station list
>     #
>     # Arbitrary Station Component Network Location  Trigger
>     #           Code    Code      Code    Code      Time To Live
>     # --------- ------- ------- --------- --------- ------------
>       station   GMW	      EHZ	UW        --		10
>       station   GSM       EHZ	UW        --		10
>       station   BLN       EHZ	UW        --		10
>       station   CPW       EHZ       UW        --		10
>       station   JCW       EHZ       UW        --		10

Module Index | CarlStaTrig/CarlSubTrig Overview | CarlSubTrig Commands