.. highlight:: rst

.. _autolambda:

##########
autolambda
##########

**Automatic array processing**


Description
===========




Module Configuration
====================

| :file:`etc/defaults/global.cfg`
| :file:`etc/defaults/autolambda.cfg`
| :file:`etc/global.cfg`
| :file:`etc/autolambda.cfg`
| :file:`~/.seiscomp/global.cfg`
| :file:`~/.seiscomp/autolambda.cfg`

autolambda inherits :ref:`global options<global-configuration>`.

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



.. note::

   **connection.\***
   *Additional parameters for connecting to the messaging system.*


.. confval:: connection.locationGroup

   Default: ``LOCATION``

   Type: *string*

   Location message group where origins will be sent e.g. from
   backprojection.
   Picks are sent to the group defined by the global parameter
   \"connection.primaryGroup\".


.. note::

   **bindings.\***
   *Bindings for array processing*


.. confval:: bindings.slownessgrid

   Type: *list:string*

   Slowness grid bindings for an array. A binding
   consists of an array profile name, a base profile and a
   slowness grid profile. Each binding is a triplet separated
   by a semicolon.
   Example: \"PSA;f1\-8;default,4A;f2\-10;default\"
   
   Note the difference of a comma and a semicolon.


.. confval:: bindings.backprojection

   Type: *list:string*

   Backprojection bindings for an array. A binding
   consists of an array profile name, a base profile and a
   backprojection profile. Each binding is a triplet separated
   by a semicolon.
   Example: \"PSA;f1\-8;default,4A;f2\-10;default\"
   
   Note the difference of a comma and a semicolon.


.. confval:: bindings.pmcc

   Type: *list:string*

   PMCC bindings for an array. A binding
   consists of an array profile name, a base profile and a
   PMCC profile. Each binding is a triplet separated
   by a semicolon.
   Example: \"PSA;f1\-8;default,4A;f2\-10;default\"
   
   Note the difference of a comma and a semicolon.


.. note::

   **arrays.\***
   *Configure one ore more array profiles.*


.. note::

   **arrays.$name.\***
   *Define the array.*
   $name is a placeholder for the name to be used and needs to be added to :confval:`arrays` to become active.

   .. code-block:: sh

      arrays = a,b
      arrays.a.value1 = ...
      arrays.b.value1 = ...
      # c is not active because it has not been added
      # to the list of arrays
      arrays.c.value1 = ...


.. confval:: arrays.$name.channels

   Type: *list:string*

   Defines a list of channels to use. E.g.
   
   CX.PB01..HHZ, CX.PB02..HHZ, CX.PB03..HHZ
   
   or
   
   CX.PB01.:00.HHZ, CX.PB02.10:20:30.HHZ, CX.PB03..HHZ, CX.PB04..
   
   The latter gives preference to the first occurrence of
   listed parameters separated by \":\". Here the
   list contains location codes. Wildcards are not supported.
   If the channel codes is omitted, the vertical channel
   occurring first in the inventory is selected.


.. note::

   **pmcc.\***
   *PMCC specific parameters.*


.. confval:: pmcc.dumpFamilies

   Default: ``false``

   Type: *boolean*

   If enabled then each PMCC detection family is exported as
   SeisComP event parameters XML. The path is configured in
   pmcc.exportPath.
   The filename of the family is generated
   as Family_<time>_Origin.PMCC.<time>.xml.


.. confval:: pmcc.exportPath

   Default: ``@LOGDIR@/lambda/families``

   Type: *path*

   The PMCC family export path.


.. note::

   **profiles.\***
   *Processing profiles*


.. note::

   **profiles.base.\***
   *Base processing parameters such as filters and time windows.*


.. note::

   **profiles.base.$name.\***
   $name is a placeholder for the name to be used.


.. confval:: profiles.base.$name.phaseHint

   Default: ``P``

   Type: *string*

   The phaseHint of the created pick.


.. confval:: profiles.base.$name.targetSampleRate

   Default: ``200``

   Unit: *sps*

   Type: *double*

   The common sample rate for all array elements. Channels that
   do not match this sample rate will be resampled.


.. confval:: profiles.base.$name.maximumChannelDelay

   Default: ``60``

   Unit: *s*

   Type: *double*

   The maximum channel delay allowed before a particular channel
   is reset and processing is continued with all remaining
   channels. This value is always with respect to the latest
   sample of each channel in the array.


.. confval:: profiles.base.$name.minimumFrequency

   Default: ``0``

   Unit: *Hz*

   Type: *double*

   The lower corner frequency of the filter. If lower or
   equal to zero then it is disabled and the resulting
   filter is a lo\-pass filter. If both frequencies are
   disabled then filtering will be disabled.


.. confval:: profiles.base.$name.maximumFrequency

   Default: ``0``

   Unit: *Hz*

   Type: *double*

   The upper corner frequency of the filter. If lower or
   equal to zero then it is disabled and the resulting
   filter is a hi\-pass filter. If both frequencies are
   disabled then filtering will be disabled.


.. confval:: profiles.base.$name.frequencySteps

   Default: ``1``

   Type: *int*

   The number of frequencies to be generated between
   minimumFrequency and maximumFrequency. This feature is
   currently not supported and this parameter will be
   ignored.


.. confval:: profiles.base.$name.timeWindow

   Default: ``2``

   Unit: *s*

   Type: *double*

   The processing time window.


.. confval:: profiles.base.$name.timeStep

   Default: ``1``

   Unit: *s*

   Type: *double*

   The processing time step. After a time window has been
   processed, the window is shifted by this value.


.. confval:: profiles.base.$name.noiseWindow

   Default: ``4``

   Unit: *s*

   Type: *double*

   The noise window added before the detection, e.g. to
   calculate the SNR.


