In this exercise you will complete the setup of a case to run with SERGHEI. We will use a well known benchmark case for shallow water models which reproduces a laboratory scale experiment of the tsunami which hit the Monai valley in the Okushiri island, just west of Hokkaido, Japan in 1993. The SERGHEI setup follows a well established benchmark.
This tutorial assumes that you have built SERGHEI and have managed to run some simple test case before.
1. Get some data for this case
Clone the GitLab repository which contains the basic data for this case, into a directory of your choice. A suggestion is to use $HOME/monaiTsnuami
.
2. What do I need to set up?
SERGHEI requires, a minimum set of 3 input files:
- a Digital Elevation Model (DEM), which must be named
dem.input
- a simulation control file called
parameters.input
- a shallow water model control input file
sw.input
However, many other files can be defined. A tutorial on the input files is here.
What did you get already?
In the data which you cloned you will find the dem.input
file with the experimental scale bathymetry and topography of the affected region. This is an ASCII raster file. You can inspect it by simply opening it as a text file.
Generating an appropriate DEM is a job in itself and will not be discussed here.
You also get a wave.input
file containing a time-series definition of the input wave which serves as a forcing boundary and drives the tsunami into the computational domain. You can also inspect this text file, which has a very simple and human readable structure.
Finally, you get the polygon.input
file which defines the geometry for the boundary in which the wave flows in.
What's missing?
For all the points herein, you can refer to the aforementioned Quick tutorial: setup a model page for details.
To fully define this case we don't need all of the possible input files, only a few:
parameters.input
sw.input
extbc.input
3. First setup
Let's first setup parameters.input
and sw.input
, which are mandatory. Remember to put these files inside the input
directory.
parameters.input
.
Simulation control The simulation duration should be 20s, with a CFL value of 0.5, spatial output with a frequency of 1s and observation output frequency of 0.25s.
We will run this test on a single compute node, therefore no domain decomposition is necessary in either the x nor y directions. Consequently parNx
and parNy
should be 1.
We will use NETCDF
output, default boundaries should be REFLECTIVE
, and a reasonable screen output is between 200-1000.
sw.input
Shallow water model control The initial conditions for the experiment are those of a quiescent (still water) water surface. That is, we want a horizontal water surface at sea level with zero velocity.
In the typical shallow water variable naming h
is water depth, z
is the elevation of the bed relative to some arbitrary datum, and therefore h+z
is the elevation of the water surface relative to the same datum. This datum must be consistent with that of the DEM. In the DEM z=0
is the mean sea level. With this information, set initialMode
to h+z
and initialValue
to sea level.
This benchmark typically uses Manning's friction law, with a roughness value of 0.01. Set this up in the file. Finally, because of the small scale of the experiment, and because in a tsunami we are particularly interested on the advancement of the wave over dry land, we will use a dry depth tolerance of 0.0001 m.
4. Running the simulation
Copy the example sbatch script that was created in a previous tutorial and modify it to include the path to this tsunami case. Then run the sbatch script.
5. Visualising results
Let's check out the results. Although the output of this exercise is rather small, we will nonetheless visualise it in a lightweight way in the remote system.
We first start by forwarding graphics, often referred to as forwarding X from the remote server into our local machine, with the same SSH command with which you login, but including -X
.
ssh -X -i ~/.ssh/id_ed25519 <yourid>@jureca.fz-juelich.de
Upon login, source the modules necessary for SERGHEI, and also load the Panoply module
module load Panoply/4.11.6
Navigate to where your results are, into the output folder, until you can find the output.nc
file.
Let's open this with
panoply output.nc
This should prompt a window, looking roughly like this
Select the bed elevation (z) variable and click on "Create plot". Set up the axis correctly so that we can see bed elevation (z) in space (x-y). This should look more or less like this
The bed elevation is assumed not to change in time, and therefore you don't have a temporal dimension to advance through. However, if you plot the water depth (h), or water surface elevation (h+z) or velocity variables (u, v) they are time dependant. Check out how the other variables look, and advance them in time.
Note that there is nothing actually happening in this simulation. The still water remains still. This is because
- the initial condition was one of still water
- there is no forcing through the boundaries
- there is no forcing through source or sink terms
Nonetheless, it is important to highlight that still water equilibrium is a very important property of the numerical scheme signalling well-balancing between the fluxes and source terms in the numerical solver.
6. Run the full simulation
Now we want to run the full simulation, with boundaries which model the incoming tsunami wave. For this we need to create the extbc.input
file (extbc
stands for external boundary conditions).
Details on how to setup boundary conditions are in the SERGHEI BC wiki page. Try setting this up simply following the documentation.
We need to devine a single boundary, which we may call inlet
. We wish to define an inflow stage hydrograph, i.e., a time series of water surface elevations (t, h+z). You therefore need to include the relevant bctype
code for this. direction
indicates the inflow direction of the hydrograph in a unit vector fashion, i.e., 1.0 1.0
would mean a 45 degree angle (North-East), -1, 0
would mean a 180 degree angle (West).
Finally, the polygon
and hydrograph
entries require the name of the polygon file which defines where to find the boundary (polygon.input
), and the file containing the stage hydrograph (i.e., wave.input
).
Try to understand how the polygon encodes the information. It defines a polygon which envelopes the west boundary (x=0
), where the tsunami wave should come from, flowing eastwards.
Once all this is setup, run the simulation again and visualise the results again. If everything is set correctly, results at the end of the simulation should look like this