Program: MKLOCSMITH

  mklocsmith.......LOCSMITH main program: location of Earthquakes on grids
 
  call: [exitstatus,loc,mygrid]=mklocsmith(lsopt,statcat,seisdat);
        [exitstatus,loc,mygrid]=mklocsmith(lsopt,statcat,seisdat,mygrid);
 
            lsopt: (structure)
                   LOCSMITH options structure as returned by MKLSOPT
 
          statcat: (structure)
                   Optional LSD structure containing Station descriptions
                   This struct may contain station descriptions
                   (coordinates) to be used when the SEISDAT structure does
                   not contain all station information (or no station info
                   at all)
                   This might be empty [], then only the station
                   information from the SEISDAT structure is used.
 
                   IMPORTANT:
                   It is not checked if STATCAT and SEISDAT contain
                   contradictory informations, e.g. different coordinates
                   for the same station. If such contradictory data is
                   given, it is undefined which information is actually
                   used, and phantastic things may happen!
 
          seisdat: (structure)
                   LSD structure containing seismic arrival data for a
                   single event. The structure may optionally contain
                   station information data.
 
                   NOTE: _some_ station information must be given! If
                   neither STATCAT nor SEISDAT contain station info, the
                   location cannot be carried out!
 
           mygrid: (structure)
                   Optional grid structure: The output of a previous run of
                   MKLOCSMITH can be used as input, i order to further
                   refine the grid. This is useful if the previous solution
                   is not compatible with all data or is suspect to be
                   incomplete. You can also just produce a solution with
                   better resolution.
                   BUT: if this is the output of MKLOCSMITH, then
                   MKLOCSMITH had some reason to quit. So if you restart
                   with this grid and the same LSOPT as before, MKLOCSMITH
                   will quit immediately, since the termination condition
                   is still true. So you have to change at least one of the
                   iteration control parameters in LSOPT!
 
 
  result: 
          exitstatus: (string)
                   a string denoting the reason why MKLOCSMITH came to a
                   halt. This string should be considered when evaluating
                   the output. The follwiong values are possible:
 
                   'unexpected': the exit status is initialized with this
                                 value. At any legal exit condition, a new
                                 value should be written into the string.
                                 If this is not the case, the init value
                                 remains, because the stopping of the
                                 routine was indeed due to an unexpected
                                 reason. This should never occur.
 
                   'no data':    There is no data to evaluate. No grid is
                                 generated and no location produced.
 
                   'vertically converged':  
                                 The desired spatial grid resolution for the
                                 location has been reached. The routine
                                 quits because the job is done.
 
                   'vertical iteration timeout':
                                 The maximum number of iterations to
                                 deterimine the focal depth has been
                                 reached. This limit is defined in
                                 lsopt.iter_vertical_max.
                                 If this occurs, the job is NOT done and
                                 you should probably retry the location 
                                 with a higher iter_layer_max limit.
                                 lsopt.iter_vertical_max is intended to be an
                                 emergency brake to avoid infinite
                                 iteration, not a standard tool to finish
                                 the program!
 
                   'horizontal iteration timeout': 
                                 The maximum number of iterations to 
                                 determine the horizontal extent of the 
                                 location has been reached. 
                                 This limit is defined in lsopt.iter_max.
                                 If this occurs, the job is NOT
                                 done and you should probably repeat the
                                 location with a higher iter_max limit.
                                 lsopt.iter_max is intended to be an
                                 emergency brake to avoid infinite
                                 iteration, not a standard tool to finish
                                 the program!
 
          incomp: (numeric array) [counter]
                  final incompatiblity status as determined by
                  MKLSGRIDEVALINCOMP. 
 
                  incomp(1): This value shows how many of the data
                            are not compatible with the returned solution.
                            0: all data compatible. congratulations, you have located
                            the quake!
                            >0: a number of INCOMP data values is not compatible with
                                the observations. You should look into MYGRID and
                                into the data to find out the reason (outlier data,
                                wrong velocity model or other problems)
                                Running MKLOCSMITH at higher verbosity (level 4 or higher)
                                will give hints which data are not compatible.
                  incomp(2): This is just the total number of data against
                             which the nodes were checked. You need this to
                             find out how severe the incompatibility really is.
 
          loc: (structure)
               This structure contains the 4D coordinates of those node
               which fit the data best. The details of the structure depend
               on grid type, see MKLSGRIDEXTRACTLOC for details.
               
                    
 
          mygrid: (structure array)
                  The search grid as it is at the end of the location
                  process. This is a LOCSMITH search grid structure as
                  returned by MKLSGRIDNEW.
 
 
  MKLOCSMITH is the main routine of the LOCSMITH package. This routine is
  the one called by the user in order to locate a quake. It drives the
  construction and subsequent modifcation of the search grid and the
  evaluation of the seismoligcal data on this grid.
 
  ALGORITHM:
 
  In the outermost loop, the maximum attainable compatibility with the
  given data is computed as one dimensional integer function of the vertical
  coordinate (depth or radius, depending on grid type). The maxima of this
  function are searched.
  For each value of the vertical coordinate, a whole layer is evaluated to
  determine the compatiblity as function of the horizontal coordinates. The
  iteration of layers therefore serves as the method to determine the
  function values of compatibility as function of depth/radius.
 
 
  Martin Knapmeyer, 03.02.2005, 04.07.2005, 05.02.2007

Read M-File Source Code


eof.