Installation and Setup

AUTOSIGMA and SIGMA software packages

  1. Obtain the gsm script from gempa and use it to install the SIGMA package:

    1. Add the AUTOSIGMA and SIGMA packages to the list of packages:

      $ gsm setup

    2. Update the package repository list and install the added package. AUTOSIGMA and SIGMA are both provided by the sigma package:

      $ gsm update
$ gsm install sigma

    3. Install the oq-engine package from gempa if you wish to use external GMPEs from OpenQuake [6]:

      $ gsm install oq-engine

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

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

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

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

    or

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

Software dependencies

AUTOSIGMA and SIGMA 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.

Use the seiscomp script to install the required software dependencies:

$ seiscomp install-deps sigma

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

Events and inventory

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

The global parameter database should be configured if the event and inventory parameters are to be fetched routinely from a SeisComP database (sigma.cfg)

database = mysql://localhost/seiscomp

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

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

Note

In SIGMA, the connection to the database and the FDSN server can be adjusted interactively during runtime in the Preferences menu.

Output database

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

  1. Standard |scname| database extended with the sigma tables or

  2. Separate sigma database based on SeisComP database tables.

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

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

Standard SeisComP database

For using the standard SeisComP database add the SIGMA-specific tables to the SeisComP database. Assuming that the database name is seiscomp and the user name is sysop execute:

$ 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

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

Separate sigma database

Follow the next steps for creating a separate database for AUTOSIGMA and SIGMA if you do not want to use the standard SeisComP database.

  1. Log in as database root

    $ mysql -u root -p

  2. 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):

    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:

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

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

    $ 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 SIGMA database to a newer version, all upgrade scripts for MariaDB / MySQL are listed below:

  • Upgrade from SIGMA database version 1 to 2

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

Configuration

Use AUTOSIGMA and SIGMA either with

  • The standard database of SeisComP containing the required SIGMA tables, e.g.:

    output.database = mysql://localhost/seiscomp

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

    output.database = mysql://localhost/sigma

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

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

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

Vs30 grid

AUTOSIGMA and SIGMA can consider Vs30 models when calculating ground motion parameters. Whether the Vs30 model is considered or not depends on the used GMPE.

