Tutorial 7: Creating a Custom Configuration

For this tutorial, we assume that you have played around with the Examples, and have reviewed the previous Tutorials.  Here, creating your own simulation, separate from the Examples, is described.

The recommended approach is:

·       Create a gridded 2D bathy/topo surface, covering the area you wish to simulate.  The grid can be of any resolution, but the finer the better.  If you wish to overlay a satellite image or some other custom raster, create that image with the same spatial extents as your 2D bathy/topo surface.

·       Using the provided configuration scripts (or custom versions thereof), specify basic simulation parameters, such as model grid size (does not need to be the same as the 2D bathy/topo surface), Courant number, constant friction factor, boundary conditions, etc.

·       Upload the script-generated input files into the “Upload Custom Configuration Files here:” section of the “Start Here” panel. Click “Start Simulation” to load and run simulation.

For the workflow described in this tutorial, the user should have access to and be somewhat familiar with Matlab. Everything described in this tutorial can also be done in Python, but Python scripts are not provided here.  It is assumed that any user who wishes to create a custom configuration of a simulation with a Boussinesq-type model has a technical background.

Creating a 2D Bathy/Topo Surface

This data can be from any source.  I find that NOAA’s Data Viewer:

https://coast.noaa.gov/dataviewer/#/

is the best source to get both high res bathy/topo and satellite imagery for coastlines in the US.  But again, any source is fine.  You will want to work with the data such that it can be plotted and saved with the Matlab command:

pcolor(x,y,h)

shading interp

save celeris_bathy.mat x y h

where “x” and “y” are 1D vectors in units of meters, with size “1 by nx” and “ny by 1” respectively.  “h” is the seafloor elevation (i.e. offshore is negative) in meters from whatever datum the user chooses and is a 2D surface of size “ny by nx”.  The file “celeris_bathy.mat“ contains the information that will be loaded by the configuration script.

If you wish to load a satellite or other overlay for the topography, create that file during this step.  The overlay file, which should be an image (jpg’s tend to be fine in quality and are relatively small in file size), must cover the exact area as the 2D bathy/topo files.  The only restriction here is that the maximum dimension of the overlay image must be 8192 pixels or less.  Neither the dimensions nor the aspect ratio of the overlay image needs to be the same as the 2D bathy/topo file.

Creating Input Files with Configuration Script

The attached “create_Celeris_inputs.m” and "spectrum_2D.m" will generate the necessary input files. 

The primary configuration options in "create_Celeris_inputs.m" are:

% High-Level Simulation Control Parameters

NLSW_or_Bous =1; % =0 for Nonlinear Shallow Water Solver (long waves only) otherwise Boussinesq (wind waves)

dx=1.5; % uniform grid size to use in model - the loaded bathy files will be interpolated to this grid size

Courant_num = 0.2; %Target Courant #.  ~0.25 for P-C, ~0.05 for explicit methods. Default: 0.2

isManning=0; % A boolean friction model value, if==1 "friction" is a Mannnigs n, otherwise it is a dimensionless friction factor (Moody)

friction=0.001;  % dimensionless friction coefficient, or Mannings "n", depending on isManning choice

% Waves

Hmo=3.;  % Spectral wave height (m)

Tp=15;  % peak period (sec)

Thetap=90; % mean direction (deg w.r.t. numerical grid) 0=from west, 90=from south, 180=from east, -90 or 270 from north

%  Boundary conditions - at least one of the boundaries should be = 2

west_boundary_type=0; % west_boundary_type, 0=solid wall, 1=sponge layer, 2= waves loaded from file, created by spectrum_2D above

east_boundary_type=0; % east_boundary_type, 0=solid wall, 1=sponge layer, 2= waves loaded from file, created by spectrum_2D above

south_boundary_type=2; % south_boundary_type, 0=solid wall, 1=sponge layer, 2= waves loaded from file, created by spectrum_2D above

north_boundary_type=1; % north_boundary_type, 0=solid wall, 1=sponge layer, 2= waves loaded from file, created by spectrum_2D above

and these can be changed depending on the simulation.  Note that the “dx” need not be the same as the grid size used when creating the bathy/topo surface.  The configuration script will interpolate the given surface to fit the numerical grid. The above inputs should be fairly self-explanatory for someone familiar with numerical simulation.  The input wave condition is generated with a TMA spectrum (calls the function “spectrum_2D.m”), using the three specified parameters.  It is straightforward to use a custom input wave condition, but again, this would require some understanding of scripting, and loading/generating a custom spectrum within the script. 

The output of this configuration script is:

·       config.json – the simulation control file, including the simulation parameters specified within the script, as well as domain parameters determined from the bathy/topo surface

·       bathy.txt – the bathy/topo surface fit to the numerical grid, in a simple format for loading into the web simulator.

·       waves.txt – the input wave spectrum file, consisting of a set of amplitudes, periods, and directions

Loading Input Files and Running Simulation

From the “Start Here” Panel:

Click on the gray “Load JSON…” box and load your control file.  If loaded correctly, the box should turn green.  Do the same for the bathy, waves, and overlay file.  If all files have been uploaded correctly, the Panel should appear as:

Click Start Simulation, and if files have been generated correctly, the simulation should load and run.  If not, check the console for errors or hangs.  Post a question / help request in the forum if you cant figure it out, and provide your inputs files.

Some notes:

In general, you will want to keep simulations around or less than 1 million grid points in total (e.g. 1000 by 1000) to maintain near real-time simulation of coastal domains using the Boussinesq option.  The fastest available GPU (as of this writing the 4090), will run such sized domains 3-5 times faster than real-time.

Running large simulations on machines with relatively under-powered GPUs can result in sluggish behavior of the web browser, where the page scrolls and responds slowly.  In these cases, the web page can break its connection with the GPU, and the simulation canvas will disappear.  When this occurs, the page will need to be reloaded, and the user should recognize that the attempted simulation may be beyond the limit of what the hardware can handle.

I have a repository of all the simulation directories here:

https://www.dropbox.com/scl/fo/xdlsgirw2efdic97epaj0/ANofWQQ4xytKZjatxopJc-4?rlkey=2sl7ll7o4ojfvixq0uktdt8o9&st=jgqrraa1&dl=0

In this directory, you can see what my bathy/topo and overlay files look like, as well as the input files used by the model.