Search:
wiki:carlsubtrig
Last modified 16 months ago Last modified on 05/22/12 13:47:32

# Earthworm Module: carlsubtrig

Contributed by:

## Function

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.

## Details

### Introduction

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.

### Carlstatrig

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.

### Carlsubtrig

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

- Lynn's Notes on CarlStaTrig
- CarlStaTrig tuning at Mammoth California

## Configuration File Commands

On startup, CarlSubTrig reads the configuration file named on the command line. Commands in this file set all the parameters used for performing the subnet logic for the Carl Johnson trigger system. In the control file, lines may begin with a valid carlsubtrig 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!).

### IMPORTANT NOTE

Carlsubtrig supports the ability to use late arriving station triggers in the subnet trigger logic. It 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.

Because Carlsubtrig uses both system and data time to perform the subnet trigger logic, the system time must be set to UTC. If this is not done, no triggers will occur.

### FUNCTIONAL COMMAND LISTING

Below are the commands recognized by carlsubtrig, grouped by the function they influence. All of the commands are required except Debug; they may be specified in any order in the control file.

    	Earthworm system setup:
    		MyModuleId		required
    		RingNameIn		required
    		RingNameOut		required
    		HeartBeartInterval	required
    		Debug
    		GetEventsFrom		required
    		TrigIdFilename		optional

    	Station parameters:
    		StationFile		required
    		Latency			required
    		DefStationDur		required

    	Subnet trigger parameters:
    		NetTriggerDur		required
    		SubnetContrib		required
    		PreEventTime		required
    		MaxDuration		required
    		Subnet			required

    	Trigger message parameters:
    		ListSubnets		optional
    		AllSubnets		optional
    		CompAsWild		optional
    		Channels	      	optional
    		MaxTrigMsgLen		optional
    		CoincidentStaTriggers		optional
    		IgnoreCoincident		optional

### 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 the values used by PNSN are listed after each command description.

The following list is organized by:

command [argument here]

AllSubnets [nsubnets]
Processed by: ReadConfig
Function: Earthworm setup

If nsubnets trigger for an event, then the trigger message will include the SCNL wildcard. A process reading the trigger message could understand this wildcard to mean "retrieve data for All stations".

    Default:  0
    Example:  AllSubnets  10

Channel [SCNL]
Processed by: ReadConfig
Function: Earthworm setup

Specify a single SCNL that should be listed in all trigger messages. For example, this can be used to list time channels that never trigger but should always be present in waveform data filesets. This command can be used as many times as necessary.

    Default:  0
    Example:  Channel WWVB.TIM.UW

CoincidentStaTriggers
Processed by: ReadConfig
Function: Earthworm setup

The number of station triggers that match exactly to the second that must be met for a trigger message to be rejected. The idea here is to eliminate telemetry glitches by mapping exactly coincident in time trigger on times. The carlstatrigger messages only have on time to the whole second.

    Default:  0  (not set)
    Example:  CoincidentStaTriggers 9

CompAsWild
Processed by: ReadConfig
Function: Earthworm setup

