wiki:eqprelim

Version 4 (modified by branden, 8 years ago) (diff)

--

Earthworm Module: eqprelim

Contributed by:

Function

Initiates preliminary event processing (alternate head of mega-module).

Details

Eqprelim is a first process in the earthquake-processing mega-module (sometimes referred to as "the sausage") that produces preliminary earthquake locations for the Earthworm system. Eqprelim is very similar to eqroc, which produces Earthworm's final event locations. 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 one-directional pipe. Each newly created sub-module 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 sub-module has its own configuration file and its own log file.

After starting up the next link in "the sausage," eqprelim's main job is to gather information from picker(s) and binder, to decide when it's time to report a preliminary hypocenter for a given event, to assemble all the information related to that event, and to pass it on to the next event-processing sub-module.

Eqprelim collects messages from the picker(s) (TYPE_PICK2K and TYPE_CODA2K) and from binder (TYPE_QUAKE2K and TYPE_LINK). A TYPE_PICK2K message contains an observed P-wave arrival-time and amplitude for a given seismic channel along with the installation id, module id, and pick sequence number; the picker releases the pick message within ~3 seconds of a P-wave detection. A TYPE_CODA2K message contains coda duration and amplitude information along with the installation id, module id, and sequence number of the pick it relates to; the picker releases the coda message up to 144 seconds after its corresponding pick message. A TYPE_QUAKE2K message contains an event id number, origin time and hypocenter; binder issues a new quake message each time it associates a new pick with [or deletes pick(s) from] a given event id. A TYPE_LINK message contains an event id, an installation id, a picker module id, a pick sequence number and a phase identifier; binder issues a new link message for every pick it associates with (or deletes from) an active event.

Eqprelim maintains two circular buffers:

  1. Pick list Contains the most recent MAXPCK (=1000) picks and their coda and link information (related by installation id, module id and pick sequence number) and the system-time that the pick was entered.
  1. Quake list Contains the most recent location and status of the last MAXHYP (=100) event ids and the system-time that the location was entered.

Each time eqprelim receives a TYPE_QUAKE2K message, it checks to see how many phases are associated with that event id. If the number of P-arrivals associated the event is greater than or equal to "NumPickNotify" (set in the configuration file), eqprelim initiates preliminary earthquake processing.

Eqprelim:

  1. gathers from its pick list all picks linked to that event id. If some picks do not have coda information yet, eqprelim continues the preliminary processing with zeroed coda information for those picks.
  2. builds an ascii TYPE_EVENT2K message containing the event's location and all of its supporting phase information,
  3. pipes the TYPE_EVENT2K message to the next process in the mega-module,
  4. notes in its quake list that the status of this event id is "preliminary location done."

Eqprelim will initiate only one preliminary location per binder event id, so NumPickNotify should be set at the number of phases where most event locations become stable. Often, no coda information or only poor coda information is available at the time eqprelim initiates the preliminary location. Thus most preliminary locations will have poor or absent duration magnitudes.

Note: It is possible that binder may kill an event (decide it was not real) after eqprelim has initiated the preliminary location. Eqprelim does not send out any kind of "event killed" messages. One must assume that if a final location (via eqproc) does not arrive within a given time interval (say 5-10 minutes), then the preliminary location was for a busted event.

Configuration File Commands

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:

#  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!).

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
#
@ncal_model.d# Load the central California crustal model

FUNCTIONAL COMMAND LISTING

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.

	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

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 Calnet are listed after each command description.

The following list is organized by:

command [argument here]

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.

THE "MEGA-MODULE" WHICH BEGINS WITH EQPRELIM

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":

  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.

Helpful Hints