# scrtdd

Double-difference earthquake relocation module.

## Configuration

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

scrtdd inherits global options.

automaticOrigins

  Type: boolean

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

manualOrigins

  Type: boolean

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

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

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.

activeProfiles

  Type: list:string

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

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

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

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

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

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 `rtdd.activeProfiles` to become active.

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

profile.$name.regionType

  Type: string

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

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.

profile.$name.methodID

  Type: string

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

profile.$name.tableType

  Type: string

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

profile.$name.tableModel

  Type: string

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

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

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

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

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.

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.

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.

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

profile.$name.catalog.phaFile

  Type: path

  Path to catalog picks file to be used for this profile

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

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

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.

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

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.

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.

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

  Type: int

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

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

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.

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

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

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.

profile.$name.crossCorrelation.enable

  Type: boolean

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

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

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

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

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

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

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

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

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

  Type: double

  Unit: sec

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

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

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

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

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

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

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

  Type: double

  Unit: sec

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

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.

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.

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

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.

profile.$name.solver.solverType

  Type: string

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

profile.$name.solver.algoIterations

  Type: int

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

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

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

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

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

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

--test

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

### Database

### Records

### Mode

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

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

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

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

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

--load-profile-wf profile

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

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

--profile profile

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

--clusters clusters

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

--xcorr-cache xcorr.csv

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

--xmlout

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

--dump-diagnostics

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

### Catalog

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

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

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