CMS-Flow:Features: Difference between revisions

From CIRPwiki
Jump to navigation Jump to search
(45 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= Steering =
= Hot Start =
Steering refers to the coupling process between CMS-Flow and CMS-Wave. In CMS-Flow versions v3.75 and older (explicit CMS-Flow), the steering was done by the SMS interface. The new inline CMS contains both CMS-Flow and CMS-Wave and performs the coupling process internally. In either, the steering process is similar. First the wave model is run twice at time zero to the first steering interval. The wave information is then interpolated on to the flow grid and the flow model is run from time zero to the first steering interval. The flow information is then interpolated on the wave grid and the wave model is run for the second steering interval and the process is repeated until the simulation is complete.
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 or restarting simulations at intermediate times. The hot start controls are set in the ''Flow'' tab  of the ''CMS-Flow Model Control'' window.  


Before running steering, it is a good idea to test the CMS-Flow and CMS-Wave  separately to make sure there are no  problems with their grids, or input  parameters. Once the CMS-Flow and CMS-Wave models have been setup  properly and loaded in SMS, the steering can be initiated.
==Hot Start File ==
[[Image:Hot_Start_HDFView.png|thumb|right|500px| Figure 1. HDFView showing the structure of the CMS Hot Start File. ]]
The CMS hot start feature CMS lets the user restart simulations that have been stopped due to 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, then the water depth and sediment concentrations are also saved for each size class. Only the very last record of information is preserved (no starting from earlier intervals).


* '''Notes''':
The CMS hot start files are written as binary XMDF files by default. Depending on the type of hot start (single file or recurring), the names are as follows are saved in the directory of the CMS-Flow files:
:# For both the SMS steering and inline steering, the CMS-Wave input spectra need to be spaced at regular time intervals and begin at the same time as the CMS-Flow model.
* SingleHotStart.h5
:# The way variables are interpolated and extrapolated both in space and time are slightly different between the SMS steering and inline steering versions of CMS.
* AutoHotStart.h5
:# Currently, the inline version of CMS only contains the implicit CMS-Flow solution scheme. Therefore, if the user decides to switch from  explicit to implicit  solvers, the user must also change the CMS-Flow  executable under the SMS  preferences.  


<br  style="clear:both" />
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.
== CMS-Flow Versions 3.75 and Older ==
 
In CMS-Flow versions 3.75 and older, the steering process is done by the SMS interface. The interface does all of the variable interpolation and passing of variables from one model to another using communication files. The advantage of this approach is that it keeps the CMS-Flow and CMS-Wave codes separate and makes them easier to maintain and update.  
'''Table 1. Hot Start CMS-Flow Cards'''
{| border="1"
! Card !!  Arguments !! Default !! Range !!  Description
|-
| HOT_START_TIME || REAL || none || none || Single time after start at which to output a single hot start file.
|-
| AUTO_HOT_START_INTERVAL || REAL || none || none || Sets the recurring hot start output interval .
|}


* Make sure both the CMS-Flow and CMS-Wave grids are loaded in SMS.
<br style="clear:both"  />


<br  style="clear:both" />
==Initial Conditions File==
[[Image:Shark_Fig40.PNG|thumb|right|500px|Figure 1. ''File Location'' tab within the ''SMS Preferences'' window.]]
[[Image:Hot_Start_XMDFView_Initial_Condition.png|thumb|right|300px| Figure 2. Dataset Toolbox showing a time step sample of the water  elevation and current velocity datasets for use in a hot start (initial condition) file.]]
* Check the CMS-Flow and CMS-Wave file names under the SMS Preferences menu (see Figure 1).
:# Click on ''Edit | Preferences''.
:# Under the ''File Locations'' tab, in the section called ''Model Executables'' check the file names for CMS-Flow and CMS-Wave and make sure they are consistent with the latest releases (http://cirp.usace.army.mil/products/index.html CIRP Products).


<br  style="clear:both" />
There are several situations where it is desired to specify a user-defined hot start file from which to start a simulation. If the user has previously specified a hot start file be written either at a specific time or at a recurring interval, they can simply indicate to start from that hot start as an initial condition from the SMS interface, or by adding a card to the parameter file. The card name and format are shown below.
[[Image:SMS_10p1_Steering_V2.png|thumb|right|600px|Figure 2. SMS Steering Module for CMS v3.75 and older.]]
* Start Steering Module to run the CMS
:# Open the SMS Steering Wizard by clicking on the menu ''Data'' <nowiki>|</nowiki> ''Steering Module''.
:# Click on ''CMS-Flow <-> CMS-Wave'', click next,
:# Enter the steering interval next the ''Time'' section.
:# Check the variables which should be passed from one model to the other.
:# Click ''Start''.
:# A window will appear that says ''Are you sure you want CMS-Wave to run every <x> hours''. Make sure the steering interval is correct and click ''Yes'' to start the steering module or click ''No'' to exit.


<br  style="clear:both" />
<br  style="clear:both" />
'''Table 2. CMS-Flow card for specifying the initial condition file.'''
{|  border="1"
! Card !! Arguments !! Default !! Range !! Description
|-
| INITIAL_STARTUP_FILE <nowiki>|</nowiki> INITIAL_CONDITION_FILE || CHARACTER ||  none  || none || Hot start filename that contains the information for a Hot Start.
|}


== CMS-Flow Versions 4.0 and Newer ==
CMS Versions 4.0 and newer the steering process is done internally by the CMS. This means that that both CMS-Flow and  CMS-Wave are contained within a single code or executable. Even though  CMS-Flow and CMS-Wave use different grids, the two models are in a single code which facilitates the model coupling and speeds up the computation by avoiding communication files, variable allocation and model initialization at every steering interval.
The inline CMS can be launched from the SMS Steering Wizard or as a command line with arguments specifying the input files and steering options.


The table below describes the CMS-Flow cards used for the steering process in the inline CMS.  
Sometimes, the user may forget to set up the model output a hot start file or may have been running steady-state conditions. In these cases, a hot start file can easily be created and exported by the user from the SMS interface. The model requires records for water levels, current velocities, concentrations, and water depths and datasets that are missing from the initial file.
Note: It is important that the names and paths of the initial condition datasets are written correctly.  


<br  style="clear:both" />
'''Table 3. Path and name for initial condition file variables.'''
'''Table 1.   CMS-Flow cards related to steering'''
{| border="1"
{| border="1"
! Card !!  Arguments !! Default !! Range !! Description
! Variable !!  Path and Name
|-
|-
| CMS-WAVE_SIM_FILE || CHARACTER || none ||  none || File name including path for the CMS-Wave sim file.
| Water surface elevation ||  Datasets\Water_Elevation
|-
|-
| WAVE_SIM_FILE || CHARACTER || none || none  || Same as CMS-WAVE_SIM_FILE.
| Current velocity ||  Datasets\Current_Velocity
|-
|-
| STEERING_INTERVAL || REAL || none ||  none    || Sets the recurring hot start output time.
| Sediment concentrations ||  Datasets\Concentration
|-
|-
| WAVE_WATER_LEVEL  || CHARACTER || TIDAL_PLUS_VARIATION || LAST  <nowiki>|</nowiki> TIDAL <nowiki>|</nowiki>  TIDAL_PLUS_VARIATION|| Determines the method used to calculate the water  levels passed to the wave model.
| Salinity concentrations ||  Datasets\Salinity
|-
|  FLOW_EXTRAPOLATION_DISTANCE || REAL|| Calculated based on grid geometry  || none || Determines the extrapolation distance used for flow variables  on the wave grid.
|-
|  WAVE_EXTRAPOLATION_DISTANCE || REAL||  Calculated based on grid geometry  || none || Determines the extrapolation distance used for wave variables on the flow grid.
|}
|}
'''Interpolation Files'''
When running the inline CMS with flow and waves, the CMS steering module write out two files named:
* Intpcoef_flwav.bin
* Intpcoef_wavfl.bin
These files contain the interpolation information between the CMS-Flow and CMS-Wave grids. Because calculating the interpolation infomration can take several minutes, saving this information in files allows the model to quickly read this information and avoid their computation for subsequent runs when using the same CMS-Flow and CMS-Wave grids. When the model is restarted it will automatically detect these files and read them if the grids are the same size. If changes have been made to the grids but the grid size is the same, the steering module will not be able to detect the changes and the interpolation information will be incorrect. Therefore, it is recommended to delete the interpolation files every time a change is made the either the CMS-Flow or CMS-wave grid. In the future, this problem will be avoided by writing a counter to the CMS-Flow and CMS-Wave files every time a change is made to them from the interface.
<br    style="clear:both" />
=== SMS Steering Module ===
The inline CMS can be launched from the SMS 11.0 Steering Module in a similar way to previous versions of CMS. The steps for launching the inline CMS (versions 4.0 and higher) are outlined below.
* Make sure both the CMS-Flow and CMS-Wave grids are loaded in SMS.
<br style="clear:both" />
[[Image:Shark_Fig40.PNG|thumb|right|500px|Figure 3. Changing the  CMS-Flow model executable.]]
* Check the CMS executable file name under the SMS preferences menu (see Figure 2).
:# Click on ''Edit <nowiki>|</nowiki> Preferences''.
:# Under the ''File Locations'' tab, in the section called ''Model  Executables'' check the file names for CMS-Flow and make sure it is consistent with the latest releases  (http://cirp.usace.army.mil/products/index.html CIRP Products). Although both CMS-Flow and CMS-Wave are in the same executable, the inline CMS version is
<br  style="clear:both" />
<br  style="clear:both" />
* '''Notes:'''
:# When Running the inline CMS from SMS, it is not necessary to specify the CMS-Wave Sim File or Steering Interval in the advanced cards section.
:# Steering options besides the CMS-Wave Sim File and Steering Interval such as the extrapolation distances need to be specified in the Advanced Cards


=== CMS-FLOW Menu ===
One example showing the steps for creating a user-defined hot start or initial condition file from a CMS-Flow solution file is outlined below.
The second option for launching CMS versions 4.0 and newer is by entering the steering information in the cmcards file and simply running from the SMS CMS-Flow menu. The steps 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 condition
::* Click on ''Data'' | ''Data Set Toolbox''
:::* Under the ''Tools'' section, select ''Sample time steps''.
:::* Under the ''Datasets'' section, click on the ''Water Elevation''
:3. Export the initial condition  datasets to an XMDF file


* Make sure both the CMS-Flow and CMS-Wave grids are loaded  in SMS.  
More to come about the process above.


<br  style="clear:both" />
[[Image:Hot_Start_Sample.png|thumb|left|500px| Figure 3. Dataset Toolbox showing a time step sample of the water elevation and current velocity datasets for use in a hot start (initial condition) file.]]
[[Image:Shark_Fig40.PNG|thumb|right|500px|Figure  4. Changing the  CMS-Flow model executable.]]
[[Image:Hot_Explorting_User_Defined_Arrows.png|thumb|right|500px| Figure 4. Dataset Toolbox showing a time step sample of the water elevation and current velocity datasets for use in a hot start (initial condition) file.]]
* Check the CMS executable file name under the SMS preferences menu.
:# Click on ''Edit <nowiki>|</nowiki>  Preferences''.
:# Under the ''File Locations'' tab, in the section called ''Model  Executables'' check the file names for  CMS-Flow and CMS-Wave and make  sure they are consistent with the latest  releases  (http://cirp.usace.army.mil/products/index.html CIRP Products).


<br style="clear:both" />
<br style="clear:both" />
[[Image:Shark_Fig41.PNG|thumb|right|400px|Figure  5. Setting the CMS steering information.]]
* Set the steering  information.
:# Click on ''CMS-Flow'' <nowiki>|</nowiki> ''Model Control''…
:# Enter the  steering interval and CMS-Wave *.sim file using the advanced cards described in the table above. Note that the full path to the *.sim file must be provided  within quotation marks.


<br  style="clear:both"  />
= Global Output =
[[Image:Shark_Fig42.PNG|thumb|right|400px|Figure 6. Example  of launching the inline CMS-Flow steering run.]]
[[image:Output_Tab.png|thumb|right|400px| Figure 1. ''Output'' tab in SMS 11.0 ]]
* Start Steering  Module
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.
:# Click on ''CMS-FLOW'' | ''Run''
:# In the ''SMS Steering Wizard'' select the ''CMS INLINE'' option and click on the ''Next''> button.
:# Enter the ''Steering Interval'' under  the ''Time'' section and and click on the ''Start'' button.


<br style="clear:both"  />
== Output Datasets ==
 
A description of the CMS-Flow cards used to specify the global output variable datasets is provided below.  
=== Standalone Program ===
 
Standalone refers to the fact that the CMS executable is not part of a larger software package nor does it require a network connection, and support or services of the operating system or other software. If the CMS could only be run from the SMS than it would not be considered a standalone program.  
    
    
Because the inline CMS does all of the steering internally, it is a standalone program and there is really no need for CMS to be launched from SMS. Running CMS outside of SMS is useful because it allows the user to launch CMS from script files and also to pause the model for checking model results during the model simulation without causing access errors. When running several models, pausing the some of them will free up some of the computer to do other tasks such as plotting and checking model results. Running CMS outside of SMS, also avoid the extra memory and work requirements from the interface.
'''Table 1. Output datasets.'''
* There are two mean approaches f running CMS as a standalone program
{|    border="1"
:# From a command prompt
! Output Dataset !! Group  !!  Description !! Units
:# Double clicking or dragging and dropping input files on the executable or shortcut to the executable.
|-
====Command prompt====
| Current_Velocity  || Velocity || Depth-averaged and cell-centered current velocity vector dataset and with respect to local grid coordinates || m/s
The first step is to open a command prompt. There are two ways of doing this: 
|-
 
| Current_Magnitude || Velocity || Depth-averaged and cell-centered current velocity magnitude dataset || m/s
[[Image:Command_Prompt_from_Accessories.png|thumb|right|400px|Figure 7. Example  of launching the inline CMS-Flow steering run.]] 
|-
* The first method for  opening a command prompt is:# Click on the Windows ''Start'' menu then  the Run… utilityIn the      Run window, enter the command      cmd and click OK 
| Water_Elevation || Water surface elevation|| Cell-centered water surface elevation || m
 
|-
<br  style="clear:both" />  
| Eddy_Viscosity || Eddy viscosity || Cell-centered horizontal eddy viscosity || m^2/s
[[Image:Command_Prompt_from_Run.png|thumb|right|400px|Figure 7. Example  of launching the inline CMS-Flow steering run.]] 
|-
* The second method for opening a command prompt 
| Concentration  ||  Transport || Depth-averaged and cell-centered sediment concentration  || kg/m^3
:# Click on Windows ''Start'' menu then click on ''Run…''.
|-
:# In the ''Run'' window, enter the command ''cmd'' and click ''OK''
| Capacity || Transport || Depth-averaged and cell-centered sediment concentration capacity || kg/m^3
 
|-
<br style="clear:both" />
| Total_Sediment_Transport ||  Transport  || Depth-averaged and cell-centered total-load sediment transport ||  m^2/s
* '''Note:'''
|-
: It is recommended to put a shortcut to the Command Prompt for easier access.
| Salinity || Transport || Depth-averaged and cell-centered sediment concentration capacity || kg/m^3
 
|-
Once the command prompt is open the CMS can be lauched using one of the following syntax 
| Depth || Morphology || Cell-centered still water depth || m
:>> [cms2d_*exe] [sim or cmcards file] [sim or cmcards file] [steering interval] [wave water level option]
|-
where the steering interval is in hours and the wave water level option is either
| Morphology_Change || Morphology ||  Cell-centered morphology (bed) change. Positive is accretion and negative is erosion || m
:1 – Wave water levels are estimate as the last water levels from the flow model (i.e. WAVE_WATER_LEVEL option equal to LAST).
:2 – Wave water levels are estimated as the mean tidal water level at the wave time step (i.e. WAVE_WATER_LEVEL option EQUAL TO TIDAL).
:3 – Wave water levels are estimated as the mean tidal water level at the wave time step plus the water surface variations estimated from the last flow time step (i.e. WAVE_WATER_LEVEL option EQUAL TO TIDAL_PLUS_VARIATION).
* '''Important Notes:'''
:# The sim and cmcards files must contain the full or relative path with respect to the executable if different from the executable.
:# If no input arguments are specified, than the user will be prompted to manually enter the name of the CMS-Flow and CMS-Wave files and steering information.
:# If the cmcards file is specified the CMS will check for the steering cards.
:# If the sim file is found, than it will run in steering.
:# If no steering interval is specified in the cmcards file or the command line, than a default value of 3.0 hours will be used.
:# If no wave water level option is specified in the cmcards file or the command line, than a default method equal to three.
:# It is possible to create a short-cut to the model executable and simply drag-and-drop the cmcards file and or sim file with the steering options specified in the cmcards file.
:# For advanced users, it is recommended to put a copy of the CMS executable in the project directory and running the CMS from a command prompt. This keeps a record of the executable used for the project, facilitates making and transferring script files for running multiple project alternatives and keeps the window open after the model has completed or even crashed.
* Below are some examples
<font size=2>
>> cms2d_v4b43-x32.exe  
  >> cms2d_v4b43-x32.exe Flow.cmcards
  >> cms2d_v4b43-x32.exe Flow.cmcards Wave.sim 
>> cms2d_v4b43-x32.exe Wave.sim Flow.cmcards
  >> cms2d_v4b43-x32.exe Flow.cmcards Wave.sim 1.0
  >> cms2d_v4b43-x32.exe Wave.sim Flow.cmcards 3.0 1
</font>
 
= 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 or restarting simulations at intermediate times. The hot start controls are set in the ''Flow'' tab  of the ''CMS-Flow Model Control'' window.
 
==Hot Start  File ==
[[Image:Hot_Start_HDFView.png|thumb|right|500px| Figure 2. XMDFView  showing the structure of the CMS Hot Start File. ]]
The CMS hot start feature CMS lets the user restart simulations that have  been stopped due to 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, then 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  1 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.
 
'''Table 1.  Hot Start CMS-Flow Cards'''
{| border="1"
! Card !!  Arguments !! Default !! Range !!  Description
|-
|-
|   HOT_START_OUTPUT_FILE || CHARACTER || none || none || Julian hour.
| Wave_Height  || Waves || Cell-centered significant wave height || m
|-
|-
| HOT_START_TIME || REAL || none || none || Sets the hot start output time.
| Wave_Height_Vec  || Waves || Cell-centered  significant wave height vector || m
|-
|-
| AUTO_HOT_START_INTERVAL || REAL || none || none  || Sets the recurring hot start output time.
| Wave_Period  || Waves || Cell-centered peak wave period || s
|}
|}
<br  style="clear:both" />


<br style="clear:both"  />
== Output Time Series and Lists ==
==Initial Conditions File==
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.  
[[Image:Hot_Start_XMDFView_Initial_Condition.png|thumb|right|500px|  Figure 3. Dataset  Toolbox showing a time step sample of the water  elevation and current  velocity datasets for use in a hot start (initial  condition) file.]]


There are several situations where  it is convenient to specify a user defined hot start file. For example,  if the user forgets to setup the model output a hot start file or when  running steady state 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. It is important to note  that the names and paths of the initial condition datasets is  important.
'''Table 2. Time series and List Cards.'''
 
{| border="1"
'''Table 2. Path and name for initial  condition file variables.'''
! Card !! Aguments/Format !! Default value !!  Description
{| border="1"
|-
! Variable !!  Path and Name
| TIME_SERIES_1 ||  [length of list 1] [output times for list 1] || 0 || Output time series for list 1 in hours.
|-
| TIME_SERIES_2  || [length  of list 2] [output times for list 2] || 0 || Output time  series for list 2 in hours.
|-
|  TIME_SERIES_3 || [length  of list 3] [output times for list 3] || 0 ||  Output time series for list 3 in hours.
|-
| TIME_SERIES_4 || [length  of list 4] [output times for list  4] || 0 || Output time series for list 4 in hours.
|-
|-
| Water surface elevation ||  Datasets\Water_Elevation
| TIME_LIST_1 || [number of sublists] [sublist 1: start, end, increment] [sublist 2: start, end, increment]...|| 0 || Sublist(s) for  output time series 1. For each sublist, the arguments are starting time,  end time and increment in hours.
|-
|-
| Current velocity ||  Datasets\Current_Velocity
| TIME_LIST_2 || [number of sublist] [sublist 1: start, end, increment]  [sublist 2: start, end, increment]...|| 0 || Sublist(s) for output time  series 2. For each sublist, the arguments are starting time, end time and increment in hours.
|-
|-
| Sediment concentrations ||  Datasets\Concentration
| TIME_LIST_3  || [number of sublist] [sublist 1:  start, end, increment] [sublist 2:  start, end, increment]...|| 0 || Sublist(s) for output time series 3.  For each sublist, the arguments are starting time, end time and increment in hours.
|-
|-
| Salinity concentrations ||  Datasets\Salinity
| TIME_LIST_4 ||  [number of sublist] [sublist 1:  start, end, increment] [sublist 2:  start, end, increment]...|| 0 || Sublist(s) for output time series 4.  For each sublist, the arguments are starting time, end time and  increment in hours..
|}
|}
<br  style="clear:both" />
The  steps for creating a user defined hot start or initial condition file  from a CMS-Flow solution file are outlined below.
# Import  CMS-Flow grid and solution file.
# Sample a time step of the  solution datasets for use in the initial condition
## Click on  ''Data'' | ''Data Calculator''
### Under the ''Tools'' section,  select ''Sample time steps''.
### Under the ''Datasets'' section,  click on the ''Water Elevation''
# Export the initial condition  datasets to an XMDF file
#
[[Image:Hot_Start_Sample.png|thumb|left|500px|  Figure 3. Dataset  Toolbox showing a time step sample of the water  elevation and current  velocity datasets for use in a hot start (initial  condition) file.]]
[[Image:Hot_Explorting_User_Defined_Arrows.png|thumb|right|500px|  Figure 4. Dataset  Toolbox showing a time step sample of the water  elevation and current  velocity datasets for use in a hot start (initial  condition) file.]]


<br  style="clear:both" />
'''Table 3. Cards used to specify the output time series or list for each output group or dataset.'''
'''Table 3. CMS-Flow card for specifying the initial  condition file.'''
{|  border="1"
{|  border="1"
! Card !! Arguments !! Default !! Range !!  Description
! Card !! Arguments !! Default value !! Description  
|-
| WSE_OUT_TIMES_LIST || INTEGER || 0 || Output time series  id for the water surface elevation in m.
|-
| VEL_OUT_TIMES_LIST || INTEGER || 0 || Output time series  id for currentvelocity and magnitude in m/s.
|-
| MORPH_OUT_TIMES_LIST || INTEGER || 0 || Output time series  id for the water depth and morphology (bed) change in m.
|-
| TRANS_OUT_TIMES_LIST || INTEGER || 0 || Output time series  id for sediment transport rates, concentations, and salinity.
|-
| WAVES_OUT_TIMES_LIST || INTEGER || 0 || Output time series  id for the wave height in m, period in sec, and wave vectors.
|-
| EDDY_VISCOSITY_OUT_TIMES_LIST || INTEGER || 0 || Output time series  id for the eddy viscosity in m^2/s.
|-
| VISC_OUT_TIMES_LIST || INTEGER || 0 || Output time series  id for the eddy viscosity in m^2/s.
|-
| WIND_OUT_TIMES_LIST || INTEGER || 0 || Output time series  id for wind velocity and magnitude in m/s.
|-
| STRESS_OUT_TIMES_LIST || INTEGER || 0 || Output time series id for mean  bed shear stress in Pa.
|-
|-
| INITIAL_STARTUP_FILE || CHARACTER || none || none || Julian  data in YYDDD with YY being last two digits of  the  year, and DDD the  Julian day of the year.
| WAVE_OUTPUT_DETAILS || ON  <nowiki>|</nowiki> OFF || OFF || Outputs additional wave variables including wave direction, radiation stresses, breaking dissipation and roller energy.  
|}
|}


<br  style="clear:both" />
== XMDF Output ==
= Output =
The default option in CMS is to output all output groups to the same XMDF file (*_sol.h5). This option works well as long as the solution does not get too big. If the solution becomes too big, the SMS interface may have trouble reading the file. The option is also avaible to output different variable groups into separate XMDF files which helps reduce the file and makes it easier to visualize individual datasets in SMS. This feature is available in CMS-Flow Versions 4, Release 5 and more recent. This is done by either manually modifying the cards in the Output section of the cmcards file or by using new Advanced Cards. A list of the cards and their description is provided in the table below.
In addition to the variables specified in the SMS interface, CMS has the option to output advanced mode output including the bed shear stress, bed composition, wind speed, etc. The following advanced cards have been added to CMS v4.0 and higher for outputting additional output information, ASCII file output, and more.


'''Table 2. Advanced output datasets.'''
'''Table 2. XMDF file .'''
{| border="1"
{|   border="1"
! Card !! Aguments/Format !! Default value !! Description
! Card !! Argument Type !! Format !! Example !! Default !! Version
|-
| TIME_SERIES_1 || [length of list 1] [output times for list 1] || 0 || Output time series for list 1 in hours.
|-
| TIME_SERIES_2 || [length  of list 2] [output times for list 2] || 0 || Output time series for list 2 in hours.
|-
| TIME_SERIES_3 || [length  of list 3] [output times for list 3] || 0 || Output time series for list 3 in hours.
|-
|-
| TIME_SERIES_4 || [length of list 4] [output times for list 4] || 0 || Output time series for list 4 in hours.  
| WSE_OUT_FILE  ||  CHARACTER || [<file path>/<file name>] || "<simulation label>_wse.h5" || "<simulation label>_wse.h5" || V4.1
|-
|-
| TIME_LIST_1 || [number of sublists] [sublist 1: start, end, increment] [sublist 2: start, end, increment]...|| 0 || Sublist(s) for output time series 1. For each sublist, the arguments are starting time, end time and increment in hours.
| VEL_OUT_FILE || CHARACTER || [<file path>/<file name>] || "<simulation label>_vel.h5" || "<simulation label>_vel.h5"|| V4.1
|-
|-
| TIME_LIST_2 || [number of sublist] [sublist 1: start, end, increment] [sublist 2: start, end, increment]...|| 0 || Sublist(s) for output time series 2. For each sublist, the arguments are starting time, end time and increment in hours.
| VISC_OUT_FILE || CHARACTER || [<file path>/<file name>] || "<simulation label>_visc.h5" || "<simulation label>_visc.h5"|| V4.1
|-
|-
| TIME_LIST_3 || [number of sublist] [sublist 1: start, end, increment] [sublist 2: start, end, increment]...|| 0 || Sublist(s) for output time series 3. For each sublist, the arguments are starting time, end time and increment in hours.
| TRANS_OUT_FILE || CHARACTER || [<file path>/<file name>] || "<simulation label>_trans.h5" || "<simulation label>_trans.h5"|| V4.1
|-
|-
| TIME_LIST_4 || [number of sublist] [sublist 1: start, end, increment] [sublist 2: start, end, increment]...|| 0 || Sublist(s) for output time series 4. For each sublist, the arguments are starting time, end time and increment in hours..
| MORPH_OUT_FILE ||  CHARACTER || [<file path>/<file name>] || "<simulation label>_morph.h5" || "<simulation label>_morph.h5"|| V4.1
|-
|-
| WAVE_OUT_TIMES_LIST || integer || 0 || Output time series id for wave height, period, and vector.  
| WAVES_OUT_FILE || CHARACTER || [<file path>/<file name>] || "<simulation label>_wave.h5" || "<simulation label>_wave.h5" || V4.1
|-
|-
| EDDY_OUT_TIMES_LIST || integer || 0|| Output time series id for eddy viscosity in m^2/s.
| GLOBAL_WATER_LEVEL_OUTPUT || CHARACTER  CHARACTER || [<file path>/<file name>] [<dataset path>] || "<simulation label>_wse.h5" || "<simulation label>_wse.h5" || V4.1
|-
|-
| VISC_OUT_TIMES_LIST || integer || 0 || Output time series id for eddy viscosity in m^2/s. Same as EDDY_OUT_TIMES_LIST
| GLOBAL_VELOCITY_OUTPUT || CHARACTER  CHARACTER || [<file path>/<file name>] [<dataset path>] || "<simulation label>_vel.h5" || "<simulation label>_vel.h5" || V4.1
|-
|-
| WIND_OUT_TIMES_LIST || integer || 0 || Output time series id for wind velocity and magnitude in m/s.  
| GLOBAL_MORPHOLOGY_OUTPUT || CHARACTER  CHARACTER || [<file path>/<file name>] [<dataset path>] || "<simulation label>_morph.h5" || "<simulation label>_morph.h5" || V4.1
|-
|-
| STRESS_OUT_TIMES_LIST || integer || 0 || Output time series id for mean bed shear stress in Pa.  
| GLOBAL_TRANS_RATE_OUTPUT ||  CHARACTER  CHARACTER ||  [<file path>/<file name>] [<dataset path>] || "<simulation label>_trans.h5" || "<simulation label>_trans.h5" || V4.1
|-
|-
| BED_SHEAR_STRESS_OUT_TIMES_LIST || integer || 0 ||  Output time series id. Same as BED_SHEAR_STRESS_OUT_TIMES_LIST
|}
|}


== XMDF File ==
Notes:
The standard CMS-Flow output is written to an XMDF file with the name <Case Name>_sol.h5. The bindary file may be written in compressed format using the card described in the table below.
# The dataset path is not used by the CMS-Flow and is therefore not necessary to include.
# In CMS-Flow versions ealier than V4R5, the above output cards are not used and all of the variable groups are output to the same XMDF file (*_sol.h5).


Table 3. CMS-Flow card for compressing the XMDF output file
=== Multiple Output Files ===
{| border="1"
Be default, all solution output is broken into multiple files. If you want some of the output placed into the same file, you must specify cards in the CMCARDS file to change from the default.  This is presently necessary for running PTM with CMS results.
! Card !! Arguments !! Description !! Default  value
|-
| XMDF_COMPRESSION || ON  <nowiki>|</nowiki> OFF || Compresses the h5 file by a factor of about 7 || OFF
|}


== Statistics ==
In SMS 11.2 and previous (CMS Version <= 5.0), the cards needed are as follows:
CMS V4.0 has the option to calculate  statistics over the whole model domain for a user-specified time period.  This option is accessed using the advanced cardss. The starting time, end time, and time interval should be  specified in hours with respect to the model start time. The time  interval should be larger or equal to the hydrodynamic time step. When  activated the global statistics will be output in the same solution file  within a subfolder named ''stats''.


This option outputs the statistics for hydrodynamics, sediment and salinity transport. If only the statistics for one group
  WSE_OUT_FILE          project_sol.h5
  VEL_OUT_FILE          project_sol.h5


* The hydrodynamic statistics output are:
In SMS 12.3+ (CMS Version 5.1+), a simpler way has been created. One card can be added to put all output into the single solution file, project_sol.h5. The previous two cards are still available if you only want those two solutions in a single file.
# Maximum  current velocity
# Maximum water level
# Residual currents  (vectors and magnitude)
# Hydroperiod
# Maximum spatial gradient for water levels
# Maximum spatial gradient for current magnitude


* Sediment Transport and Morphology Change
  USE_COMMON_SOLUTION_FILE            ON
# Maximum total load transport rate, m^2/hr
# Net total load sediment transport rates, m^2/hr
# Average  total  load sediment transport rates, m^2/hr
# Gross  total load sediment  transport rates, m^2/hr
# Positive  and negative total load  transport rates (in x and y directions), m^2/hr
# Maximum spatial  gradient of bathymetry


* Salinity Statistics
=== File Compression ===
# Mean Salinity
The standard CMS-Flow output is written to an XMDF file with the name <Case Name>_sol.h5. The binary file may be written in compressed format using the card described in the table below.


'''Table 3. CMS-Flow cards related to output statistics'''
'''Table 4. CMS-Flow card for compressing the XMDF output file'''
{| border="1"
{| border="1"
! Card !! Arguments !! Description !! Default  value
! Card !! Arguments !! Default  value !! Description
|-
| GLOBAL_STATISTICS ||  [t0] [tn] [dt]  || Calculates  global statistics if specified || none
|-
|-
| FLOW_STATISTICS || [t0] [tn] [dt] || Calculates flow statistics if specified || none
| XMDF_COMPRESSION || ON <nowiki>|</nowiki> OFF || OFF || Compresses the h5 file by a factor of about 7
|-
| SEDIMENT_STATISTICS || [t0] [tn] [dt] || Calculates sediment statistics if specified || none
|-
| SALINITY_STATISTICS || [t0] [tn] [dt] || Calculates salinity  statistics if specified || none
|}
|}


==ASCII Output Files==
== ASCII Output ==
In addition to the XMDF output file, CMS-Flow provides the output two types of ASCII output files:  
In addition to the XMDF output file, CMS-Flow provides the output two types of ASCII output files:  
# Tecplot snap shot (*.dat), and history files (*.his)
# Tecplot snap shot (*.dat), and history files (*.his)
Line 307: Line 218:
The CMS-Flow cards used for outputting these two types of files are described in the Table below.
The CMS-Flow cards used for outputting these two types of files are described in the Table below.


Table 4. CMS-Flow cards used to output Tecplot and SMS Super ASCII files.
'''Table 3. CMS-Flow cards used to output Tecplot and SMS Super ASCII files.'''
{| border="1"
{| border="1"
! Card !! Arguments !!  Description !! Default value
! Card !! Arguments !!  Description !! Default value
Line 313: Line 224:
|  GLOBAL_TECPLOT_FILES || ON  <nowiki>|</nowiki> OFF ||  Outputs Tecplot ASCII files || OFF
|  GLOBAL_TECPLOT_FILES || ON  <nowiki>|</nowiki> OFF ||  Outputs Tecplot ASCII files || OFF
|-
|-
|  GLOBAL_SUPER_FILES || ON  <nowiki>|</nowiki> OFF || Outputs Tecplot ASCII files || OFF
|  GLOBAL_SUPER_FILES || ON  <nowiki>|</nowiki> OFF || Outputs general ASCII solution files || OFF
|}
 
= Output Cells =
[[image:Cells_Tab.png|thumb|right|400px| Figure 1. ''Cells'' tab in  SMS 11.0 ]]
Time series at selected ''Obervation'' cells is set in the ''Cells'' tab of the ''CMS-Flow Model Control'' window. A description of CMS-Flow cards used for specifying ''Observational'' cells are described below.
 
'''Table 5. CMS-Flow card for compressing the XMDF output  file'''
{| border="1"
! Card !! Arguments  !! Description
|-
| TIME_SERIES_INCREMENT  || REAL || Sets the output time increment for the ''Time series'' ''Observation'' points.
|-
| ELEV_OBS_CELLS_BEGIN || none || Marks the begging of an ''Times series'' ''Observation'' point list.
|-
| ELEV_OBS_CELLS_END  || none || Marks the end of an ''Times series'' ''Observation'' point list.
|-
| FLOW_RATE_INCREMENT  || REAL || Sets  the output time increment for the ''Flow rate'' ''Observation''  points.
|-
| FLOW_OBS_CELLS_BEGIN  || none || Marks the  end of an ''Flow rate'' ''Observation'' point list.
|-
| FLOW_OBS_CELLS_END  || none || Marks the  end of an ''Flow rate'' ''Observation'' point list.
|-
| Q_TRANS_INCREMENT  || REAL || Sets  the output time increment for the ''Flow rate'' ''Observation''  points.
|-
| Q_TRANS_OBS_CELLS_BEGIN  || none || Marks the  end of an ''Transport''  ''Observation'' point list.
|-
| Q_TRANS_OBS_CELLS_BEGIN  || none ||  Marks the  end of an ''Transport'' ''Observation''  point list.
|}
 
 
<br style="clear:both" />
 
= Statistics =
CMS V4.0 has the option to calculate  statistics over the whole model domain for a user-specified time period.  This option is accessed using the advanced cardss. The starting time, end time, and time interval should be  specified in hours with respect to the model start time. The time  interval should be larger or equal to the hydrodynamic time step. When  activated the global statistics will be output in the same solution file  within a subfolder named ''stats''.
 
This option outputs the statistics for hydrodynamics, sediment and salinity transport. If only the statistics for one group
 
* '''Hydrodynamics:'''
:# Maximum  current velocity
:# Maximum water level
:# Residual currents  (vectors and magnitude)
:# Hydroperiod
:# Maximum spatial  gradient for water levels
:# Maximum spatial gradient for current  magnitude
 
* '''Sediment Transport and Morphology Change''':
:# Maximum total load transport rate, m^2/s
:# Net total load sediment transport rates, m^2/s
:# Average  total  load sediment transport rates, m^2/s
:# Gross  total load sediment  transport rates, m^2/s
:# Positive  and negative total load  transport rates (in x and y directions), m^2/s
:# Maximum spatial  gradient of bathymetry
 
* '''Salinity Statistics''':
:# Mean Salinity
 
'''Table 6. CMS-Flow cards related to output statistics'''
{| border="1"
! Card !! Arguments !! Description !! Default value !! Notes
|-
| GLOBAL_STATISTICS ||  [t0] [tn] [dt]  || Calculates  global statistics if specified || none || [start] [end] [increment]
|-
| FLOW_STATISTICS || [t0] [tn] [dt] || Calculates  flow statistics if specified || none || [start] [end] [increment]
|-
| SEDIMENT_STATISTICS || [t0] [tn] [dt] || Calculates sediment statistics if specified || none || [start] [end] [increment]
|-
| SALINITY_STATISTICS || [t0] [tn]  [dt] ||  Calculates salinity  statistics if specified || none || [start] [end] [increment]
|}
|}


Line 335: Line 313:
| MATRIX_SOLVER  ||  CHARACTER || GMRES ||  GAUSS-SEIDEL <nowiki>|</nowiki>  GAUSS-SEIDEL-SOR  <nowiki>|</nowiki> BICGSTAB  <nowiki>|</nowiki>  GMRES || Selects the matrix solver for  flow, sediment and salinity.
| MATRIX_SOLVER  ||  CHARACTER || GMRES ||  GAUSS-SEIDEL <nowiki>|</nowiki>  GAUSS-SEIDEL-SOR  <nowiki>|</nowiki> BICGSTAB  <nowiki>|</nowiki>  GMRES || Selects the matrix solver for  flow, sediment and salinity.
|-
|-
|  HYDRO_MAX_ITERATIONS || INTEGER || Function of grid size ||  >0 ||  Sets the maximum number of iterations for the flow (hydro)  solver (outer  loop).
|  HYDRO_MAX_ITERATIONS || INTEGER || Function of grid size ||  >0 ||  Sets the maximum number of iterations for the flow (hydro)  solver (outer  loop). Typical range: 30-50 for GAUSS-SEIDEL and GAUSS-SEIDEL-SOR, and 20-30 for BICGSTAB and GMRES.
|-
|-
|  PRESSURE_ITERATIONS ||  INTEGER || Depends on Solver || >0 ||  Sets  the number of solver  iterations for the pressure equation (inner loop).
|  PRESSURE_ITERATIONS ||  INTEGER || Depends on Solver || >0 ||  Sets  the number of solver  iterations for the pressure equation (inner loop). Typical range: 80-100 for GAUSS-SEIDEL and GAUSS-SEIDEL-SOR, and 15-25 for BICGSTAB and GMRES.
|-
|-
| VELOCITY_ITERATIONS || INTEGER || Depends  on Solver || >0  ||  Sets the number of solver iterations for the  velocity or momentum  equations (inner loop).
| VELOCITY_ITERATIONS || INTEGER || Depends  on Solver || >0  ||  Sets the number of solver iterations for the  velocity or momentum  equations (inner loop). Typical range: 20-30 for GAUSS-SEIDEL and GAUSS-SEIDEL-SOR, and 5-10 for BICGSTAB and GMRES.
|-
|-
| SEDIMENT_MAX_ITERATIONS || integer  ||  20 || Maximum number  of iterations (outer loop) for the sediment  transport
| SEDIMENT_MAX_ITERATIONS || integer  ||  20 ||  >0 || Maximum number  of iterations (outer loop) for the sediment  transport
|-
|-
| SALINITY_MAX_ITERATIONS ||  integer  || 20 || Maximum number  of iterations (outer loop) for the  salinity transport
| SALINITY_MAX_ITERATIONS ||  integer  || 20 || >0|| Maximum number  of iterations (outer loop) for the  salinity transport
|}
|}



