# Eqproc Configuration File Commands

(last revised September 8, 1999)
Page Index:
1. Example configuration file
2. Functional command listing
3. Alphabetic command listing & description
4. Description of eqproc's log file
5. The "mega-module" which begins with eqproc

On startup, eqproc 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 eqproc 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!).

## 1. EXAMPLE CONFIGURATION FILE

    #              This is Eqproc's Parameter File

    MyModuleId  MOD_EQPROC     # Module id for this instance of eqproc

    RingName    PICK_RING      # Ring to get input from

    LogFile     1              # 0 to completely turn off disk log file

    ReportS     0              # If 0, don't send S-phases to next process

    PipeTo    "eqbuf eqbuf.d"  # Send output to this command

    maxsite     2000           # Maximum stations in station list

    rpt_dwell   60.0

    rpt_grab    4.0

    # print                    # For debugging

    # graph                    # For debugging

    site_file "calsta.hinv.qa"    # Station list used by hypoinverse

@ncal_model.d# Load the central California crustal model

    # The message logos to grab from transport ring

    #              Installation       Module          Message Types

    GetPicksFrom   INST_WILDCARD    MOD_WILDCARD    # pick2k & coda2k

    GetAssocFrom   INST_MENLO       MOD_BINDER_EW      # quake2k & link

## 2. FUNCTIONAL COMMAND LISTING

Below are the commands recognized by eqproc, 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 eqproc 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:

    		rpt_dwell

    		rpt_grab

    		ReportS		required

    	Output Control:

    		LogFile		required

    		print

    		graph

## 3. 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.

    command arg1				processed by		function

    GetAssocFrom inst mod_id		eqp_config		Earthworm setup

> Controls the association messages input to eqproc. Eqproc 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 eqproc 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 eqproc. Eqproc 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 eqproc to process all picks & codas, regardless of their place of origin.
> Note: both binder and eqproc should be set to listen to the same pick source(s)!

>     Default:  none

>     Calnet:   GetPicksFrom  INST_WILDCARD  MOD_WILDCARD

    graph  					eqp_config 		output

> Requests that a graphical representation of all phases and their residuals be written to a file named GRyyyymmddhhnn## (see "print" command for naming convention). The plot displays the time-residual horizontally and the epicentral distance vertically. See Johnson (1994) for a more complete description of this graph. This file is useful for tuning and debugging.

>     Default:  don't write the GR* file

    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 eqproc 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				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, eqproc will write a daily log file(s) called eqprocxx.log_yyyymmdd where xx is eqproc'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 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_EQPROC

    PipeTo cmdstring			eqp_config		Earthworm setup

> Sets the command to which eqproc 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 "eqbuf eqbuf.d"

    print					eqp_config		output

> Requests that the final hypocenter and phase summary data for each event be written to a file. The file's name combines the earthquake's origin-time and the last 2 digits of its event id# (assigned by binder) in the form PRyyyymmddhhnn## where yyyy is the year, mm is the month, dd is the day of the month, hh is the hour (0-23), nn is the minutes past the hour, and ## is the last 2 digits of the event id. For example, picks from event id# 1399 on July 12, 1995 at 0123 GMT would be found in PR19950712012399. All phases with a residual less than maxres ("rpt_grab" command) are included in this file regardless of how the picks are associated. Picks are tagged with the phase that is being considered. If a pick is associated with a different event, it is labeled with that event's id#. If a pick is not associated with any event, it is labeled as WAIF. This file is useful for tuning and debugging.

>     Default:  don't write the PR* file

    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 eqproc 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

    rpt_dwell treport			eqp_config		notification

> Sets the length of time (seconds) to wait after the last modification to a hypocenter before reporting the event.

>     Default:  rpt_dwell 30.0		Calnet:  rpt_dwell 60.0

    rpt_grab maxres				eqp_config		notification

