.. highlight:: rst

.. _scrtdd:

######
scrtdd
######

**Double-difference earthquake relocation module.**


Configuration
=============

| :file:`etc/defaults/global.cfg`
| :file:`etc/defaults/scrtdd.cfg`
| :file:`etc/global.cfg`
| :file:`etc/scrtdd.cfg`
| :file:`~/.seiscomp/global.cfg`
| :file:`~/.seiscomp/scrtdd.cfg`

scrtdd inherits `global options <https://docs.gempa.de/seiscomp/current/apps/global.html>`_.



.. confval:: automaticOrigins

   Type: *boolean*

   Allow relocation of automatic origins.
   Default is ``true``.

.. confval:: manualOrigins

   Type: *boolean*

   Allow relocation of manual origins.
   Default is ``true``.

.. confval:: onlyPreferredOrigins

   Type: *boolean*

   Relocate only preferred origins. When disabled, scrtdd processes all
   origins received on the LOCATION messaging group. When enabled, it
   only processes preferred origins from events received on the EVENT group.
   Default is ``true``.

.. confval:: acceptedOriginAuthors

   Type: *list:string*

   A comma\-separated list of author IDs. Only origins from these authors
   will be considered for relocation. If empty, origins from all authors are
   considered.


.. confval:: activeProfiles

   Type: *list:string*

   Defines a list of active profiles for single\-event \(real\-time\) processing.


.. confval:: performance.delayTime

   Type: *int*

   Unit: *sec*

   Specifies a delay in seconds after an origin is created\/updated
   to trigger the single\-event relocation.
   Default is ``10``.

.. confval:: performance.profileTimeAlive

   Type: *int*

   Unit: *sec*

   Defines how long the profile data should be kept in memory \(in
   seconds\). This is useful to release memory \(catalog waveform data\)
   after a period of inactivity. A negative value force the profiles to
   stay always in memory.
   Default is ``600``.

.. confval:: performance.cacheWaveforms

   Type: *boolean*

   Save reference catalog waveforms to local disk after they have been
   loaded for the first time. This avoids re\-reading them from the
   configured recordStream.
   Default is ``true``.

.. confval:: performance.cacheDirectory

   Type: *path*

   Defines the base directory for the waveform cache. Each profile will
   store its waveforms in a subdirectory named after the profile
   \(e.g., \@cacheDirectory\@\/[profile_name]\/wfcache\).
   Default is ``@ROOTDIR@/var/lib/rtdd``.

.. confval:: performance.cachedWaveformLength

   Type: *double*

   Unit: *sec*

   The waveform length \(centered around pick time\) to be used for the
   disk cache. Although the required waveform length is inferred from
   the cross\-correlation settings, this option allows for a longer
   disk\-cached trace that is useful if cross\-correlation settings
   are changed in the future.
   Default is ``10``.

.. note::
   **profile.\***
   *Each profile is a configuration set with an optional region. The region*
   *is used in real-time processing to select a profile for an incoming origin.*
   *If an origin falls into multiple profile regions, the profile defined first*
   *in the 'activeProfiles' list will be used. This allows for hierarchical*
   *regions, where specific regions are defined first and a broader region is*
   *defined last. A profile is only active in real-time processing when*
   *added to the 'activeProfiles' list.*



.. note::

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

   .. code-block:: sh

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


.. confval:: profile.$name.regionType

   Type: *string*

   Type of region: RECTANGULAR or CIRCULAR.
   Default is ``CIRCULAR``.

.. confval:: profile.$name.region

   Type: *list:double*

   Optional. If regionType is RECTANGULAR, 4 comma\-separated values
   are expected: min_lat, min_lon, max_lat, max_lon. If regionType is
   CIRCULAR, 3 comma\-separated values are expected: lat, lon, radius
   in km. If left empty, the region is limitless.


.. confval:: profile.$name.methodID

   Type: *string*

   The methodID label to be stored in created origins.
   Default is ``RTDD``.

.. confval:: profile.$name.tableType

   Type: *string*

   Travel\-time table format type \(e.g. homogeneous, NLLGrid, LOCSAT\).
   Default is ``LOCSAT``.

.. confval:: profile.$name.tableModel

   Type: *string*

   The model to be used. The format depends on tableType.
   Default is ``iasp91``.

.. confval:: profile.$name.PSTableOnly

   Type: *boolean*

   If enabled, travel\-time information is fetched using 'P' and 'S'
   tables only, and the specific phase type \(e.g., Pg, Sg, Pn\)
   is not considered.
   Default is ``true``.

.. confval:: profile.$name.P-Phases

   Type: *list:string*

   A list of accepted P\-wave phases. Phases not in this list will be ignored.
   Default is ``P,Pg,Pn``.

.. confval:: profile.$name.S-Phases

   Type: *list:string*

   A list of accepted S\-wave phases. Phases not in this list will be ignored.
   Default is ``S,Sg,Sn``.

.. confval:: profile.$name.automaticOriginP

   Type: *string*

   Phase mapping of automatic origin P phase. This defines which specific
   catalog arrival \(e.g., Pg, Pn\) is paired with the generic P phase of
   automatic origins. Only catalog phases matching the selected type are
   used.


.. confval:: profile.$name.automaticOriginS

   Type: *string*

   Phase mapping of automatic origin S phase. This defines which specific
   catalog arrival \(e.g., Sg, Sn\) is paired with the generic S phase of
   automatic origins. Only catalog phases matching the selected type are
   used.


.. confval:: profile.$name.pickUncertaintyClasses

   Type: *list:string*

   Unit: *s*

   Defines pick time uncertainty thresholds \(in seconds\) used to classify
   picks for weighting. This parameter defines a list of interval boundaries.
   A pick's class is determined by the interval its uncertainty falls into.
   E.g., a pick with an uncertainty of 0.150s falls into the 4th interval
   \(between 0.100 and 0.200\) and is assigned class 4. If a pick's
   uncertainty is absent, the lowest class is used.
   The pick weight is computed as: 1 \/ 2\^\(class\-1\).
   Default is ``0.000,0.025,0.050,0.100,0.200,0.400``.

.. note::
   **profile.$name.catalog.\***
   *Define the reference catalog for this profile.*



.. confval:: profile.$name.catalog.eventFile

   Type: *path*

   Path to event file to be used for this profile. If this file
   contains just one column called \"origin\", then each line must be an
   existing origin id and neither phase.csv nor station.csv files are
   required. Alternatively the extended format requires all of
   event.csv, phase.csv and station.csv files to be provided


.. confval:: profile.$name.catalog.phaFile

   Type: *path*

   Path to catalog picks file to be used for this profile


.. confval:: profile.$name.catalog.stationFile

   Type: *path*

   Path to the stations file to be used for this profile


.. note::
   **profile.$name.doubleDifferenceSystem.\***
   *Clustering configuration, which is responsible for selecting the event*
   *pairs and their phases to be used in the double-difference equation system.*



.. note::
   **profile.$name.doubleDifferenceSystem.eventFiltering.\***
   *Exclude poorly connected events (events with not enough phases and/or neighbours).*



.. confval:: profile.$name.doubleDifferenceSystem.eventFiltering.minNumPhases

   Type: *int*

   Minimum number of phases at common stations required between an
   event pair. Pairs not satisfying this condition will not be used.
   Default is ``8``.

.. confval:: profile.$name.doubleDifferenceSystem.eventFiltering.minNumNeighbours

   Type: *int*

   Minimum number of neighbours required by an event. Events not
   satisfying this condition will not be used in the relocation.
   Default is ``4``.

.. note::
   **profile.$name.doubleDifferenceSystem.phaseFiltering.\***
   *Exclude non-optimal phases from the DD system.*



.. confval:: profile.$name.doubleDifferenceSystem.phaseFiltering.minStationToEventPairDistRatio

   Type: *double*

   Minimum ratio between the event\-station distance and the inter\-event
   distance. Phases from stations not satisfying this condition will not be used.
   Default is ``3``.

.. confval:: profile.$name.doubleDifferenceSystem.phaseFiltering.minStationDistance

   Type: *double*

   Unit: *km*

   Minimum distance \(km\) between an event and a station for a
   phase to be used. Phases from stations not satisfying this
   condition will not be used.


.. confval:: profile.$name.doubleDifferenceSystem.phaseFiltering.maxStationDistance

   Type: *double*

   Unit: *km*

   Maximum distance \(km\) between an event and a station for a phase
   to be used. Phases from stations not satisfying this
   condition will not be used. A value of 0 or less disables this limit.


.. note::
   **profile.$name.doubleDifferenceSystem.eventPairSelection.\***
   *Controls how neighbouring events are selected. In the simplest*
   *form, 'numEllipsoids' is set to 0 and neighbours are selected*
   *on a nearest-neighbor basis within a search distance of*
   *'maxNeighbourDistance'. When 'numEllipsoids' is not 0, the*
   *ellipsoid selection algorithm (Waldhauser, 2009) is used to ensure*
   *spatially homogeneous subsampling. Reference events are selected*
   *within concentric, vertically elongated ellipsoidal layers of*
   *increasing thickness. Each layer is split into eight quadrants (cells),*
   *and neighboring events are selected from each of the resulting cells*
   *in a round-robin fashion until 'maxNumNeighbours' is reached.*