Revision as of 17:51, 6 March 2020

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 or restarting simulations at intermediate times. The hot start controls are set in the Flow tab of the CMS-Flow Model Control window.

Hot Start File

Figure 1. HDFView showing the structure of the CMS Hot Start File.

The CMS hot start feature CMS lets the user restart simulations that have been stopped due to 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, then the water depth and sediment concentrations are also saved for each size class. Only the very last record of information is preserved (no starting from earlier intervals).

The CMS hot start files are written as binary XMDF files by default. Depending on the type of hot start (single file or recurring), the names are as follows are saved in the directory of the CMS-Flow files:

  • SingleHotStart.h5
  • AutoHotStart.h5

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.

Table 1. Hot Start CMS-Flow Cards

Card Arguments Default Range Description
HOT_START_TIME REAL none none Single time after start at which to output a single hot start file.
AUTO_HOT_START_INTERVAL REAL none none Sets the recurring hot start output interval .


Initial Conditions File

Figure 2. Dataset Toolbox showing a time step sample of the water elevation and current velocity datasets for use in a hot start (initial condition) file.

There are several situations where it is desired to specify a user-defined hot start file from which to start a simulation. If the user has previously specified a hot start file be written either at a specific time or at a recurring interval, they can simply indicate to start from that hot start as an initial condition from the SMS interface, or by adding a card to the parameter file. The card name and format are shown below.


