hysea

HySEA (Hyperbolic Systems and Efficient Algorithms) is a high-performance package developed by the EDANYA group at the University of Málaga, Spain, for the simulation of geophysical flows including tsunami.

Description

The GSS simulation plugin simhysea requires the HySEA tsunami simulation software. This documentation implies that the publicly available version from GitHub is used. The version referred to in this document is Tsunami-HySEA 1.2.

The creation of a simulation consists of following steps:

  • The user (or automatic processing) starts a HySEA simulation

  • TOAST / GSS creates a directory where HySEA is to be executed

  • It creates the file config.json which contains the configuration parameters for HySEA

  • It creates the file source.json which contains the faults parameters

  • The Python script hysea.py is executed

    • which creates the file input.txt for HySEA from config.json and source.json

    • then executes the HySEA code

    • then converts the NetCDF grid output to Golden Software Surfer binary format using gdal_translate for performance reasons

  • Upon completion, when the simulation is selected, the resulting Surfer grid files and the NetCDF file for the time series are imported in TOAST

The Python script can be configured and adapted by the user.

Configuration

In order to be loaded by the GSS, the simhysea plugin needs to be added to the global section of the gss module (gss.cfg).

plugins = ${plugins},simhysea

The configuration of simhysea can be done using scconfig Modules ‣ gempa ‣ hysea or by editing the configuration file hysea.cfg.

Bathymetry files

The current open source version supported by TOAST uses bathymetry files in NetCDF format. The file ending has to be .nc or .grd. Some requirements for the files:

  • The bathymetry variable must be called z

  • It has to be single precision (Float32)

  • It has to be negative downwards. Note that this might change with the next Tsunami-HySEA version!

Conversion tools

To convert between bathymetry formats, following Linux command line tools are useful: gdal_tranlate (package gdal-bin), ncap2 (package nco), ncdump (package netcdf-bin).

Conversion examples

To use a NetCDF grid downloaded from GEBCO, perform following steps:

gdal_translate -if netCDF -of netCDF -a_nodata NaNf -ot Float32 file1 file2
ncap2 -O -v -s 'z=elevation' file2 file3

To convert a Golden Software Surfer binary grid file to NetCDF:

gdal_translate -if GSBG -of netCDF -a_nodata NaNf -ot Float32 file1 file2
ncap2 -O -v -s 'z=Band1' file2 file3

Inspection tools

Following command is useful to inspect the content of a generated NetCDF file:

gdalinfo results.nc

And to get more information about a specific part:

gdalinfo NETCDF:"results.nc":eta

Output

The HySEA simulation plugin generates results as NetCDF files, one for the grids (results.nc) and one for the time series (results_ts.nc).

The output directory is usually located at: ~/.seiscomp/toast/hysea/output.

Input file

The TOAST user does not have to take care of the input file for the HySEA executable as it is generated automatically. However, to get more details about the installed HySEA version and parameters, just execute the binary at ~/seiscomp/bin/hysea-oss in a terminal.

Module Configuration

etc/defaults/global.cfg
etc/defaults/hysea.cfg
etc/global.cfg
etc/hysea.cfg
~/.seiscomp/global.cfg
~/.seiscomp/hysea.cfg

hysea inherits global options.

Note

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

gempa.licensePath = @CONFIGDIR@/licenses
hysea.binary

Default: @DATADIR@/simhysea/hysea.py

Type: string

Path to executable script that creates the input.txt and executes the HySEA binary

hysea.data

Default: @CONFIGDIR@/gss/hysea/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. The format has to be NetCDF.

hysea.forecastPoints

Type: list:string

Registration of forecast points.

hysea.maxProcesses

Default: 1

Type: int

Maximum number of simultaneous processes started by this plugin.

hysea.maxTime

Default: 60

Unit: min

Type: int

Maximum time span for which the tsunami propagation is calculated.

hysea.output

Default: @CONFIGDIR@/toast/hysea/output

Type: string

Base directory of HySEA outputs.

hysea.profiles

Type: list:string

Registration of simulation profiles.

hysea.ruptureRatio

Default: 0.0

Type: double

Rupture length to width ratio

hysea.maxShadowPOIDist

Default: 100

Unit: km

Type: int

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

hysea.levels

Default: 1

Type: int

Number of levels

hysea.cfl

Default: 0.5

Type: double

CFL

hysea.cropType

Default: 1

Type: int

Cropping of initial condition. 0: None, 1: Relative, 2: Absolute.

hysea.cropValue

Default: 0.01

Type: double

Cropping value. In [0,1] for relative, [0,inf] for absolute.

hysea.epsilon

Default: 0.005

Unit: m

Type: double

Epsilon h

hysea.stabilityCoefficient

Default: 0.2

Type: double

Stability coefficient

hysea.waterBottomFriction

Default: 0.03

Type: double

Water-bottom friction (Manning coefficient))

hysea.maxAllowedWaterVelocity

Default: 100

Type: double

Maximum allowed velocity of water

hysea.condition.upperBorder

Default: 1

Type: int

Upper border condition (1: open, -1: wall)

hysea.condition.lowerBorder

Default: 1

Type: int

Lower border condition (1: open, -1: wall)

hysea.condition.leftBorder

Default: 1

Type: int

Left border condition (1: open, -1: wall)

hysea.condition.rightBorder

Default: 1

Type: int

Right border condition (1: open, -1: wall)

Note

hysea.forecastPoints.$name.* $name is a placeholder for the name to be used and needs to be added to forecastPoints to become active.

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

Type: string

Absolute filename of the forecast point file in dBase format

hysea.step.ssh

Default: 15

Unit: min

Type: int

Output interval of result grids in minutes.

hysea.step.traces

Default: 15

Unit: sec

Type: int

Output interval of timeseries in seconds.

hysea.thresholds.t1

Default: 0.01

Unit: m

Type: double

Threshold for the minimum detectable positive amplitude.

hysea.thresholds.arrivalTimes

Default: 0.0000001

Unit: m

Type: double

Threshold for arrival times (m).

hysea.thresholds.wafScheme

Default: 20

Unit: m

Type: double

Threshold for the 2s+WAF scheme.

hysea.patches.dipAlign

Default: 0.5

Unit: 0, 1

Type: list:double

List of alignments in dip direction in range [0, 1]

hysea.patches.length

Default: 100

Unit: km

Type: int

Initial patch length

hysea.patches.strikeAlign

Default: 0.5

Unit: 0, 1

Type: list:double

List of alignments in strike direction in range [0, 1]