User Guide 002

2 CMS-Flow Model Setup

Overview of Input and Output The CMS-Flow (and also for most morphodynamic models) input and output can be classified as: 1. Input a. Control file (model parameters, options, pointers to other files). b. Geometry (grid). c. Initial condition (bathymetry, bed composition, etc.). d. Boundary conditions 2. Output a. Transient solution i. Global (for the whole domain) ii. Point (at a single point or cell) b. Statistical parameters c. Hot start (may include internal variables) d. Diagnostic Files A detailed description of the CMS input and output files is provided below.

Input Files

There are at least three required files to run CMS-Flow: (1) the Card File (*.cmcards), (2) the XMDF Grid File (*_grid.h5), (3) and the XMDF Model Parameters File. If a telescoping grid is used then an additional ASCII Telescoping Grid File is required. For a description of types of Cartesian grids available in CMS-Flow see section Cartesian Grids. If any input datasets such as the Manning’s coefficient or bed composition are specified in separate XMDF files then the file name and path must be specified in the Card File. Using separate input files for user-defined datasets makes it easier to make project alternatives or conduct sensitivity studies. The user-defined datasets can be easily created and exported from SMS. The procedure is described in detail in subsequent sections. A brief description of the CMS input files is provided in the table below.

Insert table 2-1 here

CMS-Flow Card/Control File

In CMS-Flow, the Control File is an ASCII text file referred to also as the Card File because it contains a list of cards used to specify model input such as parameters, coefficients, options, etc. A card is simply a unique character string which the model uses to identify a specific model input. The Card File is the main input file which sets input parameters and points to other files. In general most of the “light” input data is specified in the Card File. Light data refers to input parameters which is relatively small in size and can easily be specified by the user in a few lines such as global parameters. Any input that is relatively large, such as time series, and spatially varying datasets are referred to as “heavy” data. Heavy data is stored in separate files such as the Grid File, Model Parameters File, or other user-specified files. The heavy data is then simply pointed to in the Card File.

Example 2 1. CMS-Flow Cards.

CMS_VERSION 4.0 !Version of input card file BATHYMETRY_DATASET "Flow_Shark_grid.h5" "Flow_Shark/Datasets/Depth" GRID_ANGLE 13.0 ’deg’ !Clock-wise from X-axes TIME_LIST_1 2 0.0 3.0 1.0 3.0 6.0 0.5 ________________________________________

Formatting Rules and Conventions The CMS-Flow Card File is a simple ASCII file with the following simple formatting rules and conventions: 1. Commented lines should be preceded by the characters ! or # or ignored. Comments can start at any column within the card file. 2. Cards are always written in capital letters. 3. Any character string in all capital letters after a card is an argument from a list options for that specific card (e.g. ON or OFF). 4. Card arguments are read in free-format. This means that input arguments should always be separated by at least one blank space or a comma. 5. Cards should always begin on a new line (i.e. only one card is allowed per line). 6. Character strings do not need to be enclosed in single or double quotation unless they contain white spaces. No characters besides letters (no accents) and numbers are allowed in character strings except: ‘(’, ‘)’, and ‘-’. 7. The end of the card file is specified by the END_PARAMETERS card. Any statements after this card are ignored.

Style Recommendations The following recommendations are optional and provided for readability and to avoid commonly made formatting errors. 1. Single line cards should start at the first column unless the card is specified within a block in which case the card should be indented by 2 to 3 spaces. 2. Input arguments should start at column 37 for readability. 3. Double quotes should be used for file names and paths 4. Single quotes should be used for units.

Insert table 2-2 here

Many input cards have relationships to one another. For example a card may only be applicable if another card is specified. This is referred to here as a dependency. Dependencies are hierarchal in nature and may be listed either downwards or upwards in the dependency tree. One example of a dependency is the angle and repose and avalanching activation cards. The angle of repose is dependent on the avalanching being activated; otherwise it is not applicable. When two cards cannot exist together because they conflict with one another, this is referred to as an exclusion. An example of an exclusion is the bottom roughness specification using both a Manning’s n and bottom friction coefficient. The bottom roughness can only be specified once and therefore the input cards used to specify the Manning’s and bottom friction coefficient would conflict with one another. In the tables describing the input cards it is convenient to use to establish a notation for the card input formats.

Insert table 2-3 here

Insert table 2-4 here

Below is an example of how the CMS-Flow cards are specified including com-ments at the end of each line.

Insert table 2-5 here

table 2-6

table 2-7

table 2-8

table 2-9

table 2-10

table 2-11

