For this tutorial, we assume that you have some experience creating custom Celeris configurations, and that you are comfortable running Matlab scripts to generate config.json, bathy.txt, and other model input files.
Nested grids are useful when you want to simulate a large region with a relatively coarse grid, and then pass the computed wave signal into one or more smaller, higher-resolution grids. This is especially useful for tsunami simulations, where the wave may travel across a large basin before reaching the area of interest.
The example described here is based on a Japan 2011 tsunami nested-grid setup. The scripts and files for this configuration can be found here:
The workflow creates four grids:
gridA -> large basin-scale grid
gridB -> first nested grid
gridC -> second nested grid
gridD -> finest local grid
The basic idea is:
Run gridA
Save time series around the boundary of gridB
Use those time series to force gridB
Run gridB
Save time series around the boundary of gridC
Use those time series to force gridC
Run gridC
Save time series around the boundary of gridD
Use those time series to force gridD
For this first nested-grid workflow, the simulations use the Nonlinear Shallow Water equations:
"NLSW_or_Bous": 0
For large tsunami domains, the grids can also be run in spherical coordinates:
"grid_type": 2
When grid_type = 2, the model interprets:
"dx": dlon,
"dy": dlat
as longitude and latitude spacing in degrees. The grid location is specified with:
"lat_LL": 21.26,
"lon_LL": 201.94,
"lat_UR": 21.42,
"lon_UR": 202.16
For Pacific domains, it is generally easiest to use a continuous 0-360 longitude convention.
Creating the Nested Grid Files
The Matlab master script creates one directory for each grid:
gridA/
gridB/
gridC/
gridD/
Each directory contains the files needed to run that grid. For example:
config.json
bathy.txt
The A-grid also includes an initial free-surface condition:
IC.txt
The nested child grids are forced by boundary time series. For example, gridB expects:
gridB_time_series_bc_west.txt
gridB_time_series_bc_east.txt
gridB_time_series_bc_south.txt
gridB_time_series_bc_north.txt
These files are not created before gridA runs. They are created by gridA as nested-grid output files.
Parent Grid Output Rectangle
Each parent grid contains a rectangular output region that corresponds to the next child grid. For example, gridA contains the rectangle that defines the boundary of gridB.
The important parameters are:
"nestedGridOutput_i0": 1240,
"nestedGridOutput_j0": 160,
"nestedGridOutput_i1": 1440,
"nestedGridOutput_j1": 280,
"nestedGridOutput_start_time": 0,
"nestedGridOutput_end_time": 36000,
"nestedGridOutput_dt": 10,
"nestedGridOutput_max_samples": 8192,
"nestedGridOutput_trigger": 1,
"nestedEtaWriteThreshold": 0.001,
"nestedGridOutput_file_prefix": "gridB"
The model samples the four sides of this rectangle and writes boundary time-series files for the child grid.
The nestedEtaWriteThreshold parameter avoids writing a long time series of zeros before the tsunami arrives. The model waits until the free surface elevation along the rectangle exceeds this threshold, and then begins storing the output time series.
Child Grid Boundary Conditions
Nested child grids use boundary type 5, which means time-series boundary forcing:
"west_boundary_type": 5,
"east_boundary_type": 5,
"south_boundary_type": 5,
"north_boundary_type": 5
The corresponding boundary files are listed in the config:
"ts_west_file": "gridB_time_series_bc_west.txt",
"ts_east_file": "gridB_time_series_bc_east.txt",
"ts_south_file": "gridB_time_series_bc_south.txt",
"ts_north_file": "gridB_time_series_bc_north.txt"
At runtime, the model interpolates these time series in both space and time along the boundary. If the user provides only a small number of points along a boundary, the model linearly interpolates between them. Outside the provided range, it uses nearest-value extrapolation.
Running the Nested Grids Manually
The manual workflow is:
-
Run
gridA. -
Load
gridA/config.json,gridA/bathy.txt, andgridA/IC.txt. -
Start the simulation.
-
When
gridAfinishes, it writes files like:
gridB_time_series_bc_west.txt
gridB_time_series_bc_east.txt
gridB_time_series_bc_south.txt
gridB_time_series_bc_north.txt
-
Copy those files into the
gridBdirectory. -
Run
gridB, loadinggridB/config.json,gridB/bathy.txt, and the fourgridB_time_series_bc_*.txtfiles. -
Repeat the same process for
gridCandgridD.
There is no waves.txt file in this tsunami nested-grid workflow. The first grid is forced by the initial condition, and the child grids are forced by time-series boundary files.
Running the Nested Grids Automatically
A Python automation script (“run_nested_WebGPU.py” in the example) can also be used to run the grids one after another. The script does the following:
Run gridA
Wait for completed.txt
Copy gridB boundary files into gridB/
Run gridB
Wait for completed.txt
Copy gridC boundary files into gridC/
Run gridC
Wait for completed.txt
Copy gridD boundary files into gridD/
Run gridD
The automation script uses Selenium to control the browser and upload the correct files. It also updates each config.json with the output/write triggers needed to make the simulation write final files and close cleanly.
The relevant output trigger is:
"trigger_writeWaveHeight": 1
This writes summary output files such as:
current_FSmax.bin
current_Hs.bin
current_Hrms.bin
current_FSmean.bin
current_Speedmax.bin
completed.txt
The automation script waits for completed.txt before moving to the next grid.
If you want to run through a local server, start the server from the Celeris repository root:
python -m http.server 8080
Then set the automation script URL to:
app_url = "http://127.0.0.1:8080/"
DEM Selection and Datum Notes
The current nested-grid setup can automatically choose different DEM sources depending on the requested grid resolution.
The general hierarchy is:
Average grid size > 50 m:
ETOPO
Average grid size > 20 m:
NOAA gridded DEMs
Coastal Relief Model
ETOPO
Average grid size <= 20 m:
NOAA CUDEM
NOAA gridded DEMs
Coastal Relief Model
ETOPO
A DEM source must contain at least 95% valid data to be accepted. Remaining missing data are filled by interpolation. The selected source and datum are recorded in the generated metadata and config files.
For spherical tsunami grids, the DEM should be on a longitude/latitude grid and should use the same longitude convention as the model configuration.
Practical Notes
Large parent grids can be expensive, but they are usually still cheaper than trying to run the entire basin at the finest resolution.
The nested output time step should not be unnecessarily small. If the requested number of output samples exceeds the maximum allowed number, the model will increase the output interval and print a warning.
If the child grid starts with no waves entering the domain, check that the four boundary time-series files were loaded correctly.
If a child grid appears to start at the wrong simulation time, check the first time value in the boundary files. The model uses the first loaded boundary time as the child grid time shift.
If a nested rectangle appears in the wrong location, check the nestedGridOutput_i0, nestedGridOutput_j0, nestedGridOutput_i1, and nestedGridOutput_j1 values in the parent config.
If the simulation does not advance or no output files are written, check the browser console and make sure trigger_writeWaveHeight is enabled.
Nested grids are still a technical workflow, but they make it possible to connect basin-scale tsunami propagation to much higher-resolution nearshore simulations without running the entire domain at the finest grid spacing.