7.0.0

# screloc

Automatic relocator.

## Description

screloc is an automatic relocator that receives origins from realtime locators such as scautoloc and relocates them with a configurable locator. screloc can be conveniently used to test different locators and velocity models or to relocate events with updated velocity models. Check the Example applications for screloc.

screloc processes any incoming automatic origin but does not yet listen to event information nor does it skip origins for that a more recent one exists.

To run screloc along with all processing modules add it to the list of clients in the seiscomp configuration frontend.

    seiscomp enable screloc
    seiscomp start screloc

Descriptions of parameters for screloc:

    seiscomp exec screloc -h

Test the performance of screloc and learn from debug output:

    seiscomp exec screloc --debug

## Setup

The following example configuration shows a setup of screloc for NonLinLoc:

    plugins = ${plugins}, locnll

    # Define the locator algorithm to use
    reloc.locator = NonLinLoc

    # Define a suffix appended to the publicID of the origin to be relocated
    # to form the new publicID.
    # This helps to identify pairs of origins before and after relocation.
    # However, new publicIDs are unrelated to the time of creation.
    # If not defined, a new publicID will be generated automatically.
    reloc.originIDSuffix = "#relocated"

    ########################################################
    ################ NonLinLoc configuration################
    ########################################################
    NLLROOT = ${HOME}/nll/data

    NonLinLoc.outputPath = ${NLLROOT}/output/

    # Define the default control file if no profile specific
    # control file is defined.
    NonLinLoc.controlFile = ${NLLROOT}/NLL.default.conf

    # Set the default pick error in seconds passed to NonLinLoc
    # if no SeisComP pick uncertainty is available.
    NonLinLoc.defaultPickError = 0.1

    # Define the available NonLinLoc location profiles. The order
    # implicitly defines the priority for overlapping regions
    #NonLinLoc.profiles = swiss_3d, swiss_1d, global
    NonLinLoc.profiles = swiss_3d, global

    # The earthModelID is copied to earthModelID attribute of the
    # resulting origin
    NonLinLoc.profile.swiss_1d.earthModelID = "swiss regional 1D"

    # Specify the velocity model table path as used by NonLinLoc
    NonLinLoc.profile.swiss_1d.tablePath = ${NLLROOT}/time_1d_regio/regio

    # Specify the region valid for this profile
    NonLinLoc.profile.swiss_1d.region = 41.2, 3.8, 50.1, 16.8

    # The NonLinLoc default control file to use for this profile
    NonLinLoc.profile.swiss_1d.controlFile = ${NLLROOT}/NLL.swiss_1d.conf

    # Configure the swiss_3d profile
    NonLinLoc.profile.swiss_3d.earthModelID = "swiss regional 3D"
    NonLinLoc.profile.swiss_3d.tablePath = ${NLLROOT}/time_3d/ch
    NonLinLoc.profile.swiss_3d.region = 45.15, 5.7, 48.3, 11.0
    NonLinLoc.profile.swiss_3d.controlFile = ${NLLROOT}/NLL.swiss_3d.conf

    # And the global profile
    NonLinLoc.profile.global.earthModelID = iaspei91
    NonLinLoc.profile.global.tablePath = ${NLLROOT}/iasp91/iasp91
    NonLinLoc.profile.global.controlFile = ${NLLROOT}/NLL.global.conf

## Examples

- Relocate all origins given in an SCML file according to the configuration of screloc. Write all output to unformatted SCML.

      screloc -d localhost --ep origins.xml > origins_screloc.xml

- Relocate the previously preferred origins of all events (scevtls) within some period of time using a specific locator and locator profile. Use some userID and authorID for uniquely recognizing the relocation. Configuring the ref:scevent parameter `eventAssociation.priorities` to TIME_AUTOMATIC before running the example will prefer the latest origin (which will be created by screloc) for the event the new origin is associated to. The new origins are automatically sent to the messaging.

      #!/bin/bash

      # locator type
      locator=[your_locator]
      # locator profile
      profile=[your_profile]
      # set some userID
      userID=[your_user]
      # set some authorID
      authorID=[screloc]

      IFS=',' read -ra events <<< `scevtls -d localhost -p -D , --begin 2025-01-01 --end 2025-02-01`
      for event in "${events[@]}"; do
          preferredOrigin=$(echo $event | awk '{print $2}')
          screloc -d localhost -O $preferredOrigin --locator $locator --profile $profile -u $userID --author=$authorID
      done

## Module Configuration

`etc/defaults/global.cfg`
`etc/defaults/screloc.cfg`
`etc/global.cfg`
`etc/screloc.cfg`
`~/.seiscomp/global.cfg`
`~/.seiscomp/screloc.cfg`

screloc inherits global options.

reloc.locator

  Type: string

  Defines the locator to be used such as NonLinLoc.

reloc.profile

  Type: string

  The locator profile to use.

reloc.ignoreRejectedOrigins

  Default: `false`

  Type: boolean

  Ignores origins with status REJECTED.

reloc.allowAnyStatus

  Default: `false`

  Type: boolean

  Triggers processing on origins with any evaluation status. Overrides "allowPreliminaryOrigins" but not "ignoreRejectedOrigins".

reloc.allowPreliminaryOrigins

  Default: `false`

  Type: boolean

  Triggers processing also on origins with status PRELIMINARY. Origins with any other status is ignored anyway. The parameter is overridden by "allowAnyStatus".

