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:
Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!).# 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).
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.
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.
1. FUNCTIONAL COMMAND LISTING
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
Decomation
2. ALPHABETIC COMMAND LISTING & 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
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: cmd.html 4571 2011-08-18 20:28:39Z stefan $
#
# 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
4. Sample Station File
#
# carlsta/subtrig.sta FOR PNSN
#
# PNSN station list
#
# Arbitrary Station Component Network Trigger
# 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
Contact: Questions? Issues? Subscribe to the Earthworm Google Groups List.