wiki:eqassemble

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

--

Earthworm Module: eqassemble

Contributed by: CISN

Function

Initiates event processing multiple times (CISN contrib) v7.2 addition

Details

Eqassemble is the first process in the earthquake-processing mega-module (sometimes referred to as "the sausage") that produces 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 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 (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 sub-module has its own configuration file and its own log file.

Eqassemble is the result of merging three other Earthworm programs: eqprelim, eqrapid (used only at Caltech), and eqproc. This merger was needed for the CISN project. It results in a single module that can release event messages meeting any of three different rule sets that are derived from the original programs' rules. By merging the three programs into one, we also gain by having to run only a single sausage instead of three.

After starting up the next link in "the sausage," eqassemble's main job is to gather information from picker(s) and binder, to decide when en event is ready for release, to assemble all the information related to that event, and to pass it on to the next event-processing sub-module.

Eqassemble collects messages from the picker(s) (TYPE_PICK_SCNL and TYPE_CODA_SCNL) and from binder (TYPE_QUAKE2K and TYPE_LINK). A TYPE_PICK_SCNL message contains an observed P-wave (or S-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_CODA_SCNL 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.

Eqassemble 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.

Eqassemble applies up to three configurable rule sets to decide when to release event messages. These rule sets are:

preliminary rule:

N (=25) P phases associated with the event. At Menlo Park, this is used to publish a preliminary location (with no magnitude) for an event of potential interest to the public. This event message is assigned version 0.

rapid rule:

release the event message N (=90) seconds after either origin time or detection time, provided there are at least M (=5) P phases associated with the event. This message is used in CISN to initiate Ml calculations. The waiting time is to allow sufficient waveforms to be available to compute local magnitude as rapidly as feasible. This event message is assigned version 1.

final rule:

release the event message N (=60) seconds after binder has stopped updating the solution, provided there are M (=4) associated P phases. In addition, eqassemble can optionally wait for the TYPE_CODA_SCNL messages for this event. If eqassemble is configured to wait for codas, it will wait until coda messages are received for all associated picks; but not more that 150 seconds. The 150 second wait duration is not configurable, since it is based on the 144 second coda time of pick_ew. This event message is assigned version 2.

If eqassemble is configured not to wait for codas, then the event message produced by eqassemble will contain no coda durations. This option is intended for networks which do not want to produce duration magnitudes with the Earthworm sausage.

Occasionally, binder will decide to cancel event on which it has been working, It indicates this by reducing the number of associated picks to zero. If eqassemble sees this happen after it has released any version of the event message, it will issue a TYPE_CANCELEVENT message.

Occasionally, eqassemble will receive more TYPE_QUAKE2K and TYPE_LINK message for a given event id after it has finalized that event. Eqassemble will note these messages in its log file, but it will never send another TYPE_EVENT2K message thru the mega-module for that event id.

Configuration File Commands

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

Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!).

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


# 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
#		 P phases associated.
#	RapidRule numPhases seconds SinceOrigin
#     or
#	RapidRule numPhases seconds SinceDetection
#		Event2K message released with version 1  since
#		origin or detection time provided  P phases
#		associated.
#	FinalRule numPhases seconds [WaitForCodas]
#		Event2K message released with version 2 when solution has
#		been stable for , has  P phases associated,
#		and optionally after codas have arrived.
# Codas are reported only with the FinalRule and only if the
# WaitForCodas flag is included in the FinalRule command
#
PrelimRule    25
RapidRule     5 30 SinceDetection
FinalRule     4 60 WaitForCodas

# If we are going to wait for codas, and some picks are imported from
# other Earthworm Installations, eqassemble can optionally wait for codas
# from those other installations with one or more of:
# CodaFromInst InstId
# You do not need to list your own Inst ID.
# CodaFromInst is ignored if the FinalRule does not wait for codas.
CodaFromInst INST_MENLO

# DataSrc: single character to indicate the source of phase data
DataSrc    W

# MaxPhasesPerEq: restrict the number of phases to be reported for
# the RapidRule and FinalRule to this value. Cannot be set greater than
# the Earthworm limit of 250, which is also the default for this parameter
MaxPhasesPerEq 250

# Control debugging info to log
#------------------------------
 WaifTolerance   4.0  # tolerance (sec) for noting waif picks for
		      #   in log file. (optional: default = 4.0)

FUNCTIONAL COMMAND LISTING

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.

	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

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]

Helpful Hints