.. highlight:: rst

.. _easywave2:

#########
easywave2
#########

**EasyWave**


Description
===========

.. _toast_easywave:

|ewname| simulates tsunami generation and propagation very rapidly and on the
fly during runtime of |toast|.
It supports computation on GPU resulting in a vast speed-up compared to CPU.
|ewname| is thus very well suited for the application in |toast|.

|ewname| is not part of |gss| (rights owner is Andrey Babeyko, GFZ German
Research Center for Geosciences, Potsdam, babeyko@gfz-potsdam.de), but
|gss| is delivered including |ewname| executables and a plugin acting as
interface between |gss| and |ewname| (for simplicity also called |ewname|
or `easywave2`).


Configuration
=============

|gss| uses |ewname| through a plugin which takes care of the generation of
required input files for |ewname|, executes it with appropriate options and
reads in the computed output.

Several parameters for |ewname| can be configured using: :program:`scconfig`
:menuselection:`--> Modules --> gempa --> easywave2 --> easywave2`.
These parameters are stored in `~/seiscomp/etc/easywave2.cfg`.

A description of the parameters can be found at the end of this section under
*Configuration*. See also: :ref:`toast_forecast_zones_configuration`.


.. _toast_bathymetry_files_configuration:

Bathymetry files
----------------

(From TOAST Simulation bathymetry files configuration)

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:

.. code-block:: sh

  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 the GSS documentation on how to configure the default bathymetry for
the simulations within a source region.


.. _toast_creating_bathymetry:

Creating bathymetry files
~~~~~~~~~~~~~~~~~~~~~~~~~

|gss| 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).

|ewname| executable internal technical description
==================================================

.. note::
   The generation of input files for |ewname| and the import of the computed
   results is handled by the |toast| |ewname| plugin, nevertheless we here
   give a description on how |ewname| is structured and works internally.
   Execute `~/seiscomp/bin/easywave2` to get additional information about
   |ewname| options.


Tsunami source modeling
-----------------------

There are two possibilities to set-up tsunami generation in |ewname|:

#. Providing earthquake fault(s) parameters (as is done by |toast|)
#. Providing the initial condition directly (sea floor deformation)

Both source options assume instant sea-surface displacement.
Time-dependent forcing is presently not implemented.

#. Co-seismic displacement is modeled according to the classical Okada model
   (1985) for the uniform-slip rectangular rupture in a homogeneous half space.
   Any number of faults can be given in an input file which allows the user
   to simulate ruptures with complicated non-uniform slip distributions.
   There is no fixed set of input fault parameters in |ewname|.
   General rule - a fault should be sufficiently defined.
   For example, one can literally specify the whole set of Okada's parameters:
   location, depth, length, width, slip, strike-, dip- and rake-angle, or give
   fault location, orientation and earthquake moment magnitude.
   In the latter case, scaling relations (usually, Wells and Coppersmith, 1994)
   are implied to estimate rupture geometry and amount of slip.
#. Alternatively, the initial condition can be directly given on the program
   input. In this case input 2D-map should be stored in text- or binary-
   Golden Software GRD-format.


Wave propagation
----------------

|ewname| follows the computational algorithm presented in Kowalik and Whitmore (1991).
Two-dimensional shallow water equations are solved on a staggered finite-difference
grid in spherical coordinates implying explicit time-stepping.
In |ewname| only linear approximation is considered, i.e., advection,
bottom-friction and Coriolis terms are disabled (see General Description and
Motivation above).
The algorithm does not calculate coastal inundations and detailed run-ups directly.
Instead, |ewname| brings the tsunami wave until the validity limit of the linear
shallow water model (usually, 20-50 meter water depth) and then estimates run-ups
with empirical relations (e.g., Chesley and Ward, 2006).


Validation
----------

|ewname| has been compared to TUNAMI-N2 (Imamura, 1996), a widely used
tsunami simulation software for a number of scenarios around the Indian Ocean.
Leading, non-reflected waves show perfect coincidence till the very shallow
(<10m) depths except for the cases when the leading wave travels long distances
along the coast thus accumulating second-order shallow-water effects like bottom
friction.
In this case |ewname| showed somewhat earlier and lower-amplitude first arrival
(the differences being still inside the tolerance of the early warning precision).


Configuration files
-------------------

