User Guide 008

Example 2-44. Constant WSE BC specification using a block structure.

---

BOUNDARY_BEGIN

  CELLSTRING   "Boundaries.bid"  1 ![file name] [cellstring ID]
  WSE_BEGIN
     VALUE          0.0 m   !constant water level, units optional
     GRADIENTS      1.E-5 0.0 !Optional, global coordinate system
     ADJUSTMENT     ON      !Optional, turns on the forcing corrections
  WSE_END

BOUNDARY_END

---

Single Water Level Time Series

A single water level time-series is one of the most commonly boundary condition types used for coastal modeling.

Table 2-55. CMS-Flow cards related to the single water level time series boundary condition.

Input	Format	Notes
WSE time series file	[cards=(CURVE,WSE_CURVE), parent=WSEblock] [name=WSEfile, type=char, default=none] [name=WSEpath, type=char, default=none]	Specifies the WSE Data File Name (including path if different from Card File) and Dataset Path (for XMDF files only). Optional. Assumed to be the same as the cellstring if not specified.
WSE gradients	[card=(WSE_GRADIENTS,GRADIENTS), parent=WSEblock] [name=WSEgrad, type=float, optional=true, default=’0.0,0.0’)]	Specifies WSE gradients which are superimposed on the boundary. Used to approximate regional circulation.
WSE Temporal Interpolation Order	[card=TIME_INTERP_ORDER] [name=WSEnti, type=int, range=(1<WSEnti<3),default=2]	Order of Lagrangian polynomial used to interpolate time-series.
WSE Temporal Smoothing Iterations	[card=TIME_SMOOTH_ITER] [name=WSEnsi, type=int, range=(0<WSEnsi<10), default=2]	Temporal smoothing iterations. Smoothing is done by a central moving average.
WSE Temporal Smoothing Window Width	[card=TIME_SMOOTH_WIDTH] [name=WSEnsw, type=int, range=(0<WSEnsw<10), default=0]	Temporal smoothing window width. Should be an odd number Smoothing is done by a central moving average.

Example 2-45. Single WSE time-series BC specification using a block structure.

---

BOUNDARY_BEGIN

  CELLSTRING  "Flow_mp.h5" "PROPERTIES/Model Params/Boundary"
  WSE_BEGIN
     CURVE     "Flow_mp.h5" "PROPERTIES/Model Params/Boundary"
  WSE_END

BOUNDARY_END

---

Example 2-46. Single WSE time-series BC specification using a block structure and advanced options.

---

BOUNDARY_BEGIN

  NAME         "My offshore boundary"
  CELLSTRING   "Boundaries.bid"  1 
  WSE_BEGIN
     CURVE          "WSE.xys"
     OFFSET         0.1 m   !Optional
     GRADIENTS      1.E-5 0.0 !Optional, global coordinate system
     TIME_INTERP_ORDER  2 !Temporal interpolation
     TIME_SMOOTH_ITER   1 !Temporal smoothing iterations
     TIME_SMOOTH_WIDTH  3 !Temporal smoothing window width
  WSE_END

BOUNDARY_END

---

Example 2-47. Constant WSE BC specification using a block structure.

---

BOUNDARY_BEGIN

  CELLSTRING    "Flow_mp.h5" "PROPERTIES/Model Params/Boundary"
  WSE_BEGIN
     CURVE      "WSE.tsd"
     OFFSET     0.1 m     !Optional, positive is upwards
     GRADIENTS  1.E-5 0.0 !Optional, global coord system, nondimensional
     ADJUSTMENT ON        !Optional, turns on the forcing corrections
  WSE_END

BOUNDARY_END

---

Multiple Water Level Time Series Boundary

