Changes between Version 3 and Version 4 of eqassemble


Ignore:
Timestamp:
05/26/12 11:46:51 (8 years ago)
Author:
branden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • eqassemble

    v3 v4  
    192192command [argument here] 
    193193 
     194CodaFromInst inst_id            eqas_config             Event Notification        
     195Identify 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. 
     196 
     197Default:  none 
     198Calnet:   CodaFromInst  INST_UCB 
     199 DataSrc name           eqas_config             Event Notification        
     200Identify 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.) 
     201 
     202Default:  " " 
     203Calnet:   DataSrc  W 
     204 FinalRule Np Msec WaitForCodas         eqas_config             Event Notification        
     205The 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. 
     206The 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". 
     207 
     208The 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. 
     209 
     210 
     211Default:  none 
     212Calnet:   FinalRule     4 60 WaitForCodas 
     213 GetAssocFrom inst mod_id               eqas_config             Earthworm setup   
     214Controls 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. 
     215 
     216Default:  none 
     217Calnet:   GetAssocFrom  INST_MENLO  MOD_BINDER 
     218 GetPicksFrom inst mod_id               eqas_config             Earthworm setup   
     219Controls 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. 
     220Note: both binder and eqassemble should be set to listen to the same pick source(s)! 
     221 
     222Default:  none 
     223Calnet:   GetPicksFrom  INST_WILDCARD  MOD_WILDCARD 
     224 HypCheckInterval M             eqas_config             Event Notification        
     225Check the list of currently active events every M seconds to see if they are ready for release under the rapid or final rules. 
     226 
     227Default:  10 (seconds) 
     228Calnet:   HypCheckInterval   5 
     229 lay depth velocity                    t_com                   model      
     230Defines 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. 
     231Note: binder and eqassemble calculate travel times independently. Be sure that both programs are using the same velocity model! 
     232 
     233Default:  none                          Calnet:  lay   0.0  4.0 
     234                                                 lay   3.5  5.9 
     235                                                 lay  15.0  6.85 
     236                                                 lay  25.0  7.85 
     237 LogFile switch                         eqas_config             output    
     238 
     239Sets 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). 
     240 
     241Default:  none 
     242 maxsite N                               eqas_config            Event Notification        
     243Restrict 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. 
     244         
     245Default:  MaxPhasePerEq 250 
     246Calnet:   MaxPhasePerEq 250 
     247 maxsite nsite                           site_com                model    
     248Allocates memory to store nsite station locations in the site table. 
     249         
     250Default:  maxsite 1000                  Calnet:  maxsite 1000 
     251 MyModuleId mod_id                      eqas_config             Earthworm setup   
     252Sets 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. 
     253 
     254Default:  none                          Calnet:  MyModuleId MOD_EQASSEMBLE 
     255 pick_fifo_length N             eqas_config             Earthworm setup   
     256Specify the size of the pick FIFO buffer as N picks. This value should be at least as large as binder's pick_fifo_length. 
     257 
     258Default:  1000 
     259Calnet:   pick_fifo_length 4000 
     260 PipeTo cmdstring                       eqas_config             Earthworm setup   
     261Sets 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. 
     262Note 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. 
     263 
     264 
     265Default:  none 
     266Calnet:   PipeTo "exec eqbuf eqbuf.d" 
     267 PrelimRule N           eqas_config             Event Notification        
     268The 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. 
     269The 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. 
     270 
     271 
     272Default:  none 
     273Calnet:   PrelimRule    25 
     274 psratio value                           t_com                   model    
     275 
     276Sets the value of the P/S seismic velocity ratio. 
     277 
     278Default:  psratio  1.72                 Calnet:  psratio  1.72 
     279 quake_fifo_length N            eqas_config             Earthworm setup   
     280Specify the size of the quake FIFO buffer as N events. This value should be at least as large as binder's quake_fifo_length. 
     281 
     282Default:  100 
     283Calnet:   quake_fifo_length  100 
     284 RapidRule Np Msec SinceX               eqas_config             Event Notification        
     285The "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. 
     286This ruleset is intended to be used to initiate a magnitude calculation as soon as possible after an event, before the binder solution has stablized. 
     287 
     288The 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. 
     289 
     290 
     291Default:  none 
     292Calnet:   RapidRule     5 30 SinceOrigin 
     293 ReportS switch                         eqas_config             notification      
     294 
     295Sets 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. 
     296 
     297Default:  none                          Calnet:  ReportS  0 
     298 RingName ring                          eqas_config             Earthworm setup   
     299Tells 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. 
     300 
     301Default:  none                          Calnet:  RingName PICK_RING 
     302 site name latitude longitude           site_com                model     
     303Enters 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. 
     304 site_file filename                     site_com                model     
     305 
     306Enters 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. 
     307 WaifTolerance N                eqas_config             OutPut Control    
     308When 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. 
     309 
     310Default:  none 
     311Calnet:   WaifTolerance  4.0 
     312 
     313 
     314=== DESCRIPTION OF EQASSEMBLE'S LOG FILE === 
     315 
     316{{{ 
     317Eqassemble writes a number of different lines of information to its log file 
     318when an event is first detected, as binder evolves its location, and when 
     319eqassemble releases the various versions of TYPE_EVENT2K message or the 
     320TYPE_CANCELEVENT messages. This section describes the log file entries. 
     321 
     322Every time eqassemble grabs a TYPE_QUAKE2K message from the shared memory 
     323ring, it writes a line to its log file.  It's sort of giving you a time-stamped 
     324summary of binder's output.  Here are some example lines and what they contain: 
     325 
     326 146 56.00:70131066  146 41.07  38.3540 -122.7992 18.00 0.00  0.0  0.0   0  5 
     327 146 56.00:70131066  146 39.49  38.2606 -122.7295 25.50 0.18 19.7 54.7 282  5 
     328 146 56.00:70131066  146 39.48  38.2603 -122.7294 25.50 0.27 19.8 54.0 282  6 
     329123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 
     330 
     331field  columns   Description 
     332       (approx) 
     3331,2      1-10    System time (hrmn sec) at which this TYPE_QUAKE2K message 
     334                 was received. 
     335 3      12-19    Binder's event id. 
     3364,5     21-30    hrmn sec of event origin time 
     337 6      32-39    latitude 
     338 7      41-49    longitude 
     339 8      50-55    depth 
     340 9      56-60    rms 
     34110      61-65    dmin: distance to nearest station 
     34211      66-70    ravg: average epicentral distance of all associated stations 
     34312      72-74    maximum azimuthal gap 
     34413      75-77    total # picks associated with this event. 
     345 
     346You'll notice that the first line has zero's for rms, dmin, ravg, and gap. 
     347This is binder's initial stack location for the event. 
     348The subsequent locations for the event come from binder's simple L1 locator. 
     349 
     350------------------------------------------------------------------------------ 
     351 
     352The log entries for an event meeting the rapid rule set produces log entries 
     353similar to these: 
     354 
     355 147 51.00:70131066 #### Rapid report: 200702120146_66 
     35670131066 2007Feb12  146 48.02  38.8037 -122.7957  0.65 0.10  0.5 21.6  73 13 
     357GCR   EHZ NC  02 2007Feb12  146 49.64 P D0   7.7   0.00 
     358GBG   EHZ NC  -- 2007Feb12  146 50.14 P D1  10.1   0.01 
     359GSG   EHZ NC  02 2007Feb12  146 50.19 P U0  10.4  -0.00 
     360GAX   EHZ NC  -- 2007Feb12  146 50.37 P D2  10.9   0.08 
     361GPM   EHZ NC  02 2007Feb12  146 50.97 P U0  14.2  -0.00 
     362GRT   EHZ NC  -- 2007Feb12  146 51.33 P D2  18.6  -0.58 
     363GMK   EHZ NC  -- 2007Feb12  146 52.39 P ?2  18.4   0.53 
     364NHS   EHZ NC  -- 2007Feb12  146 52.75 P D3  23.0  -0.05 
     365GSS   EHZ NC  -- 2007Feb12  146 52.76 P U2  22.5   0.06 
     366NMT   EHZ NC  -- 2007Feb12  146 54.03 P D2  30.9  -0.13 
     367NSH   EHZ NC  -- 2007Feb12  146 54.94 P U2  35.7  -0.00 
     368NEA   EHZ NC  -- 2007Feb12  146 59.15 P ?2  56.4   0.81 
     369123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 
     370The first line tells you that a rapid message is being released 
     371Field    Description 
     372 1,2     system time (hrmn sec) when the event met the "rapid" ruleset 
     373  3      binder's event id, 
     374  5      a string that contains the event origin time (yyyymmddhhmm_xx) 
     375         where xx is the last 2 digits of the event id. 
     376 
     377The second line is a summary line with: 
     378Field    Description 
     379  1      the event id from binder 
     380 2,3,4   origin time, 
     381  5      latitude, 
     382  6      longitude, 
     383  7      depth, 
     384  8      rms, 
     385  9      dmin, 
     386 10      ravg, 
     387 11      gap, 
     388 12      # associated phases. 
     389 
     390The remaining lines describe the phases associated with the event: 
     391    columns  Description 
     392       1-10  station (site,net,component), 
     393      12-21  arrival time, 
     394      31-32  phase that binder called it, 
     395         33  polarity, 
     396         34  pick quality (0-4), 
     397      35-40  epicentral distance, and 
     398      41-47  traveltime residual (sec). 
     399      49-?   optional comment (only in final event report) 
     400 
     401------------------------------------------------------------------------------ 
     402 
     403When eqassemble decides that binder is finished with an event, you'll see 
     404a set of lines that look something like this: 
     405 
     406 148 16.00:70131066 #### Final report: 200702120146_66 
     40770131066 2007Feb12  146 48.02  38.8037 -122.7957  0.65 0.10  0.5 21.6  73 13 
     408GCR   EHZ NC  02 2007Feb12  146 49.64 P D0   7.7   0.00 
     409GBG   EHZ NC  -- 2007Feb12  146 50.14 P D1  10.1   0.01 
     410GSG   EHZ NC  02 2007Feb12  146 50.19 P U0  10.4  -0.00 
     411GAX   EHZ NC  -- 2007Feb12  146 50.37 P D2  10.9   0.08 
     412GPM   EHZ NC  02 2007Feb12  146 50.97 P U0  14.2  -0.00 
     413GRT   EHZ NC  -- 2007Feb12  146 51.33 P D2  18.6  -0.58 
     414GMK   EHZ NC  -- 2007Feb12  146 52.39 P ?2  18.4   0.53 
     415NHS   EHZ NC  -- 2007Feb12  146 52.75 P D3  23.0  -0.05 
     416GSS   EHZ NC  -- 2007Feb12  146 52.76 P U2  22.5   0.06 
     417NMT   EHZ NC  -- 2007Feb12  146 54.03 P D2  30.9  -0.13 
     418NSH   EHZ NC  -- 2007Feb12  146 54.94 P U2  35.7  -0.00 
     419NEA   EHZ NC  -- 2007Feb12  146 59.15 P ?2  56.4   0.81 
     420KPK   EHZ WR  -- 2007Feb12  146 59.15 P ?2 158.3   0.54 WAIF 
     421ANT   SHZ NN  -- 2007Feb12  146 59.15 Pn?2 388.7  -0.98 WAIF 
     422ANT   SHZ NN  -- 2007Feb12  146 59.15 Pg?2 388.7  -3.04 WAIF 
     423MGN   SHZ NN  -- 2007Feb12  146 59.15 Pn?2 380.6   3.86 WAIF 
     424MGN   SHZ NN  -- 2007Feb12  146 59.15 Pg?2 380.6   1.87 WAIF 
     425ADH   SHZ NN  -- 2007Feb12  146 59.15 PgD2 374.3   3.89 WAIF 
     426TER   EHZ CI  -- 2007Feb12  146 59.15 PnU1 491.7  -2.77 WAIF 
     427123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 
     428 
     429The format is the same as for the preliminary and rapid event reports, except 
     430that the phase lines may have entries in the comment field here. 
     431These are the lines that have either "#xxxx" (an event id) or "WAIF" written 
     432after the residual in the optional comment field.  These are phases that 
     433eqassemble thought could possibly have been associated with this event, but 
     434that weren't.  If the comment is "#xxxx" then that phase is actually 
     435associated with a different event (whose id is xxxx).  If the comment is 
     436"WAIF" then the phase is not associated at all. 
     437}}} 
     438 
     439 
     440=== THE "MEGA-MODULE" WHICH BEGINS WITH EQASSEMBLE === 
     441 
     442The 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. 
     443 
     444Note 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. 
     445 
     446As of 11 February 2007, the eqassemble mega-module consists of the following "links": 
     447{{{ 
     448  SUB-MODULE    INPUT FROM                      OUTPUT TO 
     449  ----------    ----------                      --------- 
     450  eqassemble    shared memory (PICK_RING)       pipe to eqbuf 
     451  eqbuf         stdin (pipe from eqassemble)    pipe to eqcoda 
     452  eqcoda        stdin (pipe from eqbuf)         pipe to eqverify 
     453  eqverify      stdin (pipe from eqcoda)        pipe to hyp2000_mgr 
     454  hyp2000_mgr   stdin (pipe from eqverify)      shared memory (HYPO_RING) 
     455}}} 
     456 
     457==== Inter-link (Intra-mega-module) Communication ==== 
     458 
     459All 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: 
     460{{{ 
     461  pipe_init     starts up the next "link", replacing its stdin with 
     462                a pipe from the "parent" program. 
     463  pipe_put      writes a message of a given type to the pipe. 
     464  pipe_get      gets the next message from the pipe. 
     465  pipe_close    closes the pipe. 
     466}}} 
     467 
     468==== Heartbeats ==== 
     469 
     470The 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. 
     471 
     472==== Error Messages ==== 
     473 
     474Since 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. 
     475 
     476==== Final Output from Mega-module ==== 
     477 
     478The 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. 
    194479 
    195480