reloc.allowManualOrigins

  Default: `false`

  Type: boolean

  Triggers processing also on origins with evaluatuion mode MANUAL. Otherwise only origins with mode AUTOMATIC are considered. The triggering may be limited due to an evaluation status, see "allowPreliminaryOrigins".

reloc.useWeight

  Default: `false`

  Type: boolean

  Whether to use the weight of the picks associated with the input origin as defined in the input origin as input for the locator or not. If false then all picks associated with the input origin will be forwarded to the locator with full weight.

reloc.adoptFixedDepth

  Default: `false`

  Type: boolean

  If the input origin’s depth is fixed then it will be fixed during the relocation process as well.

reloc.storeSourceOriginID

  Default: `false`

  Type: boolean

  Whether to store the ID of the input origin as comment in the relocated origin or not.

reloc.originIDSuffix

  Type: string

  Suffix appended to the publicID of the origin to be relocated to form the new publicID. This helps to identify pairs of origins before and after relocation. However, new publicIDs are unrelated to the time of creation. If not defined, a new publicID will be generated automatically.

Note

picks.* Parameters specific to picks.

picks.streamsSetUnused

  Type: list:string

  List of streams from which picks are set to unsed by their referencing arrivals before locating. The concerned arrivals are kept but the picks will not be used for locating. Streams take the format NET.STA.LOC.CHA. Wildcards * and ? are supported.

  Example:

  GE.MOX.*.HH? : All arrivals on any HH stream of station MOX will be kept but not used for locating.

## Command-Line Options

### Generic

-h, --help

  Show help message.

-V, --version

  Show version information.

--config-file arg

  Use alternative configuration file. When this option is used the loading of all stages is disabled. Only the given configuration file is parsed and used. To use another name for the configuration create a symbolic link of the application or copy it. Example: scautopick -> scautopick2.

--plugins arg

  Load given plugins.

-D, --daemon

  Run as daemon. This means the application will fork itself and doesn’t need to be started with &.

--auto-shutdown arg

  Enable/disable self-shutdown because a master module shutdown. This only works when messaging is enabled and the master module sends a shutdown message (enabled with --start-stop-msg for the master module).

--shutdown-master-module arg

  Set the name of the master-module used for auto-shutdown. This is the application name of the module actually started. If symlinks are used, then it is the name of the symlinked application.

--shutdown-master-username arg

  Set the name of the master-username of the messaging used for auto-shutdown. If "shutdown-master-module" is given as well, this parameter is ignored.

### Verbosity

--verbosity arg

  Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info, 4:debug.

-v, --v

  Increase verbosity level (may be repeated, eg. -vv).

-q, --quiet

  Quiet mode: no logging output.

--component arg

  Limit the logging to a certain component. This option can be given more than once.

-s, --syslog

  Use syslog logging backend. The output usually goes to /var/lib/messages.

-l, --lockfile arg

  Path to lock file.

--console arg

  Send log output to stdout.

--debug

  Execute in debug mode. Equivalent to --verbosity=4 --console=1 .

--log-file arg

  Use alternative log file.

### Messaging

-u, --user arg

  Overrides configuration parameter `connection.username`.

-H, --host arg

  Overrides configuration parameter `connection.server`.

-t, --timeout arg

  Overrides configuration parameter `connection.timeout`.

-g, --primary-group arg

  Overrides configuration parameter `connection.primaryGroup`.

-S, --subscribe-group arg

  A group to subscribe to. This option can be given more than once.

--content-type arg

  Overrides configuration parameter `connection.contentType`.

  Default: `binary`

--start-stop-msg arg

  Default: `0`

  Set sending of a start and a stop message.

### Database

--db-driver-list

  List all supported database drivers.

-d, --database arg

  The database connection string, format: service://user:pwd@host/database. "service" is the name of the database driver which can be queried with "--db-driver-list".

--config-module arg

  The config module to use.

--inventory-db arg

  Load the inventory from the given database or file, format: [service://]location .

--db-disable

  Do not use the database at all

### Mode

--dump

  Dump processed origins as XML to stdout. Use in combination with -O.

--test

  Test mode, do not send any message.

### Input

--locator arg

  Overrides configuration parameter `reloc.locator`.

--profile arg

  Overrides configuration parameter `reloc.profile`.

--ep arg

  Event parameters XML file for offline processing of all contained origins. This option should not be mixed with --dump.

-O, --origin-id arg

  Reprocess the origin and send a message unless test mode is activated.

--use-weight

  Overrides configuration parameter `reloc.useWeight`.

--streams-set-unused arg

  Overrides configuration parameter `picks.streamsSetUnused`.

  Type: list:string

  List of streams from which picks are set to unsed by their referencing arrivals before locating. The concerned arrivals are kept but the picks will not be used for locating. Streams take the format NET.STA.LOC.CHA. Wildcards * and ? are supported.

--replace

  Used in combination with --ep. If given then each origin for that an output has been generated is replaced by the result of relocation. In other words: two LocSAT origins in, two NonLinLoc origins out. All other objects are passed through.

### Output

--evaluation-mode

  Evaluation mode of the new origin (AUTOMATIC or MANUAL).

-f, --formatted

  Use formatted XML output. Otherwise XML is unformatted.

--origin-id-suffix

  Create origin ID from that of the input origin plus the specfied suffix.

### Profiling

--measure-relocation-time

  Measure the time spent in a single relocation

--repeated-relocations arg

  Improve measurement of relocation time by running each relocation multiple times. Specify the number of relocations, e.g. 100.