Flag with no value. If present, carlsubtrig will put the wildcard `*' in the trigger message in place of component names. This can be used if you have multi-component stations but only want to listen for station triggers from the vertical component.

    Default:  0  (flag not set)
    Example:  CompAsWild

Debug [level]
Processed by: ReadConfig
Function: Earthworm setup

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

    Default:  0
    Example:  Debug  3

DefStationDur [nsecs]
Processed by: ReadConfig
Function: Station parameters

Sets the default station trigger duration to nsecs seconds. This value is used to terminate a station trigger only if no trigger-off message matching a trigger-on message is received from CarlStaTrig.

    Default:  none
    Example:  DefStationDur  120

GetEventsFrom [inst mod_id]
Processed by: ReadConfig
Function: Earthworm setup

Contrls the TYPE_CARLSTATRIG messages input to carlsubtrig. CarlSubTrig will only process TYPE_CARLSTATRIG messages that come from module mod_id at installation inst. inst and mod_id are character strings (valid strings are listed in earthworm.h/earthworm.d) which are related to single-byte numbers that uniquely identify each installation and module. Only one "GetSumFrom" command may be issued; wildcards (INST_WILDCARD and MOD_WILDCARD) will force carlsubtrig to process all station trigger messages, regardless of their place of origin.

    Default:  none
    Example   GetEventsFrom  INST_WILDCARD  MOD_WILDCARD

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

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

    Default:  none
    Example:  HeartBeatInterval 30

IgnoreCoincident [nsubs]
Processed by: ReadConfig
Function: Earthworm setup

If more than the specified number of subnets nsubs are coincidentally triggered, then the coincident check for triggers is not performed. The reason for this option is because the coincident check should only be performed for a small number of subnets triggering since telemetry glitches would not cross more than a few subnetworks.

    Default:  3
    Example:  IgnoreCoincident 4

Latency [nsec]
Processed by: ReadConfig
Function: Station parameters

Specifies the number of seconds that carlsubtrig will wait for delivery of station trigger messages. This allows for slow telemetry paths and other delays.

    Default:  none
    Example:  Latency   15

ListSubnets [ls]
Processed by: ReadConfig
Function: Earthworm setup

Flag for determining how which SCNLs will be listed in the trigger message. When ListSubnets is absent or ls is 0, the trigger message will include all triggered SCNLs. If ls is 1, the trigger list will include the untriggered SCNLs as well as the triggered SCNLs from the triggered subnets (but will omit triggered SCNLs that are NOT in the triggered subnets). When ListSubnets is 2, the trigger message will list all SCNLs from the triggered subnets, as well as all other triggered SCNLs (union of options 0 and 1). When ListSubnets is 3, the trigger message will list all SCNLs in any subnets that have at least one triggered SCNL. However, if more than AllSubnets have triggered, then the SCN wildcard will be listed instead of a long list of non-triggered stations. If this flag is absent, then carlsubtrig lists only stations that actually triggered during the event.

The idea here is to adjust the number of SCNLs in the trigger message for a small event. With ListSubnets at 1, we include untriggered SCNLs from triggered subnets. If the subnets are layed out in small geographic areas, then we might expect to have some seismic signal from all SCNLs in triggered subnets. By including those SCNLs in the trigger message, we allow downstream analysis to have the opportunity to look at the data from those SCNLs. If we increase ls to 3, then we are being more conservative in that we save data for anything in subnets that had any SCNLs trigger. In practice, we find that this high value results in almost every SCNL being listed. This is particularly true when there is a lot of weather or telemetry noise present on the network.

    Default:  0  (flag not set)
    Example:  ListSubnets  1

MaxDuration [nsec]
Processed by: ReadConfig
Function: Subnet parameters

Specifies the maximum duration of a network trigger as nsec seconds. This could be used to limit the size of datafiles retrieved from a wave server.

    Default:  none
    Example:  MaxDuration  1800

MaxTrigMsgLen [nsec]
Processed by: ReadConfig
Function: Subnet parameters

Specifies the maximum length (bytes) of a triglist message; up to MAX_BYTES_PER_EQ (earthworm.h).

    Default:  MAX_BYTES_PER_EQ
    Example:  MaxTrigMsgLen  30000

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_CARLSUBTRIG

NetTriggerDur [nsecs]
Processed by: ReadConfig
Function: Subnet parameters

Sets the base network trigger duration to nsecs seconds. The minimum trigger duration is the sum of PreEventTime, NetTriggerDur and SubnetContrib times the number of subnets that triggered.

    Default:  none
    Example:  NetTriggerDur  10

PreEventTime [nsecs]
Processed by: ReadConfig
Function: Subnet parameters

Specifies the number of seconds nsecs before the initial station trigger to start the network trigger. This can be used to start saving waveform data prior to the first phase arrivals. The minimum trigger duration is the sum of PreEventTime, NetTriggerDur and SubnetContrib times the number of subnets that triggered.

    Default:  none
    Example:  PreEventTime  10

RingNameIn [ring]
Processed by: ReadConfig
Function: Earthworm setup

Tells carlsubtrig 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  PICK_RING

RingNameOut [ring]
Processed by: ReadConfig
Function: Earthworm setup

Tells carlsubtrig 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 HYPO_RING

StationFile [sta_file]
Processed by: ReadConfig
Function: Station parameters

Specifies sta_file as the file of stations to be monitored by carlsubtrig. This file can be the same station file as the one for CarlStaTrig. This file must list all the stations that make up the Subnets. This file lists each station by station name, component and network. It also specifies the Trigger Time To Live. This is the number of seconds that each station trigger will be help active in CarlSubTrig after CarlStaTrig reports the station trigger off. This Trigger Time To Live allows for the seismic signal propagation time from each station to the other stations in the subnet.

    Default:  none
    Example:  StationFile  pnsn_trig.sta

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        00	10
      station   BLN     EHZ	    UW        00	15
      station   CPW     EHZ     UW        01	10
      station   JCW     EHZ     UW        --	10

Subnet [code ntrig sta.comp.net ...]
Processed by: ReadSubnet
Function: Subnet parameters

This command lists the subnet code, number of stations ntrig required to trigger the subnet, and the list of stations making up the subnet. Code is a string (up to 3 characters) that is used to identify the subnet in logged messages. There may be any number of Subnet commands, and there may be up to 20 stations in one subnet.

This command supports a "|" symbol in the list of stations. It differenitates those stations to be used in the trigger count (stations to the left of "|") and those stations that are not. All stations in a subnet are recorded if sufficient stations to the left of the "|" are triggered.

The "subnet" command supports non-numeric subnet names of a maximum of 9 characters. These non-numeric names are now stored and passed through to later routines through the triglist2k message. If the subnet name is numeric, no subnet name is passed through to later routines. Currently, the subnet names are used only in filenames written by sudsputaway.

    Default:  none
    Examples: Subnet 2   4   LO2.EHZ.UW FMW.EHZ.UW RER.EHZ.UW RCM.EHZ.UW RCS.EHZ.UW
              Subnet RG  3   MLK.VHZ.NC MEM.VHZ.NC MSL.VHZ.NC MCS.VHZ.NC MCM.VHZ.NC

SubnetContrib [nsecs]
Processed by: ReadConfig
Function: Subnet parameters

Specifies the number of seconds nsecs that each triggered subnet contributes to the total duration of the network trigger. The minimum trigger duration is the sum of PreEventTime, NetTriggerDur and SubnetContrib times the number of subnets that triggered.

    Default:  none
    Example:  SubnetContrib   15

TrigIdFilename [filename]
Processed by: ReadConfig
Function: Earthworm setup

Tells carlsubtrig which filename to find the next_id for the trigger id's. If this is used, then the hard coded command @trig_id.d should not be used.

    Default:  none
    Example:  TrigIdFilename trig/trig_id.d

### SAMPLE CONFIGURATION FILE

     #
    # CarlSubTrig's Parameter File
    #

    #
    #  Basic Earthworm Setup
    #
    MyModuleId	MOD_CSU_TEST	# Module id for this instance of CarlSubTrig -
    				#
    Debug		2		# Write out debug messages? (0 = No,
    				#   1 = Minimal, 3 = Chatterbox )
    RingNameIn	PICK_RING	# Name of ring from which station triggers
    				#   will be read - REQUIRED.
    RingNameOut	HYPO_RING	# Name of ring to which triggers will be
    				#   written - REQUIRED.
    HeartBeatInterval	30	# Heartbeat Interval (seconds).

    #
    # CarlSubTrig Specific Setup
    #
    StationFile	"pnsn_trig.sta"	# Name of file containing station information -
    				#   REQUIRED.
    Latency		15		# Number of seconds that the Network clock
    				#   is behind wall clock REQUIRED.
    NetTriggerDur   10		# Number of seconds for the base network
    				#   trigger duration REQUIRED.
    SubnetContrib   15		# Addition contribution to network trigger
    				#   duration for each subnet that triggered
                                    #   REQUIRED.
    PreEventTime	10		# Number of seconds added to beginning of
    				#   network trigger REQUIRED.
    MaxDuration     500		# Maximum duration allowed for network trigger
    DefStationDur   120		# Default number of seconds for station
    				#   trigger duration if the trigger-off
    				#   message is not received. REQUIRED.
    ListSubnets     1               # Flag to list untriggered stations
                                    #   =0 or command not present: list all
                                    #        triggered stations
                                    #   =1 list all stations in triggered subnets
                                    #   =2 list all stations in triggered subnets
                                    #        plus any other triggered stations.
                                    #   =3 list all stations in subnets that had
                                    #        any stations triggered
    AllSubnets      10              # If this many subnets trigger, put wildcard
                                    #   SCNL in event message
    CompAsWild                      # Flag (no value) to list component names in
                                    #   trigger messages as `*' (wildcard).
    MaxTrigMsgLen   30000           # maximum length (bytes) of a triglist message;
                                    #   up to MAX_BYTES_PER_EW (earthworm.h).

    # Load the next valid trigger sequence number
    # this is one way to specify where the next id comes from:
    @trig_id.d            # this name is hard-coded; do not change

    # or you can use this now so you can place it somewhere else:

    TrigIdFilename  trig/trig_id.d   # a new way to specify where the trig_id.d command

    # List the message logos to grab from transport ring
    #              Installation       Module          Message Types (hard-wired)
    GetEventsFrom  INST_WILDCARD    MOD_WILDCARD    # TYPE_CARLSTATRIG # REQUIRED.

    # Non-seismic or other channels that should be included in all event messages
    # List one SCNL per line, as many as you need
    Channel  *.TIM.UW
    Channel  LON.LHZ.UW.--

    # Subnet definitions for the CarlSubTrig Earthworm module
    # Each Subnet must be on a single line
    # Subnet  Minimum to      List of Station.Component.Network
    # Number  Trigger         Codes (space delimited)
    # ------- ---  -------------------------------------------
    Subnet 0   3   CRF.EHZ.UW.-- EPH.EHZ.UW.-- GBL.EHZ.UW.-- MDW.EHZ.UW.-- OT3.EHZ.UW.-- RC1.EHZ.UW.-- VT2.EHZ.UW.-- WA2.EHZ.UW.-- WRD.EHZ.UW.--
    Subnet 1   4   BRV.EHZ.UW.-- ET3.EHZ.UW.00 GBL.EHZ.UW.00 MDW.EHZ.UW.00 OT3.EHZ.UW.-- PRO.EHZ.UW.-- RSW.EHZ.UW.-- WA2.EHZ.UW.--

### 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

### Download in other formats:

- Plain Text