Note: • The unit character strings are NOT case sensitive. Therefore, ‘km/hr’ is equivalent to ‘Km/hr’.

It is recommended to become familiar with the CMS-Flow Card File and view it using a text editor which allows syntax highlighting such as Textpad (see Figure 2 1) or Notepadd++ (see Figure 2 2).

figure 2-1 here

figure 2-2 here

Tips: 1. It is recommended to become familiar with the CMS-Flow card file and to learn how to manually edit and enter cards without having to use the SMS interface. When the user saves the CMS-Flow project in SMS, all of the input files are rewritten including the grid and model parameters file (which can be large). Therefore if only one parameter needs to be changed in the card file, it is much easier and faster to open the card file, manually edit the field, and re-save the card file instead of potentially having to reload the project in SMS, wait for the project to display, open the Model Control Window, edit the input parameter, and re-save the project. 2. It is recommended to view the CMS-Flow Card File in a text editor which supported user-defined syntax highlighting such as Notepad++, Textpad, and UltraEdit. Syntax definitions for Textpad and Notepadd++ are available from the CIRP wiki website at http://cirp.usace.army.mil/wiki/Utilities. 3. Since all of the statements after the END_PARAMETERS card are ignored. This section of the card file is useful for placing metadata or cards saving card sections when testing different model setups. 4. There are basically two types of cards in CMS: (1) single line cards, and (2) block declaration cards. Single line cards have input arguments specified on the same line as the card and in general to not depend on the order in which the cards are specified. Block declaration cards specify the beginning and end of a block. Blocks are used to group several input parameter statements. Blocks may contain multiple single line cards or other blocks.

Output Files The minimum output files are the XMDF Global Solution File (*.h5), the Diagnostic File (CMS_DIAG.txt). By default, all of the solution variables are output to the same Global Solution File, but it is possible If Observa-tion Cells (Save Points) are selected for output time series at individual cells, then additional ASCII files are written for each of the output varia-bles. More information on the Observation Cells is provided in the section Output: Observation Cells (Save Points).

table 2-12

Overview of SMS Interface

All of the CMS-Flow model parameters, settings, and output options are controlled from the CMS-Flow Model Control Window (see Figure below). The window also has a section for Advanced Cards in which features and options can be entered which have not been incorporated into the SMS interface yet or more advanced model features more experienced users.

figure 2-3

figure 2-4

Geospatial Information Horizontal Coordinate Systems and Conventions CMS-Flow uses a local coordinate system in which all vector values are positive along the I and J axis (Figure 4-2). All output vector arrays are specified in the local coordinate system. Any input that is specified on the local grid must be specified in the local coordinate system (e.g. initial condition for currents, interpolated wave forcing, etc). If input vector arrays are specified on a different grid, such as a spatially variable wind field or waves on a CMS-Wave grid, then the vectors are assumed to follow the coordinate system of their native grid. The grid is always created in SMS with the origin is by default always at the lower left hand corner of the grid.

figure 2-5

In the SMS, the term “projection” refers to a horizontal map projection such as “State Plane” or “Geographic”. Within the software, a global pro-jection can be associated with a project. Individual datasets may also have their own projections, which if properly associated with their original reference, can be displayed without the global projection reference. Previous versions of the SMS software referred to projections as “coordinate systems” and reprojection as “coordinate conversion”. The projection for the project can be specified from the Edit | Projection pull-down menu command. Changing the projection does not alter the coordinates of the project data. To change the projection of the individual project data, the dataset must be reprojected to the common reference system. The CMS models operate in a Cartesian coordinate system such as State Plane or UTM. Currently in SMS 11.1 the horizontal projection information in the grid file (*_grid.h5). The projection of the CMS-Flow simulation may be different from that of the grid and is specified in the CMS-Flow Control File. Specifying the projection information in the Control File is only necessary if any model input (such as wind or parent grids) is specified in any other projections. Otherwise the CMS assumes that all the horizontal projections are the same and no internal conversions are necessary. The table below describes the CMS-Flow cards used to specify the horizontal projection.

table 2-13

example 2-2

A list of the supported horizontal datums, coordinate systems, or units are described in the following tables.

table 2-14

table 2-15

table 2-16

Notes: In the CMS V4.1, it is not possible to convert between datums NAD27 and NAD83, therefore all of the input horizontal projections must have the same datum. Since the difference between the International Foot and US Survey Foot is 6.0960×10-7 m, the difference can be ignored for the purposes of coastal modeling and no differentiation is made between them in the CMS.

