.. highlight:: rst .. _autothor: ######## autothor ######## **Automated seismic event location by waveform coherence analysis.** Description =========== *autothor* is the automatic locator process which works by examining fixed time windows continuously. Offline Testing =============== In order to test particular datasets, *autothor* can be run in offline mode which does not require a messaging connection and even the database connection is optional. A requirement for fetching the correct metadata of the stations is to provide a reference time (:confval:`thor.inventoryReferenceTime`) of the dataset. This reference time is being used to read the station configuration at that date from the inventory. This can be done either via configuration file or on the command line: .. code:: sh $ autothor --thor.inventoryReferenceTime=2024-09-25 To output the results to an XML file which will contain all picks and origins, add the :option:`--ep` command line option: .. code:: sh $ autothor --thor.inventoryReferenceTime=2024-09-25 --ep > ep.xml Instead of running against a database, provide all inventory and binding information via XML files: .. code:: sh $ autothor --thor.inventoryReferenceTime=2024-09-25 --ep --inventory-db inv.xml --config-db cfg.xml > ep.xml Data pushed into *autothor* is recommended to be sorted by end time. See *scmssort* or *scart* to support you with that operation. Example configuration file -------------------------- .. code:: sh thor { # The list of stations to be considered. stations = AB.1234, AB.5678 # The regions of the grid. region = 10x10+10.1234-20.5678 # The depth range of the grid. depths = 0:5 # The grid nodes grid = 1000x1000x10 # The initial search grid search = 100x100x2 # The filter to be applied before the characteristic function # is being formed. filter = "RMHP(0.1)>>DIFF" # The common sample rate of all channels. Channels not matching this # sample rate will be re-sampled. sampleRate = 100 # The minimum overall correlation to accept an origin as solution. minimumCorrelation = 0.3 # The signal length in seconds. signal = 4 # The overlap ration of two subsequent processing windows. overlap = 0.5 # Dump the grids as .png images. dump = true # The travel time table setup. ttt { interface = LOCSAT model = iasp91 } stacking { default { staP = 0.05 ltaP = 0.1 staS = 0.1 ltaS = 0.2 # The minimum STALTA ratio. If below, the characteristic function # will be scaled down. minimumSTALTA = 5 } } } Example call ------------ .. code:: sh $ autothor --thor.inventoryReferenceTime=2024-09-25 --ep -I data.sorted.mseed --inventory-db inv.xml --config-db cfg.xml > ep.xml Module Configuration ==================== | :file:`etc/defaults/global.cfg` | :file:`etc/defaults/autothor.cfg` | :file:`etc/global.cfg` | :file:`etc/autothor.cfg` | :file:`~/.seiscomp/global.cfg` | :file:`~/.seiscomp/autothor.cfg` autothor inherits :ref:`global options`. .. note:: Modules/plugins may require a license file. The default path to license files is :file:`@DATADIR@/licenses/` which can be overridden by global configuration of the parameter :confval:`gempa.licensePath`. Example: :: gempa.licensePath = @CONFIGDIR@/licenses .. _thor: .. confval:: thor.region Type: *string* The processing region which is interpolated in the grid. The format is [lon_width_in_km]x[lat_width_in_km]+\/\-[lon_in_degrees]+\/\-[lat_in_degrees]. .. confval:: thor.rotation Default: ``0`` Unit: *deg* Type: *double* The counter clockwise rotation angle of the region around the min_lat\/min_lon coordinate. .. confval:: thor.depths Unit: *km:km* Type: *string* The depth range to search. The format is [min_depth_in_km]:[max_depth_in_km]. .. confval:: thor.grid Default: ``100x100x10`` Type: *string* The processing grid in [nodes_x]x[nodes_y]x[nodes_z]. The grid does not include the corresponding maximum values of each dimension. The actual cell size in one dimension is length \/ nodes. .. confval:: thor.search Default: ``10x10x2`` Type: *string* The initial search grid. This grid is a coarser grid than the final grid. It is used to speed up computation by not evaluation the full space. After finding the maximum in this inital search grid, the cell and its direct neighbors are evaluated with the final grid cellspacing. .. confval:: thor.stations Type: *list:string* A list of stations to be used. The location code and channel code is read from the bindings detecLocid and detecStream. If the stations list is empty, then bindings are evaluated and all stations are being used which are enabled for thor. .. confval:: thor.inventoryReferenceTime Type: *time* The metadata reference time for fetching station configurations from inventory. .. confval:: thor.filter Default: ``RMHP(1)>>DIFF`` Type: *string* A processing filter which is applied to each channel before stacking takes place. .. confval:: thor.filter2 Type: *string* A secondary processing filter which is applied to each channel before stacking takes place. This secondary filter will be applied to the horizontal components if provided. Otherwise the primary filter will be used. .. confval:: thor.cloneHorizontalsFromVertical Default: ``false`` Type: *boolean* If a single component station should be used, then this parameter decided whether the single vertical component will be cloned to the missing two horizontal components \(true\) or if the application will be terminated due to missing metadata \(false\). .. confval:: thor.sampleRate Default: ``100`` Unit: *sps* Type: *double* The common sample rate to be used. Data which is not sampled with another rate will be resampled to match this value. .. confval:: thor.signal Default: ``5`` Unit: *s* Type: *double* The length of the signal window. .. confval:: thor.maxWindow Default: ``0`` Unit: *s* Type: *double* The effective data window is computed as signal plus maximum expected time shift. In order to limit this effective data window this value can be used. If larger than zero, then it will be taken as the maximum length of the data window. For samples which are required during stacking but are not available in the data window, zeros will be used. Note that it can't be less than signal. .. confval:: thor.overlap Default: ``0.5`` Type: *double* The overlap of the signal window when forwarding to another time window. The effective stepping length is signal \* \(1\-overlap\). .. confval:: thor.dump Default: ``false`` Type: *boolean* Dump each solution as graphical PNG image and Surfer grid files in local directory. The files are named are controlled by \"thor.useOriginID\". .. confval:: thor.useOriginID Default: ``false`` Type: *boolean* Use the public ID of the related origin for creating the names of the dumped solution files. True: \"grid_[publicID].[png\|grd]\" Default: \"grid_[step].[png\|grd]\" .. confval:: thor.minimumCorrelation Default: ``0.25`` Type: *double* The minimum correlation value to accept a solution. This value should be between 0 and 1. .. confval:: thor.minimumStations Default: ``0`` Type: *integer* The minimum number of stations which must contribute to a solution. .. confval:: thor.stacking Default: ``default`` Type: *string* The stacking processor to be applied. If no additional plugin has been loaded, then only the \"default\" processor is available. .. confval:: thor.cacheDirectory Default: ``@CONFIGDIR@/cache/thor`` Type: *directory* The directory where the travel time grids of the stations are saved. .. confval:: thor.pickFromComponent Default: ``false`` Type: *boolean* Whether to set the pick time from the maximum index of the stack function \(false\) or from the maximum of each contributing component \(true\). .. confval:: thor.removeZeroWeightArrivals Default: ``false`` Type: *boolean* Remove arrivals having a weight of 0. .. confval:: thor.pickUncertainty Default: ``false`` Type: *boolean* Whether to set the pick time uncertainty to the used time window or not. .. _thor.ttt: .. note:: **thor.ttt.\*** *Configuration options for the travel time computation.* .. confval:: thor.ttt.interface Default: ``LOCSAT`` Type: *string* The travel time table interface used to compute travel times from each grid node to a station. .. confval:: thor.ttt.model Default: ``iasp91`` Type: *string* The travel time table model used to compute travel times from each grid node to a station. .. _thor.stacking: .. _thor.stacking.gpu: .. confval:: thor.stacking.gpu.enable Default: ``false`` Type: *boolean* Whether to run the stacking algorithm on GPU. .. confval:: thor.stacking.gpu.numWorkers Default: ``0`` Type: *integer* The number of workers to use when computing the stacking grid. 0 means all available NVIDIA GPUs in the system. Falls back to CPU processing if set to 0 and no compatible GPUs are found. .. confval:: thor.stacking.gpu.precision Default: ``double`` Type: *string* Values: ``single,double`` Whether to use single or double precision arithmetic in GPU processing. .. _thor.stacking.default: .. note:: **thor.stacking.default.\*** *Configuration options for the default stacking* *algorithm.* .. confval:: thor.stacking.default.staP Default: ``0`` Unit: *s* Type: *double* The length of the P short\-term window in seconds for STALTA. .. confval:: thor.stacking.default.ltaP Default: ``0`` Unit: *s* Type: *double* The length of the P long\-term window in seconds for STALTA. .. confval:: thor.stacking.default.staS Default: ``0`` Unit: *s* Type: *double* The length of the S short\-term window in seconds for STALTA. .. confval:: thor.stacking.default.ltaS Default: ``0`` Unit: *s* Type: *double* The length of the S long\-term window in seconds for STALTA. .. confval:: thor.stacking.default.minimumSTALTA Default: ``0`` Type: *double* The minimum STALTA value for each phase. .. confval:: thor.stacking.default.scaleBySTALTA Default: ``true`` Type: *boolean* Whether to scale traces by STALTA or discard them. If enabled, then each traces will be scaled down if its maximum STALTA value is below the minimum configured STALTA value. The scaling factor will be maxAmp \/ minimumSTALTA. .. confval:: thor.stacking.default.scaleByAmplitude Default: ``false`` Type: *boolean* Whether to scale by the maximum amplitude of all components among the vertical or horizontal group. If enabled, then the maximum value of all vertical STALTA traces is used to scale each vertical STALTA function by maxSTALTA\(trace\) \/ globalMaxSTALTA. The same applies for the horizontal components. This will downweight traces in farther distances. .. confval:: thor.stacking.default.horizontalSTALTACorrection Default: ``true`` Type: *boolean* If enabled, then the characteristic function formed by the horizontals will be corrected w.r.t to the characteristic function of the vertical component to suppress the strong P onsets on the horizontals and to bring out the characteristic function of the S phase. .. confval:: thor.stacking.default.threads Default: ``0`` Type: *integer* The number of threads to use when computing the stacking grid. 0 means half the number of reported CPU cores. A value greater than 0 will use exactly this number of threads. .. confval:: thor.stacking.default.dump Default: ``false`` Type: *boolean* Whether to dump the processed traces for each time step or not. Bindings Parameters =================== .. confval:: thorEnable Default: ``false`` Type: *boolean* Enables\/disables processing with THOR. Command-Line Options ==================== .. _Generic: Generic ------- .. option:: -h, --help Show help message. .. option:: -V, --version Show version information. .. option:: --config-file file The alternative module configuration file. When this option is used, the module configuration is only read from the given file and no other configuration stage is considered. Therefore, all configuration including the definition of plugins must be contained in that file or given along with other command\-line options such as \-\-plugins. .. option:: --plugins arg Load given plugins. .. option:: -D, --daemon Run as daemon. This means the application will fork itself and doesn't need to be started with \&. .. option:: --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\). .. option:: --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. .. option:: --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 --------- .. option:: --verbosity arg Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info, 4:debug. .. option:: -v, --v Increase verbosity level \(may be repeated, e.g., \-vv\). .. option:: -q, --quiet Quiet mode: no logging output. .. option:: --component arg Limit the logging to a certain component. This option can be given more than once. .. option:: -s, --syslog Use syslog logging backend. The output usually goes to \/var\/lib\/messages. .. option:: -l, --lockfile arg Path to lock file. .. option:: --console arg Send log output to stdout. .. option:: --debug Execute in debug mode. Equivalent to \-\-verbosity\=4 \-\-console\=1 . .. option:: --log-file arg Use alternative log file. .. _Messaging: Messaging --------- .. option:: -u, --user arg Overrides configuration parameter :confval:`connection.username`. .. option:: -H, --host arg Overrides configuration parameter :confval:`connection.server`. .. option:: -t, --timeout arg Overrides configuration parameter :confval:`connection.timeout`. .. option:: -g, --primary-group arg Overrides configuration parameter :confval:`connection.primaryGroup`. .. option:: -S, --subscribe-group arg A group to subscribe to. This option can be given more than once. .. option:: --content-type arg Overrides configuration parameter :confval:`connection.contentType`. Default: ``binary`` .. option:: --start-stop-msg arg Default: ``0`` Set sending of a start and a stop message. .. _Database: Database -------- .. option:: --db-driver-list List all supported database drivers. .. option:: -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\". .. option:: --config-module arg The config module to use. .. option:: --inventory-db arg Load the inventory from the given database or file, format: [service:\/\/]location . .. _Records: Records ------- .. option:: --record-driver-list List all supported record stream drivers. .. option:: -I, --record-url arg The RecordStream source URL. Format: [service:\/\/]location[#type]. \"service\" is the name of the RecordStream driver which can be queried with \"\-\-record\-driver\-list\". If \"service\" is not given, \"file:\/\/\" is used and simply the name of a miniSEED file can be given. .. option:: --record-file arg Specify a file as record source. .. option:: --record-type arg Specify a type for the records being read. .. _Mode: Mode ---- .. option:: --offline Do not connect to messaging .. option:: --ep arg Implies offline and outputs all results as a single event parameters XML document to stdout .. _Offline: Offline ------- .. option:: -E, --eventID arg Define an event ID to be relocated. If both an origin and event IDis given, then the origin ID has precedence. .. option:: -O, --originID arg Define an origin ID to be relocated. If both an origin and event IDis given, then the origin ID has precedence.