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


Earthworm Module: carlsubtrig

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

Helpful Hints