Phase Definition Parameter Files in genloc

The genloc Phase_handle object related parameter file definitions:


The first thing to understand about the phase definitions parameter files is that they are an encapsulation of an object-oriented definition of what I call a "phase handle" in genloc.  That is the phase handle is a C structure (C++ object) that encapsulates all the information required in the location process to deal with a given phase name.  This is an important flexibility element of genloc as it allows arbitrarily complex calculators to be assigned to any phase that can be tagged with a unique name.  If you know C, you might find the following definition from the location.h include file for libgenloc to be helpful:


typedef struct Phase_handle {
        char *name;
        Distance_weight_function *arrival_time;
        Distance_weight_function *ux,*uy;
        float deltat0, deltau0;
        double deltat_bound, deltau_bound;
 
        Arr *time_station_corrections;
        Arr *ux_sc, *uy_sc;
        Travel_Time_Function_Output (*ttcalc)();
        Slowness_Function_Output (*ucalc) ();
} Phase_handle;

Now let's compare this to an example phase definition for genloc for a P phase:

P  &Arr{
        travel_time_calculator general
        TTmodel kyrghyz
        TTmethod tt1dcvl tt1dcvl u1dcvl
        time_distance_weight_function &Tbl{
        0.0     1.0
        2.5     1.0
        3.0     0.25
        5.0     0.01
        92.0    0.01
        360.0   0.0
        }
        ux_distance_weight_function &Tbl{
        0.0     1.0
        180.0   1.0
        }
        uy_distance_weight_function &Tbl{
        0.0     1.0
        180.0   1.0
        }
        default_time_uncertainty 0.1
        default_slowness_uncertainty 0.01
        dt_bound_factor 0.01
        du_bound_factor 0.035
        time_station_corrections &Tbl{
AAK -1.24
CHM 0.54
ULHL -0.2
        }
        ux_station_corrections &Tbl{
        }
        uy_station_corrections &Tbl{
        }
}

The name field in the parameter file is used to define a key that indexes this phase handle in genloc so the program can quickly find the method to handle, in this case, a P phase.  The string "P" is also saved in the name field of the phase handle.

The most important variable in the parameter file is the one called travel_time_calculator.   The last two lines in the typedef for the Phase_handle object are a C construct for a pointer to an external function.  Internally when genloc initializes it resolves these pointers to a particular travel time calculator defined by a keyword it gets from the travel_time_calculator  parameter.  At the time of this writing the acceptable names associated with the travel_time_calculator parameter are:  general, ttlvz,  and "uniform table interpolation".  ttlvz and uniform interpolation are in the process of being phased out (see genloc_ttinterface(3) for more details on these calculators).  The preferred approach for the future is to use the "general" interface which uses the generic interface described in the antelope man pages under tt(3).  The example above uses this interface.  The TTmethod and TTmodel parameters define the method and model parameters passed to the generic tt interface.   The example above looks in a velocity model database (see  velocity model schema document. ) for a model named "kyrghyz" and says to use the method called "tt1dcvl" (a simple 1d, flat-earth, travel time calculator implemented through the generic travel time interface -- functionally the same as ttlvz).

Distance weighting is controlled by the time_distance_weight_function, ux_distance_weight_function, and uy_distance_weight function definitions.  When distance weight is turned on in these define ordered pairs of (distance (degrees), weight) values that define a continuous distance weighting function by linear fits between the given node point.  The example above for time uses a weight of 1.0 to a distance of 2.5 degrees then dropping in two stages to a small value at 5 degrees, then falling to 0 beyond 92 degrees.  The ux and uy weight functions are for array slowness vector measurements.  In this example, they are null.  When any of the distance weight function tables are empty genloc defaults to a weight of 1.0 for all distances (effectively turning distance weighting off for that particular phase).   Note that genloc ALWAYS uses vector components ux,uy to specify slowness vector data.  Normally one should assume the same weight function should be used for both components, but this is generalized here to be different if desired.

The default_time_uncertainty and default_slowness_uncertainty map directly into the deltat0 and deltau0 entries in the phase handle object.  As described in the man pages for genloc arrival time and slowness vector weighting always turned on.  If the deltim, delslo, and delaz fields in the arrival table are filled in these are used to weight each measurement by the reciprocal of that number.  If a field is null these parameters set the default value of uncertainty for this phase for time and slowness  vector data respectively.

The dt_bound_factor  and du_bound_factor are used in a model error bound calculator computed by genloc.  See the genloc man pages for more information on this.  Most people will likely not want to change these.

Overall File structure


The overall structure of a phase parameter definition file is like this:

velocity_model_name myvelocitymodel
phases &Arr{

P  &Arr{
-- as in example above --
}
S &Arr{
-- as in example above --
}
Pn &Arr{
-- as in example above --
}
S-P &Arr{
-- as in example above --
}

}


That is, each token with the &Arr after it defines a Phase_handle object for the phase name it is associated with.  For the example above this is:  P, S, Pn, and S-P.  Other phases can be added if desired.  Each phase may use any method or model you wish to use provided you complete the rest of the description properly for the calculator you choose.  For example, it is quite possible to use the taup calculator to complute P phase arrival times and use a 1d layered model calculator to compute Pn arrival times.  A potentially confusing point here is that you will quickly note that there are two different "velocity model name" quantities.  The one inside the phase handle (tagged as TTmodel) is used only to search the database for the keyword name that tags a given model.  It is essentially a lower level model name tag.  The one shown above as myvelocitymodel above that appears as a separate parameter in the phase definition is a global name tagged to this model.  Currently the primary use of this keyword is for tagging an origin estimate produced by dbgenloc.  That is the auth field of dbgenloc will contain an entry of the form "dbgenloc:myvelocitymodel" (Noting, of course, that the auth field is not wide enough to actually contain the tag used here.  You should use more cryptic labels like "kyrg".)

There is one feature here that requires a separate discussion.  One of the phase handles listed above has the tag "S-P".  The genloc library now accepts "minus" phases and automatically forces processing in this form in certain circumstances.  S-P is the type example of a minus phase where the raw arrival times are replaced by the difference in arrival time of the two phases.  They are most valuable when dealing with data containing timing problems since the differencing removes the dependence upon the origin time.   It is possible to use only minus times for a list of stations or have the feature automatically implemented using a database table called "timing.   See the man pages on genloc for more details on this feature.