In this boundary condition type, an individual water level time-series is specified for each boundary cell. The SMS 11.1 interface allows the user to extract these time-series from a larger CMS or ADCIRC simulation or to synthesize them from interpolated tidal constituents from a tidal database. Once these time-series are generated, the user can then go into the CMS-Flow Model Control File (*.cmcards file), and use the advanced block structure format to be able to specify additional input options. Specifically, the block structure allows the user to choose a spatial interpolation order, and spatial smoothing along the cellstring. The temporal interpolation is calculated using a piece-wise Lagrangian polynomial of order 1 to 3. The first order polynomial reduces to linear interpolation. The higher order interpolation methods improve the smoothness of the interpolation but can lead to oscillations if the parent simulation is noisy or the solution file output times are very large. This is why the interpolation order is limited to 3. Temporal and spatial smoothing is applied (optional) as central moving averages with a user-specified window width and number of iterations. The spatial smoothing is applied first and then the temporal smoothing to the input boundary water levels. The smoothed water levels are then interpolated to the model time step using the piece-wise Lagrangian interpolation. The boundary water levels may be user-specified in a Time Series Data (TSD) file (*.tsd) or extracted in SMS from a larger simulation or tidal constituent database. Each option is covered in the sections below with examples. The option is also available to output the extracted water levels to a TSD file. The cards used to specify the multiple water level time-series boundary are described in the table below.

Table 2-56. CMS-Flow cards related to the single water level time series boundary condition.

Input	Format	Notes
WSE Input Time series file	[card=(WSE_DATA,DATASET,DATA) parent=WSEblock] [name=WSEfile, type=char, default=none] [name=WSEpath, type=char, parent=WSEblock, default=none]	Specifies the WSE Data File Name (including path if different from Card File) and Dataset Path (for XMDF files only). Optional. Assumed to be the same as the cellstring if not specified. The file must contain a time-series for each boundary cell.
WSE Temporal Interpolation Order	[card=TIME_INTERP_ORDER, parent=WSEblock] [name=WSEnti, type=int, range=(1<WSEnti<3), default=2]	Order of Lagrangian polynomial used to interpolate time-series.
WSE Temporal Smoothing Iterations	[card=TIME_SMOOTH_ITER, parent=WSEblock] [name=WSEnsi, type=int, range=(0<WSEnsi<10), default=2]	Temporal smoothing iterations. Smoothing is done by a central moving average.
WSE Temporal Smoothing Window Width	[card=TIME_SMOOTH_WIDTH, parent=WSEblock] [name=WSEnsw, type=int, range=(0<WSEnsw<10), default=0]	Temporal smoothing window width. Should be an odd number Smoothing is done by a central moving average.
WSE Spatial Smoothing Iterations	[card=SPACE_SMOOTH_ITER, parent=WSEblock] [name=WSEnsi, type=int, range=(0<WSEnsi<10), default=2]	Spatial smoothing iterations. Smoothing is done by a central moving average.
WSE Spatial Smoothing Window Width	[card=SPACE_SMOOTH_WIDTH, parent=WSEblock] [name=WSEnsw, type=int, range=(0<WSEnsw<10), default=0]	Spatial smoothing window width. Should be an odd number Smoothing is done by a central moving average.

Example: SMS-generated Multiple Water Levels

In the example below the SMS interface is used to create a multiple water level time-series boundary and the CMS project files are saved. The CMS-Flow card file is then modified by commenting out the SMS generated card MULTI_HDRIVER_CELLSTRING , and placing the card information in the user-specified boundary block. It is noted that both the cellstring information and the extracted water levels are contained within the same path of the CMS-Flow Model Parameters File (*_mp.h5). This is the reason why both the CELLSTRING and DATASET cards contain the same file name and path. The temporal interpolation order is set to 2, and two iterations of simple moving average filter are applied along the cellstring with a window width of 3.

Example 2-48. Multiple water levels time series boundary specification using a block structure.

---

1. MULTI_HDRIVER_CELLSTRING "Flow_mp.h5" "PROPERTIES/Model Params/Boundary"

BOUNDARY_BEGIN

  NAME         "Extracted Offshore BC"
  CELLSTRING   "Flow_mp.h5" "PROPERTIES/Model Params/Boundary"
  WSE_BEGIN
     DATASET   "Flow_mp.h5" "PROPERTIES/Model Params/Boundary" 
     OFFSET    0.1 m    !Optional, default = 0.0 m
     TIME_INTERP_ORDER   2 !Optional, Temporal interpolation
     TIME_SMOOTH_ITER    1 !Optional, Temporal smoothing iterations
     TIME_SMOOTH_WIDTH   3 !Optional, Temporal smoothing window width
     SPACE_SMOOTH_ITER   2 !Optional, Spatial smoothing iterations
     SPACE_SMOOTH_WIDTH  3 !Optional, Spatial smoothing window width
  WSE_END 