Table 2. CMS-Flow card for specifying the initial condition file.

Card Arguments Default Range Description
INITIAL_STARTUP_FILE | INITIAL_CONDITION_FILE CHARACTER none none Hot start filename that contains the information for a Hot Start.


Sometimes, the user may forget to set up the model output a hot start file or may have been running steady-state conditions. In these cases, a hot start file can easily be created and exported by the user from the SMS interface. The model requires records for water levels, current velocities, concentrations, and water depths and datasets that are missing from the initial file. Note: It is important that the names and paths of the initial condition datasets are written correctly.

Table 3. Path and name for initial condition file variables.

Variable Path and Name
Water surface elevation Datasets\Water_Elevation
Current velocity Datasets\Current_Velocity
Sediment concentrations Datasets\Concentration
Salinity concentrations Datasets\Salinity


One example showing the steps for creating a user-defined hot start or initial condition file from a CMS-Flow solution file is outlined below.

1. Import CMS-Flow grid and solution file.
2. Sample a time step of the solution datasets for use in the initial condition
  • Click on Data | Data Set Toolbox
  • Under the Tools section, select Sample time steps.
  • Under the Datasets section, click on the Water Elevation
3. Export the initial condition datasets to an XMDF file

More to come about the process above.

Figure 3. 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 4. Dataset Toolbox showing a time step sample of the water elevation and current velocity datasets for use in a hot start (initial condition) file.


