CMS-Flow and CMS-Wave Model Coupling

Coupling is the process of passing information between different models (i.e. CMS-Flow and CMS-Wave) or grids. There are two types of coupling available: one-way coupling and two-way coupling. In one-way coupling information is passed only in one direction from one to another whereas in two-way coupling information exchanged between two models or grids. In CMS, one-way coupling of CMS-Wave and CMS-Flow is referenced simply as model forcing and two-way coupling is referred to as steering.

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:

1. 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.
2. 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.
3. 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.

Before coupling CMS-Wave and CMS-Flow, 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.

One-way coupling

User Specified Wave Datasets for CMS-Flow

SMS 10.1

In this approach, precomputed wave height, period and direction datasets are provided to CMS-Flow. The advantage of this approach is that any wave model can be used and that the waves do not have to be recomputed for multiple CMS-Flow runs. The disadvantage is that the currents are not included in the wave model calculation (one-way coupling). The second approach is to run CMS-Flow and CMS-Wave together or in Steering mode. The user must provide several datasets of information which has been mapped to the flow grid geometery.

1. Radiation stress gradient
2. Wave height
3. Wave period
4. Wave direction
5. Wave dissipation

CMS-Flow cards related to wave forcing (one-way coupling)

Card	Arguments	Type
WAVE_RSTRESS_DATASET	File name Dataset path	character
WAVE_HEIGHT_DATASET	File name Dataset path	character
WAVE_PERIOD_DATASET	File name Dataset path	character
WAVE_DIRECTION_DATASET	File name Dataset path	character
WAVE_DISSIPATION_DATASET	File name Dataset path	character

User Specified Flow Datasets for CMS-Wave

MISSING

Steering (Two-way coupling)

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.

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.

Figure 1. File Location tab within the SMS Preferences window.

• Check the CMS-Flow and CMS-Wave file names under the SMS Preferences menu (see Figure 1).

1. Click on Edit | Preferences.
2. 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

https://cirpwiki.info/wiki/CMS_Releases

Figure 2. SMS Steering Module for CMS v3.75 and older.

• Start Steering Module to run the CMS

1. Open the SMS Steering Wizard by clicking on the menu Data | Steering Module.
2. Click on CMS-Flow - CMS-Wave, click next,
3. Enter the steering interval next the Time section.
4. Check the variables which should be passed from one model to the other.
5. Click Start.
6. 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 steering interval, in hours.
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 information 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.

Figure 3. Changing the CMS-Flow model executable.

• Check the CMS executable file name under the SMS preferences menu (see Figure 2).

1. Click on Edit nowiki|/nowiki Preferences.
2. 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 https://www.xmswiki.com/wiki/SMS:Steering

Products). Although both CMS-Flow and CMS-Wave are in the same executable, the inline CMS version is

• Notes:

1. 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.
2. 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.

Figure 4. Changing the CMS-Flow model executable.

• Check the CMS executable file name under the SMS preferences menu.

1. Click on Edit nowiki|/nowiki Preferences.
2. 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

https://www.xmswiki.com/wiki/SMS:CMS-Flow_Menu

Figure 5. Setting the CMS steering information.

• Set the steering information.

1. Click on CMS-Flow nowiki|/nowiki Model Control…
2. 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.

Figure 6. Example of launching the inline CMS-Flow steering run.

• Start Steering Module

1. Click on CMS-FLOW | Run
2. In the SMS Steering Wizard select the CMS INLINE option and click on the Next button.
3. Enter the Steering Interval under the Time section and and click on the Start button.

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.

• There are three mean approaches for running CMS as a standalone program

1. From a command prompt
2. Double click on the CMS executable or shortcut to the executable.
3. Drag-and-Drop the CMS input files on the CMS executable or shortcut to the executable.

Notes:

1. 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.
2. To pause the simulation, press the Pause/Break button on your keyboard.
3. To stop the model simulation, press and hold the Ctrl key and press the C key.

Command Prompt

The first step is to open a command prompt. There are two ways of doing this:

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

Figure 8. Example of launching the inline CMS-Flow steering run.

• The second method for opening a command prompt

1. Click on Windows Start menu then click on Run….
2. In the Run window, enter the command cmd and click OK

• Note:

It is recommended to put a shortcut to the Command Prompt for easier access.

Once the command prompt is open the CMS can be lauched using one of the following syntax

[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

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:

1. The sim and cmcards files must contain the full or relative path with respect to the executable if different from the executable.
2. 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.
3. If the cmcards file is specified the CMS will check for the steering cards.
4. If the sim file is found, than it will run in steering.
5. 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.
6. If no wave water level option is specified in the cmcards file or the command line, than a default method equal to three.
7. 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.

• Below are some examples

  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

Drag-and-Drop

To launch CMS as a standalone application using the drag-and-drop method:

1. Select all of the CMS input files by holding the Ctrl key and single-clicking on each input file.
2. Drag all of the input files on the CMS executable or shortcut to the executable by holding the left mouse button.
3. Drop the the files by letting go of the left mouse buttom.

• Note: If running steering, make sure all of the steering options are in the cmcards file when using the method.

Double-Click

Figure 9. Example of running CMS by double clicking on the executable.

This is one of the easiest ways of running the CMS but also one of the most time consuming because it requires the user to type the name and path (if different from executable) for all of the input files and if necessary the steering options.

• To run the CMS by using the Double-Clik method:

1. Double-click on the executable
2. Follow the instructions on the screen.

• Note: If CMS input files are not in the same folder as the executable, the file names must include the full or relative path with respect to the executable.