User Guide 013
Hard Bottom
Hard Bottom is a morphologic constraint that provides the capability to simulate mixed bottom types within a single simulation. This cell-specific feature limits the erodability of the constrained cells down to a specified depth below the water surface. During sediment transport calculations, exposed hard bottom cells may become covered through deposition. By default, CMS-Flow cells are fully-erodible cells with no specified hard bottom depth (inactive cells; denoted by the CMS-Flow null value of -999.0). Hard bottom only needs to be specified only for computational (ocean) cells.
Figure 2-91. CMS-Flow Model Control window showing the location where the hard bottom dataset is specified.
Figure 2-92. Specification of the Hardbottom Dataset in the Sediment tab of the CMS-Flow Model Control window in SMS 11.1.
Within the CMS-Flow Model Control window, the hard bottom dataset can be created from the Sediment tab. If the dataset does not exist, it can be created using the Create Dataset button. If a dataset exists (created using the Data Calculator) which represents the intended hard bottom specifications, the Select Dataset button can be used to select such dataset and copy the values to the hard bottom dataset.
When specified, cell hard bottom depths will appear in the Project Explorer as a scalar dataset beneath the CMS-Flow grid. This dataset cannot be deleted, though it can be edited like any other dataset. A CMS-Flow simulation must contain the hard bottom dataset (even if it is not specified) so SMS will create a defaulted (inactive cells) dataset if it does not already exist when saving the simulation. The hard bottom dataset can created, edited, viewed and verified using the following SMS interface features.
Figure 2-93. SMS Project Explorer showing Hard bottom dataset
Example 2-90. Specifying the hard bottom dataset.
HARDBOTTOM_DATASET "Flow_grid.h5" "FLOW/Datasets/Hard Bottom"
Boundary and Initial Conditions
In the case of the Equilibrium Total Load sediment transport model, all boundaries are set to the equilibrium transport rate. For the Equilibrium Bed Load plus Advection Diffusion model, the suspended load is specified as the equilibrium concentration at inflow cells and a zero gradient at outflow cells. For the Total load nonequilibrium sediment transport model, the sediment concentration is set to the equilibrium concentration at inflow cells and a zero gradient boundary condition is applied at outflow cells.
In the case an initial conditions file is NOT specified both the hydrody-namics and sediment concentrations are initialized as zero. If an initial conditions file is specified, than the initial sediment concentrations are read in. If an initial conditions file is specified but without the sediment concentration, than the initial sediment concentration is set to the equilibrium concentration.
Table 2-96. CMS Flow cards related to the boundary conditions.
| Card | Arguments | Default | Range | Description |
|---|---|---|---|---|
| NET_LOADING_FACTOR | real | 1.0 | 0.5-2.0 | Used to specify under- or overloading at sediment inflow boundaries. Only for NET. |
| SEDIMENT_INFLOW_LOADING_FACTOR | Real | 1.0 | 0.5-2.0 | Used to specify under- or overloading at sediment inflow boundaries. |
| CALC_MORPH_DURING_RAMP | character | ON | ON OFF | Determines whether to calculate the morphology change during the ramp period |
Step-by-Step Sediment Transport Application for Shark River Inlet, NJ
TBC
Numerical Methods
Temporal Solution Scheme
This refers to the temporal discretization of the hydrodynamic, sediment and salinity transport equations. There are two options in CMS: Implicit and Explicit. The implicit scheme uses a time step on the order of 5-20 minutes and is designed for tidal flow, and mid-term morphology change. The explicit scheme uses a time step on the order of 0.5-1.0 seconds and is appropriate for cases that vary quickly in time such as flooding or barrier island breaching.
Table 2-97. CMS-Flow cards related to the temporal solution scheme.
| Input | Format | Notes |
|---|---|---|
| Hydrodynamic
time step |
[cards=HYDRO_TIMESTEP,
optional=false] [name=HydroDt, type=float, default=none] [name=HydroDtUnits, type=char, options=timeUnits, default=’s’] |
Sets the time step for the hydrodynamics. |
| Temporal
solution scheme |
[cards=SOLUTION_SCHEME,
versions=(>4.0)] [name=TimeSolSch, type=float, options=(EXPLICIT,IMPLICIT), default=IMPLICIT] |
Determines the temporal solution scheme used in CMS-Flow. |
| Implicit
weighting factor |
[cards=IMPLICIT_WEIGHTING_FACTOR,
CMS_version=(4.10.00)] [name=ImpWghtFac, type=float, options=(0.0>=ImpWghtFac<=1.0), default=0.0] |
Weighting factor in implicit temporal scheme. 0 – First order, 1-second order. For more details on the temporal solution scheme see the Temporal Discretization section. |
Note:
- • The second order implicit temporal scheme requires three time step levels. Therefore, for the first time step, the model uses the first order two-level temporal scheme. In addition, if the time step is increased or decreased during the simulation. The first order scheme is used.
Implicit Solver Options
The solvers implemented in the implicit temporal solution scheme are the SIP, ICCG, Gauss-Seidel, Gauss-Seidel with Successive-Over-Relaxation, BICGSTAB, and GMRES. Currently, the same solver is applied to flow, sediment and salinity. The default solver is the GMRES. The solver may be changed using the advanced card in the table below. The SIP and ICCG solvers are only available for non-telescoping grids. The maximum number of outer and inner loop iterations may also be changed. The outer loop is the loop over which the governing equations are solved successively, while the inner loop is the loop within the matrix solver for each governing equation.
Table 2-98. CMS-Flow cards related to the implicit solver options.
Maximum number of iterations for the pressure equation| Input | Format | Notes |
|---|---|---|
| Maximum number of iterations for the hydrodynamic outer loop | [cards=HYDRO_MAX_ITERATIONS,
dependance=(TimeSolSch==IMPLICIT)] [name=HydroMaxIter, type=int] |
Sets the maximum number of iterations for the flow (hydro) solver (outer loop). |
| Matrix Solver | [cards=MATRIX_SOLVER,
dependance=(TimeSolSch==IMPLICIT)] [name=Solver, type=float, options=(SIP,ICCG,BICGSTAB, GAUSS-SEIDEL,GAUSS-SEIDEL-SOR, BICGSTAB,GMRES), default=GMRES] |
Selects the matrix solver for flow, sediment and salinity. |
| Maximum number of iterations for the pressure equation | [cards=PRESSURE_ITERATIONS,
dependance=(TimeSolSch==IMPLICIT)] [name=PresIter, type=float, typical=(5>PresIter<30), default=none] |
Sets the number of solver iterations for the pressure equation (inner loop). |
| Maximum number of iterations for the velocity equation | [cards=VELOCITY_ITERATIONS,
dependance=(TimeSolSch==IMPLICIT)] [name=VelIter, type=float, typical=(5>VelIter<30), default=none] |
Sets the number of solver iterations for the velocity equation (inner loop). |
| Maximum number of iterations for the sediment transport equation equation | [cards=SEDIMENT_MAX_ITERATIONS,
dependance=(TimeSolSch==IMPLICIT)] [name=SedMaxIter, type=float, typical=(5>SedMaxIter<30), default=20] |
Sets the number of solver iterations for the sediment transport (outer loop) |
[cards=SALINITY_MAX_ITERATIONS,
dependance=(TimeSolSch==IMPLICIT)] [name=PresIter, type=float, typical=(5>PresIter<30), default=none] |
Sets the number of solver iterations for the pressure equation (inner loop). |
Skewness Correction
When the lines connecting cell centers do not intercept the cell-face centers, the cells are said to be skewed. When interpolating variables to the cell-face or calculating cell-face gradients a correction is needed for second order accuracy. There are several ways in which the correction can but involves some form of reconstruction of the variable on the cell face or within the neighboring cells. In CMS a linear cell reconstruction is performed within skewed cells for the correction.
Table 2-99. CMS-Flow cards related to the skewness correction.
| Input | Format | Notes |
|---|---|---|
| Second order
Skewness Correction |
[cards=SKEWNESS_CORRECTION,
dependance=(TimeSolSch==IMPLICIT)] [name=SkewCorr, type=bool, options=(ON,OFF), default=ON] |
Turns on or off the second order skewness correction which account for non-orthogonality in the telescoping grids. |
Advection Schemes
As in the case of the implicit solution scheme, the same advection scheme is applied for the flow, sediment and salinity transport equations. Future versions of the CMS will allow the user to select different advection schemes for different governing equations. There are several choices for advection schemes with the implicit model which are listed in the table below. The schemes range from first to third order. The hybrid scheme is fast but is the most diffusive. The exponential scheme is based on the 1D analytical solution to a steady-state advection-diffusion equation and produces very stable results. The HLPA is very stable and non-diffusive, but requires slightly more computational time. For most applications, the exponential scheme is recommended and is set as the default. The advection scheme may be change using the advanced card described in the table below.
Table 2-100. CMS-Flow cards related to the implicit solver options.
| Input | Format | Notes |
|---|---|---|
| Advection scheme | [cards=ADVECTION_SCHEME,
dependance=(TimeSolSch==IMPLICIT)] [name=AdvSch, type=char, options=(NONE,UPWIND,HYBRID, POWERLAW,EXPONENTIAL,HLPA, GAMMA,CUBISTA,ALVSMART,HOAB), default=EXPONENTIAL] |
Specifies the advection scheme for the implicit solver. The advection scheme is applied to the momentum, and sediment and salinity transport equations. |
Wetting and Drying
In CMS, a minimum depth is required for cells to be considered. A cell is classified as wet if the total water depth is larger than this depth. Cell faces are either classified as either open if the two cells neighboring cells are wet or otherwise closed (i.e. cell faces are not classified as wet or dry) , in order to improve stability.
Table 2-101. CMS-Flow cards related to wetting and drying.
| Input | Format | Notes |
|---|---|---|
| Wetting and drying depth | [cards=DRYING_DEPTH]
[name=hmin, type=real, default=0.05 ’m’, range=(hmin>0.0 ’m’)] [name=hminUnits, type=char, options=DistUnits), default=’m’] Sets the minimum depth for wet cells. | |
| Water ponding | [cards=WATER_PONDING,
dependance=(TimeSolSch==IMPLICIT)] [name=Solver, type=char, options=(ON,OFF), default=OFF] |
Turns On or Off water ponding. If water ponding is Off, isolated bodies of water will become dry. |
| Allow flow through one-cell wide channels | [cards=(ONE_CELL_WIDE_CHANNELS,
ONE-CELL-WIDE-CHANNELS, NARROW_CHANNELS), dependance=(TimeSolSch==IMPLICIT)] [name=PresIter, type= char, typical=(5>PresIter<30), default=none] |
Limits wetting and drying to areas with at least 3 cells wide. When turned off, the model stability is improved. |
Parallelization
The CMS-Flow is parallelized for PC’s with multi-core processors using OpenMP. The parallelization works by splitting the computational work into “threads” among several cores. Some cores are hyper-threaded, meaning a single core may support two threads. The number of threads is specified in the CMS-Flow Model Control Window. The number of threads must be equal or greater to 1 and cannot be larger than the number of threads available on the machine. If a number is specified which is larger than the maximum number available on the machine, then the code will default to the maximum number available.
Table 2-102. CMS-Flow card used to specify the number of threads.
| Input | Format | Notes |
|---|---|---|
| [cards=NUM_THREADS]
[name=NumThr, type=int, range=(NumThr>=1), default=1] |
Determines the number of threads used for parallel processing. |
Note:
- • The OpenMP parallelization requires that compatibility OpenMP run-time library (libiomp5md.dll) be in search paths.
- • When running multiple simulations at once, the user should keep track of how many threads are being used by each simulation and make sure that the maximum number of threads on the computer is not exceeded. Exceeding the maximum number of threads on the computer will slow down the simulations and also make the computer slow.
- • It is always recommended to at least leave one thread unused by model simulations so that the computer is responsive while the simulations are running.
Hot Start
The term “hot start” refers to starting a simulation with an initial condition other zero (cold start). Hot starts are used for specifying initial conditions other than the default zero value or restarting simulations at intermediate times. The hot start controls are set in the CMS-Flow Model Control window under the Flow tab in SMS 11.0 (see Figure 2-94) and in the General tab in SMS 11.1 and later (see Figure 2 95).
Figure 2-94. Location of Hot Start input and output options within the Flow tab of the CMS-Flow Model Control window in SMS 11.0.
Figure 2-95. Location of Hot Start input and output options within the Flow tab of the CMS-Flow Model Control window in SMS 11.0.
The hot start options are the input Initial Conditions file, the output time and recurring interval for the Hot Start file. A description of these controls and options are provided in the subsequent sections.
Hot Start Output File
The CMS Hot Start feature lets the user restart simulations that have been ended or stopped due to for example electric outages, hardware malfunctions, or model crashes. In the case of a model crash the user, may restart the model using larger solver iterations and/or time steps to stabilize the simulation. The user has the option to specify a hot start output time or an interval for outputting a recurring hot start file. Every time the hot start file is written, it overwrites the previous information. The CMS Hot Start file saves information on the water elevation (pressure), and current velocities. If the sediment transport is active, the water depth and sediment concentrations are also saved for each size class. The CMS Hot Start File is a binary XMDF file, has the name Hot_Start.h5 and is saved in the directory of the CMS-Flow files. Figure 2 96 shows the structure of the hot start file. After saving a CMS Hot Start File, it is a good idea to rename the file with a different name before using it as an initial conditions file. This way, the file will not be overwritten in future simulations.
Figure 2-96. HDFView showing the structure of the CMS Hot Start File.
Table 2-103. CMS-Flow cards used to specify the hot start output file.
| Input | Format | Notes |
|---|---|---|
| Hot start output file | [cards=HOT_START_OUTPUT_FILE, versions=(>3.75.00)] [name=HotStartFile, type=char, default=”Hot_Start.h5”, optional=true] | Specifies the name of the hot start output file |
| [cards=HOT_START_TIME] [name=HotStartTime, ype=real, default=48.0][name= HotStartTimeUnits, type=char, optional=true, options=TimeUnits), default=’hrs’] | Specifies a single hot start time, typically at the end of a simulation | |
[cards=(AUTO_HOT_START_INTERVAL,
HOT_START_INTERVAL)] [name=HotStartInter, type=real, default=12.0] [name= HotStartInterUnits, type=char, optional=true, options=TimeUnits), default=’hrs’] || |
- |
Example 2-91. Hot Start Output Options – Simple Case.
!Hot Start
AUTO_HOT_START_INTERVAL 24.0 hrs !default units is hrs
Example 2-92. Hot Start Output Options – Advanced Case
!Hot_Start HOT_START_TIME 7.0 days !Units optional, default is hrs HOT_START_INTERVAL 2.0 days !can also use AUTO_HOT_START_INTERVAL HOT_START_OUTPUT_FILE "myHotStartFile.h5" !default is “Hot_Start.h5”
Table 2-104. Path and name for hot start file variables.
| Variable | Path and Name | Units | Notes | |
|---|---|---|---|---|
| Water pressure | m2/s2 | Equal to the water level times gravity. | ||
| Current velocity | Datasets\Current_Velocity | m/s | Saved as a vector dataset | |
| Total water depth | Datasets\Depth | m | ||
| Single-size
sediment concentrations |
Datasets\Concentration | kg/m3 | For single-size sediment transport. | Only for multiple-sized sediment transport. |
Multiple-sized
sediment concentrations |
Datasets\Concentration_k | kg/m3 | Sediment concentration for the kth size class.
Only for multiple-sized sediment transport. | |
| Bed layer
thickness |
Datasets\Thickness_(l) | m | Thickness for bed layer l.
Only for multiple-sized sediment transport. | |
| Bed composition | Datasets\Fraction_k(l) | |||
| Fractional bed composition for the kth size class and bed layer l.
Between 0 and 1. Sum of all fractions in each layer and cell must equal to 1.0. Only for multiple-sized sediment transport. | ||||
| Salinity
concentrations |
Datasets\Salinity | ppt |
Initial Conditions Input File
There are several situations where it is convenient to specify a user defined initial condition (hot start) file. For example, if the user forgets to setup the model output a hot start file or when running idealized cases with known initial conditions. A hot start file can easily be created and exported by the user from the SMS interface. The model requires at water levels, current velocities, concentrations, and water depths. Any datasets that are missing from the initial file are assigned a default value which depends on the dataset. If the water level or current velocities are not specified, they are set to zero. If the depth is not specified, then it is set to the input grid depth. If the sediment concentrations are not specified, then they are set to the equilibrium concentrations. It is important to note that the names and paths of the initial condition datasets are important.
Table 2-105. CMS-Flow cards used to specify the hot start input file.
| Input | Format | Notes |
|---|---|---|
| Input initial conditions file | [cards=INITIAL_CONDITION_FILE,
versions=(>3.75.00)] [name=InitCondFile, type=char, default=”Hot_Start.h5”, optional=true] |
Specifies the name of the input initial conditions file. |
| Initial condition time | [cards=INITIAL_CONDITION_TIME]
[name= InitCondTime, type=real, default=none] [name= InitCondTimeUnits, type=char, optional=true, options=TimeUnits), default=’hrs’] |
Specifies the initial condition starting time relative to the current simulating starting time |
| Initial condition date and time | [cards=INITIAL_CONDITION_DATE_TIME]
[name= InitCondDateTime, type=char, default=none, example=”2013/11/25 23:59:00”] |
Specifies the calendar date and time |
The initial conditions file contains grid datasets with initial values for water levels, current velocities, salinity and sediment concentrations, bed composition, bed layer thicknesses, and water depth. All of the input da-tasets are optional. If the dataset does not exist than it is set to the default value.
Table 2-106. Path and name for initial condition file variables.
Water surface elevation| Variable | Path and Name | Units | Notes |
|---|---|---|---|
| Datasets\Water elevation | m | Same as water level.
Either the water level or water pressure need to specified and not both. | |
| Water pressure | Datasets\Water_Pressure | m2/s2 | Equal to the water level times gravity.
Either the water level or water pressure need to specified and not both. |
| Current velocity | Datasets\Current_Velocity | m/s | Saved as a vector dataset |
| Total water depth | Datasets\Depth | m | |
| Single-size
sediment concentrations |
Datasets\Concentration | kg/m3 | For single-size sediment transport.
Only for multiple-sized sediment transport. |
Multiple-sized
sediment concentrations |
Datasets\Concentration_k | kg/m3 | Sediment concentration for the kth size class.
Only for multiple-sized sediment transport. |
| Bed layer
thickness |
Datasets\Thickness_(l) | m | Thickness for bed layer l.
Only for multiple-sized sediment transport. |
| Bed composition | Datasets\Fraction_k(l) | ||
| Fractional bed composition for the kth size class and bed layer l.
Between 0 and 1. Sum of all fractions in each layer and cell must equal to 1.0. Only for multiple-sized sediment transport. | |||
| Salinity
concentrations |
Datasets\Salinity | ppt |
Example 2-93. Initial Condition Options –Hot Start File.
!Hot Start INITIAL_CONDITION_FILE "myHotStartFile.h5" !default is “Hot_Start.h5”
Example 2-94. Initial Condition Options – User-specified datasets.
!Hot_Start INITIAL_CONDITION_FILE "myInitCondFile.h5" !User-specified datasets !Note: The time of the initial condition is read from the input file
Example 2-95.Initial Condition Options – User-specified datasets.
!Hot_Start INITIAL_CONDITION_FILE "Init_Cond.h5" !User-specified datasets INITIAL_CONDITION_TIME 24.0 days !default units is hrs !Note: The time of the initial condition in the XMDF file is ignored and !set to the above value
Note:
- • The time of the initial conditions file is with respect to a reference time of the current simulation. The default units is hours but may be changed to any units.
- • The initial condition and hot start files only contain a single time step. Therefore, when selecting the second-order backward difference implicit scheme which uses two previous time steps, the first time step is calculated using the first-order backward difference scheme. In the case of the explicit temporal scheme, only the first-order forward difference scheme is available.
Creating an Initial Conditions File
The steps for creating a user defined hot start or initial condition file from a CMS-Flow solution file are outlined below.
- 1. Import CMS-Flow grid and solution file.
- 2. Sample a time step of the solution datasets for use in the initial condi-tion
- 2.1. Click on Data | Data Calculator
- 2.1.1. Under the Tools section, select Sample time steps.
- 2.1.2. Under the Datasets section, click on the Water Elevation
- 2.1. Click on Data | Data Calculator
- 3. Export the initial condition datasets to an XMDF file
Figure 2-97. Dataset Toolbox showing a time step sample of the water elevation and current velocity datasets for use in a hot start (initial condition) file.
Figure 2-98. Dataset Toolbox showing a time step sample of the water elevation and current velocity datasets for use in a hot start (initial condition) file.
Table 2-107. CMS-Flow card for specifying the initial condition file.
| Card | Arguments | Default | Range | Description |
|---|---|---|---|---|
| INITIAL_STARTUP_FILE | character | none | none | Name of initial condition file. The path must be specified if it is different from the cmcards file. |
Output Options
Global Output
Global output refers to the variables that are output on every active cell on the grid. The global output options are specified in Output tab of the CMS-Flow Model Control window. More information on the global output variables, groups and CMS-Flow cards is provided in the sections below.
Figure 2-99. Output tab in SMS 11.0
Output Datasets
Global output datasets are divided into groups and each group is assigned an output times, and file. A description of the various output datasets and the associated groups is provided in the table below.
Table 2-108. CMS-Flow cards related to the output datasets.
Output Dataset Group Description Units Current_Velocity Velocity Depth-averaged and cell-centered current velocity vector dataset and with respect to local grid coordinates m/s Current_Magnitude Velocity Depth-averaged and cell-centered current velocity magnitude dataset m/s Water_Elevation Water surface elevation Cell-centered water surface elevation m Eddy_Viscosity Eddy viscosity Cell-centered horizontal eddy viscosity m^2/s Concentration Transport Depth-averaged and cell-centered sediment concentration kg/m^3 Capacity Transport Depth-averaged and cell-centered sediment concentration capacity kg/m^3 Total_Sediment_Transport Transport Depth-averaged and cell-centered total-load sediment transport kg/m/s Salinity Transport Depth-averaged and cell-centered sediment concentration capacity kg/m^3 Depth Morphology Cell-centered still water depth m Morphology_Change Morphology Cell-centered morphology (bed) change. Positive is accretion and negative is erosion m Wave_Height Waves Cell-centered significant wave height m Wave_Height_Vec Waves Cell-centered significant wave height vector m Wave_Period Waves Cell-centered peak wave period s
Output Time Series and Lists
The times at which each group is output is determined by the selecting one of four user defined output time series or lists. In SMS versions 10.1 and earlier, the output time series were used. However, because the output time series can become very large for long-term simulations, the time series have been replaced by lists in which the output times are specifying a list of starting, ending and increments. This option is more compact and also makes it easier to manually change the output options in the cmcards file.
Table 2-109. CMS-Flow cards used for specifying the time series and lists.