nswing

A tsunami maker

Synopsis

nswing bathy.grd initial.grd -tdt [ -1bat_lev1 ] [ -2bat_lev2 ] [ -3… ] [ -Afname.sww ] [ -C ] [ -D ] [ -E[p][m][+a][,decim] ] [ -Fx_epic/y_epic/dip/strike/rake/slip/length/width/topDepth ] [ -Fk[c]w/e/s/n ] [ -Gname[+m],int ] [ -H[momentM,momentN[,t]] ] [ -Ptime_jump[+trun_time_jump] ] [ -L[name1,name2] ] [ -M[-|+[maskname]] ] [ -Nn_cycles ] [ -OBCfile ] [ -Qz_offset ] [ -Rregion ] [ -S[x|y|n][+m][+s][+a] ] [ -Tmareg|x/y[+ooutmaregs][+tint] ] [ -Xmanning0[,…] ] [ -V[level] ] [ -fflags ] [ -xn ] [ --PAR=value ]

Note: No space is allowed between the option flag and the associated arguments.

Description

nswing is a Non-linear Shallow Water model that propagates a tsunami over a bathymetry grid. Starting from a base level bathymetry and an initial-condition (source) grid it integrates the shallow water equations in time and writes the resulting wave field (water level, velocity, momentum, energy, …) either as a series of GMT grids, a 3D netCDF file, or as time series sampled at virtual maregraph (tide-gauge) locations. Nested grids of increasing resolution may be used to refine the solution near the coast, and a tsunami source can be generated on the fly from Okada fault parameters.

Required Arguments

bathy.grd

The base level bathymetry grid (positive up; negative = below sea level). (See Grid File Formats).

initial.grd

The initial-condition (source) grid holding the sea surface displacement at time zero. (See Grid File Formats).

-tdt

Time step (in seconds) for the simulation.

Optional Arguments

-1bat_lev1 -2bat_lev2 … -9bat_lev9

Nested bathymetry grids, one per nesting level. Each level refines the solution inside the area covered by its grid. Warning, the grids must be aligned and have a cell size that is an integer fraction of the previous level. The number of levels is determined by the number of -1 … -9 options given. These grids are not trivial to create, the best way is to use the Mirone TINTOL tool.

-Afname.sww

Save the result as a .sww ANUGA-format file.

-nbase

Basename for MOST triplet files (no extension).

-C

Add the Coriolis effect.

-D

Write grids with the total water depth. These grids will have wave height on the ocean and water thickness on land.

-E[p][m][+a][,decim]

Write grids with energy, or with power if p is appended (-Ep). Append m to save only a single grid holding the max values. This can noticeably slow the run, so optionally append a decim decimator factor after the comma (causes aliasing visible under shaded illumination). The file name comes from name in -G complemented with a _max prefix; saving of multiple grids is then disabled.

With -G’s 3D netCDF cube, Energy/Power replaces the sea-surface (z) variable unless +a is appended, in which case Energy/Power is written as an extra variable alongside z (same idea as -S’s +a).

-Fx_epic/y_epic/dip/strike/rake/slip/length/width/topDepth

Okada fault parameters used to build the source. x_epic, y_epic are the x and y coordinates of the beginning of the fault trace; dip, strike (azimuth), rake, slip (m), length, width and topDepth (depth from the sea-bottom) follow. All dimensions must be in km.

If no bathymetry grid is given, -F (or -Fk) together with -R and -G computes the deformation over -R’s grid geometry (e.g. -Rgrid) and writes it straight to -G’s name: no simulation is run, so -t and -G’s saving interval are not needed.

-Fkwest/east/south/north

Build a prism source with these limits and a height of 1 meter.

  • -Fkcx/y/nx/ny - alternatively give the prism size as centre x/y and nx/ny half-width cell numbers.

  • -Fk…/RxC - loop over a matrix of size R by C starting at the Lower Left Corner given by w/e/s/n.

  • -Fk…/dx[/dy] - given the w/e/s/n region (pixel registration) loop over the prisms obtained by dividing the region in increments of dx/dy (if dy is not given, dy = dx).

Using -Fk sets the output maregraph file to netCDF, unless rows = cols = 1.

-Gname[+m],int

Save the water level every int time steps in a single 3D netCDF file called name.nc (the extension is appended when name has none). Append +m to instead write each saved step as a separate grid; files are then named name#.grd. When doing nested grids the finest level is the one saved.

-H

