.. highlight:: rst

.. _scfinder:

########
scfinder
########

**scfinder is a wrapper module for the Finite-Fault Rupture Detector (FinDer)
Earthquake Early Warning algorithm.**


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

Part of the :ref:`EEW<EEW>` package (used by :ref:`FinDer<FINDER>`).

*scfinder* is released under the GNU Affero General Public License (Free
Software Foundation, version 3 or later). It uses the same library as
:ref:`sceewenv` to compute acceleration envelope values provided as input for
the `Finite-Fault Rupture Detector`_ API.

This module requires FinDer to be installed and SeisComP to be compiled from
source. The FinDer software is distributed by the Swiss Seismological Service 
(SED) at ETH Zurich. Access to the source code is limited to users who have an 
established collaboration with the SED. In other cases, compiled binaries (in a 
docker image) may be provided instead. Please contact Dr. Maren Böse (SED) for 
requests and further information.

FinDer provides estimates of the rupture centroid, length and strike. These
values are attached by *scfinder* within a derived object called *strong motion
origin*, which uses the strong motion database extension. In order to save the
strong motion origins to the database and to provide them to other modules, the
messaging system must be able to handle these messages. Therefore, the
plugins *dmsm* must be available to :ref:`scmaster`.

The plugins can be most easily **added** through the configuration parameters
in :file:`global.cfg`:

.. code-block:: sh

   plugins = dmsm

.. note::

   Within :ref:`scfinder`, FinDer uses continuously updated envelope amplitudes 
   from the same library than module :ref:`sceewenv` and the same pre-processing.


scevent configuration
=====================

*scfinder* can produce an origin as soon as seismic waves have reached a minimum
number of stations as configured in finder.config. :ref:`FinDer` is not
pick-based; the phase number attached to its origin relates to the
stations exceeding :ref:`FinDer` ground motion acceleration threshold. For
:ref:`scevent` to create an event from an origin with 4 phases requires the
following setting:

.. code-block:: sh

   # Minimum number of Picks for an Origin that is automatic and cannot be
   # associated with an Event to be allowed to form a new Event.
   eventAssociation.minimumDefiningPhases = 4


Users interested in EEW may decide to run both FinDer and VS together. 
:ref:`scvsmag` uses the preferred origin for VS magnitude computation, and it
should not run on a FinDer origin. In order to run *scfinder* and 
:ref:`scvsmag` on the same system, *scfinder* should be excluded from the 
list of potential preferred origins. This can be achieved by explicitely defining a 
method priority list that does not include the FinDer *methodID* in the configuration of 
:ref:`scevent`:

.. code-block:: sh

   # The method priority list. When the eventtool comes to the point to select a
   # preferred origin it orders all origins by its methodID priority and selects
   # then the best one among the highest priority method. It also defines the
   # method priority for custom priority checks (eventAssociation.priorities). A
   # defined method string must match exactly the string in Origin.methodID.
   eventAssociation.methods = "NonLinLoc(L2)",\
                              "NonLinLoc(EDT)",\
                              "iLoc",\
                              "Hypo71",\
                              "LOCSAT"

   eventAssociation.priorities =  AGENCY, STATUS, METHOD, PHASES_AUTOMATIC, TIME_AUTOMATIC 


.. note::
   
   Do not include the "MVS" nor "Mfd" magnitude types within :ref:`scevent` list of preferred 
   magnitude types (:confval:`eventAssociation.magTypes`), otherwise, the first origin
   with an "MVS" or "Mfd" will remain preferred for automatic processing despite any newer origins. 

.. target-notes::

.. _`Finite-Fault Rupture Detector` : http://www.seismo.ethz.ch/en/knowledge/earthquake-data-and-analysis-tools/EEW/finite-fault-rupture-detector-finder/



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

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

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



.. confval:: saturationThreshold

   Type: *double*

   Unit: *percent*

   Saturation threshold in percent of 2\*\*23 of raw values \(COUNTS\).
   Default is ``80``.

.. confval:: baselineCorrectionBuffer

   Type: *double*

   Unit: *s*

   Length of base line correction buffer.
   Default is ``60``.

.. confval:: horizontalBuffer

   Type: *double*

   Unit: *s*

   Length of buffer for horizontal components. Because horizontal components
   are being received seperately they must be buffered to align them properly.
   This buffer size correlates to the maximum latency of one horiontal component
   with respect to the other.
   Default is ``60``.

.. note::
   **streams.\***
   *Defines the white- and blacklist of data streams to be used. The*
   *rules to decide if a stream is used or not are the following:*
   **
   *1. if whitelist is not empty and the stream is not on the whitelist,*
   *don't use it, ok otherwise*
   **
   *2. if blacklist is not empty and the stream is on the blacklist,*
   *don't use it, ok otherwise*
   **
   *Both checks are made and combined with AND. Either whitelist or*
   *blacklist contains a list of patterns (wildcard allowed as * and ?),*
   *eg GE.*.*.*, *, GE.MORC.*.BH? Each stream id (NET.STA.LOC.CHA) will*
   *be checked against the defined patterns.*



.. confval:: streams.whitelist

   Type: *list:string*

   The stream whitelist


.. confval:: streams.blacklist

   Type: *list:string*

   The stream blacklist


.. confval:: vsfndr.envelopeInterval

   Type: *double*

   Unit: *s*

   Interval of the envelope computation. The maximum is taken with that
   data interval and declared as envelope value. The intervals do not overlap.
   Default is ``1.0``.

.. confval:: finder.config

   Type: *path*

   Path to Finder config.


.. confval:: finder.magnitudeGroup

   Type: *string*

   Messaging group to send magnitudes to.
   Default is ``MAGNITUDE``.

.. confval:: finder.strongMotionGroup

   Type: *string*

   Messaging group to send strong motion objects to.
   Default is ``LOCATION``.

.. confval:: finder.envelopeBufferSize

   Type: *double*

   Unit: *s*

   Size of envelope buffer in seconds. This value should be set
   large enough for the longest anticipated rupture duration.
   The envelope buffer is a ring buffer and FinDer receives a
   maximum from it based on the time window defined by defaultFinDerEnvelopeLength.
   Default is ``120``.

.. confval:: finder.defaultFinDerEnvelopeLength

   Type: *double*

   Unit: *s*

   Default window length \(in seconds\) of envelope buffer to search when
   passing maximum to FinDer. This default window length will be used
   when there are no active FinDer events, or the largest FinDer event
   rupture \(in km\) is less than the default time window \(in seconds\) \* 1.5.
   Otherwise the window length \(in seconds\) is computed as
   maximum rupture length \(in km\) \/ 1.5, up to the maximum size of the
   envelope buffer as defined by envelopeBufferSize. A smaller value will
   reduce false detections caused by noise, but the value should be large enough
   to account for station spacing and the number of trigger stations used by FinDer.
   Default is ``60``.

.. confval:: finder.scanInterval

   Type: *double*

   Unit: *s*

   Defines the interval to scan amplitudes by Finder. If set to 0
   then the scan is called as soon as an amplitude change has been
   detected. This can cause a high CPU usage.
   Default is ``1``.

.. confval:: finder.processInterval

   Type: *double*

   Unit: *s*

   Defines the interval to process Finder objects. If set to 0
   then Finder is called as soon as data has been scanned.
   This can cause a high CPU usage.
   Default is ``1``.

.. confval:: finder.maxEnvelopeBufferDelay

   Type: *double*

   Unit: *s*

   Sets the maximum delay for the latest update of each envelope buffer before
   skipping the related station stream in FinDer PGA input data. The default is 15s.
   Default is ``15``.

.. confval:: finder.clipTimeout

   Type: *double*

   Unit: *s*

   Defines the delay following a clipped record that a stream is not used
   in FinDer. Default is 30s.
   Default is ``30``.

.. confval:: finder.preferredGainUnits

   Type: *string*

   Defines the preferred data gain units in case envelopes are provided by several
   different instruments from the same location code. Default is \"M\/S\*\*2\". Set \"\"
   \(empty\) to disable prevailing.
   Default is ``M/S**2``.

.. confval:: finder.regionFile

   Type: *string*

   Set the full file path to the BNA file that contains the region\(s\) used for filtering
   finder solutions. Geographic filtering requires both \"regionFile\" and \"regionNames\"
   to be defined and valid.


.. confval:: finder.regionNames

   Type: *string*

   Defines the name\(s\) of the region\(s\), as a comma\-separated list, within which finder
   solutions should be filtered. Geographic filtering requires both \"regionFile\" and
   \"regionNames\" to be defined and valid.


.. confval:: debug.maxDelay

   Type: *double*

   Unit: *s*

   Sets the maximum absolute value of packet delay before issuing a warning. That
   parameter does not configure buffers as such but only a threshold \(in seconds
   with fractional part\) to warn the user that something is not real\-time anymore.
   The default is 3s.
   Default is ``3``.

.. confval:: debug.filterCornerFreq

   Type: *double*

   Unit: *Hz*

   Sets the corner frequency of the Butterworth \(4 poles\) high\-pass filter, default is 1\/3 Hz.
   Default is ``1/3``.


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


Generic
-------

.. option:: -x, --expiry time

   Time span in hours after which objects expire.

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

   OriginID to calculate amplitudes for and exit.

.. option:: --dump-records

   Dumps the filtered traces to ASCII when using \-O.


Verbosity
---------


Messaging
---------

.. option:: --test

   Test mode where no messages are sent.


Database
--------


Records
-------


Offline
-------

.. option:: --offline

   Do not connect to the messaging. This mode requires
   either an explicit database connection to read the
   inventory from or an inventory XML file. This option
   implies \-\-test.

.. option:: --dump-config

   Show configuration in debug log and stdcerr and exit.

.. option:: --ts

   Start time of data acquisition time window, requires also \-\-te

.. option:: --te

   End time of data acquisition time window, requires also \-\-ts

.. option:: --calculate-mask

   Calculate FinDer mask according to scfinder configuration \(i.e.,
   FinDer \"MASK_STATION_DISTANCE\", FinDer template resolution \"D_KM\"
   as well as scfinder \"streams.whitelist\" and \"streams.blacklist\"\),
   output in specified path, and exit.

