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:
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).
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.
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.
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.
1. IMPORTANT NOTE
2. FUNCTIONAL COMMAND LISTING
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
3. ALPHABETIC COMMAND LISTING & DESCRIPTION
command arg1 processed by function
AllSubnets nsubnets ReadConfig 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 ReadConfig 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 ReadConfig 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 ReadConfig 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 ReadConfig 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 ReadConfig 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 ReadConfig 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 ReadConfig Earthworm setup
Defines the number of seconds, nsec between TYPE_HEARTBEAT messages issued by carlsubtrig.Default: none Example: HeartBeatInterval 30
IgnoreCoincident ReadConfig Earthworm setup IgnoreCoincident nsubs 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 ReadConfig 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 ReadConfig 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 ReadConfig 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 ReadConfig 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 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_CARLSUBTRIG
NetTriggerDur nsecs ReadConfig 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 ReadConfig 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 ReadConfig 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 ReadConfig 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 ReadConfig 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 ... ReadSubnet 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 ReadConfig Subnet parametersSpecifies 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 ReadConfig 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
4. 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.--
5. 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
Contact: Questions? Issues? Subscribe to the Earthworm Google Groups List.