Write grids with the momentum (velocity times water depth).

  • -Hfname_momentM,fname_momentN[,t] - hot start using these moment grids. The optional t is the hot-start time (also needs the surface displacement corresponding to the time of these grids).

-Ptime_jump[+trun_time_jump]

Do not write grids or maregraphs for times before time_jump (seconds). When doing nested grids, append +time to NOT start nested-grid computations before this time has elapsed. Allowed forms: -Pt1, -P+t2, -Pt1+t2 or -Pt1 -P+t2.

-L

Use the linear approximation in the moment conservation equations (faster but less accurate).

  • -Lin_fname,out_fname - do Lagrangian tracers, where in_fname is the tracers initial-position file and out_fname the file to hold the results.

-M[-|+[maskname]]

Write a grid with the max water level (name from name in -G, _max prefix). Append - to instead compute the maximum water retreat, written to a mask file (default long_beach.grd; append a name after - to change it, e.g. -M-beach_long.grd). Append + for a mask with the Run In extent (behaves like -M-). -M may be repeated, e.g. -M -M- -M+ computes all three. With -G the long and short beach arrays are also saved in the .nc file.

-Nn_cycles

Number of cycles in the simulation [Default 1010]. Total simulation time is n_cycles times the time step dt.

-OBCfile

Name of a Boundary Condition ASCII file (experimental).

-Qz_offset

Apply a vertical offset to ALL bathymetry grids (e.g. to simulate tide).

-Rwest/east/south/north[/zmin/zmax][+r][+uunit]

Specify the region of interest. Note: If using modern mode and -R is not provided, the region will be set based on previous plotting commands. If this is the first plotting command in the modern mode levels and -R is not provided, the region will be automatically determined based on the data in table (equivalent to using -Ra). (See full description) (See technical reference).

The region may be specified in one of several ways:

  1. -Rwest/east/south/north. This is the standard way to specify geographic regions when using map projections where meridians and parallels are rectilinear. The coordinates may be specified in decimal degrees or in [±]dd:mm[:ss.xxx][W|E|S|N] format.

  2. -Rwest/south/east/north+r. This form is useful for map projections that are oblique, making meridians and parallels poor choices for map boundaries. Here, we instead specify the lower left corner and upper right corner geographic coordinates, followed by the modifier +r. This form guarantees a rectangular map even though lines of equal longitude and latitude are not straight lines.

  3. -Rg or -Rd. These forms can be used to quickly specify the global domain (0/360 for -Rg and -180/+180 for -Rd in longitude, with -90/+90 in latitude).

  4. -Rcode1,code2,…[+e|r|Rincs]. This indirectly supplies the region by consulting the DCW (Digital Chart of the World) database and derives the bounding regions for one or more countries given by the codes. Simply append one or more comma-separated countries using either the two-character ISO 3166-1 alpha-2 convention (e.g., NO) or the full country name (e.g., Norway). To select a state within a country (if available), append .state (e.g, US.TX), or the full state name (e.g., Texas). To specify a whole continent, spell out the full continent name (e.g., -RAfrica). Finally, append any DCW collection abbreviations or full names for the extent of the collection or named region. All names are case-insensitive. The following modifiers can be appended:

    • +r to adjust the region boundaries to be multiples of the steps indicated by inc, xinc/yinc, or winc/einc/sinc/ninc [default is no adjustment]. For example, -RFR+r1 will select the national bounding box of France rounded to nearest integer degree, where inc can be positive to expand the region or negative to shrink the region.

    • +R to adjust the region by adding the amounts specified by inc, xinc/yinc, or winc/einc/sinc/ninc [default is no extension], where inc can be positive to expand the region or negative to shrink the region.

    • +e to adjust the region boundaries to be multiples of the steps indicated by inc, xinc/yinc, or winc/einc/sinc/ninc, while ensuring that the bounding box is adjusted by at least 0.25 times the increment [default is no adjustment], where inc can be positive to expand the region or negative to shrink the region.

  5. -Rxmin/xmax/ymin/ymax[+uunit] specifies a region in projected units (e.g., UTM meters) where xmin/xmax/ymin/ymax are Cartesian projected coordinates compatible with the chosen projection (-J) and unit is an allowable distance unit [e]; we inversely project to determine the actual rectangular geographic region. For projected regions centered on (0,0) you may use the short-hand -Rhalfwidth[/halfheight]+uunit, where halfheight defaults to halfwidth if not given. This short-hand requires the +u modifier.

  6. -Rjustifylon0/lat0/nx/ny, where justify is a 2-character combination of L|C|R (for left, center, or right) and T|M|B (for top, middle, or bottom) (e.g., BL for lower left). The two character code justify indicates which point on a rectangular region region the lon0/lat0 coordinates refer to and the grid dimensions nx and ny are used with grid spacings given via -I to create the corresponding region. This method can be used when creating grids. For example, -RCM25/25/50/50 specifies a 50x50 grid centered on 25,25.

  7. -Rgridfile. This will copy the domain settings found for the grid in specified file. Note that depending on the nature of the calling module, this mechanism will also set grid spacing and possibly the grid registration (see Grid registration: The -r option).

  8. -Ra[uto] or -Re[xact]. Under modern mode, and for plotting modules only, you can automatically determine the region from the data used. You can either get the exact area using -Re [Default if no -R is given] or a slightly larger area sensibly rounded outwards to the next multiple of increments that depend on the data range using -Ra.

