Installation and Setup
======================

.. _sigma-gsm:

|autoappname| and |guiname| software packages
-------------------------------------------------

1. Obtain the **gsm** script from |gempa| and use it to install the |guiname| package:

   #. Add the |autoappname| and |guiname| packages to the list of packages:

      .. code-block:: bash

         $ gsm setup

   #. Update the package repository list and install the added package. |autoappname|
      and |guiname| are both provided by the *sigma* package:

      .. code-block:: bash

         $ gsm update
         $ gsm install sigma

   #. Install the *oq-engine* package from gempa if you wish to use
      :ref:`external GMPEs <sigma-gmpes-external>` from
      :cite:t:`openquake`:

      .. code-block:: bash

         $ gsm install oq-engine

   **Alternatively**, receive the package tar balls and extract it into the
   |scname| installation, e.g.:

   .. code-block:: bash

      $ cd $SEISCOMP_ROOT/..
      $ tar zxvf sigma-<version>-sei-<SC3 release>-<SC3 version>-<OS>-<OS version>-<architecture>.tar.gz
      $ tar zxvf oq-engine.tar.gz

#. gsm copies the licenses to the correct directory. Alternatively, copy the
   license file to ONE of the the license directories

   .. code-block:: sh

      $ cp sigma.crt sigma-license.txt autosigma.crt autosigma-license.txt $SEISCOMP_ROOT/share/licenses

   or

   .. code-block:: sh

      $ cp sigma.crt sigma-license.txt autosigma.crt autosigma-license.txt $HOME/.seiscomp/licenses

   .. note::

      When using the gsm script and including licenses into the package list, the
      license files are automatically installed by gsm into $SEISCOMP_ROOT/share/licenses
      which the preferred place.


.. _sigma-install-deps:

Software dependencies
---------------------

|autoappname| and |guiname| may require installing additional software packages. The packages
and their installation depends on the installed Linux distribution.
The install script *install-sigma.sh* is provided for various Linux flavors in *$SEISCOMP_ROOT/share/[flavor]/[version]*.
It can be used for installing the software requirements in the same way as
`the SeisComP software requirements <https://docs.gempa.de/seiscomp/current/base/installation.html>`_.

Use the seiscomp script to install the required software dependencies:

.. code-block:: sh

   $ seiscomp install-deps sigma

Alternatively you may install the dependencies using the installations script
:file:`install-sigma.sh` which matches your system. The scripts are located in
:file:`$SEISCOMP_ROOT/share/deps`.


Events and inventory
--------------------

In contrast to other modules for |scname|, |guiname| runs
without connection to the messaging of |scname| and event and station information
can be received from FDSNWS or the |scname| database.

The global parameter :confval:`database` should be configured if the event and
inventory parameters are to be fetched routinely from a |scname| database
(:file:`sigma.cfg`)

.. code-block:: properties

   database = mysql://localhost/seiscomp

One default FDSN server URL is configurable by :confval:`fdsnwsUrl`, e.g. (:file:`sigma.cfg`)

.. code-block:: properties

   fdsnwsUrl = https://service.iris.edu/fdsnws

.. note ::

   In |guiname|, the connection to the database and the FDSN server can be adjusted
   interactively during runtime in the :ref:`Preferences menu <sigma-proc-otf-customization>`.


.. _sigma-output-db:

Output database
---------------

Together with the parameters of one |scname| event the related ground motion
parameters which |autoappname| and |guiname| calculate form an incident.
|autoappname| stores such incidents in a database. The database storage is optional for
|guiname|. For storing the incidents both modules can operate on a

#. :ref:`Standard |scname| <sigma-install-db-standard>` database extended with the
   sigma tables or
#. :ref:`Separate sigma <sigma-install-db-separate>` database based on |scname| database tables.

Both solutions require a configuration. Using a separate database is the
recommended solution.
Regardless of which database is being used, the |guiname| database extensions
must be applied on top of the |scname| database schema. The database
schema extension scripts are provided in :file:`$SEISCOMP_ROOT/share/db/sigma/*.sql`.

To set up the MariaDB / MySQL database for |guiname|, the read the instructions below.


.. _sigma-install-db-standard:

Standard |scname| database
^^^^^^^^^^^^^^^^^^^^^^^^^^

