.. _global_stdloc:

######
StdLoc
######

Generic locator plugin for SeisComP.

Description
===========

StdLoc is a SeisComP locator plugin that combines standard location methods
and was developed with the focus on local seismicity, although the methods
are generic enough to work at larger scales as well.


Plugin
======

To enable StdLoc the plugin ``stdloc`` must be loaded. Add this value to the
global configuration parameter :confval:`plugins` as or similar to

.. code-block:: sh

   plugins = ${plugins},stdloc


How does it work?
=================

The locator can apply a multitude of location methods and it is particularly useful to
combine them to achieve better solutions:

* LeastSquares: this is the classic algorithm that solves the linearized problem of
  travel time residual minimization via iterative least squares. However an initial
  location estimate is required. This is the intended method to select when StdLoc
  is used in combination with a pick associator: it provides the initial location
  estimate and StdLoc will improve it. When used in :ref:`scolv` or :ref:`screloc`,
  the location of the origin to be relocated is used as starting estimate.
  The configuration doesn't require any mandatory parameters:

  .. code-block:: params

     method = LeastSquares

* GridSearch: finds the source parameters by evaluating the hypocenter probability
  of each point in a grid and returning the maximum likelihood hypocenter.
  Because the search space is fully evaluated there is no need for an initial
  location estimate and the location uncertainty is completely known. However the
  method is very slow. It can be used to relocate events in :ref:`scolv` that seem
  difficult to locate via other methods or to verify the uncertainty of a solution.
  The following example configuration computes a grid search around the average
  location of the picked stations. The grid points are spaced apart 0.5km
  horizontally and 2km vertically.

  .. code-block:: params

     method = GridSearch
     GridSearch.center = auto,auto,15
     GridSearch.size = 40,40,30
     GridSearch.numPoints = 81,81,16

* GridSearch+LeastSquares: this method can be used in very complex networks where
  a bad initial location estimates can get LeastSquares stuck in a local minimum.
  The method finds a LeastSquares solution for each cell in a (coarse) grid, using
  the cell centroid as initial location estimate. If finally returns the maximum
  likelihood solution. This method is intended to be used in :ref:`screloc` or 
  :ref:`scolv`  to relocate existing events.
  The following example configuration returns the best among the 75 (5x5x3)
  LeastSquares solutions, computed for every point in the grid.

  .. code-block:: params

     method = GridSearch+LeastSquares
     GridSearch.center = auto,auto,15
     GridSearch.size = 100,100,30
     GridSearch.numPoints = 5,5,3

* OctTree: this method produces similar results to GridSearch but it is extremely
  faster and it follows the NonLinLoc approach. The OctTree search starts by
  evaluating the hypocenter probability of each cell in a grid, computed as the
  probability density at the cell center coordinates times the cell volume. The
  search then continues by repeatedly fetching the  cell with highest probability
  and splitting it in 8 sub-cells. These 8 cells are then inserted in the pool of
  cells to fetch from at next iteration.
  The search terminates after either a maximum number of iterations or after
  reaching a minimum cell size. At that point the maximum likelihood hypocenter
  is selected. Because the algorithms splits only the cells with higher
  probability, the search space is sampled in a very efficient way and it makes
  the method way faster than GridSearch.
  This method is intended to be used in :ref:`screloc` or :ref:`scolv` to
  relocate existing events.
  The following example is a plausible configuration for the entire Swiss
  network:

  .. code-block:: params

     method = OctTree
     GridSearch.center = 47.0,8.5,50
     GridSearch.size = 700,700,100
     GridSearch.numPoints = 21,21,11
     OctTree.maxIterations = 100000
     OctTree.minCellSize = 0.001

  However in this example we are at the size limit for a flat earth study
  geometry and for bigger regions `GridSearch.center` should be set to
  `auto` and `GridSearch.size` to a smaller size. 

* OctTree+LeastSquares: this method allows the OctTree search to find the
  maximum probability cell in the network and uses that as the initial
  location estimate for LeastSquares. 
  This method is intended to be used in :ref:`screloc` or :ref:`scolv` to
  relocate existing events.
  The following example is a plausible configuration for the entire Swiss
  network:

  .. code-block:: params

     method = OctTree+LeastSquares
     GridSearch.center = 47.0,8.5,50
     GridSearch.size = 700,700,100
     GridSearch.numPoints = 21,21,11
     OctTree.maxIterations = 10000
     OctTree.minCellSize = 1.0

  However in this example we are at the size limit for a flat earth study
  geometry and for bigger regions `GridSearch.center` should be set to
  `auto` and `GridSearch.size` to a smaller size.

