CMS-Flow:Features
Steering
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.
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.
- Notes:
- 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.
- 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.
- 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.
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.
- Make sure both the CMS-Flow and CMS-Wave grids are loaded in SMS.
- 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).
- Start Steering Module to run the CMS
- Open the SMS Steering Wizard by clicking on the menu Data | 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.
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.
Table 1. CMS-Flow cards related to steering
Card | Arguments | Default | Range | Description |
---|---|---|---|---|
CMS-WAVE_SIM_FILE | CHARACTER | none | none | File name including path for the CMS-Wave sim file. |
WAVE_SIM_FILE | CHARACTER | none | none | Same as CMS-WAVE_SIM_FILE. |
STEERING_INTERVAL | REAL | none | none | Sets the recurring hot start output time. |
WAVE_WATER_LEVEL | CHARACTER | TIDAL_PLUS_VARIATION | LAST | TIDAL | TIDAL_PLUS_VARIATION | Determines the method used to calculate the water levels passed to the wave model. |
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.
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.
- Check the CMS executable file name under the SMS preferences menu (see Figure 2).
- Click on Edit | 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
- 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
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.
- Make sure both the CMS-Flow and CMS-Wave grids are loaded in SMS.
- Check the CMS executable file name under the SMS preferences menu.
- 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).
- Set the steering information.
- Click on CMS-Flow | 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.
- Start Steering Module
- 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.
Command Line
Because the inline CMS does all of the steering internally, 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.
- The steering information may be specified either through the advanced cards as
- >> cms2d_*.exe [*.cmcards]
- or command line arguments.
- >> cms2d_*.exe [*.sim] [*.cmcards] [steering interval] [wave water level option]
- Notes:
- It is possible to create a short-cut to the model executable and simply drag-and-drop the cmcards 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 model 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.
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
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
Card | Arguments | Default | Range | Description |
---|---|---|---|---|
HOT_START_OUTPUT_FILE | CHARACTER | none | none | Julian hour. |
HOT_START_TIME | REAL | none | none | Sets the hot start output time. |
AUTO_HOT_START_INTERVAL | REAL | none | none | Sets the recurring hot start output time. |
Initial Conditions 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. 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 |
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
- Click on Data | Data Calculator
- Export the initial condition datasets to an XMDF file
Table 3. CMS-Flow card for specifying the initial condition file.
Card | Arguments | Default | Range | Description |
---|---|---|---|---|
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. |
Output
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.
Card | Aguments/Format | Default value | Description |
---|---|---|---|
TIME_SERIES_1 | [length of list] [time series list] | 0 | Output time series for list 1 in hours. |
TIME_SERIES_2 | [length of list] [time series list] | 0 | Output time series for list 2 in hours. |
TIME_SERIES_3 | [length of list] [time series list] | 0 | Output time series for list 3 in hours. |
TIME_SERIES_4 | [length of list] [time series list] | 0 | Output time series for list 4 in hours. |
TIME_LIST_1 | [number of lists] [List 1: start, end, increment] [List 2: start, end, increment]... | 0 | List(s) of time series output entered in hours. For each list, the arguments are starting time, end time and increment. |
TIME_LIST_2 | [number of lists] [List 1: start, end, increment] [List 2: start, end, increment]... | 0 | List(s) of time series output entered in hours. For each list, the arguments are starting time, end time and increment. |
TIME_LIST_3 | [number of lists] [List 1: start, end, increment] [List 2: start, end, increment]... | 0 | List(s) of time series output entered in hours. For each list, the arguments are starting time, end time and increment. |
TIME_LIST_4 | [number of lists] [List 1: start, end, increment] [List 2: start, end, increment]... | 0 | List(s) of time series output entered in hours. For each list, the arguments are starting time, end time and increment. |
WAVE_OUT_TIMES_LIST | integer | 0 | Output time series id for wave height, period, and vector. |
EDDY_OUT_TIMES_LIST | integer | 0 | Output time series id for eddy viscosity in m^2/s. |
VISC_OUT_TIMES_LIST | integer | 0 | Output time series id for eddy viscosity in m^2/s. Same as EDDY_OUT_TIMES_LIST |
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. |
BED_SHEAR_STRESS_OUT_TIMES_LIST | integer | 0 | Output time series id. Same as BED_SHEAR_STRESS_OUT_TIMES_LIST |
GLOBAL_TECPLOT_FILES | ON | OFF | OFF | Outputs Tecplot ASCII files |
GLOBAL_SUPER_FILES | ON | OFF | OFF | Outputs Tecplot ASCII files |
XMDF File
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.
Table 3. CMS-Flow card for compressing the XMDF output file
Card | Arguments | Description | Default value |
---|---|---|---|
XMDF_COMPRESSION | ON | OFF | Compresses the h5 file by a factor of about 7 | OFF |
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
- The hydrodynamic statistics output are:
- 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/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
- Mean Salinity
Table 3. CMS-Flow cards related to output statistics
Card | Arguments | Description | Default value |
---|---|---|---|
GLOBAL_STATISTICS | [t0] [tn] [dt] | Calculates global statistics if specified | none |
FLOW_STATISTICS | [t0] [tn] [dt] | Calculates flow statistics if specified | none |
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
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)
- 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 4. 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 Tecplot ASCII files | OFF |
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). |
PRESSURE_ITERATIONS | INTEGER | Depends on Solver | >0 | Sets the number of solver iterations for the pressure equation (inner loop). |
VELOCITY_ITERATIONS | INTEGER | Depends on Solver | >0 | Sets the number of solver iterations for the velocity or momentum equations (inner loop). |
SEDIMENT_MAX_ITERATIONS | integer | 20 | 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 |
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:
- Setting up alternatives
- Creating batch file
- 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
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 |