Global Output

Figure 1. Output tab in SMS 11.0

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.

Output Datasets

A description of the CMS-Flow cards used to specify the global output variable datasets is provided below.

Table 1. 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 m^2/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. Time series and List Cards.

Card Aguments/Format Default value Description
TIME_SERIES_1 [length of list 1] [output times for list 1] 0 Output time series for list 1 in hours.
TIME_SERIES_2 [length of list 2] [output times for list 2] 0 Output time series for list 2 in hours.
TIME_SERIES_3 [length of list 3] [output times for list 3] 0 Output time series for list 3 in hours.
TIME_SERIES_4 [length of list 4] [output times for list 4] 0 Output time series for list 4 in hours.
TIME_LIST_1 [number of sublists] [sublist 1: start, end, increment] [sublist 2: start, end, increment]... 0 Sublist(s) for output time series 1. For each sublist, the arguments are starting time, end time and increment in hours.
TIME_LIST_2 [number of sublist] [sublist 1: start, end, increment] [sublist 2: start, end, increment]... 0 Sublist(s) for output time series 2. For each sublist, the arguments are starting time, end time and increment in hours.
TIME_LIST_3 [number of sublist] [sublist 1: start, end, increment] [sublist 2: start, end, increment]... 0 Sublist(s) for output time series 3. For each sublist, the arguments are starting time, end time and increment in hours.
TIME_LIST_4 [number of sublist] [sublist 1: start, end, increment] [sublist 2: start, end, increment]... 0 Sublist(s) for output time series 4. For each sublist, the arguments are starting time, end time and increment in hours..