The algorithms implemented in StdLoc are standard methods described in "Routine Data
Processing in Earthquake Seismology" by Jens Havskov and Lars Ottemoller. The OctTree
search algorithm is based on NonLibLoc by Antony Lomax.



Why is stdloc suitable for local seismicity?
============================================

When dealing with very local seismicity (few kilometers or hundreds of meters) 
simplifications that are common for regional seismicity have to be removed. 
In particular the locator should take into consideration:

* Station elevation and even negative elevation (e.g. borehole sensors)
* Earthquake location can be above a seismic sensor (e.g. borehole sensors)
* Possible negative earthquake depth (above surface).

More importantly the travel time tables used by the locator must be able to take
into consideration all the above too.


Travel Time Table
=================

StdLoc can be configured with any Travel Time Table type available in SeisComP,
however only the `homogeneous` type is able to take into consideration station
elevation, negative source depth and sources happening above stations. For this
reason `homogeneous` should be the preferred choice when working on very local
seismicity and especially with borehole sensors.




.. _global_stdloc_configuration:

Module Configuration
====================


.. note::
   **StdLoc.\***
   *Locator parameters: StdLoc. This locator requires the plugin*
   *"stdloc" to be loaded.*



.. confval:: StdLoc.profiles

   Type: *list:string*

   Defines a list of profiles to make available to the plugin.


.. note::

   **StdLoc.profile.$name.\***
   $name is a placeholder for the name to be used and needs to be added to :confval:`StdLoc.profiles` to become active.

   .. code-block:: sh

      StdLoc.profiles = a,b
      StdLoc.profile.a.value1 = ...
      StdLoc.profile.b.value1 = ...
      # c is not active because it has not been added
      # to the list of StdLoc.profiles
      StdLoc.profile.c.value1 = ...


.. confval:: StdLoc.profile.$name.method

   Default: ``LeastSquares``

   Type: *string*

   Values: ``LeastSquares,GridSearch,OctTree,GridSearch+LeastSquares,OctTree+LeastSquares``

   The location method to use: LeastSquares, GridSearch,
   OctTree, GridSearch+LeastSquares or OctTree+LeastSquares.


.. confval:: StdLoc.profile.$name.tableType

   Default: ``LOCSAT``

   Type: *string*

   Values: ``homogeneous,libtau,LOCSAT``

   Type of travel\-time interface. Also consider
   \"tableModel\"\!


.. confval:: StdLoc.profile.$name.tableModel

   Default: ``iasp91``

   Type: *string*

   The travel\-time model to be used. The
   availability of models depends on
   \"tableType\".


.. confval:: StdLoc.profile.$name.PSTableOnly

   Default: ``true``

   Type: *boolean*

   If enabled, the arrival travel time information are fetched
   using 'P' and 'S' tables only and the user selected
   specific phase type is not considered \(e.g. Pg, Sg,
   PmP, SmS, P1, S1, etc\).


.. confval:: StdLoc.profile.$name.usePickUncertainties

   Default: ``false``

   Type: *boolean*

   Use pick time uncertainties rather than a fixed
   time error of XXX s. If true, an arrival weight is
   associated according to the uncertainty of the pick
   and \"pickUncertaintyClasses\".


.. confval:: StdLoc.profile.$name.pickUncertaintyClasses

   Default: ``0.000,0.025,0.050,0.100,0.200,0.400``

   Type: *list:string*

   Unit: *s*

   Comma\-separated list of time limits of uncertainty
   classes from which, along with pick time uncertainties,
   arrival weights are computed. The first value
   defines the lower limit of class 0.
   
   The interval into which a pick time uncertainty falls
   defines the index of the uncertainty class starting
   with 0.
   
   The corresponding arrival weight is computed as:
   weight \= 1 \/ 2\^\(index\).
   
   Example: A pick with a time uncertainty of 0.15 s is
   within the 4th interval ranging from 0.1 to 0.2 s.
   The class index is then 3.
   
   If pick uncertainty is absent, the highest class index
   applies.