.. note::
   **profile.$name.doubleDifferenceSystem.eventPairSelection.singleEvent.\***
   *Configuration for single-event relocation.*



.. confval:: profile.$name.doubleDifferenceSystem.eventPairSelection.singleEvent.maxNumNeighbours

   Type: *int*

   Maximum number of neighbors per event. A value of 0 disables this limit.
   Default is ``80``.

.. confval:: profile.$name.doubleDifferenceSystem.eventPairSelection.singleEvent.maxNeighbourDistance

   Type: *double*

   Unit: *km*

   Maximum distance between an event and its neighbouring
   events. If 'numEllipsoids' is greater than 0, this value is
   the horizontal axis length \(km\) of the outermost boundary. Each
   inner concentric layer axis will be half of the previous one.
   The vertical axis is twice as long as the horizontal ones.
   Default is ``5``.

.. confval:: profile.$name.doubleDifferenceSystem.eventPairSelection.singleEvent.numEllipsoids

   Type: *int*

   If set to 0, the nearest\-neighbor event selection is used.
   Otherwise, this is the number of concentric ellipsoidal layers
   to be used in the neighboring event selection.
   Default is ``5``.

.. note::
   **profile.$name.doubleDifferenceSystem.eventPairSelection.multiEvent.\***
   *Configuration for multi-event relocation.*



.. confval:: profile.$name.doubleDifferenceSystem.eventPairSelection.multiEvent.maxNumNeighbours

   Type: *int*

   Maximum number of neighbors per event. A value of 0 or less
   disables this limit.
   Default is ``40``.

.. confval:: profile.$name.doubleDifferenceSystem.eventPairSelection.multiEvent.maxNeighbourDistance

   Type: *double*

   Unit: *km*

   Maximum distance between an event and its neighbouring
   events. If 'numEllipsoids' is greater than 0, this value is
   the horizontal axis length \(km\) of the outermost boundary. Each
   inner concentric layer axis will be half of the previous one.
   The vertical axis is twice as long as the horizontal ones.
   Default is ``5``.

.. confval:: profile.$name.doubleDifferenceSystem.eventPairSelection.multiEvent.numEllipsoids

   Type: *int*

   If set to 0, the nearest\-neighbor event selection is used.
   Otherwise, this is the number of concentric ellipsoidal layers
   to be used in the neighboring event selection.
   Default is ``0``.

.. note::
   **profile.$name.crossCorrelation.\***
   *Waveform cross-correlation is used to improve the differential travel*
   *times used in the double-difference system.*



.. confval:: profile.$name.crossCorrelation.enable

   Type: *boolean*

   Enable or disable waveform cross\-correlation.
   Default is ``false``.

.. confval:: profile.$name.crossCorrelation.minStationDistance

   Type: *double*

   Unit: *km*

   Minimum allowed distance between event and station. Phases belonging
   to closer stations will not be used in cross\-correlation.
   Default is ``0``.

.. confval:: profile.$name.crossCorrelation.maxStationDistance

   Type: *double*

   Unit: *km*

   Maximum allowed distance between event and station. Phases belonging
   to more distant stations will not be used in cross\-correlation.
   A value of \-1 or less removes this limit.
   Default is ``60``.

.. confval:: profile.$name.crossCorrelation.maxInterEventDistance

   Type: *double*

   Unit: *km*

   Maximum allowed distance \(km\) between events for cross\-correlation
   to be performed. Phases of event pairs whose inter\-event distance is
   greater than this value will not be cross\-correlated.
   A value of \-1 or less removes this limit.
   Default is ``2``.

.. confval:: profile.$name.crossCorrelation.p-phase.minCCCoef

   Type: *double*

   Minimum cross\-correlation coefficient required to use a differential
   travel time derived from cross\-correlation.
   Default is ``0.70``.

.. confval:: profile.$name.crossCorrelation.p-phase.winStart

   Type: *double*

   Unit: *sec*

   Start of the data window to cross\-correlate, relative to the
   pick time \(+\/\- seconds\).
   Default is ``-0.50``.

.. confval:: profile.$name.crossCorrelation.p-phase.winEnd

   Type: *double*

   Unit: *sec*

   End of the data window to cross\-correlate, relative to the
   pick time \(+\/\- seconds\).
   Default is ``0.50``.