Table 3. Cards used to specify the output time series or list for each output group or dataset.

Card Arguments Default value Description
WSE_OUT_TIMES_LIST INTEGER 0 Output time series id for the water surface elevation in m.
VEL_OUT_TIMES_LIST INTEGER 0 Output time series id for currentvelocity and magnitude in m/s.
MORPH_OUT_TIMES_LIST INTEGER 0 Output time series id for the water depth and morphology (bed) change in m.
TRANS_OUT_TIMES_LIST INTEGER 0 Output time series id for sediment transport rates, concentations, and salinity.
WAVES_OUT_TIMES_LIST INTEGER 0 Output time series id for the wave height in m, period in sec, and wave vectors.
EDDY_VISCOSITY_OUT_TIMES_LIST INTEGER 0 Output time series id for the eddy viscosity in m^2/s.
VISC_OUT_TIMES_LIST INTEGER 0 Output time series id for the eddy viscosity in m^2/s.
WIND_OUT_TIMES_LIST INTEGER 0 Output time series id for wind velocity and magnitude in m/s.
STRESS_OUT_TIMES_LIST INTEGER 0 Output time series id for mean bed shear stress in Pa.
WAVE_OUTPUT_DETAILS ON | OFF OFF Outputs additional wave variables including wave direction, radiation stresses, breaking dissipation and roller energy.

