[seiscomp, scanloc] Install, add .gitignore

share/doc/seiscomp/html/_sources/apps/msrtsimul.rst.txt

@@ -0,0 +1,201 @@
+.. highlight:: rst
+
+.. _msrtsimul:
+
+#########
+msrtsimul
+#########
+
+**MiniSEED real time playback and simulation**
+
+
+Description
+===========
+
+msrtsimul simulates a real-time data acquisition by injecting miniSEED data from a
+file into the seedlink buffer via the mseedfifo plugin for seedlink. It can be
+used for simulating real-time conditions in playbacks for whole-system
+demonstrations, user training, etc.
+
+The data is played back as if they were recorded at current time. Therefore,
+creation times and the actual data times including pick times, event times etc.
+will be **obscured**. :ref:`Historic playbacks <sec-msrtsimul-historic>` allow
+keeping the actual data times.
+
+.. hint::
+
+   * Playbacks on production systems are normally not recommended.
+   * For real-time playbacks, the data must be sorted by end time. This
+     requirement may be violated. Use :ref:`scmssort` for sorting the data by
+     (end) time.
+   * Stop :ref:`slarchive` before running msrtsimul for avoiding that data with
+     wrong times are archived.
+   * Normally, :ref:`seedlink` assumes that the data is provided in records of
+     512 bytes. msrtsimul issues a warning when detecting a record of other size.
+   * Data available in other record sizes can be repacked to 512 bytes by
+     external software such as :program:`msrepack` available with
+     :cite:t:`libmseed-github`.
+   * Applications other than standard :ref:`seedlink` in |scname| or
+     :ref:`seedlink` compiled specifically may accept other record sizes. For
+     accepting these records use msrtsimul with :option:`--unlimited`.
+
+
+Non-default seedlink pipes
+--------------------------
+
+By default, msrtsimul writes the data into the mseedfifo pipe
+*$SEISCOMP_ROOT/var/run/seedlink/mseedfifo*.
+If the data is to be written into the pipe of a :program:`seedlink` alias or
+into any other pipe, the pipe name must be adjusted. Use the option
+
+* :option:`--seedlink` to replace *seedlink* by another name, e.g. a seedlink instance
+  created as an alias, **seedlink-test**. This would write into
+  *$SEISCOMP_ROOT/var/run/seedlink-test/mseedfifo*.
+* :option:`--stdout` to write to standard output and then redirect to any other location.
+
+
+.. _sec-msrtsimul-historic:
+
+Historic playbacks
+------------------
+
+You may use msrtsimul with the :option:`-m` *historic* option to maintain the
+time of the records,
+thus the times of picks, amplitudes, origins, etc. but not the creation times.
+Applying :option:`-m` *historic* will feed the data into the seedlink buffer at the time
+of the records. The time of the system is untouched. GUI, processing modules, logging,
+etc. will run with current system time. The historic mode allows to process waveforms
+with the stream inventory valid at the time when the data were recorded including
+streams closed at current time.
+
+.. warning ::
+
+   When repeating historic playbacks, the waveforms are fed multiple times to the
+   seedlink buffer and the resulting picks are also repeated with the same pick
+   times. This may confuse the real-time system. Therefore, seedlink and other modules
+   creating or processing picks should be
+   stopped, the seedlink buffer should be cleared and the processing
+   modules should be restarted to clear the buffers before starting the
+   historic playbacks. Make sure :ref:`scautopick` is configured or started with
+   the :option:`--playback` option. Example:
+
+   .. code-block:: sh
+
+      seiscomp stop
+      rm -rf $SEISCOMP_ROOT/var/lib/seedlink/buffer
+      seiscomp start
+      msrtsimul ...
+
+
+seedlink setup
+--------------
+
+For supporting msrtsimul activate the :confval:`msrtsimul` parameter in the
+seedlink module configuration (:file:`seedlink.cfg`), update the configuration
+and restart seedlink before running msrtsimul:
+
+.. code-block:: sh
+
+   seiscomp update-config seedlink
+   seiscomp restart seedlink
+   msrtsimul ...
+
+
+Examples
+--------
+
+1. Playback miniSEED waveforms in real time with verbose output:
+
+   .. code-block:: sh
+
+      $ msrtsimul -v miniSEED-file
+
+#. Playback miniSEED waveforms in historic mode. This may require :ref:`scautopick`
+   to be started with the option *playback*:
+
+   .. code-block:: sh
+
+      msrtsimul -v -m historic miniSEED-file
+
+#. Feed the data into the buffer of a specific seedlink instance, e.g. *seedlink-test*:
+
+   .. code-block:: sh
+
+      msrtsimul -v --seedlink seedlink-test miniSEED-file
+
+
+.. _msrtsimul_configuration:
+
+Module Configuration
+====================
+
+| :file:`etc/defaults/global.cfg`
+| :file:`etc/defaults/msrtsimul.cfg`
+| :file:`etc/global.cfg`
+| :file:`etc/msrtsimul.cfg`
+| :file:`~/.seiscomp/global.cfg`
+| :file:`~/.seiscomp/msrtsimul.cfg`
+
+msrtsimul inherits :ref:`global options<global-configuration>`.
+
+
+
+
+Command-Line Options
+====================
+
+.. program:: msrtsimul
+
+:program:`msrtsimul [OPTION] miniSEED-file`
+
+
+Verbosity
+---------
+
+.. option:: -h, --help
+
+   Display this help message.
+
+.. option:: -v, --verbose
+
+   Verbose mode.
+
+
+Playback
+--------
+
+.. option:: -c, --stdout
+
+   Write on standard output. The output my be redirected to a
+   specific mseedfifo path.
+
+.. option:: -d, --delays
+
+   Add artificial delays.
+
+.. option:: -j, --jump float
+
+   Minutes to skip at the beginning.
+
+.. option:: -m, --mode string
+
+   Playback mode: choose between 'realtime' and 'historic'
+
+.. option:: --seedlink string
+
+   The seedlink module name. Useful if a seedlink alias or
+   non\-standard names are used. Replaces 'seedlink'
+   in the standard mseedfifo path.
+
+.. option:: -s, --speed float
+
+   Speed factor. 1 is normal speed.
+
+.. option:: --test
+
+   Test mode.
+
+.. option:: -u, --unlimited
+
+   Allow miniSEED records which are not 512 bytes.
+