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