.. confval:: profiles.base.$name.semblanceTriggerOn

   Default: ``0.7``

   Type: *double*

   The value that must be exceeded to activate triggering.


.. confval:: profiles.base.$name.semblanceTriggerOff

   Default: ``0.7``

   Type: *double*

   Once the semblance trigger is activated, the maximum semblance
   is collected until the value drops below this value. The maximum
   between on and off is used to find the pick on the beam.


.. confval:: profiles.base.$name.minimumSNR

   Default: ``10``

   Type: *double*

   Minimum SNR to declare a pick on a beam trace.


.. confval:: profiles.base.$name.deadMargin

   Default: ``10``

   Unit: *%*

   Type: *double*

   Margin in percent of the data time window currently
   processed. This time window covers noise and signal
   \(noiseWindow + timeWindow\). If the pick falls inside
   this margin \(left or right side\) then it is discarded.


.. confval:: profiles.base.$name.stripBadChannels

   Default: ``false``

   Type: *boolean*

   Remove channels with low quality. Read the documenatation
   on waveform quality control for details.


.. confval:: profiles.base.$name.method

   Default: ``"beam packing"``

   Type: *string*

   The beam forming method. Valid methods are:
   
   \"beam packing\"
   
   or
   
   \"FK\".
   
   Reminder: The value should enclosed with double quotes
   if it contains white spaces.


.. confval:: profiles.base.$name.grid.extent

   Default: ``50x50``

   Unit: *nodes*

   Type: *string*

   Number of grid nodes of the processing grid in either direction.


.. note::

   **profiles.slownessgrid.\***
   *Processing parameters for the slowness grid to detect events*
   *within a specific slowness range.*


.. note::

   **profiles.slownessgrid.$name.\***
   $name is a placeholder for the name to be used.


.. confval:: profiles.slownessgrid.$name.grid.unit

   Default: ``s/deg``

   Type: *string*

   Defines the units of the grid ranges.
   The following units are allowed: \"s\/deg\",
   \"s\/km\" and \"k\".


.. confval:: profiles.slownessgrid.$name.grid.rect

   Default: ``100x100-50-50``

   Type: *string*

   Defines the rectangular grid ranges in either direction.
   The suported formats are:
   
   \"wxh[+\-]x[+\-]y\" with
   
   w \/ h: width \/ height
   
   x \/ y: horizontal \/ vertical offset
   
   or
   
   \"[+\-]x1[+\-]y1[+\-]x2[+\-]y2\".
   
   defining explicitely the upper and the lower values
   in horizontal and vertical direction, respectively.


.. note::

   **profiles.backprojection.\***
   *Processing parameters for the backprojection to detect events*
   *in a geographic search region.*


.. note::

   **profiles.backprojection.$name.\***
   $name is a placeholder for the name to be used.


.. confval:: profiles.backprojection.$name.rect

   Type: *string*

   Defines the rectangular geographical search region.
   The suported formats are:
   
   \"hxw[+\-]lat[+\-]lon\" with
   
   h \/ w: height \/ width
   
   lat \/ lon: latitude \/ longitude offset
   
   or
   
   \"[+\-]lat1[+\-]lon1[+\-]lat2[+\-]lon2\".
   
   defining explicitely the lower \(lat1\/lon1\) and the upper
   \(lat2\/lon2\) latitude and longitude values of the region.


.. confval:: profiles.backprojection.$name.depth

   Default: ``10``

   Unit: *km*

   Type: *double*

   Defines the depth of the grid layer to be processed.
   This is in particular important when computing
   travel times to each grid node.


.. note::

   **profiles.backprojection.$name.ttt.\***
   *Travel time table specific settings.*


.. confval:: profiles.backprojection.$name.ttt.type

   Type: *string*

   Defines the travel time table interface type
   such as \"LOCSAT\" or \"libtau\".


.. confval:: profiles.backprojection.$name.ttt.model

   Type: *string*

   Defines the travel time table to be used with
   respect to the configured type.


.. note::

   **profiles.pmcc.\***
   *PMCC processing parameters*


.. note::

   **profiles.pmcc.$name.\***
   $name is a placeholder for the name to be used.


.. confval:: profiles.pmcc.$name.consistencyThreshold

   Type: *float*

   The consistency threshold for a subarray to be able to grow:
   
   consistency <\= consistencyThreshold.


.. confval:: profiles.pmcc.$name.minimumChannels

   Type: *int*

   Pixel: The minimum number of channels in a subarray to form a pixel


.. confval:: profiles.pmcc.$name.minimumSemblance

   Type: *int*

   Pixel: The minimum semblance of channels to be reached in a subarray to form a pixel


.. confval:: profiles.pmcc.$name.minimumPixels

   Type: *int*

   Families: The minimum number of pixels to form a family.


.. confval:: profiles.pmcc.$name.timeDifference

   Unit: *s*

   Type: *float*

   Families: Difference in time between 2 pixels to be considerd for forming a family.


.. confval:: profiles.pmcc.$name.backazimuthDifference

   Unit: *deg*

   Type: *float*

   Families: Difference in backazimuth between 2 pixels to be considerd for forming a family.


.. confval:: profiles.pmcc.$name.slownessDifference

   Unit: *s/deg*

   Type: *float*

   Families: Difference in slowness between 2 pixels to be considerd for forming a family.




Command-Line Options
====================


Generic
-------

.. option:: -h, --help

   Show help message.

.. option:: -V, --version

   Show version information.

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

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


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:: --start-stop-msg arg

   Default: ``0``

   Set sending of a start and a stop message.


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, eg. \-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.


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

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

.. option:: --record-file arg

   Specify a file as record source.

.. option:: --record-type arg

   Specify a type for the records being read.