For using the standard |scname| database add the |guiname|-specific tables to the
|scname| database. Assuming that the database name is *seiscomp* and the user name
is *sysop* execute:

.. code-block:: sh

   $ seiscomp stop
   $ mysql -u sysop -p seiscomp < $SEISCOMP_ROOT/share/db/sigma/mysql.sql

More detailed database configuration options and optimizations can be found in
documentation of *SeisComP*.

.. note::

   As of SeisComP in version 4.0.0 and SeisComP3-Jakarta-2020.030 the seiscomp
   database supports 64 Bit IDs. If you have created the MySQL database tables with
   an older release, only 32 Bit IDs are available. In this case you need to add
   the sigma tables using

   .. code-block:: sh

      $ seiscomp stop
      $ mysql -u sysop -p seiscomp < $SEISCOMP_ROOT/share/db/sigma/sql-oid-int.sql


.. _sigma-install-db-separate:

Separate sigma database
^^^^^^^^^^^^^^^^^^^^^^^

Follow the next steps for creating a separate database for |autoappname| and |guiname|
if you do not want to use the standard |scname| database.

1. Log in as database root

   .. code-block:: bash

      $ mysql -u root -p

#. Create a new database named *sigma* assuming that the database user name is
   *sysop* using the password *sysop*. You may freely choose the name of the
   database as well as the credentials of the
   database user. Grant the user *sysop* full access to the database from the
   same machine (localhost):

   .. code-block:: sql

      CREATE DATABASE sigma CHARACTER SET utf8mb4;
      grant usage on sigma.* to sysop@localhost identified by 'sysop';
      grant all privileges on sigma.* to sysop@localhost;
      flush privileges;
      exit

   Instead of restricting the access to the database to a host you
   may also choose to allow access from everywhere:

   .. code-block:: sql

      grant all privileges on sigma.* to sysop@'%';
      flush privileges;

#. Create the seiscomp database table and add the table extensions for the sigma database.

   .. code-block:: sh

      $ mysql -u sysop -p sigma < $SEISCOMP_ROOT/share/db/mysql.sql
      $ mysql -u sysop -p sigma < $SEISCOMP_ROOT/share/db/sigma/mysql.sql

   Please adjust the name of the database as well as the credentials of the DATABASE
   and the paths to the sql files to match your installation.


Database upgrade
^^^^^^^^^^^^^^^^

To upgrade an existing |guiname| database to a newer version, all upgrade scripts for
MariaDB / MySQL are listed below:

* Upgrade from |guiname| database version 1 to 2

  .. code:: sql

     ALTER table SEPRecord
     DROP COLUMN distance,
     ADD COLUMN repi DOUBLE UNSIGNED AFTER waveformID_resourceURI,
     ADD COLUMN rhyp DOUBLE UNSIGNED AFTER repi,
     ADD COLUMN rjb DOUBLE UNSIGNED AFTER rhyp,
     ADD COLUMN rrup DOUBLE UNSIGNED AFTER rjb,
     ADD COLUMN vs30 DOUBLE UNSIGNED AFTER rrup,
     ADD COLUMN z1pt0 DOUBLE UNSIGNED AFTER vs30,
     ADD COLUMN z2pt5 DOUBLE UNSIGNED AFTER z1pt0;

     UPDATE Meta SET value='2' where name='SEP-Version';


.. _sec-sigma-db-config:

Configuration
^^^^^^^^^^^^^

Use |autoappname| and |guiname| either with

* The standard database of |scname| containing the required |guiname| tables, e.g.:

  .. code-block:: properties

     output.database = mysql://localhost/seiscomp

* Or the separate sigma database, e.g.:

  .. code-block:: properties

     output.database = mysql://localhost/sigma

Configure the output database in both files :file:`autosigma.cfg` and :file:`sigma.cfg`.

Later, the URL can be overridden on the command line, e.g.:

.. code-block:: sh

   $ sigma --output mysql://localhost/seiscomp


.. _sigma_vs30:

Vs30 grid
---------

|autoappname| and |guiname| can consider Vs30 models when calculating ground
motion parameters. Whether the Vs30 model is considered or not depends on the
used :ref:`GMPE <sigma-gmpes>`.