BOUNDARY_END

---

Example: User-specified Multiple Water Levels

In the example below, a multiple water level boundary condition is speci-fied using all ASCII input files. The cellstring is specified using a BID file, and the boundary water levels using a TSD file.

Example 2-49. Multiple water levels time series boundary specification using a block structure.

---

BOUNDARY_BEGIN

  NAME         "All ASCII Offshore BC"
  CELLSTRING   "Boundaries.bid"  1 ![file name] [cellstring ID]
  WSE_BEGIN
     DATASET   "Offshore_wse.tsd" !Must be TSD file
  WSE_END 

BOUNDARY_END

---

The TSD file containing the boundary water levels should contain a time series for each boundary cell and covering the whole simulation time period. The format of the TSD file is illustrated in the example below.

Example 2-50. Excerpt of the Offshore_wse.tsd file used to specify multiple water level boundary condition in the above example.

---

TIME_SERIES "Boundary WSE" "Unassigned" 7 100 "01/01/2011 00:00:00"

     0.000     0.0000    0.0000    0.0000    0.0000    0.0000    0.0000 
  1800.000     0.0020    0.0021    0.0022    0.0023    0.0024    0.0025 
  3600.000     0.0073    0.0074    0.0075    0.0076    0.0077    0.0078 
  5400.000     0.0842    0.0843    0.0844    0.0845    0.0846    0.0847 
  7200.000     0.1731    0.1732    0.1733    0.1734    0.1735    0.1736 
  9000.000     0.2546    0.2547    0.2548    0.2549    0.2550    0.2551 
  ...

---

Notes:

• If the number of time steps is set to zero (forth entry in second line of TSD file), CMS will automatically determine the number from the input file. Therefore, the parameter may be considered optional when using as an input for CMS.

Extracted Water Levels from a Parent Simulation

CMS supports automated one-way nesting within parent CMS and ADCIRC models. Additional support for other models is currently in de-velopment. When using this feature, the CMS automatically extracts the boundary condition information from the parent model solution. The user only has to specify the boundary cellstring and the location and name of the parent model simulation files. The user may force the CMS with either water levels or water levels and velocities extracted from the parent simulation.

Table 2-57. CMS-Flow cards related to the single tidal current velocity boundary condition.

Input	Format	Notes
WSE Temporal Interpolation Order	[card=TIME_INTERP_ORDER, parent=WSEblock] [name=WSEnti, type=int, range=(1<WSEnti<3), default=2]	Order of Lagrangian polynomial used to interpolate time-series.
WSE Temporal Smoothing Iterations	[card=TIME_SMOOTH_ITER, parent=WSEblock] [name=WSEnsi, type=int, range=(0<WSEnsi<10), default=2]	Temporal smoothing iterations. Smoothing is done by a simple moving average.
WSE Temporal Smoothing Window Width	[card=TIME_SMOOTH_WIDTH, parent=WSEblock] [name=WSEnsw, type=int, range=(0<WSEnsw<10), default=0]	Temporal smoothing window width. Should be an odd number Smoothing is done by a simple moving average.
WSE Spatial Smoothing Iterations	[card=SPACE_SMOOTH_ITER, parent=WSEblock] [name=WSEnsi, type=int, range=(0<WSEnsi<10), default=2]	Spatial smoothing iterations. Smoothing is done by a simple moving average.
WSE Spatial Smoothing Window Width	[card=SPACE_SMOOTH_WIDTH, parent=WSEblock] [name=WSEnsw, type=int, range=(0<WSEnsw<10), default=0]	Spatial smoothing window width. Should be an odd number Smoothing is done by a simple moving average.
WSE Output File	[cards=(OUTPUT_FILE, WSE_OUTPUT_FILE), parent=WSEblock] [name=WSEfile, type=char, default=none]	Specifies the WSE output file. Must be a TSD file. Must include relative or absolute path if different from the CMS-Flow project files.

Note:

•: Simulation results from other models may be used to force CMS by converting them into the ADCIRC format.

Table 2-58. CMS-Flow cards related to the wse boundary condition block.

