.. _toast_introduction:

Introduction
============

After the devastating tsunami in 2004 in the Indian Ocean and in 2011 offshore
Japan, it became evident that even though large tsunami do not
happen very frequently, the implementation of effective early warning systems is
crucial due to the severe impact of such events.
:term:`TOAST` is a software package designed precisely for this purpose.
Specific tsunami warning bulletins targeted to administrative districts are
generated automatically based on templates.
They can be disseminated through various channels like text message, e-mail or
video stream immediately after an event.

These warning bulletins are based on tsunami simulation results which are
either extracted from precalculated databases or computed using a so-called
*on-the-fly* approach.
This is a unique feature of |toast| and enables it to flexibly react to
unexpected events, such as earthquakes in unconsidered areas or with atypical
rupture mechanism.
Generating simulations adequate to the situation is done in a fully automatic
way and can be complemented by manual design.
Simulation results can be compared to real-time data from buoys or tide gauges
even during the propagation of a tsunami.
|toast| has good scalability and integrates perfectly with |scname| to form
a fully functional tsunami early warning system.


.. _toast_features:

Features
--------

* Automatic retrieval or generation of tsunami :ref:`simulations <toast_simulations>`
  and :ref:`comparison with observations <toast_arrivals_perspective>`
* Direct :ref:`connectivity <toast_module_configuration>` to |scname|
* :ref:`Automatic reception <toast_receive_events>` of earthquake information
  from |scname|
* Rapid :ref:`on-the-fly simulation <toast_plugin_onthefly>` of tsunamis with
  optional :ref:`GPU computation <toast_gpu>`
* Fast access to :ref:`precalculated tsunami simulations <toast_plugin_database>`.
* Calculation and :ref:`visualization <toast_display_simulation_results>` of
  SSH, SSHMax, isochrones, arrival times, coastal wave heights
* :ref:`Automatic <toast_sim_automatic>` and
  :ref:`interactive <toast_sim_interactive>` generation of simulations
* :ref:`Automatic <toast_rupture_settings>` and
  :ref:`manual <toast_draw_patches>` definition of rupture area
* :ref:`Aggregation <note-aggregation>` of scenarios to determine overall worst case
* :ref:`Configuration of stations <toast_inventory_bindings>` with different
  types of sensors (tide gauge, buoy, etc)
* Generation and :ref:`dissemination of bulletins <toast_export>` based on
  predefined templates
* Video output and :ref:`playback of simulations <toast_sim_player>`
* Integration of oceanographic :ref:`sensor data <toast_traces_perspective>`
* Tsunami :ref:`onset picking <toast_waveform_picker>`
* :ref:`Intuitive visualization <toast_map_perspective>` of all relevant parameters


.. raw:: html

   <div class="two column layout">

.. figure:: media/toast/same_size/arrival_lines_times.png
   :alt: arrival times

   Arrival isolines on maps visualize the tsunami propagation.

.. figure:: media/toast/same_size/forecast_zones.png
   :alt: forecast zones

   Maps with forecast zones show the local threat levels.


.. raw:: html

   </div>

.. raw:: html

   <div class="two column layout">

.. figure:: media/toast/same_size/perspective_traces.png
   :alt: mariograms

   Real-time waveforms provide instantaneous sea-level information and
   comparison to simulations.

.. figure:: media/toast/same_size/ssh_max.png
   :alt: SSHmax

   Maps show the maximum wave height across the ocean.

.. raw:: html

  </div>


.. _toast_history:

History
-------

|toast| has been developed by |gempa| GmbH, a spin-off from the German
Research Centre for Geosciences (:term:`GFZ`) in Potsdam.
|gempa| is part of the |scname| development group.
Several staff members were involved in the the German Indonesian Tsunami Early
Warning System project (:term:`GITEWS`) as scientists, software- or field engineers.
After the implementation of the :term:`GITEWS` decision support system initially
used by :term:`BMKG` in Jakarta it soon became obvious that the system was
complex and specialized to an extent that made it hard to adapt it to other
environments.
This is why |gempa| started the development of |toast|.

In 2022 |toast|, new requirements were proposed for |toast|:

* Allow several users concurrently working on the same incident.
* Share simulations across workstations.
* Enable user authorization.
* Shield the database from direct user access.

As a consequence, |toast| was redesigned: the former standalone application
(hereafter referred to as |toastl|) was split in three components:
the |toasts|, the |toastc| and the |gss|.

A description of the components is given in the next section.


