Version 5 (modified by branden, 10 years ago) (diff)


Earthworm Module: carlstatrig

Contributed by:


The Carl Johnson coincidence trigger for Earthworm consists of two programs. CarlStaTrig produces station trigger messages on a transport ring. CarlSubTrig reads these and writes a TRIGLIST message.



The pair of modules, carlstatrig and carlsubtrig implement Carl Johnson's STA/LTA with subnet coincidence trigger on Earthworm. This trigger can be tuned to be a fairly sensitive detection algorithm that has rather weak discrimination between noise and seismic signals.

As the names imply, carlstatrig performs trigger calculations for one or more stations, while carlsubtrig does the subnet and network trigger logic. Carlstatrig writes a TYPE_CARLSTATRIG_SCNL message for each station that triggers; these messages are placed on an earthworm transport ring. Carlsubtrig reads these station trigger messages from the transport ring. Thus there can be more than one carlstatrig or carlsubtrig module running at once. Using export_generic/import_generic, station trigger messages can be exchanged between different computers and installations, allowing great flexibility in the configuration. Provision is made for slow delivery of station trigger messages. The subnet calculations are performed after a configurable latency period has elapsed.

Carlsubtrig writes a TYPE_TRIGLIST_SCNL message to a transport ring. Among other uses, this message is intended to be used for retrieving trace data from one or more wave_serverV modules. trig2disk and ora_trace_save are examples of such an application. The TRIGLIST_SCNL message gives event start time and duration, as well as a list of stations and the times they triggered.


The station trigger algorithm works as follows. For each configured station, the short-term average (STA) of the trace is calculated. The time length of the averaging window (STAtime) is one second by default, but can optionally be specified by the user. A weighted average of previous STAs is then taken to get the long-term average (LTA) of the trace. The number of STAs used to calculate the LTA (LTAtime) is eight by default, but can optionally be specified by the user. LTAtime is the number of STAs over which the time-dependent weighting factor used in the averaging decreases by a factor of approximately 1/e. In addition to these two `straight' averages, there are corresponding rectified averages. The short-term rectified average (STAR) is taken from the absolute value of the difference between the trace and the LTA, averaged over one second (by default) or optionally over the user-specified window length described above. The long-term rectified average (LTAR) is a weighted average of previous STARs, calculated in a manner analogous to LTA.

These four averages are combined to determine the station trigger status, using a modified version of Carl Johnson's magic formula:

        eta = STAR - Ratio * LTAR - | STA - LTA | - Quiet

In its original form this calculation was done in integer arithmetic. In that case, the value of Ratio was in the form Enumer / Edenom. The current calculations are performed in floating-point arithmetic. This obviates the need for some subtle adjustments used in the earlier code, and seems to make the algorithm more sensitive.

If eta is greater than 0.0, the station is considered triggered, the trigger turns off when eta <= 0.0. When the station trigger turns on, one CARLSTATRIG message is sent to the transport ring. When the station trigger turns off, another trigger message is sent. This provides some redundancy in case one of these messages does not get delivered to carlsubtrig. If the `OFF' message is never received, carlsubtrig assumes a (configurable) maximum duration for the station trigger.


As mentioned above, carlsubtrig reads CARLSTATRIG messages from one or more carlstatrig modules and performs the subnet trigger logic. One of the configuration files is a list of `subnets' and the stations assigned to each. The list also includes the number of stations required to trigger each subnet.

As station trigger messages are received by carlsubtrig, they are stored in queues by station. Carlsubtrig maintains an internal clock which is set a fixed number of seconds (the latency period) behind wall-clock (real, system) time. This latency period allows for delayed delivery of station trigger messages. Carlsubtrig uses this internal clock to compare to station trigger times. Once the station trigger-on or -off time is later than the internal clock time, this trigger status change is noticed by carlsubtrig. In order for times to be compared between machines, all machines should be synchronized within a few seconds or better. Xntp (available with Solaris2.6 and also public domain) is a good choice for time synchronization. In addition, the system time must be set to data time, i.e. GMT.

After the station trigger off time has expired, the station is still considered triggered for an additional TimeToLive (configurable). This feature is to allow for the difference in travel times of the P-wave to each of the stations in a subnet. The idea is that for a subnet to trigger for an event, some minimum (configurable) number of its station triggers must be on at the same time. The TimeToLive parameter is set to provide this coincidence within a subnet.

When any one subnet is triggered, the network becomes triggered and an event (TRIGLIST2K) message will eventually be released and optionally. The duration of the network trigger depends on the maximum number of subnets that trigger, up to a configured maximum trigger length. When the network trigger finally expires, then the TRIGLIST2K message is sent to the transport ring. All the subnets are reset and the module waits for the next event.

Subnet configuration issues

In any given network there will usually be several subnets defined with many stations appearing in different subnets. Stations which are geographically near each other should be grouped in a subnet and these groups should be overlapping in such a way that most stations are part of two or three subnets. A particularly low-noise station might be included in any subnet more than once to let it have a much stronger influence in causing a trigger. If telemetry noise is common to several stations it is wise to try and divide these stations over several subnets so that that the coincidence of telemetry glitches are less likely to cause a trigger. Typical subnets might have from 5 to 20 stations and require from 3 to 5 station triggers to cause an event trigger.

Notes from Lynn Dietz on carlstatrig

Configuration File Commands

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!).


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

	Station file and trigger parameters:
		StationFile		required
		Startup			required
		Ratio			required
		Quiet			required
		GetWavesFrom		optional 


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.

The following list is organized by:

command [argument here]

Debug [level]
Processed by: ReadConfig
Function: 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]
Processed by: ReadConfig
Function: 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]
Processed by: ReadConfig
Function: Earthworm Setup

Defines the waveform logos to retrieve, Inst and Mod module for processing.


HeartBeatInterval [nsec]
Processed by: ReadConfig
Function: Earthworm Setup

Defines the number of seconds, nsec between TYPE_HEARTBEAT messages issued by carlstatrig.

Example: HeartBeatInterval 30

MaxGap [nlevel]
Processed by: ReadConfig
Function: 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]
Processed by: ReadConfig
Function: 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]
Processed by: ReadConfig
Function: 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]
Processed by: ReadConfig
Function: 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]
Processed by: ReadConfig
Function: 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]
Processed by: ReadConfig
Function: 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]
Processed by: ReadConfig
Function: 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]
Processed by: ReadConfig
Function: Trigger parameter

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

Default:  1
Example:  STAtime  3

LTAtime [nsta]
Processed by: ReadConfig
Function: 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]
Processed by: ReadConfig
Function: 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

Sample Configuration File

# $Id: carlstatrig_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

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

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

Helpful Hints