The Vs30 model are provided as a GeoTIFF (:code:`.grd`) or modified surfer grid
file (:code:`.tif`). In the modified surfer grid file dimX and dimY are integers
rather than shorts and the magic first 4 bytes contain GB. The GeoTIFF reader is
activated if the file extension is :code:`.tif`.
A file containing a global Vs30  modified surfer grid or a GeoTIFF file can be
obtained from |gempa| or from USGS :cite:p:`usgs-vs30`, respectively.

Execute the following steps for downloading the GeoTIFF file from
USGS :cite:p:`usgs-vs30` for installation and configuration.

#. Download the file, create a dedicated directory and place the file therein.

   * **The best way** to get and install the grid file is by using :program:`gsm`
     through the package *global_vs30*. :program:`gsm` will create the
     configured data directory which by default is
     :file:`/home/data/velocity/global_vs30/` and place the file therein,

   * Alternatively, you may download a GeoTIFF file from USGS:

     .. code-block:: sh

        $ wget -O /tmp/global_vs30_tif.zip 'https://earthquake.usgs.gov/static/lfs/data/global_vs30_tif.zip'
        $ unzip /tmp/global_vs30_tif.zip -d /tmp/
        $ mkdir -p /home/data/velocity/global_vs30/
        $ mv global_vs30.tif /home/data/velocity/global_vs30/

   .. note::

      Customized Vs30 files in grid or GeoTIFF format can be also created by the user
      itself for specific regions and higher resolution.

#. Configure |guiname| to use that grid or GeoTIFF file by
   :confval:`gmpe.vs30grid` in :file:`sigma.cfg` and :file:`autosigma.cfg`:

   .. code-block:: sh

      gmpe.vs30grid = /home/data/velocity/global_vs30/global_vs30.grd


.. _sigma-plugins:

GMPE plugins
-------------

Some ground motion parameters like :term:`MMI`, :term:`PGV` and others are calculated
based on :term:`GMPEs <GMPE>`/:term:`GMMs <GMM>` using plugins. The parameters
depend on the plugin. The plugins provide access to different implementations:

* **cppgmpe** plugin: Access to the
  :ref:`internally defined GMPEs <sigma-gmpes-internal>`. These GMPEs are
  described in section :ref:`sigma-gmpes`.
* **py3gmpe** plugin: Access to
  :ref:`externally defined GMPEs <sigma-plugins-external>` by the
  :cite:t:`openquake` GMPEs using Python3. Check the list of models in
  :cite:t:`openquake-models`.

Load the **cppgmpe** and the **py3gmpe** plugins by adding the plugin names
to the list of loaded plugins for providing the interfaces to the GMPEs.

.. code-block:: sh

   plugins = ${plugins}, cppgmpe, py3gmpe


.. _sigma-plugins-internal:

Internally defined GMPEs
^^^^^^^^^^^^^^^^^^^^^^^^

.. warning::

   As with sigma version 2024.012, the plugin gmpeeewd is fully replaced and extended by the plugin cppgmpe.
   If updating from earlier version changes in sigma.cfg and autosigma.cfg might be necessary, i.e. plugin
   loading replace `gmpeeewd` with `cppgmpe` and e.g. `EEWD/AkkarEtAl2014`
   with `cppgmpe/AkkarEtAl2014`.

The GMPE models internally defined in |autoappname| and |appname| are described
section :ref:`sigma-gmpes`. These GMPEs are provided through the plugin
**cppgmpe** and can be used without further software installations. Add the
plugin in |guiname| or |autoappname| in :file:`sigma.cfg` or :file:`autosigma.cfg`,
respectively

.. code-block:: properties

   plugins = ${plugins}, cppgmpe

* |appname|: No further configuration is required. However, you may wish to add
  the GMPEs to an existing or a new profile, e.g. "iceland" (:file:`sigma.cfg` )

  .. code-block:: properties

     gmpe.groups = iceland
     gmpe.group.iceland.name = "Internal: Iceland"
     gmpe.group.iceland.members = cppgmpe/IMO-PV09, cppgmpe/KowsariEtAl2020_Y1, cppgmpe/KowsariEtAl2020_Y2

  An example configuration is provided in
  :file:`$SEISCOMP_ROOT/etc/defaults/sigma.cfg` from which you can copy
  the relevant parameters.