Input	Format	Notes
Begins a WSE Parent Block	[begin=PARENT_BEGIN, name=Parblock]	Begins the block structure for specifying the parent simulation parameters
Ends a WSE Parent Block	[end=PARENT_END, name=Parblock]	Ends the block structure for specifying the parent simulation parameters
Parent Control File	[card=CONTROL_FILE, parent=Parblock] [name=ParCTLfile, type=char, default=none]	Name of parent simulation control file. Optional for parent ADCIRC simulations.
Parent Grid File	[card=GRID_FILE, parent=Parblock] [name=ParCTLfile, type=char, default=none]	Name of parent simulation grid file. Optional for parent CMS simulations.
Simulation Starting Date and Time	[card=STARTING_DATE_TIME] [name=StartDate0, type=char, default=none, example=”2004-12-24”] [name=StartTime0, type=char, default=none, example=”23:34:12”] [name=StartTimeZone, type=char, default=none, example=’UTC’ , otpional=true,]	Specifies the simulation starting calendar date and time. Double quotes are optional

Example: Nesting a CMS simulation within an ADCIRC simulation

In the example below, a child CMS simulation is nested within a larger ADCIRC simulation and forced with water surface elevations (WSE). The boundary information begins with user-specified name for the boundary and the cellstring information for the CMS (child) grid. The WSE block contains a WSE offset used in this case to convert between vertical coordinate systems. In addition a small amount of spatial smoothing is applied as a 3 element moving mean along the cellstring. The parent simulation block specifies all of the options of the ADCIRC simulation including the names of the grid, WSE solution files, starting date and time, and horizontal projection. The parent simulation files should include the absolute or relative path if not in the same directory as the CMS (child) simulation. The ADCIRC grid may be specified with the *.14 or *.grd extensions. The default name of the ADCIRC WSE solution file is fort.63 but the fort63.h5 name may also be used. Since the ADCIRC simulation files do not contain information on the starting date or horizontal projection, this information needs to be provided in the model input. Typically, the ADCIRC simulation will be run in a geographic coordinate system.

The simulation domain for both the ADCIRC and nested CMS computa-tional grids is presented in the figure below. In a simulation that the one below, the larger ADCIRC simulation would be forced with tidal constitu-ents while the nested grid is forced with extracted water levels from the ADCIRC simulation.

Figure 2-62. Nested CMS-Flow grid within a larger ADCIRC mesh. Note: The ADCIRC mesh was run in geographic coordinates, but was converted to the same horizontal projection as the CMS grid for display.

Note:

• ADCIRC is typically run for larger regional grids in a geographic coordinate system. If the horizontal projection is not specified then it is assumed to be NAD83, Geographic with units of degrees.

• When nesting a CMS simulation within an ADCIRC simulation, it is important that both simulations use the same horizontal datums. Otherwise, the model will not be able to internally convert between the datums.

• It is important to keep the model forcing for both the parent and child grids consistent. For example if the child grid is forced with winds, then the parent simulation should also be forced with the same winds.

• Because of differences in resolution, the grid coverages (extents) and bathymetries of the parent and child simulations will never be identical but they should be similar. If they are very different it will lead to boundary problems because the parent model solution will not be consistent with the child model solution.

Tips:

• It is recommended to display both the parent and child computa-tional grids in SMS to check that the horizontal projections are correct and that the grid coverages and bathymetries are similar.

The input cards used to nest CMS within an ADIRC simulation are pre-sented in the example below.

Example 2-51. Extracting water levels from parent ADCIRC simulation.

---

BOUNDARY_BEGIN

  NAME          "Nested Boundary"
  CELLSTRING    "Flow_mp.h5" "PROPERTIES/Model Params/Boundary"
  WSE_BEGIN !All settings for wse at the boundary set here
     OFFSET              0.1 m  !optional, positive is upwards
     TIME_INTERP_ORDER   2     !optional, temporal interpolation
     SPACE_SMOOTH_ITER   1     !optional, spatial smoothing iterations
     SPACE_SMOOTH_WIDTH  3     !optional, spatial smoothing window width
  WSE_END
  PARENT_BEGIN !All settings for parent simulation set here
     GRID_FILE           "..\ADCIRC_Regional\fort.14"
     WSE_SOL_FILE        "..\ADCIRC_Regional\fort.63" !Optional
     STARTING_DATE_TIME  2012-12-01 00:00:00 UTC
     HORIZ_PROJ_BEGIN !Optional, assumed if not specified
        DATUM        NAD83       !NAD27 | NAD83 | LOCAL
        SYSTEM       GEOGRAPHIC  !UTM | STATE_PLANE | GEOGRAPHIC | LOCAL
        UNITS        DEGREES      !METERS | FEET | DEGREES | etc.
     HORIZ_PROJ_END
  PARENT_END