Output grids only in the sub-region enclosed by west/east/south/north.

-S[x|y|n][+m][+s][+a]

Write grids with the velocity (names get _U and _V suffixes). Use x or y to save only one component, or n for no velocity grids (maregraphs only). Append +m to also write velocity (vx,vy) at maregraph locations (needs -T). Append +s to write the max speed (|v|) (_max_speed suffix). Use the n flag to NOT output the U and V components, e.g. -Sn+s.

With -G’s 3D netCDF cube, velocity is written as the only variable unless +a is appended, in which case the sea-surface (z) variable is also written (z + velocity).

-Tmareg|x/y[+ooutmaregs][+tint]

Save time series (maregraphs) at virtual tide-gauge locations. mareg is the file with the (x y) locations of the virtual maregraphs. For a single maregraph the location may be given directly as x/y instead of a file name. Append +ooutmaregs to set the output file name [Default is maregs_out.dat]. A .dat extension is added when outmaregs has none; use a .nc extension to write the maregraphs as a netCDF file instead. Append +tint to save every int simulation time steps (set by -t) [Default is every time step]. -T alone (without -G) is allowed and runs a simulation that only outputs the maregraph series.

-Xmanning0[,manning1[,…]][+depth]

Manning friction coefficients. If only one is provided, use it for all nesting levels; otherwise specify one per level, comma separated. Append +depth to apply Manning only at depths shallower than depth (positive up).

-V[level]

Select verbosity level [w]. (See full description) (See technical reference).

-xn

Number of OpenMP threads to use [Default is all available cores]. Results are identical for any number of threads.

-x[[-]n] (more …)

Limit number of cores used in multi-threaded algorithms. Multi-threaded behavior is enabled by default. That covers the modules that implement the OpenMP API (required at compiling stage) and GThreads (Glib) for the grdfilter module.

-^ or just -

Print a short message about the syntax of the command, then exit (Note: on Windows just use -).

-+ or just +

Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exit.

-? or no arguments

Print a complete usage (help) message, including the explanation of all options, then exit.

--PAR=value

Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

Examples

To propagate a tsunami over the bathymetry bathy.grd given the source source.grd, using a 5 second time step and saving the water level every 10 time steps to grids named wave#.grd, try:

gmt nswing bathy.grd source.grd -t5 -Gwave,10

To run the same simulation but generate the source on the fly from Okada fault parameters and sample the wave field at the virtual maregraphs listed in gauges.dat every 5 time steps, try:

gmt nswing bathy.grd -t5 -F-8/37/12/90/90/3/100/50/10 -Tgauges.dat+t5

To record only the time series at a single virtual tide gauge (no grids at all), give its location directly to -T:

gmt nswing bathy.grd source.grd -t5 -T-10.7/37.3

To compute just the Okada co-seismic deformation over the geometry of the grid bathy.grd (no simulation), try:

gmt nswing -Rbathy.grd -F94.3/2.8/25/330/90/10/250/65/10 -Gdeform.grd

A less hypothetical example that generates only a few layers in the tsu.nc cube:

gmt grdcut @earth_relief_02m_g -R-15/-7.5/34/39.5 -Gbat.grd
gmt nswing -Rbat.grd -F-12.49593345/35.93634937/25/58.2/90/10/215/53.75/10 -Ginit.grd
gmt nswing bat.grd init.grd -t3 -Gtsu,10 -N100 -V

See Also

gmt, grdinterpolate

Reference

[Validation of NSWING, a multi-core finite difference code for tsunami propagation and run-up]( https://www.researchgate.net/publication/275349940_Validation_of_NSWING_a_multi-core_finite_difference_code_for_tsunami_propagation_and_run-up)