* |autoappname|: Additionally, the parameter :confval:`profile.$name.gmpe` must
  be configured accordingly:

  #. Define a new processing profile, e.g. iceland,
  #. Add the name of the processing profile to :confval:`profiles`,
  #. Add the GMPE to the profile together with other control and processing parameters.

  Example of a minimum module configuration (:file:`autosigma.cfg`):

  .. code-block:: properties

     plugins = ${plugins}, cppgmpe

     # A list of processing profiles.
     profiles = iceland

     # Defines the GMPE model to be used. The format is <provider>/<model>, analogue
     # to SIGMA,e.g. "cppgmpe/CEA2014" or "py3gmpe/AbrahamsonEtAl2014".
     profile.iceland.gmpe = cppgmpe/IMO-PV09

.. note::

   All available GMPEs which are not registered through profiles will be grouped
   in |guiname| in the group "Ungrouped".

.. _sigma-plugins-external:

External GMPEs: OpenQuake specific Python scripts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

|autoappname| and |appname| can also make use of the external
:term:`GMPEs<GMPE>`/:term:`GMMs <GMM>` provided by
:cite:t:`openquake` and specific Python scripts.
In order to make use of the GMPEs provided by :cite:t:`openquake`
Python 3.5+ must be installed and linked to |scname|.

#. Install OpenQuake by the oq-engine package

   * Preferably :ref:`install OpenQuake using gsm <sigma-gsm>`, the gempa
     package manager.

     .. hint::

        When using *gsm* all related files are installed and correctly linked to
        |appname|, e.g. the oq-engine directory and the correct link
        are automatically generated.

   * Alternatively load OpenQuake from the
     public OpenQuake web repository on GitHub :cite:p:`openquake-github`
     and link to a dedicated directory, e.g. :file:`/home/data/oq-engine`.

     .. warning ::

        Installation from public repositories may result in inconsistencies and
        is currently not recommended.

     #. First install the required package. The installation depends on the Linux
        distribution and version.

        **Ubuntu 16.04+ and Debian**

        .. code-block:: sh

           $ sudo add-apt-repository -y ppa:openquake/ppa
           $ sudo apt-get update
           $ sudo apt-get install python-oq-engine

        **CentOS 7**

        .. code-block:: sh

           $ su -
           $ yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
           $ curl -sL https://copr.fedoraproject.org/coprs/gem/openquake-stable/repo/epel-7/gem-openquake-stable-epel-7.repo | sudo tee /etc/yum.repos.d/gem-openquake-stable-epel-7.repo
           $ yum install python3-oq-engine
           $ yum install centos-release-scl
           $ yum-config-manager --enable rhel-server-rhscl-7-rpms
           $ yum install rh-python35 rh-python35-scipy

     #. Create a Symlink from $SEISCOMP_ROOT/lib/python/openquake to the openquake
        directory, e.g.

        .. code-block:: sh

           $ ln -s /home/data/oq-engine/openquake $SEISCOMP_ROOT/lib/python/openquake

#. Configure the GMPEs equally for |autoappname| and |appname| in :file:`autosigma.cfg`
   and :file:`sigma.cfg`, respectively, in :file:`$SEISCOMP_ROOT/etc` (preferred)
   or in :file:`@CONFIGDIR@`. An example configuration is provided
   in :file:`$SEISCOMP_ROOT/share/sigma/pygmpe/sigma.cfg` from which you can copy
   the relevant parameters.

   For a configuration of specific GMPEs follow the example instructions:

   #. add the *py3gmpe* plugin

      .. code-block:: properties

         plugins = ${plugins}, py3gmpe

   #. add and configure GMPE group profiles to sort the GMPEs logically using
      :confval:`gmpe.group.$name.name` and :confval:`gmpe.group.$name.members`:

      .. code-block:: properties

         gmpe.group.ActiveShallowCrust.name = "ActiveShallowCrust"
         gmpe.group.ActiveShallowCrust.members = \
              py3gmpe / AbrahamsonEtAl2014RegCHN,\
              py3gmpe / AbrahamsonEtAl2014

   #. register GMPE groups in :confval:`gmpe.groups`, e.g.

      .. code-block:: properties

         gmpe.groups = ActiveShallowCrust

#. The GMPE models are invoked from one or more user-defined Python scripts. GMPEs defined
   outside of OpenQuake may be also be defined in separate scripts. However, for
   easier visibility create additional GMPE profiles to separate the definition of
   the different GMPE sources by in configurations of :ref:`AUTOSIGMA <sec-autosigma-config>`
   and :ref:`SIGMA <sec-sigma-config>`.