BOUNDARY_END

---

An example comparison of the ADCIRC (parent) and CMS (child) water level solutions is presented in the figure below. The water levels for both simulations are quite close. The differences are mainly due differences in the computational grids.

Figure 2-63. Example snapshots of water levels and current velocities for the ADCIRC (top) and CMS-Flow (bottom) simulations for the same time.

Example: Nesting a CMS simulation within a CMS simulation

If a parent CMS simulation is used, all of the necessary information in-cluding horizontal projection, grid file name, and water level solution file are extracted from the CMS Card File.

Example 2-52. Extracting water levels from parent CMS simulation.

---

BOUNDARY_BEGIN

  NAME             "Nested CMS Boundary"
  CELLSTRING       "Flow_mp.h5" "PROPERTIES/Model Params/Boundary"
  WSE_BEGIN
     WSE_OFFSET         0.1 m  !optional, positive is upwards
     TIME_INTERP_ORDER   2     !optional, temporal interpolation
     SPACE_SMOOTH_ITER   1     !optional, spatial smoothing iterations
     SPACE_SMOOTH_WIDTH  3     !optional, spatial smoothing window width
  WSE_END
  PARENT_BEGIN
     CONTROL_FILE     "..\CMS_Regional\Flow_Reg.cmcards"
     !All other settings are obtained from the control file
  PARENT_END

NESTED_WSE_BOUNDARY_END

---

Because the CMS-Flow Control (Card) File contains all of the information regarding the horizontal projection, simulation time period, and output files, nothing else needs to be specified except the parent CMS-Flow simulation Card File.

Figure 2-64. Example snapshots of water levels and current velocities for the ADCIRC (top) and CMS-Flow (bottom) simulations for the same time.

Tidal Boundary

In the case of a tidal boundary condition, the external water level is calculated as

${\bar {\eta }}_{E}(t)=\Sigma f_{i}A_{i}cos(\omega _{i}t+V_{i}^{0}+{\hat {u}}_{i}-\kappa _{i})$

(2-18)

where

i = subscript indicating a tidal constituent

A_i= mean amplitude [m]

f_i= node (nodal) factor [-]

$\omega _{i}$ = frequency [deg/hr]

t = elapsed time from midnight of the starting year [hrs]

$V_{i}^{0}+{\hat {u}}_{i}$ = equilibrium phase [deg]

$\kappa _{i}$ = phase lag or epoch [deg]

The external water level is applied equally at all boundary cells unless an inflow

The tidal constituent information is specified using a Tidal Constituent Block and is described in the table below.

Table 2-59. CMS-Flow Cards related to the Tidal Boundary specification.

Input	Format	Notes
Begins a Tidal Constituents Boundary Block	[begin=TIDAL_CONSTITUENTS_BEGIN, name=TCblock]	Begins the block structure for a flux boundary condition
Tidal constituent card time series file	[card=TIDAL_CONSTITUENT_(cname), parent=TCblock] [name=WSEfile, type=char, default=none] [name=WSEpath, type=char, parent=WSEblock, default=none]	Specifies the WSE Data File Name (including path if different from Card File) and Dataset Path (for XMDF files only). Optional. Assumed to be the same as the cellstring if not specified. The file must contain a time-series for each boundary cell.
Ends Tidal Constituents Boundary Block	[end=TIDAL_CONSTITUENTS_END, name=TCblock]	Ends the block structure for a flux boundary condition

The first example for a tidal boundary condition applies two tidal constituents. The constituents are specified by their standard names as listed in Table 2 43, the amplitude in meters, and the phase in degrees. In the example below, the water level block in not included. Since a tidal forcing boundary condition is applied, it implies a water level boundary condition, and all of the default settings are applied to the water level boundary condition.

Example 2-53. Tidal boundary condition specification using the block structure.

---

