On startup, eqprelim reads the configuration file named on the command-line. Commands in this file set up all parameters used in making preliminary earthquake notifications. In the control file, lines may begin with a valid eqprelim 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).
Below are the commands recognized by eqprelim, 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 eqprelim 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 eqprelim "mega-module" is a chain of processes that produces
preliminary earthquake locations for the Earthworm system. Only eqprelim, the first link in the mega-module, is listed
in startstop's configuration file to be started by startstop. Eqprelim
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 (eqprelim) 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.
As of 10 October, 1996, the eqprelim mega-module consists of
the following "links":
1. EXAMPLE CONFIGURATION FILE
#
# This is eqprelim's parameter file
# Basic Earthworm setup:
#
MyModuleId MOD_EQPRELIM # module id for this instance of eqprelim
RingName PICK_RING # ring to get input from
LogFile 1 # 0 to completely turn off disk log file
HeartbeatInt 30 # Seconds between heartbeats
# 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 # quake & link
LocalCode W # single char to identify local picks with
ReportS 0 # if 0, do not send S-phases to next process
NumPickNotify 25 # send preliminary event when it has this
# many picks associated with it
# Send output to the following command:
# PipeTo "eqbuf eqbuf.d"
# PipeTo "eqcoda eqcoda.d"
PipeTo "log_everything"
# Load station list
#
maxsite 1800
site_file "calsta.hinv"
# Load Central California crustal model
#
2. FUNCTIONAL COMMAND LISTING
Earthworm system setup:
GetAssocFrom required
GetPicksFrom required
MyModuleId required
PipeTo required
RingName required
Seismic network/model definition:
lay required
psratio
site \ site list required; specify with
site_file / either "site" or "site_file"
maxsite
Event notification:
NumPickNotify required
LocalCode required
ReportS required
Output Control:
LogFile required
3. ALPHABETIC COMMAND LISTING & DESCRIPTION
command arg1 processed by function
GetAssocFrom inst mod_id eqp_config Earthworm setup
Controls the association messages input to eqprelim. Eqprelim 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 eqprelim to process all quakes & links,
regardless of their place of origin.
Default: none
Calnet: GetAssocFrom INST_MENLO MOD_BINDER
GetPicksFrom inst mod_id eqp_config Earthworm setup
Controls the pick and coda message input to eqprelim. Eqprelim 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 eqprelim to process all picks & codas,
regardless of their place of origin.
Note: both binder and eqprelim should be set to listen to the same pick source(s)!
Default: none
Calnet: GetPicksFrom INST_WILDCARD MOD_WILDCARD
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 eqprelim 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
LocalCode x eqprelim_config notification
Sets the single-character label, x, to identify local picks with
in the message sent to the next process. Any picks which were
imported from other sources will be labeled with an I. Ultimately,
this character ends up in the Hypoinverse archive message in column 92
of the phase line. x must not be surrounded by quotes and it must
not be I!
Default: none Calnet: LocalCode W
LogFile switch eqp_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, eqprelim will
write a daily log file(s) called eqprelimxx.log_yymmdd where xx is
eqprelim's module id (set with "MyModuleId" command) and yymmdd is the
current UTC date (ex: 960123) on the system clock. The file(s) will
be written in the EW_LOG directory (environment variable).
Default: none
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 eqp_config Earthworm setup
Sets the module id for labeling 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_EQPRELIM
NumPickNotify npck eqprelim_config notification
Sets the threshold for initiating preliminary event processing.
When an event has at least npck P-arrivals associated with it,
eqprelim will pipe that event to the process specified in the "PipeTo"
command. Eqprelim will initiate only one preliminary location per
binder eventid, so npck should be set at the number of phases
where most event locations become stable (where additional picks
won't change the location).
Note: it is possible that binder may kill an event after eqprelim
has reported it, and eqprelim does not send out any kind of
"event killed" message.
Default: none Calnet: NumPickNotify 25
PipeTo cmdstring eqp_config Earthworm setup
Sets the command to which eqprelim will pipe a preliminary 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 "eqbuf eqbuf.d"
psratio value t_com model
Sets the value of the P/S seismic velocity ratio.
Default: psratio 1.72 Calnet: psratio 1.72
ReportS switch eqp_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 eqp_config Earthworm setup
Tells eqprelim 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 eqprelim.
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 "HYPOINVERSE STATION FILE FOR FULL 12-LETTER (S-N-C-L) CHANNEL NAMES". Use either one "site_file" command or
multiple "site" commands to load the station list into eqprelim.
4. THE "MEGA-MODULE" WHICH BEGINS WITH EQPRELIM
SUB-MODULE INPUT FROM OUTPUT TO
---------- ---------- ---------
eqprelim shared memory (PICK_RING) pipe to eqbuf
eqbuf stdin (pipe from eqprelim) pipe to eqcoda
eqcoda stdin (pipe from eqbuf) pipe to eqverify
eqverify stdin (pipe from eqcoda) pipe to hypo_mgr
hypo_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 (eqprelim), is piped through all the links, and is
deposited into shared memory by the last link (in this case, hypo_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, hypo_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.