Old SIGMA versions
~~~~~~~~~~~~~~~~~~

**This applies to old SIGMA versions only!**

In old SIGMA version the OpenQuake Python libraries had to be specifically set
and the call of SIGMA had to be redirected to $HOME/bin/sigma:

#. Create an executable file named sigma:

   .. code-block:: sh

      $ vi $HOME/bin/sigma

         export PYTHONPATH=/opt/openquake/lib/python3.5/site-packages:/opt/openquake/lib64/python3.5/site-packages
         scl enable rh-python35 "LD_PRELOAD=/opt/rh/rh-python35/root/usr/lib64/libpython3.5m.so $SEISCOMP_ROOT/bin/sigma $*"

#. Set the PATH variable correctly such that $HOME/bin is before $SEISCOMP_ROOT/bin. In ~/.bashrc set
   after the |scname| environment variables:

   .. code-block:: sh

      $ vi ~/.bashrc
         PATH=$HOME/bin:$PATH
      $ source ~/.bashrc

#. Install the additionally required software packages:

   * python3-zmq
   * python3-toml
   * python3-shapely
   * python3-psutil
   * python3-h5py
   * python3-scipy
   * python3-requests
   * python3-matplotlib


.. _sec-sigma-process-output:

autosigma: Process output
-------------------------

|autoappname| stores the incidents in the database defined by :confval:`output.database`,
read the section :ref:`sigma-output-db` for the database setup.
|autoappname| also generates files including incident XML, PNG images, grid files
in Surfer format and waveforms in
:confval:`output.exportPath`. For details on the files read section :ref:`sec-autosigma-output`.

Upon creation of the files, |autoappname| call the
script defined in :confval:`output.exportScript` is executed to treat the files,
e.g. for archiving. An example script is provided with
:file:`@DATADIR@/share/sigma/export-autosigma.sh`.

Example configuration (:file:`autosigma.cfg`):

.. code-block:: properties

   output.database = mysql://localhost/sigma
   output.exportPath = @LOGDIR@/autosigma
   output.exportScript = @DATADIR@/sigma/scripts/export-autosigma.sh

For viewing the output grid files on maps, the GUI modules showing maps can be
configured with the :cite:t:`mapmultigrid` plugin.


.. _sec-sigma-report-config:

sigma: Report generation
------------------------

SIGMA allows to interactively generate files including waveforms, maps and XML from within the
:ref:`Export dialog in SIGMA <sec-sigma-report>`. The generated files can be found
in :confval:`output.exportPath`.

Customized :ref:`reports <sec-sigma-report>` based on these files and user-defined
scripts can be generated. Example generator scripts, report templates and script
configuration are provided as part of the SIGMA package. The generator script can
also be called from within the
:ref:`Export dialog in SIGMA <sec-sigma-report>` or as a command line application.
The script and related scripts and files can be used as templates to generate user-defined
reports. Contact `gempa <https://www.gempa.de/contact/>`_ for assistance if needed.


Scripts and templates
^^^^^^^^^^^^^^^^^^^^^

The default python script for report generation is

.. code-block:: sh

   $SEISCOMP_ROOT/share/sigma/scripts/parseIncident.py

The script will generate a PDF file based on the files generated in
:confval:`output.exportPath` and a Latex template file
:file:`$SEISCOMP_ROOT/share/sigma/scripts/template.tex`

The python script and the Latex template file can be renamed and modified for customization.
The name and location of the python script must be configured correctly in
:confval:`output.exportScript` of the module configuration of SIGMA.
The python script uses functions provided in $SEISCOMP_ROOT/share/sigma/scripts/.


Software dependencies
^^^^^^^^^^^^^^^^^^^^^

The script :file:`parseIncident.py` relies on *xelatex* which must be installed.


Configuration
^^^^^^^^^^^^^

The configuration is identical for |guiname| and |autoappname| and can be equally
adjusted in both files :file:`autosigma.cfg` and :file:`sigma.cfg`.

The provided Python script :file:`parseIncident.py` takes the default configuration
from the configuration file
named according to itself, i.e. :file:`$SEISCOMP_ROOT/etc/defaults/parseIncident.cfg`.
To make changes to the configuration
copy the default file to $SEISCOMP_ROOT/etc/ and apply the required changes there.
All unmodified parameters can be removed from the new file as they are read from the
default. The default parameters may be updated during the next installation of SIGMA.

