On startup, eqassemble reads the configuration file named on the command-line. Commands in this file set up all parameters used in making earthquake notifications. In the control file, lines may begin with a valid eqassemble 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).
Below are the commands recognized by eqassemble, grouped by the function they
influence. Some of the commands are marked "required"; they describe the
Earthworm system setup and the network model. These commands must be
specified in the control file in order for eqassemble to operate.
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 Calnet are listed after each command description.
The final TYPE_EVENT2K message is assigned version number 2. This version
number will show up
in the hypoinverse archive message produced by hyp2000_mgr, usually the last
program in the "sausage".
The FinalRule command is optional. If it is absent, the final ruleset
will not be applied and no version 2 event messages will be released from
eqassemble. However, you must have at least one of PrelimRule, RapidRule,
FinalRule, or eqassemble won't have anything to do.
Note that on unix-like systems, you can precede the command with "exec". This
will cause the shell which invokes the command to be replaced by the command
instead of remaining as the command's parent process. Using this trick in
the PipeTo command in each of the sausage sub-programs will save you from
keeping several shell instances for no useful purpose.
The PrelimRule command is optional. If it is absent, the preliminary
ruleset will not be applied and no version 0 event messages will be released
from eqassemble.
However, you must have at least one of PrelimRule, RapidRule, FinalRule, or
eqassemble won't have anything to do.
This ruleset is intended to be
used to initiate a magnitude calculation as soon as possible after an event,
before the binder solution has stablized.
The PrelimRule command is optional. If it is absent, the preliminary
ruleset will not be applied and no version 0 event messages will be released
from eqassemble. However, you must have at least one of PrelimRule, RapidRule, FinalRule, or
eqassemble won't have anything to do.
The eqassemble "mega-module" is a chain of processes that produces
final earthquake locations for the Earthworm system. Only eqassemble, the first link in the mega-module, is listed
in startstop's configuration file to be started by startstop. Eqassemble
then starts the next process, specified in its "PipeTo" command, and
communicates with it via a pipe.
Each newly created process starts the next link in the same way.
From startstop's point of view, the whole mega-module inherits the name
of the first link (eqassemble) and that's the only name it displays.
From statmgr's point of view, all processes
within the mega-module share one module id, one heartbeat, and one
descriptor file. However, each process has its own configuration file
and its own log file.
Note that Earthworm logo of heartbeat and error messages from all the
"mega-module" processes is set by hyp2000_mgr, not by eqassemble or any other
sausage process.
As of 11 February 2007, the eqassemble mega-module consists of
the following "links":
1. EXAMPLE CONFIGURATION FILE
# This is Eqassemble's Parameter File
# Basic Earthworm setup:
#-----------------------
MyModuleId MOD_EQASSEMBLE # Module id for this instance of eqassemble
RingName PICK_RING # Ring to get input from
HeartbeatInt 30 # seconds between heartbeats to statmgr
LogFile 1 # 0 = turn off disk log file;
# 1 = turn on disk log
# 2 = write disk log but not to stderr/stdout
# List the message logos to grab from transport ring
# Installation Module Message Types
#-----------------------------------------------------------------
GetPicksFrom INST_WILDCARD MOD_WILDCARD # pick2k & coda2k
GetAssocFrom INST_MENLO MOD_BINDER # quake2k & link2k
# Send output to the following command (uncomment one):
#------------------------------------------------------
PipeTo "exec eqbuf eqbuf.d" # buffer events for downstream modules
#PipeTo "log_everything" # end chain here for debugging
# Load station list
#------------------
maxsite 3500
site_file calsta.hinv
# Load crustal model
# Refer to file containing "lay" commands, or list them here
#-----------------------------------------------------------
# Set pick/quake FIFO lengths (must be >= binder's fifo lengths)
#---------------------------------------------------------------
pick_fifo_length 1000 # optional: default = 1000
quake_fifo_length 100 # optional: default = 100
# Control how/when events are reported
#-------------------------------------
ReportS 0 # 0 = do not send S-phases to next process
# non-zero = do send S-phases to next process
HypCheckInterval 5.0 # interval (sec) at which to check all hypocenters
# to see if it's time to report an event
# Rules for reporting events
#---------------------------
# At least one of these rules must be given; there are no defaults
# Syntax:
# PrelimRule numPhases
# Event2K message released with version 0 when event has
#
2. FUNCTIONAL COMMAND LISTING
Earthworm system setup:
GetAssocFrom required
GetPicksFrom required
MyModuleId required
PipeTo required
RingName required
pick_fifo_length
quake_fifo_length
Seismic network/model definition:
lay required
psratio
site \ site list required; specify with
site_file / either "site" or "site_file"
maxsite
Event Notification:
PrelimRule
RapidRule
FinalRule
CodaFromInst
HypCheckInterval
ReportS required
DataSrc
MaxPhasesPerEq
Output Control:
LogFile required
WaifTolerance
3. ALPHABETIC COMMAND LISTING & DESCRIPTION
command arg1 processed by function
CodaFromInst inst_id eqas_config Event Notification
Identify from which installations (by inst_id)
eqassemble should wait for coda messages for the FinalRule, other than the local inst_id. This optional command is only useful if the
FinalRule is turned on and configured to WaitForCodas. If you are importing
TYPE_PICK_SCNL and TYPE_CODA_SCNL messages from other Earthworm installations,
then you may want eqassemble to wait for those codas. But if another Earthworm
installation was sending only TYPE_PICK_SCNL messages, then you would not want
eqassemble to wait for those TYPE_CODA_SCNL messages. You can list as many
CodaFromInst as needed. But you do not need to list your own inst_id.
Default: none
Calnet: CodaFromInst INST_UCB
DataSrc name eqas_config Event Notification
Identify the source of the phase data with a single-character
name. This code will be inserted into the hypoinverse
input message by eqcoda and will be passed through hypoinverse to show up in
the hypoinverse archive message as the Data Source Code (column 109 in the
phase lines.)
Default: " "
Calnet: DataSrc W
FinalRule Np Msec WaitForCodas eqas_config Event Notification
The final TYPE_EVENT2K message will be released after binder has not changed
the solution (no TYPE_QUAKE2K messages) in Msec seconds,
provided there are at least Np P phases associated
with the event. If the optional string WaitForCodas is
included in the FinalRule command, eqassemble will wait up to 150 seconds after
a phase arrival until the corresponding coda message is received. Normally the
extra wait for codas applies only to TYPE_CODA_SCNL messages from the local
inst_id. Use the CodaFromInst command to tell
eqassemble to wait for codas from other Earthworm installations.
Default: none
Calnet: FinalRule 4 60 WaitForCodas
GetAssocFrom inst mod_id eqas_config Earthworm setup
Controls the association messages input to eqassemble. Eqassemble will only
process quakes and links 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 2 "Get*From" commands may be issued; wildcards (INST_WILDCARD and
MOD_WILDCARD) will force eqassemble to process all quakes & links,
regardless of their place of origin.
Default: none
Calnet: GetAssocFrom INST_MENLO MOD_BINDER
GetPicksFrom inst mod_id eqas_config Earthworm setup
Controls the pick and coda message input to eqassemble. Eqassemble will only
process picks and codas 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 2 "Get*From" commands may be issued; wildcards (INST_WILDCARD and
MOD_WILDCARD) will force eqassemble to process all picks & codas,
regardless of their place of origin.
Note: both binder and eqassemble should be set to listen to the same pick source(s)!
Default: none
Calnet: GetPicksFrom INST_WILDCARD MOD_WILDCARD
HypCheckInterval M eqas_config Event Notification
Check the list of currently active events every M
seconds to see if they are ready for release under the rapid or final rules.
Default: 10 (seconds)
Calnet: HypCheckInterval 5
lay depth velocity t_com model
Defines the layered velocity structure to be used for calculating
travel times. depth is the distance (km) to the top of the layer,
and velocity is the seismic P-wave velocity (km/sec) within that
layer. No default velocity structure is defined; therefore, the user
must always supply one in the control file. Up to 20 layers can be
specified, and they should be listed in order of increasing depth.
Note: binder and eqassemble calculate travel times independently. Be
sure that both programs are using the same velocity model!
Default: none Calnet: lay 0.0 4.0
lay 3.5 5.9
lay 15.0 6.85
lay 25.0 7.85
LogFile switch eqas_config output
Sets the on-off switch for writing a log file to disk. If switch
is 0, no log file will be written. If switch is 1, eqassemble will
write a daily log file(s) called eqassemblexx.log_yyyymmdd where xx is
eqassemble's module id (set with "MyModuleId" command) and yyyymmdd is the
current UTC date (ex: 19960123) on the system clock. The file(s) will
be written in the EW_LOG directory (environment variable).
Default: none
maxsite N eqas_config Event Notification
Restrict the number of phases to be reported for the RapidRule and FinalRule
to nsite. Cannot be set greater than
the Earthworm limit of 250, which is also the default for this parameter.
Default: MaxPhasePerEq 250
Calnet: MaxPhasePerEq 250
maxsite nsite site_com model
Allocates memory to store nsite station locations in the site table.
Default: maxsite 1000 Calnet: maxsite 1000
MyModuleId mod_id eqas_config Earthworm setup
Sets the module id for labelling all outgoing messages. mod_id is
a character string (valid strings are listed in earthworm.d) that
relates (in earthworm.d) to a unique single-byte number.
Default: none Calnet: MyModuleId MOD_EQASSEMBLE
pick_fifo_length N eqas_config Earthworm setup
Specify the size of the pick FIFO buffer as N picks.
This value should be at least as large as binder's
pick_fifo_length.
Default: 1000
Calnet: pick_fifo_length 4000
PipeTo cmdstring eqas_config Earthworm setup
Sets the command to which eqassemble will pipe a "binder-finalized" event
for the next step in earthquake processing. Blank spaces are allowed
in cmdstring as long as the entire command is enclosed
in double-quotes.
Default: none
Calnet: PipeTo "exec eqbuf eqbuf.d"
PrelimRule N eqas_config Event Notification
The preliminary TYPE_EVENT2K message will be released when N P phases are associated with the event, provided that no
higher version TYPE_EVENT2K has already been released for the event. The
preliminary event message is assigned version 0.
Default: none
Calnet: PrelimRule 25
psratio value t_com model
Sets the value of the P/S seismic velocity ratio.
Default: psratio 1.72 Calnet: psratio 1.72
quake_fifo_length N eqas_config Earthworm setup
Specify the size of the quake FIFO buffer as N events.
This value should be at least as large as binder's
quake_fifo_length.
Default: 100
Calnet: quake_fifo_length 100
RapidRule Np Msec SinceX eqas_config Event Notification
The "rapid" TYPE_EVENT2K message will be released at a fixed time after either
event origin time, or event detection time (when eqassemble receives the first
TYPE_QUAKE2K message for the event), provided at least Np P phases are associated with the event. The time delay is
specified as Msec seconds. The starting time of the delay
is given in the SinceX string, which can be either
SinceOrigin or SinceDetection. This TYPE_EVENT2K will be
assigned version 1. It will not be released by eqassemble is a higher version
message has already be released for the event.
Default: none
Calnet: RapidRule 5 30 SinceOrigin
ReportS switch eqas_config notification
Sets the switch for reporting picks that binder has associated as
S-phases. If switch is 0, S-phases are not sent along to the next
process; if switch is non-zero, S-phases are included in the event
message (hypocenter plus associated picks) that is sent to the next
process.
Default: none Calnet: ReportS 0
RingName ring eqas_config Earthworm setup
Tells eqassemble 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 Calnet: RingName PICK_RING
site name latitude longitude site_com model
Enters a station location into the station site table, where name is
the station code used by the picker, and latitude and longitude
are expressed in decimal degrees (positive to the north and east).
Use either multiple "site" commands or one "site_file" command to load
the station list into eqassemble.
site_file filename site_com model
Enters site codes and station locations into the site table by reading
a HYPOINVERSE format station file called filename. In this file,
stations are described by a 5-letter site name, a 2-letter network
code and a 3-letter component code. The picker must also be using
this station-naming convention. The format of the file is described
under "NEW HYPOINVERSE STATION FILE FOR FULL 10-LETTER STATION NAMES"
in calsta2.doc by Fred Klein. Use either one "site_file" command or
multiple "site" commands to load the station list into eqassemble.
WaifTolerance N eqas_config OutPut Control
When eqassemble is preparing to release a final (version 2) TYPE_EVENT2K
message, it logs information about phases associated with the event, and about
phases not associated with this event but which have "small" travel time
residuals relative to this event. This command gives the largest absolute
value residual as N seconds. See Description of eqassemble's log file for more details
about eqassemble's log files.
Default: none
Calnet: WaifTolerance 4.0
4. DESCRIPTION OF EQASSEMBLE'S LOG FILE
Eqassemble writes a number of different lines of information to its log file
when an event is first detected, as binder evolves its location, and when
eqassemble releases the various versions of TYPE_EVENT2K message or the
TYPE_CANCELEVENT messages. This section describes the log file entries.
Every time eqassemble grabs a TYPE_QUAKE2K message from the shared memory
ring, it writes a line to its log file. It's sort of giving you a time-stamped
summary of binder's output. Here are some example lines and what they contain:
146 56.00:70131066 146 41.07 38.3540 -122.7992 18.00 0.00 0.0 0.0 0 5
146 56.00:70131066 146 39.49 38.2606 -122.7295 25.50 0.18 19.7 54.7 282 5
146 56.00:70131066 146 39.48 38.2603 -122.7294 25.50 0.27 19.8 54.0 282 6
123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789
field columns Description
(approx)
1,2 1-10 System time (hrmn sec) at which this TYPE_QUAKE2K message
was received.
3 12-19 Binder's event id.
4,5 21-30 hrmn sec of event origin time
6 32-39 latitude
7 41-49 longitude
8 50-55 depth
9 56-60 rms
10 61-65 dmin: distance to nearest station
11 66-70 ravg: average epicentral distance of all associated stations
12 72-74 maximum azimuthal gap
13 75-77 total # picks associated with this event.
You'll notice that the first line has zero's for rms, dmin, ravg, and gap.
This is binder's initial stack location for the event.
The subsequent locations for the event come from binder's simple L1 locator.
------------------------------------------------------------------------------
The log entries for an event meeting the rapid rule set produces log entries
similar to these:
147 51.00:70131066 #### Rapid report: 200702120146_66
70131066 2007Feb12 146 48.02 38.8037 -122.7957 0.65 0.10 0.5 21.6 73 13
GCR EHZ NC 02 2007Feb12 146 49.64 P D0 7.7 0.00
GBG EHZ NC -- 2007Feb12 146 50.14 P D1 10.1 0.01
GSG EHZ NC 02 2007Feb12 146 50.19 P U0 10.4 -0.00
GAX EHZ NC -- 2007Feb12 146 50.37 P D2 10.9 0.08
GPM EHZ NC 02 2007Feb12 146 50.97 P U0 14.2 -0.00
GRT EHZ NC -- 2007Feb12 146 51.33 P D2 18.6 -0.58
GMK EHZ NC -- 2007Feb12 146 52.39 P ?2 18.4 0.53
NHS EHZ NC -- 2007Feb12 146 52.75 P D3 23.0 -0.05
GSS EHZ NC -- 2007Feb12 146 52.76 P U2 22.5 0.06
NMT EHZ NC -- 2007Feb12 146 54.03 P D2 30.9 -0.13
NSH EHZ NC -- 2007Feb12 146 54.94 P U2 35.7 -0.00
NEA EHZ NC -- 2007Feb12 146 59.15 P ?2 56.4 0.81
123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789
The first line tells you that a rapid message is being released
Field Description
1,2 system time (hrmn sec) when the event met the "rapid" ruleset
3 binder's event id,
5 a string that contains the event origin time (yyyymmddhhmm_xx)
where xx is the last 2 digits of the event id.
The second line is a summary line with:
Field Description
1 the event id from binder
2,3,4 origin time,
5 latitude,
6 longitude,
7 depth,
8 rms,
9 dmin,
10 ravg,
11 gap,
12 # associated phases.
The remaining lines describe the phases associated with the event:
columns Description
1-10 station (site,net,component),
12-21 arrival time,
31-32 phase that binder called it,
33 polarity,
34 pick quality (0-4),
35-40 epicentral distance, and
41-47 traveltime residual (sec).
49-? optional comment (only in final event report)
------------------------------------------------------------------------------
When eqassemble decides that binder is finished with an event, you'll see
a set of lines that look something like this:
148 16.00:70131066 #### Final report: 200702120146_66
70131066 2007Feb12 146 48.02 38.8037 -122.7957 0.65 0.10 0.5 21.6 73 13
GCR EHZ NC 02 2007Feb12 146 49.64 P D0 7.7 0.00
GBG EHZ NC -- 2007Feb12 146 50.14 P D1 10.1 0.01
GSG EHZ NC 02 2007Feb12 146 50.19 P U0 10.4 -0.00
GAX EHZ NC -- 2007Feb12 146 50.37 P D2 10.9 0.08
GPM EHZ NC 02 2007Feb12 146 50.97 P U0 14.2 -0.00
GRT EHZ NC -- 2007Feb12 146 51.33 P D2 18.6 -0.58
GMK EHZ NC -- 2007Feb12 146 52.39 P ?2 18.4 0.53
NHS EHZ NC -- 2007Feb12 146 52.75 P D3 23.0 -0.05
GSS EHZ NC -- 2007Feb12 146 52.76 P U2 22.5 0.06
NMT EHZ NC -- 2007Feb12 146 54.03 P D2 30.9 -0.13
NSH EHZ NC -- 2007Feb12 146 54.94 P U2 35.7 -0.00
NEA EHZ NC -- 2007Feb12 146 59.15 P ?2 56.4 0.81
KPK EHZ WR -- 2007Feb12 146 59.15 P ?2 158.3 0.54 WAIF
ANT SHZ NN -- 2007Feb12 146 59.15 Pn?2 388.7 -0.98 WAIF
ANT SHZ NN -- 2007Feb12 146 59.15 Pg?2 388.7 -3.04 WAIF
MGN SHZ NN -- 2007Feb12 146 59.15 Pn?2 380.6 3.86 WAIF
MGN SHZ NN -- 2007Feb12 146 59.15 Pg?2 380.6 1.87 WAIF
ADH SHZ NN -- 2007Feb12 146 59.15 PgD2 374.3 3.89 WAIF
TER EHZ CI -- 2007Feb12 146 59.15 PnU1 491.7 -2.77 WAIF
123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789
The format is the same as for the preliminary and rapid event reports, except
that the phase lines may have entries in the comment field here.
These are the lines that have either "#xxxx" (an event id) or "WAIF" written
after the residual in the optional comment field. These are phases that
eqassemble thought could possibly have been associated with this event, but
that weren't. If the comment is "#xxxx" then that phase is actually
associated with a different event (whose id is xxxx). If the comment is
"WAIF" then the phase is not associated at all.
5. THE "MEGA-MODULE" WHICH BEGINS WITH EQASSEMBLE
SUB-MODULE INPUT FROM OUTPUT TO
---------- ---------- ---------
eqassemble shared memory (PICK_RING) pipe to eqbuf
eqbuf stdin (pipe from eqassemble) pipe to eqcoda
eqcoda stdin (pipe from eqbuf) pipe to eqverify
eqverify stdin (pipe from eqcoda) pipe to hyp2000_mgr
hyp2000_mgr stdin (pipe from eqverify) shared memory (HYPO_RING)
Inter-link (Intra-mega-module) Communication:
All messages are passed between the processes of the mega-module
via pipes. The pipe communications are encapsulated in a set of routines containing
the peculiarities of the operating system. Messages, with types defined
in earthworm.d, are sent from one link to the next, in one direction only!
If a process
doesn't need to do anything with a given message type, it just pipes it
along to the next link. The current pipe routines (in pipe.c) are:
pipe_init starts up the next "link", replacing its stdin with
a pipe from the "parent" program.
pipe_put writes a message of a given type to the pipe.
pipe_get gets the next message from the pipe.
pipe_close closes the pipe.
Heartbeats:
The mega-module has one module-id and one heartbeat. The heartbeat
initiates at the first link (eqassemble), is piped through all the links, and is
deposited into shared memory by the last link (in this case, hyp2000_mgr).
If any of the links dies,
no heartbeat will be seen by statmgr and it will complain appropriately.
Error Messages:
Since the whole mega-module has only one module-id, the sub-modules need
to share the complete set of error numbers within a common descriptor file.
Each link is assigned a
block of error numbers to use for its complaints. Each link passes along
any error messages it reads from the pipe. The last link puts all error
messages into shared memory where they are available to statmgr.
Statmgr reads one descriptor file for the mega-module.
Final Output from Mega-module:
The last link in the mega-module, hyp2000_mgr, deposits heartbeats, error
messages, and event messages
(that look like hypoinverse archive files) onto shared memory where any
other Earthworm module can find them.
Contact: Questions? Issues? Subscribe to the Earthworm Google Groups List.