Steps to setup a new simulation

The steps to quickly setup a new simulation with SUNTANS are shown:

1. Horizontal grid preparation
   Any arbitrary-shape unstructured grid can be applied in the SUNTANS model. The only requirement is that the grid should be orthogonal, unless the accuracy of the proposed spacial discretization will decrease to the first-order accuracy. The input grid files include three files points.dat, edges.dat and cells.dat, which should have the following format for each row:

• points.dat: 'point x','point y','type'
• If no point source is applied, the point type should be always 0.
• edges.dat: 'index of point 1','index of point','type','index of cell 1 with this edge','index of cell 2 with this edge'
• The type of edge include 0 for interior/computational edge, 1 for closed boundary edge, 2 for inflow boundary edge, and 3 for tidal boundary edge. When an edge is set as type 3, the cell with this edge will be treated as tidal boundary cell. Their free surface height can be setup in the boundaries.c.
• cells.dat: 'number of edge N','cell center x','cell center y',N*'index of point to form cell',N*'index of neighboring cells'
• If one edge or cell locates at boundaries, replace the missing cells or neighboring cells with -1.

2. Water depth
   Water depth can be assigned in three ways.

• Predefined function: See the function in initialization.c
• Interpolation based on the existing file: provide the known bathymetry (named as depth.dat) file for interpolation on current grid. The format of the depth.dat should be: 'point x','point y', 'depth'
• Predefined value for the existing grid: provide the known bathymetry (named as depth.dat-voro) to directly setup water depth for each cell center. The depth.dat-voro has the same format as depth.dat, but its order should be consistent with the order in cells.dat

3. Boundary condition
   All the boundary conditions can be setup in the boundaries.c.

• Temperature and salinity at boundary: function BoundaryScalars
• Tidal boundary (edge type 3): function BoundaryVelocities (cells with index from grid->celldist[1] to grid->celldist[2])
• Inflow boundary (edge type 2): function BoundaryVelocities (edges with index from grid->edgedist[2] togrid->edgedist[3])
• Surface wind stress: function WindStress
• Sediment concentration: function BoundarySediment

4. Initial condition
   All initial condition can be setup in the initialization.c.

• Water depth: function ReturnDepth
• Free surface height: function ReturnFreeSurface
• Salinity and temperature: function ReturnSalinity/ReturnTemperature
• Wind stress: function ReturnWindSpeed/ReturnWindDirection
• Culvert height: function ReturnCulvertTop
• Marsh drag: function ReturnMarshHeight/ReturnMarshDragCoefficient
• Subgrid bathyemtry: function ReturnSubgridPointDepth/ReturnSubgridPointeDepth/ReturnSubCellArea/ReturnFluxHeight
• Sediment transport: function ReturnSediment/ReturnSubgridErosionParameterizationEpslon

5. Setup vertical coordinate
   All initial condition for any arbitrary vertical coordinate can be setup in the uservertcoordinate.c.

• If z-level is applied, the distribution of layer thickness is setup in initialization.c with function GetDZ, no more additional setup is required in this file.
• For isopycnal coordinate, the initial layer thickness should be setup with function InitializeIsopycnalCoordinate.
• For sigma coordinate, the initial layer thickness should be setup with function InitializeSigmaCoordinate.
• If variational moving mesh is applied, both the monitor function (MonitorFunctionForVariationalMethod) and initial layer thickness (InitializeVariationalCoordinate) should be setup.
• If an arbitrary user defined vertical coordinate, the initial layer thickness and the related function to update the new layer thickness should all be defined in functions InitializeVerticalCoordinate and UserDefinedVerticalCoordinate.
• Please check the existing different examples for more details.

6. Parameter setting

• All the parameters are stored in a file called suntans.dat. For different parameters, please check the parameter dictionary for more details.

7. Directory setup and commands to run

• The most common way for directory setup is to store all input files (grid, parameter setup) in 'rundata' file.
• The commands to run the simulation can be found in the Makefile.
• The number of cores can be setup in Makefile.
• The customized command can be created in Makefile and the related .sh file.
• The default command is: 'make clobber': clean up/reset the directory; 'make test': run the simulation

8. Recommendation

• Always start with the existing test case! Find the most related test case first.
• Please learn some basic shell script to modify and create customized command to run a simulation.
• In boundaries.c, there is a function called UserDefinedFunction, which can be used to debug and output anything you want. This function will be run at every time step.