Vertical Coordinate System and Conventions Water depths in CMS are positive and land elevations are negative. The vertical reference Datum in CMS is a local datum. Therefore, any vertical datum can be used by the user. However, it is important to note that the default initial water surface elevation is set to zero with respect to the local datum. In choosing the vertical datum for CMS it is important to understand the differences between tidal and geodetic datums. It is common to use both types of datums. However, the most appropriate datum type depends on the project application. Tidal datums are a standard elevation defined by a tidal statistic such as the arithmetic mean of mean high water and mean low water over a tidal epoch known as the Mean Tide Level or MTL. Therefore, tidal datums vary spatially and in time. This is an important difference with respect to Geodetic datums such NAVD88 which are fixed reference elevations determined by geodetic leveling. Tidal datums should not be used for projects where the tidal datums vary spatially. It is common for bays to have tidal setup or super elevation of the mean water level caused by wind, fresh water inflow, and bottom friction. This will cause a difference in the MTL in the bay with respect to the ocean as illustrated in Figure 4-3.

figure 2-6

Currently, in CMS V4.1 the vertical projection information is only specified for metadata purposes and no internal conversions are performed yet. In the future, the goal is to be able to read in the vertical datum conversion conversions either from the model input files or to get them from an external database such as VDatum (http://vdatum.noaa.gov/welcome.html). A description of the cards used to specify the vertical projection is provided in the table below.

table 2-17

Example 2-3

The vertical offset is useful for referencing a local datum to a known vertical datum as in the example above. In CMS, the default initial water level (can be specified otherwise using a hot start file) and therefore it is com-mon practice to use a vertical datum which is close to MSL. However, be-cause MSL is a tidal datum and therefore varies spatially, it is more accu-rate to use a geodetic datum with an offset, so that the zero reference elevation of the local datum is close to MSL.

table 2-18

table 2-19

Notes: 1. If the project site is a small section of coastline with a small harbor or structures, then it is generally ok to use a tidal datum. 2. If the project site includes an estuary, it is recommended to use a geodetic datum. 3. When using a geodetic datum in combination with tidal constituent forcing, it is recommended to offset the entire bathymetry so that the geodetic datum matches the offshore MSL. The reason for this is that tidal constituent boundary assumes that the reference datum is MSL. In CMS V4.1 it is possible to specify the MSL with respect to the CMS-Flow vertical datum. 4. When using a geodetic datum in combination with water level time series, it is important to make sure the time series has the same geodetic datum as the bathymetry. In addition, an initial water level may be specified which is close to MSL (see the Hot Start section for details). 5. The units of the horizontal coordinate system should always be set to meters. By default, in SMS the horizontal units are set to feet. It is recommended to change the units to meters and save this setting by clicking on the menu File | Save Settings. This will save the horizontal projection and will be set every time SMS opens. 6. A good merged bathymetric dataset is often the result of spending 50% of the time it takes to get the model up and running just on checking and cleaning up the bathymetry alone. If a significant amount of time is spent paying attention to detail, there will be less instability problems in the hydrodynamic model which are difficult to trace back to the source. 7. Always double check that you have calculated your datum corrections very carefully by analyzing and comparing to nearby datasets. 8. When merging bathymetry, try both methods to combine the datasets and evaluate for depth consistency and dataset coverage. 9. Save often, and occasionally save new versions of your merge-testing in new folders. If you delete too much of one dataset, its useful to have the older, datum converted and unaltered datasets.

Cartesian Grids SMS supports regular and nonuniform Cartesian grids as well as regular and stretched telescoping grids (see Figure 4-4).

figure 2-7

Regular Cartesian grids are the easiest to generate making them useful for feasibility type studies, simple field cases, or test runs for more complicated field cases. Nonuniform Cartesian grids allow local refinement by gradually varying the grid spacing. These grids are offer more flexibility than regular Cartesian grids for a relatively low additional cost in generation. Nonuniform Cartesian grids are available for both CMS-Flow and CMS-Wave. For large complex modeling domains, Telescoping grids offer the most flexibility by providing local refine through the subdivision or splitting of cells into four. In many cases, the hydrodynamics can be aligned with one of the Cartesian coordinates. For these cases, the number of grid cells can be reduced by using a stretched Telescoping grid. Currently in SMS, the stretched Telescoping grids can only have a constant aspect ratio between the grid resolution in the x and y directions. When a CMS-Flow project is saved, SMS writes an XMDF Grid File named “*_grid.h5”. If the grid is non-telescoping, this file contains the x and y coordinates as well as the water depths. If a telescoping grid is saved, then the SMS saves multiple-grids in the CMS-Flow XMDF Grid File which correspond to different levels of resolution of the telescoping grid. This information is only used by SMS. The information used in CMS when saving a telescoping grid is saved in the Telescoping Grid File with the extension “*.tel”. The Telescoping Grid File contains the cell coordinates, resolution, connectivity and water depths. A description of XMDF Grid File and the Telescoping Grid File along with Matlab scripts for reading these files are provided in Grid File (*_grid.h5) and Telescoping Grid File (*.tel) sections of Appendix A: Description of Input Files. All Cartesian grids can be characterized by a grid angle (orientation), origin coordinates. These grid parameters are saved to the Card File. The table below provides a description of the CMS-Flow cards used to specify the grid information in CMS.

table 2-20

The example below shows the Cartesian grid parameters defined in the CMS-Flow Model Control File.

example 2-4

If specified and average latitude is calculated for the grid and used to estimate the Coriolis parameter. By default the cell latitudes are stored in the XMDF Model Parameters File. For additional details on this file see XMDF CMS-Flow Model Parameters File (*_mp.h5). Notes: 1. The grid angle specified in the Card File and the Telescoping Grid File use different conventions (unfortunately). The angle in the Card file is measured counter-clockwise from the East direction to the grid x-axis, while the angle in the Telescoping Grid File is measured clock-wise also from the East direction to the grid x-axis. 2. By default the XMDF Grid File also contains the bathymetry and other spatial datasets including the bottom friction, hard bottom, D50, etc. However, these datasets can be specified in separate files. 3. If a telescoping grid is used, the bathymetry is included by default in both the XMDF Grid File and the Telescoping Grid File. However, the depths in the in Telescoping Grid have -999 values for inactive cells. These cells are internally removed from the computational grid. Therefore, when using telescoping grids, only the depth values in the Telescoping Grid File are used by CMS.

The SMS Cartesian Grid Module has several tools for creating and editing Cartesian grids. A brief description of the tools is provided below

Create 2D Grid Frame The 2D Cartesian Grid Frame (purple box) creation tool allows the user to visually specify the location and orientation of the grid in space. To create a grid frame, simple click three times to the desired length and width dimensions. SMS will complete the rectangle.

 Select 2D Grid Frame

A 2D Cartesian Grid Frame can be modified with this selection tool. Once the frame is generated, the edges can be modified, the grid can be rotated (by selecting a small circle usually found in the lower left part of the grid), and the grid can be selected (middle black square) for manipulating location or opening the Grid Properties dialog box.

 Select Cell

The Select Cell tool is used to select a grid cell. A single cell is selected by clicking on it. A second cell can be added to the selection list by holding the SHIFT key while selecting it. Multiple cells can be selected at once by dragging a box around them. A selected cell can be de-selected by holding the SHIFT key as it is clicked. When a single cell is selected, its Z coordi-nate is shown in the Edit Window. The Z coordinate can be changed by typing a new value in the edit field, which updates the depth function. If multiple cells are selected, the Z coordinate field in the Edit Window shows the average depth of all selected cells. If this value is changed, the new value will be assigned to all selected cells. With one cell selected, the Edit Window shows the cells i,j location. With multiple cells selected, the Edit Window shows the number of selected cells.

Select Row/ Select Column The Select Row and Select Column tools are used to select cell rows and col-umns, respectively. Multiple rows and columns are selected in the same manner as selecting multiple individual cells: holding the SHIFT key, etc.

 Insert Column/   Insert Row

When the Insert Column or Insert Row tools are active, clicking within a cell splits the row/column containing the selected cell, creating a new row or column in the grid. The Z-values of all split cells are the same as the original cells’ values.

Drag Column/ Drag Row Boundary The position of the edge of rows or columns in a grid can be changed with the Drag Column or Drag Row tools. These tools make one column/row narrower while making its neighbor wider. These tools allow for manual specification of the resolution in specific portions of the grid. Note that depth values are not adjusted, so significant dragging of boundaries should be avoided or depths should be re-interpolated after the boundaries are modified.

 Create Cell String

The Create Cell String tool allows the modeler to group a string of cells to-gether for the purpose of assigning boundary conditions. Cell strings are created automatically around water boundaries when a grid is generated. The user may create others as desired or delete and replace the automati-cally generated cell strings. When the Create Cell String tool is active, the modeler selects each cell to be added to the string. By holding down the SHIFT key, all boundary cells between the previously selected cell and the selected cell are added to the cell string.