.. confval:: profile.$name.crossCorrelation.p-phase.winScaling

   Type: *double*

   Window scaling coefficient. The final window length is calculated as:
   Window Length \= \(winEnd\-winStart\) + TravelTime \* winScaling.
   Default is ``0.02``.

.. confval:: profile.$name.crossCorrelation.p-phase.maxDelay

   Type: *double*

   Unit: *sec*

   Maximum lag \(in seconds\) between data windows allowed.
   Default is ``0.50``.

.. confval:: profile.$name.crossCorrelation.p-phase.components

   Type: *list:string*

   Priority list of components to use for cross\-correlation \(e.g., Z,N,E,1,2,3\).
   The first component in the list that exists for both phases is used.
   Special values: 'L2' computes the L2 norm of the horizontal components;
   'T' and 'R' compute the transverse and radial components, respectively,
   relative to the event location. If empty, the component on which the
   phase was picked is used \(if identical for both phases\).
   Default is ``Z``.

.. confval:: profile.$name.crossCorrelation.s-phase.minCCCoef

   Type: *double*

   Minimum cross\-correlation coefficient required to use a differential
   travel time derived from cross\-correlation.
   Default is ``0.70``.

.. confval:: profile.$name.crossCorrelation.s-phase.winStart

   Type: *double*

   Unit: *sec*

   Start of the data window to cross\-correlate, relative to the
   pick time \(+\/\- seconds\).
   Default is ``-0.50``.

.. confval:: profile.$name.crossCorrelation.s-phase.winEnd

   Type: *double*

   Unit: *sec*

   End of the data window to cross\-correlate, relative to the
   pick time \(+\/\- seconds\).
   Default is ``1.00``.

.. confval:: profile.$name.crossCorrelation.s-phase.winScaling

   Type: *double*

   Window scaling coefficient. The final window length is calculated as:
   Window Length \= \(winEnd\-winStart\) + TravelTime \* winScaling.
   Default is ``0.04``.

.. confval:: profile.$name.crossCorrelation.s-phase.maxDelay

   Type: *double*

   Unit: *sec*

   Maximum lag \(in seconds\) between data windows allowed.
   Default is ``0.50``.

.. confval:: profile.$name.crossCorrelation.s-phase.components

   Type: *list:string*

   Priority list of components to use for cross\-correlation \(e.g., Z,N,E,1,2,3\).
   The first component in the list that exists for both phases is used.
   Special values: 'L2' computes the L2 norm of the horizontal components;
   'T' and 'R' compute the transverse and radial components, respectively,
   relative to the event location. If empty, the component on which the
   phase was picked is used \(if identical for both phases\).
   Default is ``L2``.

.. note::
   **profile.$name.crossCorrelation.waveformFiltering.\***
   *Filter waveforms before performing cross-correlation.*



.. confval:: profile.$name.crossCorrelation.waveformFiltering.filterString

   Type: *string*

   SeisComP string\-based filter definition,
   e.g., \"ITAPER\(1\)>>BW_HLP\(2,1,20\)\". Set to \"\" to disable filtering.


.. confval:: profile.$name.crossCorrelation.waveformFiltering.margin

   Type: *double*

   Unit: *sec*

   Extra seconds of data to add to the waveform ends before applying
   the filter. This helps initialize the filter and allows for
   discarding potential artifacts at the trace ends.
   Default is ``1``.

.. confval:: profile.$name.crossCorrelation.waveformFiltering.resampling

   Type: *double*

   Unit: *Hz*

   Resample all traces to this sampling frequency \(Hz\).
   Set to 0 to disable resampling.
   Default is ``0``.

.. note::
   **profile.$name.solver.\***
   *These options control the double-difference system solver. The*
   *solution is found through an iterative process: a system is built*
   *from the initial locations and solved. The hypocenters are then updated,*
   *and a new system is built and solved again. This is repeated until*
   *'algoIterations' is reached.*



.. confval:: profile.$name.solver.solverType

   Type: *string*

   Solver algorithm to use: either LSMR or LSQR.
   Default is ``LSMR``.

.. confval:: profile.$name.solver.algoIterations

   Type: *int*

   Number of iterations for the solver to perform.
   Default is ``20``.

.. confval:: profile.$name.solver.downWeightingByResidual

   Type: *list:double*

   Specifies residual thresholds for down\-weighting equations. Equations
   with residuals smaller than this value \(in standard deviations\) are
   down\-weighted and the rest discarded \(0 weighed\). A value of 0 disables
   this. If two values are given, are used for the first and last iterations
   respectively, with intermediate iterations using interpolated values.
   Default is ``10,5``.

