orbgenloc orb [-S statefile -pf pffile]
orbgenloc uses the ggnloc (Generalized Gauss-Newton location) function of genloc. The user must keep this in mind. This algorithm is subject to the well known adage of geophysical inversion theory that, "No amount of mathematical trickery can compensate for a fundamental lack of information." That is because this uses the standard iterative algorithm it can, and will, diverge in some circumstances. It will post an answer back into the orb only if the algorithm converges. Otherwise it issues a diagnostic to the error log and goes on.
statefile is an optional input statefile. orbgenloc uses the orbresurrect functions to save the packet id of the last event it processed. For caution's sake orbgenloc saves its state immediately after reading a complete block of data and immediately before trying to locate the given event. The practical consequence of this is that if orbgenloc dies for some reason inside the location algorithm, the event that caused problems will be SKIPPED. This avoids a deadly infinite loop of unending resurrections and crashes in the event of a programming bug in orbgenloc. (Unlike Microsoft I admit my code may contain bugs.) This parameter defaults to state/orbgenloc.pf.
pffile is an optional input parameter to read initial startup parameters from. The default is orbgenloc (Note: because of the way pfread works, this means the actual file name is orbgenloc.pf, and a chain of directories can be searched depending upon the setting of the environment variable PFREAD. See pf(3)) This parameter file is read at startup to build an initial pf object used as a control structure. This parameter file can be relatively complex due to the long list of options in genloc (see genloc_intro(3)).
orbgenloc works by selecting only db packets. The basic algorithm is as follows:
Note that the last step of this algorithm can fail if multiple processes emit assoc and/or arrival records. In order to prevent this the program limits the number of records that can be skipped in hunting for an arrival row associated with an arid identified by an assoc. This is prehaps overly cautious as this should be a rare event even if multiple processes emitted assoc records because orbassoc emits these packets in a single burst and the probability of an intervening assoc record causing problems is very low. On the other hand, it is probably prudent anyway because it make the program simply more robust in the presence of data errors as well.
orbgenloc's output is a series of Datascope db records saved with db2orbpkt. This version writes what it can compute into three standard css3.0 db tables: origin, origerr, and assoc. These records are then written back to the orb as /db/ packets where it is assumed they will be archived by orb2db. Note orbgenloc does NOT generate an event record. It was my prejudice that sorting out the preferred origin defined in the event record is better done at a later stage. A key reason for this is that orbgenloc was designed to potentially allow multiple instances of the program to be running off the same orb with different parameters. (see below) If each is generating origin records along with that created initially by orbassoc, it is a more complex task to sort out which is the "best" origin estimate.
In addition to all the parameters defined in genloc_intro(3), the following are special control parameters for orbgenloc.
RT_working_db. This is the master database. Normally it would be expected to be the SAME database that orb2db or orb2dbt is writing into. It is ESSENTIAL that orbgenloc be run with two conditions: (1) RT_working_db MUST be on a local disk for the machine orbgenloc is running on, and (2) the table locking mechanism MUST be enabled. This is necessary because orbgenloc opens this database r+ and alters the lastid table with each event by calling dbnextid for orid. This is essential to avoid id conflicts with orbassoc or other locators running off the same orb.
RT_logfile_directory and RT_failure_sdir. orbgenloc does a complete dump of its parameter space for each event it processes and writes this information into one of two directories defined by this pair of parameters. For each event that is successfully located orbgenloc creates a parameter dump of it's parameter state and convergence history in the RT_logfile_directory in a file called oridnnn.pf where nnn is the orid with which this file is associated (e.g. orid789.pf is the result from location for orid 789.) Along with the control parameters orbgenloc was run under this file also contains the convergence history of the algorithm and a verbose dump of the computed residuals and weights. These files contain some information found nowhere else due to the fact that genloc contains features not defined in the css3.0 schema. The same information (although some can sometimes be empty) is dumped to the subdirectory defined by RT_failure_sdir whenever a location cannot be determined for any reason. (i.e. when ggnloc returns an error.) The location of this "failure" directory is assumed to exist as a subdirectory below RT_logfile_directory with a name defined by RT_failure_sdir. (e.g. if RT_logfile_directory=/s/rtlogs and RT_failure_sdir="failures", the logfiles for locations that failed would appear in /s/rtlogs/failures.) If multiple instances of orbgenloc are run against the same orb and the same master database, it is important that each instance have a seperate directory entry for RT_failure_sdir. If they do not, and both instances fail to produce a solution for the same event the file names will collide and at best only one of the results will be saved. NOTE: RT_logfile_directory defaults to ".", and RT_failure_sdir defaults to "failures". orbgenloc ASSUMES both directories exist. Also it should go without saying that you must have write permission in this directory or orbgenloc will fail.
RT_minimum_distance and RT_maximum_distance are distance sifting parameter in degrees. These parameters define an important design feature of orbgenloc. The feature is that orbgenloc will ONLY process events whose initial location, as determined by orbassoc, is within the distance range min < delta < max from the "origin" (The origin in orbgenloc isdefined by the genloc parameters center_latitude and center_longitude that are otherwise used for an initial solution using a grid search. ) The purpose of this is that it is always necessary to run different parameters for the program for local, regional, and teleseismic events. Furthermore, it is usually desirable to use different travel time calculators for different distances. With this mechanism it is expected a network would commonly use something like the following: (1) standard layered model calculator for local events, depth always a free parameter; (2) a regional velocity model for events some distance outside the network, depth fixed; and (3) tau-p travel time calculator for teleseismic events (if appropriate), depth fixed. To implement this three instances of orbgenloc would need to be run against the same orb, each running with a different initial -pf argument. Finally, on this point, note that multiple programs may have overlapping values of this parameter. In that instance multiple origin records produced by orbgenloc will be produced for some events.
RT_db_record_skip_limit implements the sanity check to avoid errors with interleaved assoc/arrival db records (see above). A sane choice would be to set this parameter to the number of stations in the network.
velocity_model_name name to be used in model field for output db records. No checking is made to see if this is consistent with anything else, so be warned. This could cause problems a user should be aware of when using the generic tt interface where a model is given a specific name in a different field in the parameter file.
The user may choose to run orbgenloc with an initial location chosen by one of the method available in genloc (see genloc_intro(3)) instead of using the intial location passed to it by orbassoc. This can be accomplished by setting the "initial_location_method" parameter in the parameter file to something other than "manual". In general, however, I would not recommend this except perhaps for testing purposes.
relocate(1), sgnloc(1), dbloc2(1), genloc_intro(3), genloc(3), ggnloc(3), pfread(3), elog(3)
Three things are worth reiterating: