SCFINDER(1)

NAME
scfinder - ETHZ-SED EEW SeisComP contributions Documentation

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

DESCRIPTION

Part of the EEW package (used by FinDer).

scfinder is released under the GNU Affero General Public License (Free Software Foundation, version 3 or later). It uses the same library as sceewenv to compute acceleration envelope values provided as input for the Finite-Fault Rupture Detector [1] 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 scmaster.

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

plugins = dmsm

NOTE: Within scfinder, FinDer uses continuously updated envelope amplitudes from the same library than module 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. Finite-Fault Rupture Detector is not pick-based; the phase number attached to its origin relates to the stations exceeding Finite-Fault Rupture Detector ground motion acceleration threshold. For scevent to create an event from an origin with 4 phases requires the following setting:

# 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. scvsmag uses the preferred origin for VS magnitude computation, and it should not run on a FinDer origin. In order to run scfinder and 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 scevent:

# 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 scevent list of preferred magnitude types (eventAssociation.magTypes), otherwise, the first origin with an "MVS" or "Mfd" will remain preferred for automatic processing despite any newer origins.

[1] http://www.seismo.ethz.ch/en/knowledge/earthquake-data-and-analysis-tools/EEW/finite-fault-rupture-detector-finder/

CONFIGURATION
etc/defaults/global.cfg
etc/defaults/scfinder.cfg
etc/global.cfg
etc/scfinder.cfg
~/.seiscomp/global.cfg
~/.seiscomp/scfinder.cfg

scfinder inherits global options.

saturationThreshold
    Type: double

    Unit: percent

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

baselineCorrectionBuffer
    Type: double

    Unit: s

    Length of base line correction buffer. Default is 60.

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.

streams.whitelist
    Type: list:string

    The stream whitelist

streams.blacklist
    Type: list:string

    The stream blacklist

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.

finder.config
    Type: path

    Path to Finder config.

finder.magnitudeGroup
    Type: string

    Messaging group to send magnitudes to. Default is MAGNITUDE.

finder.strongMotionGroup
    Type: string

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

-x, --expiry time
    Time span in hours after which objects expire.

-O, --origin-id publicID
    OriginID to calculate amplitudes for and exit.

--dump-records
    Dumps the filtered traces to ASCII when using -O.

  Verbosity

  Messaging

--test
    Test mode where no messages are sent.

  Database

  Records

  Offline

--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.

--dump-config
    Show configuration in debug log and stdcerr and exit.

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

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

--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.

AUTHOR
Swiss Seismological Service

COPYRIGHT
2020, SED