.. confval:: profile.$name.solver.dampingFactor

   Type: *list:double*

   A non\-zero value enables a damped \(regularized\) least\-squares
   system.  If two values are given, they are for the first and last iterations,
   with interpolation in between.
   Default is ``0.01``.

.. confval:: profile.$name.solver.absoluteLocationConstraint

   Type: *list:double*

   If greater than 0, the system is modified to solve for both
   absolute and relative locations by adding equations that constrain
   absolute travel\-time residuals. This option sets the weight for
   these equations. If two values are given, they are for the first
   and last iterations, with interpolation in between.
   Default is ``0.3``.

.. confval:: profile.$name.solver.xcorrWeightScaler

   Type: *double*

   Weight scaling factor for equations that use cross\-correlation
   differential times relative to equations that use only differential
   pick times. For example, a value of 2 means they are weighted twice
   as much
   Default is ``2.0``.

.. confval:: profile.$name.solver.usePickUncertainties

   Type: *boolean*

   Whether to use pick time uncertainty to weigh each pick according
   to 'pickUncertaintyClasses'. If enabled, each double\-difference
   equation weight will be the average of its constituent pick weights.
   Default is ``false``.


Command Line
============


Generic
-------


Verbosity
---------


Messaging
---------

.. option:: --test

   Test mode, no messages are sent when relocating a single event


Database
--------


Records
-------


Mode
----

.. option:: --reloc-catalog profile

   Relocate the catalog passed as argument in multi\-event mode. The
   input can be a single file \(containing seiscomp origin ids\) or a file
   triplet \(station.csv,event.csv,phase.csv\). For input events stored
   in a XML files add the \-\-ep option. Use in combination with \-\-profile.

.. option:: -O, --origin-id origin-id

   Relocate  the origin \(or multiple comma\-separated origins\) in
   single\-event mode and send a message. Each origin will be processed
   accordingly to the matching profile region unless the \-\-profile option
   is used.

.. option:: --ep scxml-file

   Relocate contained origins in single\-event mode, unless \-\-reloc\-catalog
   is provided. In single\-event mode, each origin will be processed
   accordingly to the matching profile region unless the \-\-profile option is
   used. Together with \-\-reloc\-catalog option, the parameters XML file is
   used to fetch the input catalog data.

.. option:: --dump-clusters profile

   Find clusters in the catalog passed as argument and save them in
   the working directory.
   The catalog can be a single file \(containing seiscomp origin
   ids\) or a file triplet \(station.csv,event.csv,phase.csv\). Use
   in combination with \-\-profile.

.. option:: --dump-wf profile

   Dump processed waveforms of the catalog passed as argument
   in the current working directory.
   The catalog can be a single file \(containing seiscomp origin
   ids\) or a file triplet \(station.csv,event.csv,phase.csv\). Use
   in combination with \-\-profile.

.. option:: --load-profile-wf profile

   Load catalog waveforms from the configured recordstream and
   save them into the profile cache directory. Use in
   combination with \-\-profile.

.. option:: --send-reload-profile-msg

   Send a message to any running scrtdd module requesting to
   reload a specific profile passed as argument. Useful to reload the
   catalog without restarting the module.


ModeOptions
-----------

.. option:: --profile profile

   To be used in combination with other options: select the
   profile configuration to use.

.. option:: --clusters clusters

   Specify a list of files containing precomputed events\/phases pairs.
   Use in combination with \-\-reloc\-catalog.

.. option:: --xcorr-cache xcorr.csv

   Specify a file containing precomputed cross\-correlation values.
   Use in combination with \-\-reloc\-catalog.

.. option:: --xmlout

   Enable XML output when combined with \-\-reloc\-catalog or \-\-origin\-id
   options.

.. option:: --dump-diagnostics

   Generate a diagnostics report by creating a dedicated folder in the
   current directory containing detailed relocation diagnostic data.


Catalog
-------

.. option:: --dump-catalog catalog-file

   Dump the seiscomp event\/origin id file passed as argument into
   a catalog file triplet \(station.csv,event.csv,phase.csv\).

.. option:: --merge-catalogs catalog-files

   Merge in a single catalog all the catalog file triplets
   \(station1.csv,event1.csv,phase1.csv,station2.csv,event2.csv,
   phase2.csv,...\) passed as arguments.

.. option:: --merge-catalogs-keepid catalog-files

   Similar to the \-\-merge\-catalogs option but events keep their ids. If
   multiple events share the same id, subsequent events will be
   discarded.