.. _toast_architecture:

|toast| architecture
--------------------

|toast| consists of three components:

* the |toasts|, technically the plugin |toastd| for |scmaster|,
* the |toastc| (also referred to as |toastg|)
* and the |gss| (|gssfull|).

.. _fig-toast_arch:

.. figure:: media-src/toast/architecture/architecture-multi.png
   :align: center
   :width: 15 cm

   |toast| components.


.. _toast_server_summ:

|toasts|
~~~~~~~~

The |toasts| consists of |scmaster| and its plugin |toastd| (|toastdaemon|).
|scmaster| is the central process in any |scname| installation.
It provides messaging and database write access.

The |toastd| plugin extends |scmaster| by the ability to execute |toast| specific
tasks like the automatic triggering of incidents and simulations.
It includes the |toast| data model which is necessary to store |toast| objects in
the database.

It acts as a processor for all messages sent to its queues.
The main purpose is to respond to journal entries sent from clients in order to
queue and serialize concurrent operations from multiple clients.

The |toastd| plugin can furthermore connect to a |scname| processing queue and
create and update |toast| incidents based on configured rules automatically
whenever a new |scname| event is created or updated.

The plugin configuration also holds the configuration of the templates
(bulletins), the automatic simulation profiles, the trigger criteria and others.
The configuration of |scmaster| and also its plugins is done in the file
*scmaster.cfg* (look for *toastd* in the queues).


.. _toast_client_summ:

|toastc|
~~~~~~~~

The |toastc| is the graphical user interface (GUI) for the user.
But is not just a GUI, as for instance the computation of threat levels
based on selected simulations is done by the |toastc|.
The creation of bulletins based on the templates, the visualization in
the live tabs and execution of external scripts, for instance to
send the bulletins to the |gdsfull| |gss| is also done by the |toastc|.

Configuration which is done client-side includes among others:
:ref:`toast_live_tabs_perspective`,
:ref:`toast_threat_level_configuration` or
:ref:`toast_forecast_zones_configuration`.

In general, the user workflow for the |toastc| is very similar to the one of
the |toastl| version.


.. _gss_summ:

|gss|
~~~~~

The |gss|, the |gssfull| is a separate process running server-side which
provides pre-computed or on-the-fly simulations.
It accepts requests by the |toasts| and the |toastc|.
It has a REST API and can be accessed via HTTPS and telnet.
In principle, it can be used by other applications than |toast|.

The simulation plugins like |ewname| have to be registered in the |gss|
configuration and additionally have their own configuration files.
The installation and configuration of the |gss| is described in its
documentation.

The |gss| has its own documentation.

.. TODO:: Link to GSS doc

Summary
~~~~~~~

* Automatic incidents and simulations are triggered by the |toasts|
* Only the |toasts| writes to toast database
* Simulations are provided by the Simulation server |gss|
* Results are retrieved by the |toastc| from the |toasts| and the |gss|
* Connection between clients and servers can employ authorization
* Templates are configured on the |toasts| and evaluated by the |toastc|


.. _toast_worldwide:

Application worldwide
---------------------

Nowadays |toast| is operational worldwide in many institutions where fast and
reliable tsunami early warning is key. Some reference installations are:

* `BMKG <https://www.bmkg.go.id>`_, Indonesia
* `DGMET <https://www.met.gov.om/>`_, Oman
* `GNS <https://www.geonet.org.nz/>`_, New Zealand
* `CATAC <http://catac.ineter.gob.ni/>`_, Nicaragua
* `MSS <http://www.weather.gov.sg>`_, Singapore.


.. _simulation_concepts:

Simulation concepts
-------------------

Conventional tsunami early warning systems are exclusively based on
prototypes developed within the context of more or less scientific projects.
Based on the actually determined earthquake parameters, a lookup in a database
of precalculated earthquake scenarios and tsunami simulations is performed,
enabling prediction of arrival times and amplitudes of the tsunami wave for
relevant coastlines.
This approach takes a limited number of standard situations into account.
In case of an atypical or unexpected earthquake, these systems fail because an
*on the fly* simulation capability is not provided and the system is not able to
adapt to the situation. |toast| supports fast access to precalculated
simulations by :ref:`plugins <toast_plugin_database>`.

.. _fig-conventional:

.. figure:: media/toast/concept/conventional_tews.png
   :align: center
   :width: 17 cm

   Conventional Tsunami Early Warning System: no simulations for unexpected
   scenarios are available.