XMDF Output

The default option in CMS is to output all output groups to the same XMDF file (*_sol.h5). This option works well as long as the solution does not get too big. If the solution becomes too big, the SMS interface may have trouble reading the file. The option is also avaible to output different variable groups into separate XMDF files which helps reduce the file and makes it easier to visualize individual datasets in SMS. This feature is available in CMS-Flow Versions 4, Release 5 and more recent. This is done by either manually modifying the cards in the Output section of the cmcards file or by using new Advanced Cards. A list of the cards and their description is provided in the table below.

Table 2. XMDF file .

Card Argument Type Format Example Default Version
WSE_OUT_FILE CHARACTER [<file path>/<file name>] "<simulation label>_wse.h5" "<simulation label>_wse.h5" V4.1
VEL_OUT_FILE CHARACTER [<file path>/<file name>] "<simulation label>_vel.h5" "<simulation label>_vel.h5" V4.1
VISC_OUT_FILE CHARACTER [<file path>/<file name>] "<simulation label>_visc.h5" "<simulation label>_visc.h5" V4.1
TRANS_OUT_FILE CHARACTER [<file path>/<file name>] "<simulation label>_trans.h5" "<simulation label>_trans.h5" V4.1
MORPH_OUT_FILE CHARACTER [<file path>/<file name>] "<simulation label>_morph.h5" "<simulation label>_morph.h5" V4.1
WAVES_OUT_FILE CHARACTER [<file path>/<file name>] "<simulation label>_wave.h5" "<simulation label>_wave.h5" V4.1
GLOBAL_WATER_LEVEL_OUTPUT CHARACTER CHARACTER [<file path>/<file name>] [<dataset path>] "<simulation label>_wse.h5" "<simulation label>_wse.h5" V4.1
GLOBAL_VELOCITY_OUTPUT CHARACTER CHARACTER [<file path>/<file name>] [<dataset path>] "<simulation label>_vel.h5" "<simulation label>_vel.h5" V4.1
GLOBAL_MORPHOLOGY_OUTPUT CHARACTER CHARACTER [<file path>/<file name>] [<dataset path>] "<simulation label>_morph.h5" "<simulation label>_morph.h5" V4.1
GLOBAL_TRANS_RATE_OUTPUT CHARACTER CHARACTER [<file path>/<file name>] [<dataset path>] "<simulation label>_trans.h5" "<simulation label>_trans.h5" V4.1