> Defines the maximum residual (seconds) for reporting a given phase with respect to an event. maxres should span binder's allowed residual range for associating picks (see binder's "taper" and "taper_OT" commands); otherwise, eqproc may not list all picks that binder associated with the event. All phases with a residual less than maxres are included in an event's PR* file ("print" command) and GR* file ("graph" command), regardless of how the picks are associated.

>     Default:  rpt_grab 4.0			Calnet:  rpt_grab 4.0

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

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

## 4. DESCRIPTION OF EQPROC'S LOG FILE

    Eqproc writes a line to its log file every time it grabs a TYPE_QUAKE2K

    message from the shared memory ring.  It's sort of giving you a time-stamped

    log of binder's output.  Here are some example lines and what they contain:

    2338  8.00:       8 1617 19.70  33.8140 -116.9780  4.00 0.00  0.0  0.0   0  6

    2338  8.00:       8 1617 19.32  33.8298 -116.9644  2.21 0.06 20.4 61.7 139  6

    2338  8.00:       8 1617 19.32  33.8298 -116.9644  2.21 0.20 20.4100.9  83 12

    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.

    ------------------------------------------------------------------------------

    When eqproc decides that binder is finished with an event, you'll see

    a set of lines that look something like this:

    1835 37.00:    9312 #### PR19970130173412

        9312 1997Jan30 1734 16.67  38.8100 -122.8079  3.75 0.09  1.2 12.7  75  9

    GDX  NCVHZ 1997Jan30 1734 17.63 P U0   1.2  -0.00

    GAC  NCVHZ 1997Jan30 1734 18.51 P D0   8.5  -0.24

    GGP  NCVHZ 1997Jan30 1734 18.55 P D3   6.0   0.22

    GCR  NCVHZ 1997Jan30 1734 18.74 P U0   9.0  -0.09

    GPM  NCVHZ 1997Jan30 1734 19.46 P U0  12.8  -0.02

    GBG  NCVHZ 1997Jan30 1734 19.23 P U0  11.0   0.05

    GSG  NCVHZ 1997Jan30 1734 19.13 P U0  10.7  -0.00

    GMK  NCVHZ 1997Jan30 1734 20.43 P D2  17.8   0.10

    NSH  NCVHZ 1997Jan30 1734 23.99 P U1  36.7   0.46

    ASM  NCVHZ 1997Jan30 1734 48.76 Pn 3 186.6   3.60 WAIF

    ASM  NCVHZ 1997Jan30 1734 48.76 Pg 3 186.6   2.18 WAIF

    MLH  NCVHZ 1997Jan30 1735 17.11 PgU1 372.8   3.35 WAIF

    PMR  NCVHZ 1997Jan30 1735 19.09 PgU2 405.1   0.61 WAIF

    PKY  NCVHZ 1997Jan30 1735 23.09 PgU2 436.6   0.01 WAIF

    123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789

    The first line tells you that an event has been finalized:

    Field    Description

     1,2     system time (hrmn sec) when the event was declared "final,"

      3      binder's event id,

      5      a string that contains the event origin time (PRyyyymmddhhmmxx)

             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  polariy,

             34  pick quality (0-4),

          35-40  epicentral distance, and

          41-47  traveltime residual (sec).

          49-?   optional comment.

    Some of these lines may have either "#xxxx" (an event id) or "WAIF" written

    after the residual in the optional comment field.  These are phases that

    eqproc 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 EQPROC

The eqproc "mega-module" is a chain of processes that produces final earthquake locations for the Earthworm system. Only eqproc, the first link in the mega-module, is listed in startstop's configuration file to be started by startstop. Eqproc 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 (eqproc) 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 8 September 1999, the eqproc mega-module consists of the following "links":

      SUB-MODULE    INPUT FROM   		  	OUTPUT TO

      ----------	----------		  	---------

      eqproc 	shared memory (PICK_RING)	pipe to eqbuf

      eqbuf   	stdin (pipe from eqproc)   	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 (eqproc), 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.

Module Index | Eqproc Overview