.. code-block:: sh

   $ cp $SEISCOMP_ROOT/etc/defaults/parseIncident.cfg $SEISCOMP_ROOT/etc/
   $ vi $SEISCOMP_ROOT/etc/parseIncident.cfg

Some usually considered parameters in :file:`parseIncident.cfg` are:

* input.datadir : this is where the report generator finds the files generated by SIGMA.
  The directory name must be identical to :confval:`output.exportPath` in the module
  configuration of SIGMA.
* output.archive : the directory were the generated files will be archived by the report generator
* output.view : enable to view the generated report in the default system viewer

Execute the generator script on the command line to learn about it and to test it, e.g.:

.. code-block:: sh

   $ python $SEISCOMP_ROOT/share/sigma/scripts/parseIncident.py -h
   $ python $SEISCOMP_ROOT/share/sigma/scripts/parseIncident.py --debug


.. _sec-autosigma-config:

|autoappname| Configuration
---------------------------


Module configuration
^^^^^^^^^^^^^^^^^^^^

The module configuration parameters are stored in the configuration file :file:`autosigma.cfg`
located either in the directory @SYSTEMCONFIGDIR@ or in @CONFIGDIR@.
The configuration of the GMPEs is similar to the configuration of :ref:`SIGMA <sec-sigma-config>`.

.. note::

   Find a comprehensive example configuration file for using |autoappname| with the provided Python script
   in @DATADIR@/sigma/pygmpe.

#. Define the python script where to find the external GMPE model, e.g. :file:`oq-sm.py`
   in :confval:`gmpe.py3.models` if they should be used along with the interfacing
   Python script. Also define the basePath where the Python scripts can be found
   (:confval:`gmpe.py3.basePath`), e.g.

   .. code-block:: properties

      gmpe.py3.basePath = @DATADIR@/sigma/py3gmpe/
      gmpe.py3.models = "AbrahamsonSilva1997;oq-sm.py,AbrahamsonEtAl2014;oq-sm.py,AtkinsonBoore2006;oq-sm.py"

   .. note::

     The models may be invoked from several Python scripts. GMPEs defined
     outside of OpenQuake may be defined in separate scripts. However, for
     easier visibility create additional profiles to separate the definition of
     the different GMPE sources. See the configuration of :ref:`AUTOSIGMA <sec-autosigma-config>`
     for examples of profiles.

#. Optionally define the **list of profiles** with their parameters which may be considered. More than one
   profile may defined. GMPE models defined but not contained in profiles will be shown as "**Ungrouped**"
   in SIGMA.
   The region for which the profile is valid may be given by a rectangle or
   BNA polygon name :cite:p:`gui` for more flexibility.

   .. code-block:: properties

      profile.potsdam.region = "potsdam"
      profile.potsdam.gmpe = "cppgmpe/CEA2014"
      profile.potsdam.minimumMagnitude = 2

      profile.leipzig.rect = "51.0,12.0,51.5,12.7"
      profile.leipzig.gmpe = "py3gmpe/AbrahamsonSilva1997"
      profile.leipzig.minimumMagnitude = 1

   Configure any other parameter related to the profile. Default value will be used
   if not defined otherwise.

#. Provide the **names of the profiles** which are to be used using :confval:`profiles`.
   Choose from the **list of defined profiles**. Different profiles may be defined
   for different regions. E.g.

   .. code-block:: properties

      profiles = potsdam, leipzig

#. The processing results are stored in the SIGMA database as one
   :term:`incident <incident>` per event. Provide the database
   URI: location and name, e.g.

   .. code-block:: properties

      output.database = "mysql://localhost/sigma"

#. Define the epicentral distance in km for which stations are considered

   .. code-block:: properties

      acquisition.maximumEpicentralDistance = 1000

   The values defined in :confval:`acquisition.maximumEpicentralDistance` can be
   over-written by :confval:`acquisition.magnitudeDistanceTable` in order to
   provide maximum epicentral distances based on the event magnitudes.

#. As in SIGMA define the Vs30 as GeoTIFF or modified Surfer grid file

   .. code-block:: properties

      gmpe.vs30grid = @DATADIR@/velocity/global_vs30.tif