In order to achieve higher flexibility, |toast| provides the approach of
:ref:`on-the-fly simulation <toast_plugin_onthefly>` of tsunami
propagation. This enables |toast| to react to atypical situations,
like earthquakes in supposedly inactive regions or earthquakes exceeding the
maximum magnitude assumed for a region. For instance, before the 2004 tsunami,
most experts wouldn't have thought that a magnitude 9.3 earthquake in the Sumatra
region would be realistic, and similarly for the 2011 Tohoku earthquake in Japan.
Also the Fiordland earthquake in New Zealand in 2009 with a magnitude of 7.8 is
an example for an unexpected event.

Spanning a wide range of possibilities, *on-the-fly simulations* are triggered
automatically according to configuration options, and manually designed
simulations can be added with a few clicks.
Updates of earthquake source parameters can be immediately considered.

On the other hand, if a database with precalculated simulations is already
available, it can easily be integrated into |toast| using :ref:`customer-specific
plugins <toast_plugins>`.

.. _fig-toast:

.. figure:: media/toast/concept/toast_tews.png
   :align: center
   :width: 17 cm

   TOAST: precalculated as well as "on-the-fly" simulations are available.

On top of that, |toast| is also able to compute
:ref:`worst-case-aggregations <note-aggregation>` over a set of simulations.
This is useful in order to get a more conservative assessment,
for instance directly after a large earthquake, while the direction of its
rupture propagation is still uncertain.


.. _tsunami_gen_prop:

Tsunami generation and propagation
==================================

A tsunami is an oceanic gravity wave generated by submarine earthquakes
or other geological processes such as landslides or volcanic eruptions. 90 percent
of world-wide tsunami result from earthquakes. In deep ocean a tsunami
may show low amplitude and be barely noticed, but it increases when propagating
into shallower water and can cause devastating damage upon reaching the coast
or harbors.

The largest tsunami are generated by subduction earthquakes at the boundaries
of tectonic plates. These submarine events lift the seafloor along tenths to
hundreds of kilometers by several meters within seconds to minutes. As the sea
surface is raised along with it, waves are caused that travel outward
in all directions away from the source area, much like ripples caused by
throwing a rock into a pond.

A tsunami is made up of a series of very long waves. The wavelength and the
period depend on the generating mechanism and the extension of the causing event.
If a tsunami is caused by a large earthquake affecting a large area, its
initial wavelength and period are larger.
If on the other hand a tsunami is caused by a local landslide, both its initial
wavelength and period are shorter.
The period of a tsunami wave typically ranges from 5 to 90 minutes.
The wave crests of a tsunami can be more than a thousand km long, and from a few
to a hundred kilometers or more apart as they travel across the ocean.
While the wavelength diminishes when moving into shallower water, the period
remains constant.

The height of a tsunami from trough to crest in the open ocean may be only a
few centimeters to a meter or more - again depending on the generating source.
Tsunami waves in the deep water travel at high speeds over distances of
thousands of kilometers and lose little energy in the process (except for
geometrical spreading).
The deeper the water, the higher the speed of the tsunami. When the
tsunami approaches the coast and enters shallower water, the front is slowed
down while the rear still has higher speed and thus the amplitude of the tsunami
increases [#note]_.

The so-called long wave equation describes the phase speed at which a tsunami
travels as follows: :math:`c = \sqrt{g*H}`. Here :math:`g` is the gravity of
Earth (:math:`g\approx 9.8 m/s^2`) and :math:`H` is the local water depth.
The following table shows the effect of changing water depth. The first three
columns apply in general to any tsunami, the last two correspond to an example.

.. csv-table::
   :widths: 1 1 1 1 1
   :header: Water depth [m], Phase speed [m/s], Phase speed [km/h], Period [min], Wave length [km]
   :align: right

   10, 10, 36, 10, 6
   50, 22, 80, 10, 13
   100, 31, 113, 10, 19
   500, 70, 252, 10, 42
   1000, 99, 356, 10, 59
   2000, 140, 504, 10, 84
   3000, 171, 617, 10, 103
   4000, 198, 713, 10, 119
   5000, 221, 797, 10, 133
   6000, 242, 873, 10, 146

The wavelength :math:`\lambda` and the phase speed :math:`c` determine
the period :math:`T` of a tsunami through the dispersion relation:
:math:`\lambda=c*T`. Note that both speed and wave length depend on water depth,
while the period remains constant.


.. target-notes::

.. [#note] Adapted extract from IOC web page written by Tammy Kaitoku.