.. confval:: StdLoc.profile.$name.confLevel

   Default: ``0.9``

   Type: *double*

   Range: ``0.5:1.0``

   Confidence level, between 0.5 and 1.0, used in
   computing the hypocenter confidence ellipsoid.


.. confval:: StdLoc.profile.$name.enableConfidenceEllipsoid

   Default: ``false``

   Type: *boolean*

   Compute the hypocenter confidence ellipsoid. Disable
   this optional parameter to save some computation time.


.. note::
   **StdLoc.profile.$name.GridSearch.\***
   *Parameters controlling the GridSearch and OctTree methods.*



.. confval:: StdLoc.profile.$name.GridSearch.center

   Default: ``auto,auto,20``

   Type: *list:string*

   Unit: *deg,deg,km*

   Grid center defined as: latitude,longitude,depth. The
   special value \"auto\" can be used and the corresponding latitude, longitude
   and\/or depth will be automatically computed as the average of the arrival
   station locations.


.. confval:: StdLoc.profile.$name.GridSearch.size

   Default: ``40,40,30``

   Type: *list:string*

   Unit: *km*

   Grid size in km defined as: X,Y,Z
   direction extents around the \"GridSearch.center\",
   where X is the longitudinal extent, Y the
   latitudinal extent and Z the vertical extent.


.. confval:: StdLoc.profile.$name.GridSearch.numPoints

   Type: *list:string*

   Number of grid points in X, Y, Z
   direction. The first and last points are on the
   grid boundary unless the number of points is 1
   and the point will be in the grid center.
   
   Format: numX,numY,numZ.


.. confval:: StdLoc.profile.$name.GridSearch.misfitType

   Default: ``L1``

   Type: *string*

   Values: ``L1,L2``

   The type of misfit to use, from which
   the likelihood function is derived: L1 or L2 norm.
   L1 is less sensitive to outliers and so more
   suitable with automatic picks, L2 is the preferred
   choice for manual picks.


.. confval:: StdLoc.profile.$name.GridSearch.travelTimeError

   Default: ``0.25``

   Type: *double*

   Unit: *s*

   Typical error in seconds for travel times to
   stations. The value affects the uncertainty
   of the location. In OctTree it also influences
   the probability density computation: too
   conservative values increase the number of
   iterations required by OctTree to converge
   to a high resolution solution.


.. note::
   **StdLoc.profile.$name.OctTree.\***
   *Parameters controlling the OctTree method. OctTree*
   *uses the parameters defined in GridSearch, but*
   *applies the OctTree search algorithm on the grid.*
   *The starting cells of the OctTree search are created by*
   *dividing the initial grid in equally sized cells.*
   *The grid points becomes the cell vertices.*
   *Resulting number of cells in each direction:*
   *"GridSearch.numPoints" - 1.*



.. confval:: StdLoc.profile.$name.OctTree.maxIterations

   Default: ``50000``

   Type: *int*

   Maximum number of iterations after which the
   search stops. Zero or negatives values disable
   the stopping.


.. confval:: StdLoc.profile.$name.OctTree.minCellSize

   Default: ``0.1``

   Type: *double*

   Unit: *km*

   Minimum cell size to be generate by the OctTree
   search to stop. A zero or negative value disable
   this stopping mechanism.


.. note::
   **StdLoc.profile.$name.LeastSquares.\***
   *Parameters controlling the LeastSquares method.*



.. confval:: StdLoc.profile.$name.LeastSquares.depthInit

   Default: ``20``

   Type: *double*

   The initial depth estimate when no initial
   hypocenter is provided. Used only with
   'LeastSquares'.


.. confval:: StdLoc.profile.$name.LeastSquares.iterations

   Default: ``20``

   Type: *int*

   Number of iterations. Each iteration will
   use the location and time from the previous
   Least Squares solution.


.. confval:: StdLoc.profile.$name.LeastSquares.dampingFactor

   Default: ``0.0``

   Type: *double*

   Damping factor to be used when solving the
   system of equations.
   
   0: no damping.


.. confval:: StdLoc.profile.$name.LeastSquares.solverType

   Default: ``LSMR``

   Type: *string*

   Values: ``LSMR,LSQR``

   Algorithm to use: either LSMR or LSQR.