BOUNDARY_BEGIN

  CELLSTRING       "Flow_mp.h5" "PROPERTIES/Model Params/Boundary"
  TIDAL_BEGIN
     CONSTITUENT    M2 0.75 211.0  !Name, Amplitude[m], Phase[deg]
     CONSTITUENT    S2 0.18 231.0  !Name, Amplitude[m], Phase[deg]
  TIDAL_END

BOUNDARY_END

---

In second example below, more advanced options are specified. The name is given to the boundary. A water level offset is specified of 0.1 m width respect to the still water level (SWL). The offset is useful for converting from the local vertical datum to the SWL. The direction of the forcing is also specified using the DIRECTION card and produces a phase lag along the tidal boundary condition so that the tidal wave propagates in the direction specified.

Example 2-54. Tidal boundary condition specification using the block structure

---

BOUNDARY_BEGIN

  NAME             "Offshore tidal boundary"
  CELLSTRING       "Flow_mp.h5" "PROPERTIES/Model Params/Boundary"
  WSE_BEGIN
     OFFSET         0.1 m     !Optional, default 0.0
  WSE_END
  TIDAL_BEGIN
     DIRECTION      245.33 deg  !Optional, default is normal to bnd
     CONSTITUENT    M2 0.75 211.0  !Name Amplitude Phase
     CONSTITUENT    S2 0.18 231.0  !Name Amplitude Phase
     CONSTITUENT    K1 0.15 185.0  !Name Amplitude Phase
     CONSTITUENT    O1 0.24 191.0  !Name Amplitude Phase
  TIDAL_END

BOUNDARY_END

---

The figure below shows an example of a tidal boundary specified for Shinnecock Inlet NY, with the direction specified parallel to the shoreline for illustration purposes.

Figure 2-65. Example of a tidal boundary condition specified with an incident tidal wave direction parallel to the shore contours (not realistic).

Notes:

• The water level block may be omitted, since it is understood that a tidal forcing boundary condition applies a water level boundary condition.

Harmonic Boundary

The external water level at a harmonic boundary is calculated as

${\bar {\eta }}_{E}(t)=\Sigma A_{i}cos(\omega _{i}t-\kappa _{i})$

(2-19)

where

i = subscript indicating a harmonic constituent

A_i = mean amplitude [m]

$\omega _{i}$ = frequency [deg/hr]

t = elapsed time from the start of the simulation [hrs]

$\kappa _{i}$ = phase lag or epoch [deg]

The major difference between a tidal and a harmonic boundary condition is that the tidal boundary condition applies corrections to both the ampli-tudes and phases for each constituent which are a function of time while the harmonic boundary does not apply any corrections. Another difference is that in the case of the harmonic boundary, the speed (i.e. frequency) for each constituent must be specified rather than specifying the name of the constituent.

In the first harmonic boundary condition example, only two constituents are specified.

Example 2-55. Harmonic boundary condition specification for CMS V4.1 and later.

---

BOUNDARY_BEGIN

  CELLSTRING       "Flow_mp.h5" "PROPERTIES/Model Params/Boundary"
  HARMONIC_BEGIN
     !Constituent   Speed[deg/hr], Amplitude[m], Phase[deg]
     CONSTITUENT    28.9841042 0.75 211.0 !M2
     CONSTITUENT    13.9430356 0.24 191.0 !01
  HARMONIC_END

BOUNDARY_END

---

Example 2-56. Harmonic boundary condition specification for CMS V4.1 and later.

---

BOUNDARY_BEGIN

  NAME             "Offshore harmonic boundary"
  CELLSTRING       "Flow_mp.h5" "PROPERTIES/Model Params/Boundary"
  WSE_BEGIN
     OFFSET         0.1 m     !Optional, default 0.0
  WSE_END
  HARMONIC_BEGIN
     DIRECTION      245.33 deg  !Optional, default is normal to bnd
     !Constituent   Speed[deg/hr], Amplitude[m], Phase[deg]
     CONSTITUENT    28.9841042 0.75 211.0 !M2
     CONSTITUENT    30.0000000 0.18 231.0 !S2
     CONSTITUENT    15.0410686 0.15 185.0 !K1
     CONSTITUENT    13.9430356 0.24 191.0 !01
  HARMONIC_END

BOUNDARY_END

---

Notes:

• The water level block may be omitted, since it is understood that a harmonic boundary condition applies a water level boundary condition.