Installation and setup

Software dependencies

AUTOSIMA 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 requirements as for the SeisComP3 software requirements.

Execute the script manually or use the seiscomp script:

seiscomp --asroot install-deps sigma

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
    
    1. Update the package repository list and install the added package

      gsm update
      gsm install autosigma
      gsm install sigma
      

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

    cd $SEISCOMP_ROOT
    cd ..
    tar zxvf gempa-sigma-<version>-<SC3 release>-<SC3 version>-<OS>-<OS version>-<architecture>.tar.gz
    tar zxvf gempa-autosigma-<version>-<SC3 release>-<SC3 version>-<OS>-<OS version>-<architecture>.tar.gz
    
  2. Copy the received license file to ONE of the the license directories

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

    or

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

    Note

    When using the gsm script and including licenses into the package list, the license files are automatically installed by gsm into $HOME/seiscomp3/share/licenses.

Database

Together with the parameters of one SeisComP3 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 SeisComP3 database with the SIGMA table extension.
  2. separate SIGMA database (recommended).

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

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

Setup of a separate database

Follow the next steps for creating a separate database for AUTOSIGMA and SIGMA.

  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. Grant access to a user to the database and give the user sysop with password sysop full access to the sigma database.

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

    Please adjust the name of the database as well as the credentials of the database user.

  3. Create the SeisComP3 database table and the table extensions for SIGMA.

    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.

Using the standard SeisComP3 database

For using the standard SeisComP3 database add the SIGMA-specifc tables to the SeisComP3 database. Assuming that the database name is seiscomp3 and the user name is sysop execute:

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

More detailed database configuration options can be found in the MySQL manual or in the web at https://dev.mysql.com/doc/.

Database upgrade

To upgrade an existing SIGMA database to a newer version, all upgrade scripts for MySQL/MariaDB 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

To use AUTOSIGMA and SIGMA with a separate database, use

database.output = mysql://localhost/sigma

in the configuration files autosigma.cfg and sigma.cfg. Alternatively the URI can be passed via command line, e.g.:

sigma --output mysql://localhost/sigma

Otherwise use the standard database of SeisComP3 containing the required SIGMA table, e.g.:

database.output = mysql://localhost/seiscomp3

Vs30 grid

AUTOSIGMA and SIGMA can consider a Vs30 model in calculating ground motion parameters. A GeoTIFF file containing a global Vs30 grid can be obtained from USGS or from gempa GmbH.

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

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

    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 $SEISCOMP_ROOT/share/sigma
    mv /tmp/global_vs30.tif $SEISCOMP_ROOT/share/sigma//global_vs30.tif
    

    Note

    Customized Vs30 files in GeoTIFF format can be created by the user and considered in SIGMA.

  2. Configure SIGMA to use that GeoTIFF file by setting the gmpe.vs30grid variable in sigma.cfg and autosigma.cfg.

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

GMPE plug-ins

The GMPE s are calculated using plug-ins. The plug-ins include

  • gmpeeewd providing access to the GMPEs CEA2014 (Cauzzi et al., BEE, 2014) and BEA2014 (Bindi et al., BEE, 2014).
  • pygmpe providing access to the OpenQuake GMPEs using Python2.7 (obsolete). Check the list of models.
  • py3gmpe providing access to the OpenQuake GMPEs using Python3. Check the list of models.

Load the gmpeeewd and the py3gmpe plug-in by adding the plug-in names to the list of loaded plug-ins for providing the interfaces to the GMPEs. additionally the map plugins should be loaded.

plugins = ${plugins}, gmpeeewd, py3gmpe, mbtiles, mapprojections

Internally defined GMPEs

The GMPE models “CEA2014” (Cauzzi et al., BEE, 2014) and “BEA2014” (Bindi et al., BEE, 2014) are defined internally in AUTOSIGMA and SIGMA. They are provided through the plug-in gmpeeewd and can be used without furhter software installations. In SIGMA no further configuration is required. In AUTOSIGMA, the parameter profile.$name.gmpe must be configured with EEWD/CEA2014 or EEWD/BEA2014 as the provider and model.

OpenQuake plug-ins and specific Python scripts

AUTOSIGMA and SIGMA may be also configured to make use of the GMPE s provided by OpenQuake and specific Python scripts. This unique SIGMA feature provides the operators the opportunity to implement their own GMPEs which may come from their own research and which may be tailored to specific regions. Check the list of models provided by OpenQuake.

In order to make use of the GMPEs provided by OpenQuake Python 3.5+ must be installed in linked to SeisComP3.

  1. Load Openquake from the Web repository or install it using a package manager into a directory, e.g. /home/data/oq-engine .

  2. Create a Symlink from seiscomp3/lib/python/openquake to the openquake directory, e.g.

    ln -s /home/data/oq-engine/openquake  $SEISCOMP_ROOT/lib/python/openquake
    
  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.

Ubuntu 16.04+ and Debian

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

CentOS 7

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

Old SIGMA versions

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

This applies to old SIGMA versions only:

  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 $HOME/seiscomp3/bin/sigma $*"
    
  2. Set the PATH variable correctly such that $HOME/bin is before $SEISCOMP_ROOT/bin. In ~/.bashrc set after the SeisComP3 environment variables:

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

More software dependencies

  1. Install the additionally required software packages:
    • python3-zmq
    • python3-toml
    • python3-shapely
    • python3-psutil
    • python3-h5py
    • python3-scipy
    • python3-requests
    • python3-matplotlib

Report generation

SIGMA and AUTOSIGMA allow to generate files including waveforms, maps and XML from within the Export dialog in SIGMA. The generated files can be found in output.exportPath.

Customized reports 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 Export dialog in SIGMA 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 for assistance if needed.

Scripts and templates

The default python script for report generation is

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

The script will generate a PDF file based on the files generated in output.exportPath and a Latex template 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 output.exportScript of the module configuration of SIGMA. The python script uses functions provided in $SEISCOMP_ROOT/share/sigma/scripts/.

Software dependencies

The parseIncident.py relies on xelatex which must be installed.

Configuration

The configuration is identical for SIGMA and AUTOSIMA.

The provided Python script parseIncident.py takes the default configuration from the configuration file named according to itself, i.e. $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.

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

Some usually considered parameters in parseIncident.cfg are:

  • input.datadir : this is where the report generator finds the files generated by SIGMA. The directory name must be identical to 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.:

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

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. Define the python script where to find the external GMPE model 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@/py3gmpe/
    gmpe.py3.models = "AbrahamsonSilva1997;oq-sm.py,AbrahamsonEtAl2014;oq-sm.py,AtkinsonBoore2006;oq-sm.py"
    
  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 for more flexibility.

    profile.potsdam.region = "potsdam"
    profile.potsdam.gmpe = "EEWD/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 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: the eventID, an internal eventID and the output.exportPath defining the directory where all files are stored.

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

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 SeisComP3 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. Then AUTOSIGMA is not enabled and not started as a deamon 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 AUTOSOIGMA.

  1. Sigma does not connect to the SeisComP3 messaging. However, a SeisComP3 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.type = mysql
    database.parameters = sysop:sysop@localhost/seiscomp3
    

    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 parmater 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 directory where to find the Python scripts for calling the GMPE functions, e.g.

    gmpe.py3.basePath = @DATADIR@/sigma/
    
  6. Select the GMPEs and the Python script where they are defined. Use a comma-separated list to provide more than one GMPE, e.g.

    gmpe.py3.models = "AbrahamsonEtAl2014;py3gmpe.py,AbrahamsonSilva1997;py3gmpe.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.

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.