An example for the main configuration file of |ewname| is tsunami.cfg and is
listed below: ::

  ; TSUNAMI configuration file

  ; bathymetry file
  [bathymetry]=
  /home/data/bathymetry/C_e10_25e70s_120e33n.grd

  ; time step (for this bathymetry) [sec]
  [time_step]= 5

  ; minimal calculatuional depth [m]
  [min_depth]= 20

  ; Initial uplift: smoothing radius [grid-nodes]
  [ssh0_smooth]= 0

  ; Initial uplift: relative threshold [0-1]
  [ssh0_rel_threshold]= 0.0

  ; Initial uplift: absolute threshold [m]
  [ssh0_abs_threshold]= 0.1

  ; Ssh clip threshold [m]: calculate only in region where ssh > threshold
  plus clip-rand
  [ssh_clip_threshold]= 1.e-4

  ; Threshold for 2D-arrival time map [m]
  [ssh_arrival_threshold]= 0.0000001

  ; Ssh clip rand [grid-nodes]: to give more space for wave propagation
  beyond actual wave front
  [ssh_clip_rand]= 3

  ; progress output after each ... minutes
  [dt_out_progress]= 1

  ; 2D field output after each ... minutes
  [dt_out_2D]= 1

  ; Threshold for the ssh 2D-output transparency mask [m]
  [ssh_transparency_threshold]= 0.

  ; Always overwrite sshmax 2D output [1/0]
  [overwrite_sshmax]= 1

  ; Points-Of-Interest (POIs) file
  [POIs_file]= poi.dat

  ; POIs output after each ... seconds
  [dt_out_POIs]= 15

  ; POIs max shadow dist (if POI is on land) [km]
  [max_shadow_dist_POIs]= 100
  [min_shadow_depth_POIs]= 0


.. note::
   The configuration file tsunami.cfg is not used by the |toast| |ewname|
   plugin, as the parameters are passed as command line options. We list it
   nevertheless for reference. The configuration file when using |ewname| with
   |toast| is `~/seiscomp/etc/easywave2.cfg`.

In addition to tsunami.cfg, |ewname| reads a POI configuration file named
poi.dat and a GNSS file named gnss.dat.
The latter one is used to compute displacements at GNSS stations.
The format looks like this: ::

  BENO 115.217 -8.7666 1
  CHRS 105.669 -10.4294 1
  CHTT 91.825 22.3333 1
  CILA 109 -7.75 1
  CILI 109 -7.75 1


Output
------

|ewname| produces both 1D- and 2D-outputs.
Wave time series can be stored for any given location in a simple text-table format.
Optional run-up estimates are provided as well.
Additionally, 2D outputs of the wave propagation are stored at regular time
intervals as binary GRD-files (Golden Software grid file format).
This 2D-output is compact since only part of the grid corresponding to the
actual propagation area is written. Other 2D-outputs (also in binary GRD-format)
contain maximum wave height and tsunami arrival times.

The output directory is usually located at:
`~/.seiscomp/gss/easywave2/output`.
A typical simulation directory looks like this: ::

  `-- 83
     `-- 004006S
         `-- 100102E
             `-- 83004006S100102E6543c67e7e4a0474c85e96bf11829851ee2ba6
                 |-- fault.inp
                 |-- gnss.dat
                 |-- gnss.dat.xyz
                 |-- poi.dat
                 |-- poi.dat.lst
                 |-- protocol.txt
                 |-- source.inp
                 |-- tsunami.cfg
                 |-- wave.2D.00000.ssh
                 |-- wave.2D.00120.ssh
                 |-- wave.2D.00240.ssh
                 |-- wave.2D.00360.ssh
                 |-- wave.2D.00480.ssh
                 |-- wave.2D.00600.ssh
                 |-- wave.2D.00720.ssh
                 |-- wave.2D.00840.ssh
                 |-- wave.2D.00960.ssh
                 |-- wave.2D.01080.ssh
                 |-- wave.2D.01200.ssh
                 |-- wave.2D.01320.ssh
                 |-- wave.2D.01440.ssh
                 |-- wave.2D.01560.ssh
                 |-- wave.2D.01680.ssh
                 |-- wave.2D.01800.ssh
                 |-- wave.2D.idx
                 |-- wave.2D.sshmax
                 |-- wave.2D.time
                 |-- wave.patches
                 |-- wave.poi.ssh
                 `-- wave.poi.sshmax

The first level corresponds to magnitude, the second to latitude, the third to
longitude and then follows the unique simulation ID.
The different file types contain the following information:

\*.2D.\*.ssh
    are the sea level surface height grid files
wave.2D.sshmax
  is the maximum sea level surface height grid file
wave.2D.time
  is the arrival time grid file
wave.patches
  contain the patch information
wave.poi.ssh
  sea level surface height information
wave.poi.sshmax
  contains POI ID, maximum sea level surface height and run-up
wave.2D.idx
  contains output grid list



Module Configuration
====================

| :file:`etc/defaults/global.cfg`
| :file:`etc/defaults/easywave2.cfg`
| :file:`etc/global.cfg`
| :file:`etc/easywave2.cfg`
| :file:`~/.seiscomp/global.cfg`
| :file:`~/.seiscomp/easywave2.cfg`

easywave2 inherits :ref:`global options<global-configuration>`.

.. note::

   Modules/plugins may require a license file. The default path to license
   files is :file:`@DATADIR@/licenses/` which can be overridden by global
   configuration of the parameter :confval:`gempa.licensePath`. Example: ::

      gempa.licensePath = @CONFIGDIR@/licenses



.. _easywave2:


.. confval:: easywave2.arrivalTimesStep

   Default: ``15``

   Unit: *min*

   Type: *int*

   Output interval of the arrival times grids in minutes.


.. confval:: easywave2.binary

   Type: *string*

   EasyWave binary to execute.


.. confval:: easywave2.contourThreshold

   Default: ``0.01``

   Unit: *m*

   Type: *double*

   Contour lines with a maximum ssh value of this value are ignored.


.. confval:: easywave2.data

   Default: ``@CONFIGDIR@/gss/easywave2/data``

   Type: *string*

   Directory for input bathymetry grid files. All files found directly in this folder and ending on '.grd' are interpreted as bathymetry files. The first matching grid \(automatic calculation\) or the file selected \(interactive simulation\) is passed to EasyWave.


.. confval:: easywave2.enableLogging

   Default: ``true``

   Type: *boolean*

   Log console output of EasyWave process


.. confval:: easywave2.forecastPoints

   Type: *list:string*

   Registration of forecast points.


.. confval:: easywave2.gpu

   Default: ``false``

   Type: *boolean*

   Use GPU for processing if supported


.. confval:: easywave2.maxProcesses

   Default: ``1``

   Type: *int*

   Maximum number of simultaneous processes started by this plugin.


.. confval:: easywave2.maxTime

   Default: ``60``

   Unit: *min*

   Type: *int*

   Maximum time span for which the tsunami propagation is calculated.


.. confval:: easywave2.output

   Default: ``@CONFIGDIR@/gss/easywave2/output``

   Type: *string*

   Base directory of EasyWave outputs. The results of a particular simulation are expected in a subfolder named after the eventID specified in EasyWave input file.


.. confval:: easywave2.ruptureRatio

   Default: ``0.0``

   Type: *double*

   Rupture length to width ratio


.. confval:: easywave2.shadowPOIMinDepth

   Default: ``10``

   Unit: *m*

   Type: *int*

   To simulate the tsunami wave for a POI the next water grid point is used. Only deep water points should be used. The minimum water depth can be defined here.


.. confval:: easywave2.shadowPOIMaxDist

   Default: ``100``

   Unit: *km*

   Type: *int*

   Distance in which the next water grid point is searched in case the POI is on land.


.. confval:: easywave2.sshStep

   Default: ``15``

   Unit: *min*

   Type: *int*

   Output interval of the ssh grids in minutes.


.. confval:: easywave2.sshTracesStep

   Default: ``15``

   Unit: *s*

   Type: *int*

   Output interval of the traces in seconds.


.. confval:: easywave2.T1Threshold

   Default: ``0.01``

   Type: *double*

   Threshold for the minimum detectable amplitude. See also T1Absolute.


.. confval:: easywave2.T1Absolute

   Default: ``false``

   Type: *boolean*

   If false, only exceedance of positive amplitude counts as detection. If true, also falling below negative amplitude counts. See also T1Threshold.


.. _easywave2.forecastPoints:


.. note::

   **easywave2.forecastPoints.\***
   *Define forecast point profiles.*
   *Register the profiles at 'forecastPoints'.*
   *Note that forecast zones have to be defined and registered*
   *in TOAST.*


.. _easywave2.forecastPoints.$name:


.. note::

   **easywave2.forecastPoints.$name.\***
   $name is a placeholder for the name to be used and needs to be added to :confval:`forecastPoints` to become active.

   .. code-block:: sh

      forecastPoints = a,b
      easywave2.forecastPoints.a.value1 = ...
      easywave2.forecastPoints.b.value1 = ...
      # c is not active because it has not been added
      # to the list of forecastPoints
      easywave2.forecastPoints.c.value1 = ...


.. confval:: easywave2.forecastPoints.$name.filename

   Type: *string*

   Absolute filename of the forecast point file in dBase format


.. _easywave2.patches:


.. note::

   **easywave2.patches.\***
   *Configure settings for the automatic patches (rupture*
   *segments) generation.*


.. confval:: easywave2.patches.dipAlign

   Default: ``0.5``

   Unit: *0, 1*

   Type: *list:double*

   List of alignments in dip direction in range [0, 1].
   
   0.5: at hypocenter
   
   < 0.5: updip
   
   > 0.5: downdip
   
   0,0.5,1 creates simulations centered at the upper and lower
   extend and at the hypocenter depth of the original rupture.


.. confval:: easywave2.patches.length

   Default: ``100``

   Unit: *km*

   Type: *int*

   Initial patch length


.. confval:: easywave2.patches.strikeAlign

   Default: ``0.5``

   Unit: *0, 1*

   Type: *list:double*

   List of alignments in strike direction in range [0, 1].
   
   0.5: at hypocenter
   
   > 0.5: with strike
   
   < 0.5: against strike
   
   0,0.5,1 creates simulations centered at the far ends and
   over the hypocenter of the original rupture.