Notes:

  1. The dataset path is not used by the CMS-Flow and is therefore not necessary to include.
  2. In CMS-Flow versions ealier than V4R5, the above output cards are not used and all of the variable groups are output to the same XMDF file (*_sol.h5).

Multiple Output Files

Be default, all solution output is broken into multiple files. If you want some of the output placed into the same file, you must specify cards in the CMCARDS file to change from the default. This is presently necessary for running PTM with CMS results.

In SMS 11.2 and previous (CMS Version <= 5.0), the cards needed are as follows:

 WSE_OUT_FILE           project_sol.h5
 VEL_OUT_FILE           project_sol.h5

In SMS 12.3+ (CMS Version 5.1+), a simpler way has been created. One card can be added to put all output into the single solution file, project_sol.h5. The previous two cards are still available if you only want those two solutions in a single file.

 USE_COMMON_SOLUTION_FILE            ON

File Compression

The standard CMS-Flow output is written to an XMDF file with the name <Case Name>_sol.h5. The binary file may be written in compressed format using the card described in the table below.

Table 4. CMS-Flow card for compressing the XMDF output file

Card Arguments Default value Description
XMDF_COMPRESSION ON | OFF OFF Compresses the h5 file by a factor of about 7

ASCII Output

In addition to the XMDF output file, CMS-Flow provides the output two types of ASCII output files:

  1. Tecplot snap shot (*.dat), and history files (*.his)
  2. SMS Super ASCII files (*.sup, *.xy, *.dat)

The CMS-Flow cards used for outputting these two types of files are described in the Table below.

Table 3. CMS-Flow cards used to output Tecplot and SMS Super ASCII files.

Card Arguments Description Default value
GLOBAL_TECPLOT_FILES ON | OFF Outputs Tecplot ASCII files OFF
GLOBAL_SUPER_FILES ON | OFF Outputs general ASCII solution files OFF

Output Cells

Figure 1. Cells tab in SMS 11.0

Time series at selected Obervation cells is set in the Cells tab of the CMS-Flow Model Control window. A description of CMS-Flow cards used for specifying Observational cells are described below.

Table 5. CMS-Flow card for compressing the XMDF output file

Card Arguments Description
TIME_SERIES_INCREMENT REAL Sets the output time increment for the Time series Observation points.
ELEV_OBS_CELLS_BEGIN none Marks the begging of an Times series Observation point list.
ELEV_OBS_CELLS_END none Marks the end of an Times series Observation point list.
FLOW_RATE_INCREMENT REAL Sets the output time increment for the Flow rate Observation points.
FLOW_OBS_CELLS_BEGIN none Marks the end of an Flow rate Observation point list.
FLOW_OBS_CELLS_END none Marks the end of an Flow rate Observation point list.
Q_TRANS_INCREMENT REAL Sets the output time increment for the Flow rate Observation points.
Q_TRANS_OBS_CELLS_BEGIN none Marks the end of an Transport Observation point list.
Q_TRANS_OBS_CELLS_BEGIN none Marks the end of an Transport Observation point list.



Statistics

CMS V4.0 has the option to calculate statistics over the whole model domain for a user-specified time period. This option is accessed using the advanced cardss. The starting time, end time, and time interval should be specified in hours with respect to the model start time. The time interval should be larger or equal to the hydrodynamic time step. When activated the global statistics will be output in the same solution file within a subfolder named stats.

This option outputs the statistics for hydrodynamics, sediment and salinity transport. If only the statistics for one group

  • Hydrodynamics:
  1. Maximum current velocity
  2. Maximum water level
  3. Residual currents (vectors and magnitude)
  4. Hydroperiod
  5. Maximum spatial gradient for water levels
  6. Maximum spatial gradient for current magnitude
  • Sediment Transport and Morphology Change:
  1. Maximum total load transport rate, m^2/s
  2. Net total load sediment transport rates, m^2/s
  3. Average total load sediment transport rates, m^2/s
  4. Gross total load sediment transport rates, m^2/s
  5. Positive and negative total load transport rates (in x and y directions), m^2/s
  6. Maximum spatial gradient of bathymetry
  • Salinity Statistics:
  1. Mean Salinity

Table 6. CMS-Flow cards related to output statistics

Card Arguments Description Default value Notes
GLOBAL_STATISTICS [t0] [tn] [dt] Calculates global statistics if specified none [start] [end] [increment]
FLOW_STATISTICS [t0] [tn] [dt] Calculates flow statistics if specified none [start] [end] [increment]
SEDIMENT_STATISTICS [t0] [tn] [dt] Calculates sediment statistics if specified none [start] [end] [increment]
SALINITY_STATISTICS [t0] [tn] [dt] Calculates salinity statistics if specified none [start] [end] [increment]

Numerical Methods

Solution Scheme

This refers to the temporal discritization of the hydrodynamic, sediment and salinity transport equations. There are two options in CMS: 1. Implicit - First order backward Euler scheme. Uses a time step on the order of 5-15 minutes. Appropriate for cases which can be simulated with large computational time steps such as long term morphology change at inlets. 2. Explicit - First order forward Euler scheme. Uses a time step on the order of 0.5-1.0 second. Appropriate for cases that vary quickly in time such as flooding or barrier island breaching.

Card Arguments Default Range Description
SOLUTION_SCHEME CHARACTER EXPLICIT EXPLICIT | IMPLICIT Determines the solution scheme used in CMS-Flow.

Solver Options

The four different solvers implemented in the implicit solution scheme are the Gauss-Seidel, Gauss-Seidel with Successive-Over-Relaxation, BICGSTAB, and GMRES. 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.

Card Arguments Default Range Description
MATRIX_SOLVER CHARACTER GMRES GAUSS-SEIDEL | GAUSS-SEIDEL-SOR | BICGSTAB | GMRES Selects the matrix solver for flow, sediment and salinity.
HYDRO_MAX_ITERATIONS INTEGER Function of grid size >0 Sets the maximum number of iterations for the flow (hydro) solver (outer loop). Typical range: 30-50 for GAUSS-SEIDEL and GAUSS-SEIDEL-SOR, and 20-30 for BICGSTAB and GMRES.
PRESSURE_ITERATIONS INTEGER Depends on Solver >0 Sets the number of solver iterations for the pressure equation (inner loop). Typical range: 80-100 for GAUSS-SEIDEL and GAUSS-SEIDEL-SOR, and 15-25 for BICGSTAB and GMRES.
VELOCITY_ITERATIONS INTEGER Depends on Solver >0 Sets the number of solver iterations for the velocity or momentum equations (inner loop). Typical range: 20-30 for GAUSS-SEIDEL and GAUSS-SEIDEL-SOR, and 5-10 for BICGSTAB and GMRES.
SEDIMENT_MAX_ITERATIONS integer 20 >0 Maximum number of iterations (outer loop) for the sediment transport
SALINITY_MAX_ITERATIONS integer 20 >0 Maximum number of iterations (outer loop) for the salinity transport

