.. _toast_installation:
Installation
============
.. warning::
These installation instructions refere to the legacy (non-multiuser) version of |toast|.
They will be updated by the official release of the |toastm| version in 2024.
In this section we list requirements and instructions for the installation of
|toast|. For the installation and configuration of |scname| consult its
documentation.
Usually |toast| is installed and set up directly by |gempa| GmbH.
.. _note-gsm:
.. note::
:program:`gsm` (`gempa <https://www.gempa.de/contact/>`_ software manager)
is a command line tool for handling software packages.
Execute `./gsm -h` to list options and consult the file `README` to get
further information.
After initial setup of gsm with `./gsm setup`, the file `gsm.conf` contains
the configured parameters. Re-run setup or edit `gsm.conf` with a text editor
to make modifications.
By default, bathymetry, forecast zones, source regions, map tiles etc. are
installed at |gsmdata|. Make sure you have write permission in the specified
directories.
.. _toast_install_toast:
Install |toast|
---------------
#. Login as sysop (this is the user assumed throughout these instructions)
#. Download :ref:`gsm <note-gsm>` and extract it:
.. code-block:: sh
sysop@host:~$ mkdir install
sysop@host:~$ cd install
sysop@host:~$ wget https://data.gempa.de/gsm/gempa-gsm.tar.gz
sysop@host:~$ tar -xf gempa-gsm.tar.gz
sysop@host:~$ cd gsm
sysop@host:~$ chmod u+x gsm
#. The initial gsm configuration is performed through the command *setup* which
will auto-detect your operating system and ask for download credentials:
.. code-block:: sh
sysop@host:~$ cd $HOME/install/gsm
sysop@host:~$ ./gsm setup
#. Update the package list and install :ref:`TOAST <toast_introduction>`,
:ref:`EasyWave <toast_easywave>` and other required or desired packages:
.. code-block:: sh
sysop@host:~$ cd $HOME/install/gsm
sysop@host:~$ ./gsm update
sysop@host:~$ ./gsm install toast easywave2 licenses seiscomp recordstream
.. _toast_dependencies:
Install dependencies
--------------------
In order for |toast| to work, some library dependencies have to be met.
#. Login as root
#. Install dependencies
.. code-block:: sh
root@host:~# /home/sysop/seiscomp/bin/seiscomp install-deps base gui mysql-server toast
#. If you want to generate mp4 videos in the TOAST bulletins,
you need to install *MEncoder*. For Ubuntu and Debian distributions,
*MEncoder* is installed with the TOAST dependencies, but for RHEL it has to
be installed separately:
.. code-block:: sh
root@host:~# /home/sysop/seiscomp/bin/seiscomp install-deps toast-mencoder
.. _toast_gpu:
Enable GPU-based computation
----------------------------
.. note::
In contrast to previous versions of |toast|, in the current version the
CUDA toolkit does not have to be installed, as the necessary libraries are
included in |ewname|.
|ewname| can use either the CPU or the GPU for simulations, but on the latter it
runs significantly faster.
In order to take advantage of GPU computation, an NVIDIA graphics card
supporting CUDA is required and the corresponding drivers have to be installed.
NVIDIA driver
~~~~~~~~~~~~~
In the following we list the procedure to install the NVIDIA drivers on RHEL 7
flavor distributions.
#. Login as root
#. Make sure you have the correct version of ELRepo installed:
.. code-block:: sh
root@host:~# yum remove nvidia-detect kmod-nvidia elrepo-release
root@host:~# rpm --import https://www.elrepo.org/RPM-GPG-KEY-elrepo.org
root@host:~# yum install https://www.elrepo.org/elrepo-release-7.0-4.el7.elrepo.noarch.rpm
#. Install NVIDIA drivers:
.. code-block:: sh
root@host:~# yum install kmod-nvidia nvidia-x11-drv
root@host:~# reboot
.. _toast_dir_struct:
Directory/File structure
------------------------
|toast| is usually installed within a |scname| environment. The file/directory
structure is:
.. csv-table::
:widths: 2 3
:header: Path, Description
"seiscomp", "|scname| root directory, referred to as $SEISCOMP_ROOT. Typically installed in $HOME or /opt/."
"$SEISCOMP_ROOT/lib", "Path to |scname| and |toast| libraries"
"$SEISCOMP_ROOT/bin", "Path to the |toast| executable"
"$SEISCOMP_ROOT/share/|toastb|/templates", "Path to the default templates directory which are used for :ref:`toast_bulletins`"
"$SEISCOMP_ROOT/etc", "Configured |toast| parameters in |toastb|.cfg"
"~/.seiscomp", "User specific settings of |scname| and |toast|"
"~/.seiscomp/|toastb|", "User specific settings of |toast|"
"~/.seiscomp/|toastb|/[plugins]", "Root directory for the |toast| plugins"
.. hint::
Most installations of |toast| are installed as *sysop* user and
have */home/sysop/* as home directory.
Therefore, many examples in this documentation are for this user.
Please use your user name and the corresponding home directory instead.
.. _toast_setup:
Setup
=====
Environment variables
---------------------
|scname| and |gempa| modules require a set of system environment variables.
Add them to *~/.bashrc*:
.. code-block:: sh
sysop@host:~$ ~/seiscomp/bin/seiscomp print env >> ~/.bashrc
sysop@host:~$ source ~/.bashrc
Secure database installation
----------------------------
By default, MariaDB is used as a replacement for MySQL. After installation it
has to be started and secured:
.. code-block:: sh
sysop@host:~$ su
root@host:~# systemctl enable mariadb
root@host:~# mysql_secure_installation
Define a root password for the database and answer all other questions with *Y*.
.. _toast_wizard:
Setup wizard
------------
For a basic configuration of |scname| and |toast|, including the respective
databases, you can use: :program:`scconfig` :menuselection:`--> File --> Wizard`.
If you prefer configuration via command line, type:
.. code-block:: sh
sysop@host:~$ seiscomp setup
Enter names for :confval:`agencyID`, :confval:`datacenterID` and
:confval:`organization`. Default values for the other parameters should be fine
in most cases.
.. TODO::
* Dirk schlägt vor, als Alternative auch noch die manuelle DB Initialisierung zu beschreiben oder zu verlinken
* Falls agencyID etc. nicht überschrieben werden soll
.. _toast_module_configuration:
Module configuration
--------------------
Use :program:`scconfig` :menuselection:`--> Modules` to configure |toast|.
.. note::
Global parameters can be set either at
* :menuselection:`System --> global` to set them for all |scname|
:term:`modules <module>` or at:
* :menuselection:`gempa --> toast --> global` to set them only for |toast|.
|toast| specific parameters are set at:
* :menuselection:`gempa --> toast --> toast`.
Here we list some possible global parameter settings:
::
plugins = ${plugins},simeasywave2 # rsas is required if using CAPS
recordstream = caps://caps.acqui.de:18000 # set according to your waveform data source
database = mysql://localhost/seiscomp # where TOAST loads inventory and bindings from
connection.server = proc # configure according to your SeisComP messaging system
connection.username = toast
.. TODO::
* Dirk schlägt vor, für username statt toast->toasthostname zu verwenden
And here are some |toast| parameter settings:
::
tsunami.database = mysql://sysop:sysop@localhost/toast # database type and location
tsunami.database.loadLastDays = 1 # load n last days upon startup
.. note::
If |toast| connects to a |scname| messaging system using
:confval:`connection.server`, it will by default load inventory and database
from the database configured therein, which is usually set up for
seismic stations.
This is why above, :confval:`database` specifies the local |scname| database
for loading the tide gauge :ref:`toast_inventory_bindings`.
That in turn has not to be confounded with
:confval:`tsunami.database` which is the database where |toast|
stores incident and tsunami related data.
.. _toast_inventory_bindings:
Inventory and Bindings
----------------------
Via :ref:`gsm <note-gsm>` you can install a package with preconfigured
tide gauge inventory and :term:`bindings <binding>` for the
`Global sea monitoring network of IOC <http://www.ioc-sealevelmonitoring.org/map.php>`_.
#. Login as sysop
#. Install inventory and bindings:
.. code-block:: sh
sysop@host:~$ cd $HOME/install/gsm
sysop@host:~$ ./gsm install tidegauges-ioc
#. Update configuration and write to database:
.. code-block:: sh
sysop@host:~$ seiscomp update-config
For more information on how to configure :term:`bindings <binding>`,
consult the |scname|
`documentation <https://docs.gempa.de/seiscomp/current/apps/global.html>`_.
.. hint::
To use inventory and bindings from files instead from the database, start
|toast| with:
.. code-block:: sh
sysop@host:~$ toast --inventory-db my_inv.xml --config-db my_conf.xml
.. _toast_fault_geometry_configuration:
Fault geometry configuration
----------------------------
If a tsunami on-the-fly-simulation using |ewname| is initiated and no focal
mechanism (moment tensor) is available, then the strike-, dip-, and rake-angles
and the depth for the automatic rupture patch generation are looked up in a file
containing the information about subduction geometry and local faults (see:
:ref:`fig-sim_flowchart`).
The parameter :confval:`patches.maxFaultDist` defines the maximum horizontal
distance allowed between epicenter and the closest point in the faults for
automatic patch generation and consequently for an automatic simulation to be
started. Default value is 1 degree.
.. note::
If you define your own faults file, make sure that the largest distance
between neighboring fault lines belonging to the same geologic feature is
not larger than twice the value of :confval:`patches.maxFaultDist`, otherwise
there might be a region between lines where no simulations are generated.
1 degree is fine for the default file.
File location
~~~~~~~~~~~~~
The file provided by |gempa| containing the fault definitions is:
*$SEISCOMP_ROOT/share/toast/faults.xml.example*.
This file has to be copied in order to be used and to make modifications
introduced by the user persistent throughout |toast| updates.
.. code-block:: sh
sysop@host:~$ cd $SEISCOMP_ROOT/share/toast
sysop@host:~$ cp faults.xml.example faults.xml
.. note::
In the new |toastm| version the faults are delivered to the |toast|
client by the |gss|. Thus the file location is:
*$SEISCOMP_ROOT/share/gss/*.
Content
~~~~~~~
|toast| is currently provided with a file (version 1.2) containing almost 200
fault lines covering most subduction zones world wide. For instance, it contains
all contour lines from the `slab2-model <https://doi.org/10.5066/F7PV6JNV>`_
between 20 and 80 km depth. The lines at 0 km depth are either from the
RUM-model (Gudmundsson & Sambridge, 1998), generated manually according to
literature and bathymetry or from the previous version of the file (in which
case *reference* is not set).
Structure
~~~~~~~~~
Below is an example for the structure of the file:
.. code-block:: xml
:linenos:
<gempa faults_version="1.2">
<fault checked="true" depth="0.0" id="005" name="Algeria" reference="doi:10.1002/2014JB011751" type="reverse">
<vertex dip="70" rake="90" strike="76">
<latitude>37.590</latitude>
<longitude>8.995</longitude>
</vertex>
<vertex dip="70" rake="90" strike="81">
<latitude>37.389</latitude>
<longitude>8.023</longitude>
</vertex>
...
</fault>
...
<fault checked="true" depth="20.0" id="021" name="Calabria 20 km #1" reference="Slab2" type="reverse">
<vertex dip="36" rake="90" strike="230">
<latitude>37.334</latitude>
<longitude>13.450</longitude>
</vertex>
...
</fault>
...
</gempa>
The file contains several *fault* elements which have *vertex* sub-elements.
Faults and vertices can be added, modified and removed manually via text editor.
The format of the file is described below.
Make sure the XML is valid when editing the file
(e.g. `xmllint --noout faults.xml`).
.. csv-table:: Fault definitions file explanation
:widths: 1 20
:header: Line, Description
1, Version of the fault definitions.
2, "Fault description including the attributes
* checked (if *true* then the fault is used for :ref:`patch generation <toast_gen_patches_auto>`)
* depth (in km)
* id (unique)
* name (arbitrary, can be shown in map view)
* reference (to fault source)
* type (*reverse* for subduction zones, *normal*, *transform*)"
3, "Vertex description including the attributes *dip*, *rake*, and *strike*.
For definitions see for instance:
`openSHA <https://opensha.org/Glossary#strike-dip--rake-focal-mechanism>`_."
4, Latitude coordinate of the vertex.
5, Longitude coordinate of the vertex.
The *type* affects the way the faults are drawn in map view.
Note that in case of *reverse*, the side the triangles on a fault line point to
is *left* when progressing on the line.
Reverse the ordering of the vertices in the XML to change the pointing direction.
The ordering of the vertices is irrelevant for the generation of patches for
simulations, as the strike angle is not determined by consecutive vertex
coordinates but is an attribute of each vertex.
.. _toast_forecast_zones_configuration:
Forecast zones configuration
----------------------------
*Forecast zones* are geographical regions - oftentimes corresponding to political
districts - for which a specific tsunami early warning bulletin is generated.
Technically, the *forecast zones* are associated with *forecast points* for which
simulation results are either computed on-the-fly or by extraction from a
precalculated database.
See also: :ref:`toast_forecast_zones_perspective` and:
:ref:`Forecast zones <fig-forecast_zones>`.
.. _toast_gsm_forecast:
You can use :ref:`gsm <note-gsm>` to install a set of predefined example forecast
zones and points files:
.. code-block:: sh
sysop@host:~$ cd install/gsm
sysop@host:~$ ./gsm install forecastzones-rtsp
See :ref:`toast_forecast_formats` if you want to generate you own set of forecast
zones and points files.
The forecast zones and profiles can be configured using :program:`scconfig`.
.. note::
The forecast zones are configured at :menuselection:`gempa --> toast`,
while the forecast points are configured at plugin level, e.g.
:menuselection:`gempa --> easywave2` if used together with |ewname|.
First, add a *forecastZones* profile, configure the parameters and register the
profile:
* :confval:`forecastZones.$name.filename` - Without file ending! Points to
a shape file (ending .shp), an index file (ending .shx) and an attribute file
in dBase format (ending .dbf).
* :confval:`forecastZones.$name.blacklist.country` - Can be used if zones for
a country are present in multiple forecast zones files.
* :confval:`forecastZones` - Registration of the profile(s).
Example:
::
forecastZones.rtsp.filename = /home/data/forecastzones/rtsp/6.0/cfz/CFZ_Version_6p0
forecastZones = rtsp
Then, add a *forecastPoints* profile, configure the parameters and register the
points profile:
* :confval:`easywave2.forecastPoints.$name.filename` - Points to a file in
dBase (.dbf) format.
* :confval:`easywave2.forecastPoints` - Registration of the profile(s).
Example:
::
forecastPoints.rtsp.filename = /home/data/forecastzones/rtsp/6.0/cfp/CFP_Version_6p0.dbf
forecastPoints = rtsp
.. _toast_forecast_formats:
Forecast zones and points file formats
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. note::
Forecast zone and forecast point files are usually provided by the customer.
They can be created using GIS software like `QGIS <https://qgis.org/en>`_.
The extent of a forecast zone is related to local administrative districts,
typically it is between 50 and 500 km.
The number of points in a zone should be such that they cover the
geographical area and geological features of the zone and can vary between a
couple to a couple tens of points.
Consult the :ref:`example forecast files <toast_gsm_forecast>` as a starting point.
Consider that runup values for a zone are aggregated as described in
:ref:`note-aggregation`.
Make sure to check the points against the bathymetry used for simulations.
See :ref:`below <note-fz_naming>` the suggested naming scheme for the IDs of
the zones and points.
Forecast zones
^^^^^^^^^^^^^^
The forecast zones geographical outlines are defined in
`shapefiles <https://en.wikipedia.org/wiki/Shapefile>`_ (ending *.shp*).
Attributes data are stored in `dBase <https://en.wikipedia.org/wiki/.dbf>`_
files (ending *.dbf*), and a third file (ending *.shx*) is used as index.
The *.dbf* file may contain any attributes, following are used by |toast|:
.. csv-table:: Forecast zones metadata
:widths: 3 2 5 5
:header: Name, Datatype, Description, Forecast Zones Perspective
EX_BOX_ID, Integer, Unique forecast zone ID, ID
BOX_NAME, String, Forecast zone name, Name
PLACE_NAME, String, Place name, Place
STATE_PROV, String, Province name, Province
COUNTRY, String, Country name, Country
CNTRY_CODE, String, Country abbreviation, Geo code
CATEGORIES, String, Categories, Categories
The *EX_BOX_ID* (Exclusive Box Id) is mandatory and has to be unique (hence
*exclusive*) as it is used as identifier for the forecast points (see below).
All other parameters are optional, but the more information is provided the better.
For each forecast zone, arbitrary categories can be assigned in *CATEGORIES*
as a comma-separated string.
Forecast points
^^^^^^^^^^^^^^^
For each forecast zone |toast| needs a set of forecast points.
The points are stored in binary files in
`dBase <https://en.wikipedia.org/wiki/.dbf>`_ format (ending *.dbf*).
Following attributes in a forecast point file are used by |toast|:
.. csv-table:: Forecast points metadata
:widths: 3 2 5 5
:header: Name, Datatype, Description, Forecast Zones Perspective
CFPNO, String, Unique forecast point ID, ID (upon expanding)
EX_BOX_ID, Integer, Link to forecast zone ID, ID
POINT_Y, Double, Latitude value, Geo code
POINT_X, Double, Longitude value, Geo code
PLACE_NAME, String, Place name, Place
STATE_PROV, String, Province name, Province
COUNTRY, String, Country name, Country
*PLACE_NAME*, *COUNTRY* and *STATE_PROV* are optional and are derived from the
associated zone if they are not set.
.. _note-fz_naming:
.. note::
For the attributes *EX_BOX_ID* in the forecast zones and *CFPNO* in the
forecast points we recommend a naming scheme using the country phone code.
In this way, it is guaranteed that the IDs are unique throughout all zones
and points.
For instance, for Algeria having code +213 that would be:
*EX_BOX_ID*: 2130001, 2130002, ...
*CFPNO*: 21300000001, 21300000002, ...
.. TODO::
* in zones files, CNTRY_CODE should be string, but is number:
* in cfz_ntwc.dbf same as EX_BOX_ID
* in cfz_rtsp.dbf = 0.0
* in zones and point files, what is PB_BOX_ID?
.. _toast_threat_level_configuration:
Threat level mapping configuration
----------------------------------
*Threat level* is a property of the forecast zones, and is typically assigned
based on runup value of the :ref:`active<note-active_sim>` simulation.
However, more complex mappings are possible.
They are defined in the |toast| configuration.
.. note::
Threat level mapping has been introduced in |toast| in 2023.
Before that, threat level could only be visualized using the
forecast zones color gradient which uses runup as key.
In templates, a :ref:`clearsilver <toast_clear_silver>` definition had to be
used.
.. TODO::
* check in 2023 above
Threat level mapping is set up by creating *threatLevel* profiles using
:program:`scconfig` and registering the profiles at :confval:`threatLevels`.
The threat level profiles have to be registered in **descending** order, e.g.:
::
threatLevels = threat-warning,threat-watch,threat-none
In this case, they are assigned the numerical levels 2, 1 and 0 by |toast|.
Use these numerical levels as keys for threat level color gradients.
Variables and conditions
~~~~~~~~~~~~~~~~~~~~~~~~
- The first profile whose condition is fulfilled determines the threat level.
- The variables which can be used generally correspond to the columns in
*Forecast Zones* perspective without spaces (e.g. Geo Code -> GeoCode)
- Times can be accessed as seconds and milliseconds (e.g. T1Time.s and T1Time.ms)
- For every variable there is an additional *[Variable]Exists* variable to check
if it is valid (e.g. RunupExists). Use *simExists* to verify if a simulation
is available.
Note that if a variable is not valid, it is still initialized to a
default value. This is *0* for numeric variables and an empty string for text
variables (e.g. T1TimeExists==False -> T1Time.s=0 and T1Time.ms=0).
- Incident parameters can be accessed in the following way:
inc.mag, inc.magType, inc.lat, inc.lon, inc.depth, inc.time, inc.sourceType,
inc.sourceTypeComment, inc.sourceOrigin, inc.evalMode, inc.sev.
- Similarly, simulation parameters can be accessed in the following way:
sim.mag, sim.lat, sim.lon, sim.depth, sim.sourceType, sim.sourceTypeComment,
sim.status, sim.type, sim.maxTime, sim.availTime.
- If several simulations are selected, for each simulation a True/False value
is returned and they are combined via logical *or* (e.g. Sim1 returns True
and Sim2 returns False, then the overall value is *True*).
- The mathematical conditions are evaluated using the Mathematical Expression
Library ExprTk which is described
`here <https://www.partow.net/programming/exprtk/>`_.
.. _toast_severity:
Severity concept
~~~~~~~~~~~~~~~~
Here we give a short description of the new *Severity* feature which can be
accessed in the threat levels via inc.sev.
*Severity* is an incident property which can be used for non-earthquake events
which thus do not have a magnitude.
It can be set by the user (see: :ref:`toast_artificial_incidents`) and
corresponds to a time span in hours.
The idea is to configure the threat levels in a way that if no magnitude is
present, then severity is used and each forecast zone which has T1 below
severity is assigned a threat, and for T1 above severity no threat is assigned.
Examples
~~~~~~~~
An example for threat level profiles which depend only on runup value looks like
this:
::
threatLevel.threat-warning.title = "Warning"
threatLevel.threat-warning.condition = "Runup>=3"
threatLevel.threat-watch.title = "Watch"
threatLevel.threat-watch.condition = "Runup>=0.5"
threatLevel.threat-none.title = "No Threat"
threatLevel.threat-none.condition = "RunupExists"
Here is an example for a condition where the threat level additionally depends
on forecast zone category:
::
threatLevel.threat-cat.condition = "(Runup>=3 and 'mainland' in Categories) or (Runup>=2 and 'offshore' in Categories)"
If you want to define threat levels which depend on runup if it exists and
otherwise on travel time and magnitude, do:
::
threatLevel.mag.condition = "RunupExists ? Runup>=3 : T1TimeExists and T1Time.s>=0 and T1Time.s<3600 and sim.mag>=7"
This example uses only severity as a condition:
::
threatLevel.severity.condition = "T1Time.s/60/60<inc.sev"
Combine these example definitions in order to get the desired results.
Simulation bathymetry files configuration
-----------------------------------------
.. TODO::
Hier entfernen da verschoben nach easywave.rst
In order for a tsunami on-the-fly-simulation to be computed (in contrast to a
pre-computed scenario), a directory containing the bathymetry file(s) for the
simulation backend has to be provided. In case of |ewname|, the directory is
configured at :confval:`easywave2.data`.
Example:
::
easywave2.data = /home/data/bathymetry/
You can use :ref:`gsm <note-gsm>` to install a set of bathymetry files for
|ewname|:
.. code-block:: sh
sysop@host:~$ cd install/gsm
sysop@host:~$ ./gsm install bathymetry
See :ref:`toast_source_regions` on how to configure the default bathymetry for
the simulations within a source region.
Creating bathymetry files
~~~~~~~~~~~~~~~~~~~~~~~~~
|toast| is provided with bathymetries suiting the needs of the customer.
Additional bathymetry files for |ewname| can be made by the following procedure:
- Generate and download a bathymetry grid in geotiff format from
`NOAA Grid Extract <https://www.ncei.noaa.gov/maps/grid-extract/>`_:
- Select *ETOPO1 (bedrock)*
- Click on the icon *Select area of interest by rectangle* and use the mouse
or enter the Area of Interest manually
- Download Data
- Convert the file to binary Surfer 6 grd format as used by |ewname| in two steps:
- Use gdal software to convert the downloaded geotiff file to ArcGIS:
- :code:`gdal_translate -of AAIGrid <geotiff_file.tiff> <ascii_file.asc>`
- Use the script |toastdata|/scripts/arc2grd.py to convert the ArcGIS file to
binary surfer grid:
- :code:`./arc2grd.py <ascii_file.asc> <surfer_file.grd>`
- move the surfer file to the bathymetry directory
In case of |ewname|, the bathymetry has to be provided in *Golden Software Surfer 6*
`binary <http://grapherhelp.goldensoftware.com/subsys/surfer_6_grid_file_format.htm>`_
(preferred) or
`text <http://grapherhelp.goldensoftware.com/subsys/ascii_grid_file_format.htm>`_
format.
.. _note-show_bathymetry:
.. note::
To display the bathymetry which was used for a simulation in map view with
color coding, select a simulation and click *Bathymetry* in the
:ref:`toast_map_layers_panel`.
Note that this works only for binary, not for text format grid files.
To show the outline of a bathymetry file as green line, go to the
:ref:`toast_backend_settings` in the interactive simulation dialog and select
the respective bathymetry (grid).
.. _toast_source_regions:
Source regions configuration
----------------------------
Source regions define polygon coordinates within which simulations should be
started. See: :ref:`fig-sim_flowchart`.
Use :ref:`gsm <note-gsm>` to install a set of predefined example source region
files:
.. code-block:: sh
sysop@host:~$ cd install/gsm
sysop@host:~$ ./gsm install sourceregions
Using :program:`scconfig`, add a *sourceRegion* profile and configure the parameters.
* :confval:`sourceRegion.$name.aoi` - (Area Of Interest) points to a bna file
* :confval:`sourceRegion.$name.name` - Points to a bathymetry grd file (without
file ending). This is the default bathymetry which is used for simulations
within this source region. In the :ref:`toast_backend_settings` of
the interactive simulation dialog it is highlighted with a star.
Register the profile at: :confval:`sourceRegions`.
Example
~~~~~~~
::
sourceRegion.IndianOcean.aoi = /home/data/sourceregions/IndianOcean.bna
sourceRegion.IndianOcean.name = io_rtsp
sourceRegions = IndianOcean
In the following figure, the sourceRegion defined in the profile above is shown
as :ref:`black line <note-show_bna>`, and the outline of the default bathymetry
associated with this sourceRegion is :ref:`shown in green <note-show_bathymetry>`.
.. _fig-source_regions:
.. figure:: media/toast/install/source_region.png
:align: center
:width: 18 cm
Source region (black line) and default bathymetry outline (green)
.. _note-show_bna:
.. note::
To show source regions as black lines, copy their bna files to one of the
two locations:
* $SEISCOMP_ROOT/share/bna
* ~/.seiscomp/bna
.. _create-bna:
Create a bna polygon
~~~~~~~~~~~~~~~~~~~~
You can create a
`BNA <https://www.softwright.com/faq/support/boundary_file_bna_format.html>`_
polygon manually in |toast| :ref:`toast_map_perspective`.
Click and hold the CTRL-key and do a series of left-mouse clicks.
On the lower left you can see total length and area covered by the polygon.
Then right-mouse click -> Measurements -> Save as BNA/geoJSON File.
To save in
`GeoJSON <https://geojson.org/>`_
format use the filename extension *.geojson*.
.. _toast_bulletin_config:
Bulletins, templates and Live tabs configuration
------------------------------------------------
.. note::
With the new |toast| multiuser version released in 2023, template
and livetab functionality was extended significantly.
The configuration was adapted accordingly.
Previously, templates were configured in |toast| (toast.cfg) and re-read
from file system each time before rendering or disseminating.
The same, presently configured templates were used for all incidents.
Now, templates are configured at the |toasts|, more precisely in the
|toastd| (|toastdaemon|) plugin section of |scmaster| (file scmaster.cfg).
When an incident is created, all configured templates are stored in the
database together with the incident.
Templates can be edited from within the |toastg|.
These changes affect only the templates of the currently selected incident.
The Live tab configuration, which is still done at the |toastg|
(file toast.cfg) supports a template tree (hierarchy) setup.
Template variables were added which can be configured in |scmaster| and
edited with a dedicated variable editor widget in the |toastg|.
A revision variable for each template counts the number of times a template
has been disseminated.
See: :ref:`toast_export` on how to create templates for the generation and
dissemination of tsunami warning bulletins.
.. _toast_template_config:
Templates configuration
-----------------------
Concept
~~~~~~~
The templates are configured in a
`queue <https://www.seiscomp.de/doc/apps/scmaster.html#message-groups>`_
of |scmaster|, typically the *Production* queue.
The *toastd* plugin has to be added to the queue so that the templates and
template groups can be set up in a tree-like fashion.
Templates and groups can be added using the green plus-icon in
:program:`scconfig` :menuselection:`--> Modules --> Messaging --> scmaster -->
queues --> production --> processors --> messages --> toastd --> bulletins`
*+ Template* or *+ Group*.
Templates and groups have to be registered (linked).
The configuration is saved in the file *$SEISCOMP_ROOT/etc/scmaster.cfg*.
It is possible to add a template to more than one group.
Example
~~~~~~~
.. _fig-template_tree:
.. figure:: media/toast/install/template_tree.png
:align: center
:width: 10 cm
Template tree with one template (Definitions) and two groups (National,
State) at the base.
The template tree above is defined by the following configuration.
.. include:: includes/scmaster-templates.cfg
:literal:
.. _toast_template_variable_config:
Template variables configuration
--------------------------------
Concept
~~~~~~~
Template variables are configured in a similar way as the templates.
Use :program:`scconfig` :menuselection:`--> Modules --> Messaging --> scmaster
--> queues --> production --> processors --> messages --> toastd --> bulletins`
*+ Variable*.
Register the variables at :menuselection:`--> bulletins`.
They can be accessed in the templates via ClearSilver syntax.
The *Template variables* panel allows to edit them from within the |toastg|
via double-click on value.
Like the templates, the template variables are associated with an incident.
That is, they are stored in the database together with an incident and
modifications using the editor affect only the current incident.
Example
~~~~~~~
::
# Defines a list of context variables for the bulletin generation. Each
# variable must be defined with a Variable type.
queues.production.processors.messages.toastd.bulletins.variables = test_header
# Name of the variable as being accessed in the template.
queues.production.processors.messages.toastd.bulletins.variable.test_header.name = exerciseTestStr
# The optional initial value of the variable.
queues.production.processors.messages.toastd.bulletins.variable.test_header.value = "TEST -- TEST -- TEST -- TEST"
.. _fig-template_variable_editor:
.. figure:: media/toast/install/template_variable_editor.png
:align: center
:width: 11 cm
Template variable editor with two variables defined.
The variable value can be edited by double-click.
.. _toast_live_tab_config:
Live tabs configuration
-----------------------
Concept
~~~~~~~
The Live tabs are configured at the |toastg| (toast.cfg).
If no Live tabs are configured, per default there is one tab *Live tabs* in
which the complete template tree is available.
Alternatively, an arbitrary number of Live tabs can be configured.
Use :program:`scconfig` :menuselection:`--> Modules --> gempa --> toast -->
liveTab` + Live tab profile.
Set the :confval:`title` and optionally :confval:`defaultTemplate`,
:confval:`entryPoint` to the template tree and :confval:`buttonText`
of the dissemination button.
Register the Live tab profiles at :confval:`liveTabs`.
Example
~~~~~~~
.. _fig-livetab_state:
.. figure:: media/toast/install/livetab_state.png
:align: center
:width: 11 cm
Undocked Live tab *State* with two groups (Northern, Southern Territory)
with each two templates (No threat, Watch).
The current template is indicated to the right of the selection button.
The default button text *Disseminate* is changed to *Export*.
The example configuration is based on the template configuration from above.
It has two Live tabs with different entry points (National, State).
.. include:: includes/toast-livetabs.cfg
:literal:
.. _toast_mapstyles:
Color profiles, gradients and colors configuration
--------------------------------------------------
The default color profiles, gradients and colors for the various features
like maximum wave height, forecast zones or bathymetry are stored in the file
|toastdata|/mapstyles.default and the user-defined color profiles, gradients
and colors in |toastconfig|/mapstyles, both defined in JSON format [#]_.
The color settings can be changed directly in |toast| using the color editor
or color profile editor as described in :ref:`toast_color_profiles`.
.. note::
If a gradient or color profile is not properly defined or present,
the default gradient is used for the corresponding feature.
.. warning::
All changes made in |toastdata|/mapstyles.default are overwritten with
the next |toast| update.
.. [#] https://www.json.org/