scrtdd
Double-difference earthquake relocation module.
Configuration
etc/defaults/global.cfgetc/defaults/scrtdd.cfgetc/global.cfgetc/scrtdd.cfg~/.seiscomp/global.cfg~/.seiscomp/scrtdd.cfgscrtdd 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.