#. A customized script defined in :confval:`output.exportScript` may be used to
   generate customized output files. |autoappname| will pass 3 arguments to the script:

   #. eventID defining the :term:`event`
   #. incidentID defining the :term:`incident`
   #. :confval:`output.exportPath` defining the directory where all files are stored.

   .. code-block:: properties

      output.exportPath = @LOGDIR@/autosigma
      output.exportScript = @CONFIGDIR@/autosigma/autosigma.py

   A very simple BASH script, e.g. :file:`@DATADIR@/sigma/scripts/autosigma_script.sh`
   for moving the produced output file to a new directory, may look like this:

   .. code-block:: sh

      #!/bin/bash

      echo `date` $0 $@ >> $HOME/.seiscomp/log/autosigma_script.log

      sourceDir=$3
      targetDir=$HOME/.seiscomp/autosigma-safe/$1/$2

      mkdir -p $targetDir
      mv $sourceDir/* $targetDir
      echo `date` moved all files for event $1 incident $2 to $targetDir >> $HOME/.seiscomp/log/autosigma_script.log

   Add the file name to the configuration, e.g.

   .. code-block:: properties

      output.exportScript = @DATADIR@/sigma/scripts/autosigma_script.sh

Bindings Configuration
^^^^^^^^^^^^^^^^^^^^^^

|autoappname| requires module bindings for working with station data. The bindings
define the stations to be used and their respective data streams.


Module start
^^^^^^^^^^^^

Eventually apply all configurations: write the bindings configuration to the
database, enable |autoappname| to start the module automatically during startup of
|scname| and start |autoappname|:

.. code-block:: sh

   $ seiscomp update-config autosigma
   $ seiscomp enable autosigma
   $ seiscomp start autosigma

.. note::

   Typically |autoappname| is started on demand by other modules such as
   :cite:t:`gds`. Then |autoappname| is **not enabled**
   and **not started** as a daemon module.


   .. _sec-sigma-config:

|guiname| Configuration
------------------------


Module configuration
^^^^^^^^^^^^^^^^^^^^

The module configuration parameters are stored in the configuration file :file:`sigma.cfg`
located either in the directory @SYSTEMCONFIGDIR@ or in @CONFIGDIR@.

.. note::

   Find a comprehensive example configuration file for using SIGMA with the
   OpenQuake GMPEs and the provided Python script in @DATADIR@/sigma/pygmpe.

Take the following steps for configuration of SIGMA with the GMPEs provided by
the OpenQuake package. The configuration of the GMPEs is identical to AUTOSOIGMA.

1. Sigma does not connect to the |scname| messaging. However, a |scname| database
   can be used directly for **READING** event and station parameters. The parameters
   can be defined in the global section of the sigma configuration, e.g.:

   .. code-block:: properties

      database = mysql://sysop:sysop@localhost/seiscomp

   This parameter is optional. If unset the database can be chosen during startup.

#. Define the base URL for connecting to FDSNWS servers allowing to fetch event
   parameters and waveforms from external sources

   .. code-block:: properties

      fdsnwsUrl = http://service.iris.edu/

   This parameter is optional. It can be changed during runtime in the
   *Preferences* menu of SIGMA.

#. Define the Vs30 as GeoTIFF or grid file

   .. code-block:: properties

      gmpe.vs30grid = @DATADIR@/velocity/global_vs30.tif

#. Define the database for storing :term:`incidents <incident>`.

   .. code-block:: properties

      database.output = mysql://localhost/sigma

#. Define the GMPE models

   * add the plugins, e.g. of internal and external GMPEs

     .. code-block:: properties

        plugins = ${plugins}, cppgmpe, py3gmpe

   * for :ref:`internal GMPEs <sigma-gmpes-internal>` copy from
     :ref:`examples <sigma-plugins-internal>`

   * for GMPEs defined by the :ref:`external OpenQuake library <sigma-gmpes-external>`
     follow the :ref:`instructions for their installation and setup <sigma-plugins-external>`
     and adjust the module and bindings configurations as for :ref:`AUTOSIGMA <sec-autosigma-config>`.


Bindings Configuration
^^^^^^^^^^^^^^^^^^^^^^

|guiname| requires module bindings for working with station data and for view stations
on the maps.  The bindings define the stations to be used and their respective
data streams.