Advection scheme

As in the case of the implicit solution scheme, the same advection scheme is applied for the flow, sediment and salinity transport equations. There are three choices for advection schemes with upwinding in the implicit model: hybrid, exponential and HLPA. The hybrid scheme is fast but is the most diffusive. The exponential scheme is based on the 1D analytical solution to an 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

Table 5. CMS-Flow cards related to numerical methods.

Card Arguments Default Range Description
ADVECTION_SCHEME CHARACTER EXPONENTIAL NONE | HYBRID | EXPONENTIAL | HLPA Sets the advection scheme for flow, sediment and salinity.

Wetting and Drying

Table 5. CMS-Flow cards related to numerical methods.

DRYING_DEPTH REAL Calculated based on solution scheme and courant number none Sets to the time step for hydrodynamics in seconds.
WATER_PONDING CHARACTER OFF ON | OFF Turns On or Off water ponding. If water ponding is Off, isolated bodies of water will become dry.
ONE_CELL_WIDE_CHANNELS CHARACTER ON ON | OFF Limits wetting and drying to areas with at least 3 cells wide. When turned off, the model stability is improved.

Parallelization with OpenMP

Both Intel and AMD processors now are shipping chips with multiple cores/processors (henceforth referred to as "processors") available. CMS-Flow is now configured to make use of these extra processes that are available on newer machines.

Additional information on using Multiple Processors with CMS-Flow can be found here.

Table 5. CMS-Flow cards related to numerical methods.

Card Arguments Default Range Description
NUM_THREADS INTEGER 1 Determines the number of threads used for parallel processing.
OPENMP_THREADS INTEGER 1 Determines the number of threads used for parallel processing.

Scripting

Scipting refers to the automation of running multiple CMS runs with different parameters, without manually having to create and edit each alternative. The scripting process can include the following steps:

  1. Setting up alternatives
  2. Creating batch file
  3. Plotting and analyzing results

Scripting can be done using a variety of software programs. The examples shown here were written in Matlab becase it is widely used, easy to read and convenient for plotting and analyzing results.

Setting Up Alternatives

Figure 1. Example of scripting showing the files used.

In this example, 4 cases or alterantives are setup using the Matlab script below. The script copies the base setup files into subfolders and then modifies specific CMS-Flow cards in the *.cmcards file. The settings for each case are setup using a structure variable with field names corresponding to each CMS-Flow card (e.g. TIME_SERIES_INCREMENT). Separating each case into its own subfolder keeps the input and output separate and also allows for the different cases to be run at the same time.


% Matlab Script: setup_cases.m
clear all
flow = 'Flow_Shark';
wave = 'Wave_Shark';
ncases = 4; %Number of cases or alternatives  
r(1).MANNINGS_N_DATASET = '"Manning_Alt1.h5" "Flow_Shark/Datasets/ManningsN"';
r(1).WAVE_CURRENT_MEAN_STRESS = 'W09';
r(1).TIME_SERIES_INCREMENT = 1800;
r(2).MANNINGS_N_DATASET = '"Manning_Alt1.h5" "Flow_Shark/Datasets/ManningsN"';
r(2).WAVE_CURRENT_MEAN_STRESS = 'DATA2';
r(2).TIME_SERIES_INCREMENT = 900;
r(3).MANNINGS_N_DATASET = '"Manning_Alt2.h5" "Flow_Shark/Datasets/ManningsN"';
r(3).WAVE_CURRENT_MEAN_STRESS = 'W09';
r(3).TIME_SERIES_INCREMENT = 900;
r(4).MANNINGS_N_DATASET = '"Manning_Alt2.h5" "Flow_Shark/Datasets/ManningsN"';
r(4).WAVE_CURRENT_MEAN_STRESS = 'DATA2';
r(4).TIME_SERIES_INCREMENT = 600;
for i=1:ncases
  d = ['Case',int2str(i)];
  if ~exist(d,'dir')
    mkdir(d)
  end
  copyfile([wave,'.*'],d)
  copyfile([flow,'.*'],d)
  copyfile([flow,'_mp.h5'],d);
  copyfile([flow,'_grid.h5'],d)
  cards = fieldnames(r(i));
  file = ['.\',d,'\',flow,'.cmcards'];
  fork=1:length(cards)
    setcard(file,cards{k},r(i).(cards{k})); 
  end
end
return

The script above requires the subroutine below.

function setcard(cmcardsfile,card,value)
% setcard(file,card,value)
% Overwrites or appends a CMS-Flow card
% in the *.cmcards file
copyfile(cmcardsfile,'temp')
fid=fopen('temp','r');
fid2=fopen(cmcardsfile,'w');
nc=length(card);
ok = false(1);
if ~ischar(value)    
  value = num2str(value);
end
while 1    
  tline = fgets(fid);        
  if ~ischar(tline), break, end    
  if strncmp(card,tline,nc)        
    fprintf(fid2,'%s       %s %s' ,card,value,tline(end));                
    ok = true(1);        
    continue    
  end    
  nline = length(tline);    
  if (~ok && strcmp(tline(1:min(nline,14)),'END_PARAMETERS'))        
    fprintf(fid2,'%s       %s %s',card,value,tline(end));        
    fprintf(fid2,'%s' ,tline);        
    break 
  end    
  fprintf(fid2,'%s' ,tline);
end
fclose(fid);
fclose(fid2);
delete('temp')
return

Batch File

Although it is possible to launch CMS from Matlab a batch file is preferable to use a batch file because it allows running all of the cases without opening Matlab.

% Matlab Script: create_bat.m
cmsexe = 'cms2d_v4b42_x64p.exe'; %CMS-Flow executable
batfile = 'run_cases.bat'; %Output batch file
fid = fopen(batfile,'w');
for i=1:ncases 
  cmcards = ['.\Case',int2str(i),'\',flow,'.cmcards']; %CMS-Flow cmcards file
  fprintf(fid,'START %s %s %s',cmsexe,cmcards,char(10)); 
end
fclose(fid);
return

The following text shows what the resulting batch file (*.bat) looks like

START cms2d_v4b42_x64p.exe .\Case1\Flow_Shark.cmcards
START cms2d_v4b42_x64p.exe .\Case2\Flow_Shark.cmcards
START cms2d_v4b42_x64p.exe .\Case3\Flow_Shark.cmcards
START cms2d_v4b42_x64p.exe .\Case4\Flow_Shark.cmcards

To run the batch file, simply double click on the file and each case will launch separately in its own MS-DOS window.

Plotting

The following example reads the Observation Point time series output file (*_eta.txt) and plots the 3rd


% Matlab Script: plot_cases.m
close all 
eta = cell(ncases,1); 
for  i=1:ncases    
  etafile = ['.\Case' ,int2str(i),'\',flow,'_eta.txt' ]; %Water elevation
  eta{i} = load(etafile);    
end
figure
hold on
for i=1:ncases    
  h = plot(eta{i}(:,1),eta{i}(:,3),'-');  %3 is the index is the observation point index
end
ylabel('Water elevation, m')
xlabel('Elapsed Time, hr')
return


Units of Measurement

Variable Units Symbol
Water Surface Elevation meters
Current Velocity meters per second
Flow Rate cubic meters per second
Salinity Concentration parts per thousand
Sediment Concentration kilogram per meter cubed
Sediment Transport meter squared per second
Bed Shear Stress kilogram per meter per second squared

CMS-Flow