The Vs30 model are provided as a GeoTIFF (.grd) or modified surfer grid file (.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 .tif. A file containing a global Vs30 modified surfer grid or a GeoTIFF file can be obtained from gempa or from USGS [7], respectively.

Execute the following steps for downloading the GeoTIFF file from USGS [7] for installation and configuration.

  1. 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 gsm through the package global_vs30. gsm will create the configured data directory which by default is /home/data/velocity/global_vs30/ and place the file therein,

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

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

  2. Configure SIGMA to use that grid or GeoTIFF file by gmpe.vs30grid in sigma.cfg and autosigma.cfg:

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

GMPE plugins

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

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.

plugins = ${plugins}, cppgmpe, py3gmpe

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 AUTOSIGMA and SIGMA are described section GMPE/GMM: Ground Motion Prediction Equations and Models. These GMPEs are provided through the plugin cppgmpe and can be used without further software installations. Add the plugin in SIGMA or AUTOSIGMA in sigma.cfg or autosigma.cfg, respectively

plugins = ${plugins}, cppgmpe

  • SIGMA: No further configuration is required. However, you may wish to add the GMPEs to an existing or a new profile, e.g. “iceland” (sigma.cfg )

    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 $SEISCOMP_ROOT/etc/defaults/sigma.cfg from which you can copy the relevant parameters.

  • AUTOSIGMA: Additionally, the parameter profile.$name.gmpe must be configured accordingly:

    1. Define a new processing profile, e.g. iceland,

    2. Add the name of the processing profile to profiles,

    3. Add the GMPE to the profile together with other control and processing parameters.

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

    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 SIGMA in the group “Ungrouped”.

External GMPEs: OpenQuake specific Python scripts

AUTOSIGMA and SIGMA can also make use of the external GMPEs/GMMs provided by OpenQuake [6] and specific Python scripts. In order to make use of the GMPEs provided by OpenQuake [6] Python 3.5+ must be installed and linked to SeisComP.

  1. Install OpenQuake by the oq-engine package

    • Preferably install OpenQuake using gsm, the gempa package manager.

      Hint

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

    • Alternatively load OpenQuake from the public OpenQuake web repository on GitHub [5] and link to a dedicated directory, e.g. /home/data/oq-engine.

      Warning

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

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

      $ ln -s PATH/TO/OQ-ENGINE/openquake $SEISCOMP_ROOT/lib/python/openquake

  2. Configure the GMPEs equally for AUTOSIGMA and SIGMA in autosigma.cfg and sigma.cfg, respectively, in $SEISCOMP_ROOT/etc (preferred) or in @CONFIGDIR@. An example configuration is provided in $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:

    1. add the py3gmpe plugin

      plugins = ${plugins}, py3gmpe

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

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

    3. register GMPE groups in gmpe.groups, e.g.

      gmpe.groups = ActiveShallowCrust

  3. 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 AUTOSIGMA and SIGMA.

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:

  1. Create an executable file named sigma:

    $ 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 $*"

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

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

  3. Install the additionally required software packages:

    • python3-zmq

    • python3-toml

    • python3-shapely

    • python3-psutil

    • python3-h5py

    • python3-scipy

    • python3-requests

    • python3-matplotlib

autosigma: Process output

AUTOSIGMA stores the incidents in the database defined by output.database, read the section Output database for the database setup. AUTOSIGMA also generates files including incident XML, PNG images, grid files in Surfer format and waveforms in output.exportPath. For details on the files read section Data products and output.

Upon creation of the files, the script defined in output.exportScript is executed to treat the files, e.g. for archiving. An example script is provided with @DATADIR@/sigma/scripts/export-autosigma.sh.

Example configuration (autosigma.cfg):

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 mapmultigrid [8] plugin.

Report generation

SIGMA allows to interactively generate files including waveforms, maps and XML from within the Export dialog in SIGMA. AUTOSIGMA creates the same files but automatically.

Based on these files and user-defined scripts, customized reports can be generated. By default SIGMA/AUTOSIGMA uses the package report-generators (RGSM) for generating customizable reports. Alternatively, any other script can be used to generate reports. Make sure the script is executable and accepts three passed parameters: an eventID, an internal eventID and the export path.

Based on the files generated in output.exportPath and a Latex template file, e.g. for RGSM in $SEISCOMP_ROOT/share/rgsm/sigma/templates, the script will generate a PDF file.

Example generator scripts and report templates are provided as part of the RGSM package. The Latex template file(s) can be renamed and modified for customization. Contact gempa for assistance if needed.

Software dependencies

To use the default report generation tool RGSM, make sure that it is installed, i.e. via gsm:

$ gsm update
$ gsm install report-generators

Configuration

The configuration is identical for SIGMA and AUTOSIGMA and can be equally adjusted in both files autosigma.cfg and sigma.cfg.

For changing the report script and the output directory, modify output.exportScript and output.exportPath, respectively. Default settings:

# The script that will be called when an incident is exported. Please ensure
# that the script is executable. 3 parameters are passed: The eventID, an
# internal eventID and the export path where all files are stored.
output.exportScript = @ROOTDIR@/bin/rgsm

# The path where all result files are saved.
output.exportPath = @LOGDIR@/sigma/output

AUTOSIGMA Configuration

Module configuration

The module configuration parameters are stored in the configuration file autosigma.cfg located either in the directory @SYSTEMCONFIGDIR@ or in @CONFIGDIR@. The configuration of the GMPEs is similar to the configuration of SIGMA.

Note

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

  1. Only if external GMPE models should be used, define the python script where to find them, e.g. oq-sm.py in 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 (gmpe.py3.basePath), e.g.

    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 AUTOSIGMA for examples of profiles.

  2. 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 [2] for more flexibility.

    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.

  3. Provide the names of the profiles which are to be used using profiles. Choose from the list of defined profiles. Different profiles may be defined for different regions. E.g.

    profiles = potsdam, leipzig

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

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

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

    acquisition.maximumEpicentralDistance = 1000

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

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

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

  7. A customized script defined in output.exportScript may be used to generate customized output files. AUTOSIGMA will pass 3 arguments to the script:

    1. eventID defining the event

    2. incidentID defining the incident

    3. output.exportPath defining the directory where all files are stored.

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

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

    #!/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.

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

Bindings Configuration

AUTOSIGMA 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 AUTOSIGMA to start the module automatically during startup of SeisComP and start AUTOSIGMA:

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

Note

Typically AUTOSIGMA is started on demand by other modules such as GDS [1]. Then AUTOSIGMA is not enabled and not started as a daemon module.

SIGMA Configuration

Module configuration

The module configuration parameters are stored in the configuration 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 AUTOSIGMA.

  1. Sigma does not connect to the SeisComP messaging. However, a SeisComP 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.:

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

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

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

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

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

  3. Define the Vs30 as GeoTIFF or grid file

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

  4. Define the database for storing incidents.

    database.output = mysql://localhost/sigma

  5. Define the GMPE models

Bindings Configuration

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