CMS-Wave User Guide Part 1: Model Setup
CIRP-WN-12-2
Purpose
In this Part 1 hands-on instruction set for CMS-Wave, we provide a step-by-step user guide for setting up CMS-Wave. The Shark River Inlet, NJ is used as an example to demonstrate these steps. Part 1 of User Guide covers grid generation, preparation of input wave spectra, model parameters, structure types, wave runup and overtopping, and description of CMS-Wave post-processing MATLAB and FORTRAN codes. These are discussed in the following sections.
Grid Generation
The standard method to generate a CMS-Wave grid is the same as generating grids for the CMS-Flow in the Cartesian Grid module. Make sure you are in the CMS-Wave mode (Data | Switch Current Model and select CMS-Wave). Start the Cartesian grid generation from the grid origin location, which is the 1st point user clicks in the grid generation process. The x axis (positive direction) needs to point towards the shoreline and y axis needs to be parallel to the shoreline. CMS-Wave grids are typically generated from scatter datasets, but can be a mirror image of the flow grid if the boundary condition (BC) locations are close enough to force both the tide and waves from the same BC area. In the near future, CMS will have the option to be run fully inline, where only one grid will contain all of the information needed to run both CMS-Wave and CMS-Flow. The CMS-Wave IJ triad should be adjusted where the I-direction is pointing in the dominant wave direction, or more specifically from the open ocean. This means that it will be 180 deg off as compared to the CMS-Flow grid. Therefore, after the CMS-Flow grid is generated, the model domain should be set to include all major reaches of the bay, extending laterally a couple kilometers from the inlet and extending seaward well beyond the anticipated reach of the ebb jet. A good rule of thumb for setting the ocean boundary for inlet modeling is to place the boundary three or four times the length of the ebb jet (leaving provision for extreme discharges, such as during storm surge). The given bathymetry ends at approximately four times the length of the ebb jet at Shark River.
Transforming the CMS-Flow grid to a CMS-Wave Grid
- Open one of the generated grids rt-click the Grid in the SMS list, and click on Duplicate, select the copied grid (copy) to activate it, and go to Data, Switch Current Model (Figure 1).# Change the Model from CMS-Flow to CMS-Wave, click OK, and rename the grid by rt-clicking on the copy name and clicking Rename,
- Set the jetty and groin cells to rubble-mound type structures by selecting the cells (Figure 2), and rt-click, Cell Attributes.., and select a Rubble-mound from the Structure Type, click OK.
- File, Save As, Wave.sim (selecting the Save As Type as a .sim for simulation) in the folder with the CMS-Flow grid.
Model Control and Input Spectra
Now that all modifications to the CMS-Wave grid are complete, the spec-tral waves or wave parameters can be generated for the wave grid. Full (directional) spectra can be imported into the SMS for the CMS-Wave, as well as simplified wave parameters (angle, wave height, and period, etc).
Adding Wave Parameter Generated Spectra to CMS-Wave
- Click on CMS-Wave, Spectral Energy, and select Create Grid (wave spectra can be imported),
- Click OK for the default spectral properties, and then click Generate Spectra to bring up the window to input wave parameters (Figure 3),
- Open the Excel spreadsheet 44025buoy_199902.xls and select the wave parameters (1 month, Feb 1999), copy and paste this into the Generate Spectra – Spectral Parameters section (Figure 3), click Generate, OK.
- Go to CMS-Wave, Model Control, and turn on Allow wetting and drying and Bed friction (Figure 4).
- Users can also specify constant or varied forward and backward reflection coefficients in Settings.
- Water level and wind information are optional source as speci-fied under Wave Source in addition to the spectral input data.
- File, Save As, Wave.sim (selecting the Save As Type as a .sim for simulation) in the folder with the CMS-Flow grid.
Directional spectral data collected by NDBC or CDIP buoys can be pro-cessed as alternative source for wave input to CMS-Wave. Two examples are given below using CDIP 154 and NDBC 44025 standard spectral files for December 2009.
NDBC buoy data
Run ndbc-spectra.exe (FORTRAN) to read the NDBC standard directional wave file and generate the CMS-Wave input spectral *.eng.
- Download the NDBC standard monthly directional wave spectral file from http://www.nodc.noaa.gov/BUOY/buoy.html (e.g., 44025_200912) - see Figs 7 to 10 for accessing NDBC spectral data from the Web.
- In the DOS window, run ndbc-spectra.exe
- Responding to the on-screen input, type the NDBC spectral filename
- Type the starting timestamp (default value is 0) for saving output files
- Type ending timestamp (default is 99999999) for saving output files
- Type the time interval (hr) for saving output data
- Type 2 to save the CMS-Wave *.eng and *.txt files
- Type the CMS-Wave input spectrum filename (*.eng)
- Type the local shoreline orientation (the CMS-Wave grid y axis) in clockwise polar coordinates (deg, positive from North covering the sea, e.g., 180 deg for St Mary’s Entrance, FL/GA, or 360 deg - the wave grid orientation angle in *.sim)
- Type the NDBC buoy location water depth (m) and then the CMS-Wave seaward boundary mean water depth (m), e.g. Buoy 44025 has a nominal depth of 36.3 m relative to Mean Sea Level
- Type 1 to include wind or 0 to skip the wind input information
- Type 1 or 2 or 3 for different choice of calculated frequency bins to complete the run – see Fig 36 for running ndbc-spectra.exe in DOS.
- The output files include *.txt, *.eng, *.out (time series of wave parameters at the buoy), and *.dat (time series of shoreward wave parameters at the CMS-Wave offshore boundary).
Figure 7. NODC buoy data access website.
Figure 8. NODC buoy data access world map.
Figure 9. NODC buoy data access regional map.
Figure 10. NODC buoy spectral data download website.
Figure 11. Run ndbc-spectra.exe in DOS.
CDIP buoy data
Run cdip-spectra.exe in the DOS window similar to ndbc-spectra.exe – see Figs 12-15. Because CDIP spectral file already contains the buoy location depth information, cdip-spectra.exe will not prompt for this depth input. For processing either NDBC or CDIP data, users shall check and manually fill any data gaps in *.eng and *.txt files (using the first available spectral data from the neighboring time interval).
Figure 12. CDIP buoy data access website.
Figure 13. CDIP buoy data access website.
Figure 14. CDIP buoy data spectral data download website.
Figure 15. Run cdip-spectra.exe in DOS.
Model Parameters
When user saves a *.sim file in SMS, the following files are also saved automatically: *.dep (depth info), *.std (model parameters), and *.struct (feature cells) files. Only *.sim and *.dep are required to open *.sim in SMS. To run CMS-Wave, only four input files are required: *.sim, *.std, *.dep, and *.eng. CMS-Wave parameters can be specified in SMS under the CMS-Wave | Model control. If any new parameters have not yet been included in the SMS version being used, these need to be specified manually in the *.std file.
Additional CMS-Wave input files which are optional are: *.cur (current field input), *.eta (water surface field input), *.txt (summary of input wave parameters), *.struct , friction.dat (bottom friction coefs field), forward.dat (forward reflection coefs field), backward (backward reflection coefs field), and mud.dat (mud-bed turbulent viscosity coef field) are optional.
The *.std file should appear as shown below (e.g., Wave_HB.std)
0 0 0 0 2 0 0 3 0 0 4.0 0.0250 0.500 0.300 0 1 0 0 2 1 53 292 202 244
The first row shows the model parameters. The first six parameters are required, and the rest (up to a total of 25 parameters) are optional. The optional second and more rows are the special output locations. These are specified as nodal indices in x and y direction for each output location per line. These special output points are also called as wave monitoring stations where model output is desired. For the child grid these can serves as the wave input stations.
The 25 model parameters are (in sequential order)
iprp icur ibrk irs kout ibnd iwet ibf iark iarkr akap bf ark arkr iwvbk nonln igrav isolv ixmdf iproc
Description of each parameter follows:
iprp = 0, for wave generation and propagation (use wind input if provided)
iprp = 1, for propagation only (neglect wind input)
iprp = -1, for fast-mode simulation (for wave generation and propagation)
icur = 0, no current
icur = 1, with current input (*.cur), using data sets in the sequential order
icur = 2, with current input (*.cur), using only the first set current data
ibrk = 0 (no *.brk file)
ibrk = 1, for output of wave breaking indices (*.brk)
ibrk = 2, for output of energy dissipation fluxes (*.brk)
irs = 0 (no *.rad file)
irs = 1, for output of wave radiation stresses (*.rad)
irs = 2, for output of wave radiation stresses (*.rad) and wave setup/maximum water level (setup.wav)
irs = 3, for automatic wave run-up calculation
kout = 0 (no *.obs and selhts.out files)
kout = n, for output of spectra (*.obs) and parameters (selhts.out) at n selected cells
ibnd = 0 (no *.nst file)
ibnd = 1, for nested grid, with linear interpolation of boundary input spectra (*.nst)
ibnd = 2, for nested grid, with morphic interpolation of boundary input spectra (*.nst)
iwet = 0, for normal wetting/drying (use water level input)
iwet = 1, no wetting/drying (neglect water level input)
ibf = 0, no bottom friction
ibf = 1, for bottom friction with constant Darcy-Weisbach type coefficient (= bf)
ibf = 2, for bottom friction with variable Darcy-Weisbach type coefficient (friction.dat)
ibf = 3, for bottom friction with constant Manning coefficient (= bf)
ibf = 4, for bottom friction with variable Manning coefficient (friction.dat)
iark = 0, no forward reflection
iark = 1, with forward reflection
iarkr = 0, no backward reflection
iarkr = 1, for backward reflection
akap = <value>, diffraction intensity factor (0 for no diffraction, 4 for strong diffraction)
bf = <value>, constant bottom friction coefficient
ark = <value>, constant forward reflection coefficient (0 for no reflection, 1 for maximum forward reflection)
arkr = <value>, constant backward reflection coefficient (0 for no reflection, 1 for maximum backward reflection)
iwvbk = 0, for Extended Goda (Sakai et al. 1989) wave breaking formula
iwvbk = 1, for Extended Miche (Battjes 1972; Mase et al. 2005b)
iwvbk = 2, for formula by Battjes and Janssen (1978)
iwvbk = 3, for formula by Chawla and Kirby (2002)
nonln = 0, no nonlinear wave-wave interaction
nonln = 1, with nonlinear wave-wave interaction
igrav = 0, no infra-gravity wave effect
igrav = 1, with infra-gravity wave effect
irunup = 0, no runup calculation
irunup = 1, output runup relative to Mean Water Level
irunup = 2, output runup relative to updated water level
imud = 0, with mud effect if a mud.dat file is provided
imud = 1, without mud effect
iwind = 0, with 2D wind field if a wind.dat file is provided
iwind = 1, without 2D wind field input
isolv = 0, for Gauss-Seidel solver with multi-processor capability
isolv = 1, for Alternative Direction Iterative solver
ixmdf = 0, for input/output in ASCII format
ixmdf = 1, for output in XMDF format
ixmdf = 2, for input/output in XMDF format
iproc = 0 or 1, with a single-processor (default)
iproc = n, with n processors (only valid with isolv = 1)
iview = 0, half-plane mode
iview = 1, full-plane mode for bay and inlet
iview = 2, full-plane mode for island(s) application
Iroll = wave roller intensity factor (0 for no effect, 4 for strong effect)
Structure Types
CMS-Wave calculates wave transmission, wave setup, wave runup, and overtopping as special features on selected cells. These cells can represent jetties, floating breakwaters, a bottom-mounted breakwater, or underwater features such as reefs or submerged structures. A trench or submerged mound can be added to the seabed as features without modifying the input depth file. These feature cells are specified in the *.struct file. Each feature cell is described by four parameters, istruc, jstruc, kstruc, and cstruc in the *.struct file.
istruc = i-th column in the grid
jstruc = j-th row in the grid
kstruc = 1, for adding alternative feature or structure (immersed or ex-posed) without modifying the input depth
kstruc = 2, for calculation of wave runup and overwash on beach face or structure, and adjacent land
kstruc = 3, for calculation of transmitted waves of a floating breakwater
kstruc = 4, for a vertical wall breakwater
kstruc = 5, for a composite or rubble-mound breakwater
kstruc = 6, for high porous breakwater
kstruc = 7, for low porous breakwater
cstruc = feature structure depth, for kstruc = 1 (assume a land cell if not provided)
cstruc = beach/structure elevation above mean water level, for kstruc = 2 (use the input depth if not provided; no effect for cstruc < 0)
cstruc = floating breakwater draft, for kstruc =3 (skip if not provided or cstruc < 0.05 m)
cstruc = breakwater/structure elevation, for kstruc = 4 or 5 (use the input depth if not provided; immersed if cstruc < 0)
cstruc = ambient water depth for kstruc = 6 or 7
Users can specify feature cells in SMS. For the Shark River example in Section 1:
- Open the CMS-Wave file, Wave_HB.sim,
- Click Select grid cell tool and proceed to select cells (use the polygon or click a cell while holding the Shift key or drag the mouth while holding the Ctrl key),
- Choose CMS-Wave | Assign Cell Attributes (see Fig. 16),
- Select Structure and choose Type (i.e., rubble-mound breakwater, wave run-up, etc.) for the proper cell features,
- Select Use modification for any new elevation or additional depth (or characteristic length quantity) and OK to exit.
Wave Run-up and Overtopping
Wave run-up is triggered by either providing the Type 2 feature cells in the *.struct file or setting the model parameter irs = 3, which will automatically trigger the wave run-up for the entire grid domain. The overtopping rate is calculated and reported at the special output wave monitoring stations or locations. The wave setup and maximum water level fields, including wave run-up, are saved in the setup.wav file.
Post-processing CMS-Wave Results
This section describes three FORTRAN codes, concatwav.exe, pkcmswave.exe, and pkcmswave1.exe to assist users in handling the CMS-Wave output information. Three MATLAB codes, fig1sets.m, fig2sets.m, and fig4sets.m, are provided to plot and compare calculated wave parameters and/or measured data (NDBC or CDIP buoys). These files can be downloaded from http://cirp.usace.army.mil/wiki/Utilities#Wave_Transformation. An example is provided as a simple CMS-Flow explicit steering run of the Shark River application (run 2009.sim and 2009.cmcards for a total of 12-hr simulation with 3-hr steering interval – a10-min run time with 3-processors assigned to CMS-Flow).
Concatwav.exe: This FORTRAN code merges all individual cycle *.wav files from a CMS-Flow explicit and CMS-Wave steering (coupling) run into one single *.wav. Running concatwav.exe requires the user enter a text file that lists all or more individual *.wav files in sequential order (one-column format). A sample text file concat.dat is provided (see: http://cirp.usace.army.mil/wiki/Utilities#Wave_Transformation) that includes the first 200 cycle *.wav filenames. If a modified copy of the standard *.std is created to overwrite all individual *.std files generated in the steering process with the 7th control parameter IWET set to -2 before running the steering, then CMS will concatenate the files and concatwav.exe does not need to be run. IWET = -2 will output a total.wav file include all individual cycle *.wav files. At the present time, users should manually prepare the std.dat file and set IWET = -2 for this option. In SMS11.1 and future SMS releases, users can simply set IWET = -2 in the standard *.std (the std.dat is no longer required). Follow these steps:
- In the DOS window, run concatwav.exe in the folder with all steering cycle *.wav files
- Responding to the on-screen input, type the name of a text file that lists all or more individual *.wav files in sequential order, or simply type the sample file ‘concat.dat’ that in-cludes the first 200 cycle *.wav filenames (by using ‘concat.dat’, the output total.wav will include up to a maxi-mum of 200 cycle *.wav) – see Fig. 17 to merge all 5 cycles *.wav into one total.wav file.
Pkcmswave.exe: This code will extract the calculated wave height, period and direction information from *.wav for a single cell in the model grid. The output file is ‘oneline.dat’ that lists the extracted wave information (in sequential order) using the Wave Information Studies (WIS) short format (11-column format: id, year, month, date, hour, sig wave height, peak period, mean period, mean wave direction, wind speed, wind direction). All directions are referenced in meteorological convention.
- In the DOS window, run pkcmswave.exe
- Responding to the on-screen input, type the CMS-Wave wave output *.wav filename
- Type the year (last two digits of a calendar year), e.g. type ‘11’ for 2011
- Type the local shoreline orientation (the CMS-Wave grid y axis) in clockwise polar coordinates (deg, positive from North covering the sea, e.g., 180 deg for St Mary’s Entrance, FL/GA, or 360 deg - the wave grid orientation angle in *.sim)
- Type single cell i and j indices (two integer numbers) saving wave parameter information
- Type the starting timestamp (default value is 0) and ending timestamp (default is 99999999) for saving output files. See Figure 18 to run pkcmswave.exe to extract wave information at Cell (69, 92) from total.wav.
Pkcmswave1.exe: This code will extract the calculated wave height, pe-riod and direction information from the monitoring station output file selhts.out (exists only if the monitoring station data is specified in the *.std) for a single station. The output file is ‘oneline.dat’ that lists the extracted wave information in the WIS short format. The selhts.out file has a 15-column format:
Column 1 - spectrum label (or timestamp)
Column 2 - i index in Cartesian (i,j)
Column 3 - j index in Cartesian (i,j)
Column 4 - significant wave height (m)
Column 5 - spectral peak wave period (sec)
Column 6 - mean wave direction (deg, local coordinate system)
Column 7 - swell height (m)
Column 8 - swell wave period (sec)
Column 9 - swell direction (deg)
Column 10 - local-generated wave height (m)
Column 11 - local-generated wave period (sec)
Column 12 - local-generated wave direction (deg)
Column 13 - wave breaking index (non-zero for breaking)
Column 14 - max water level mark (m) if calculated
Column 15 - flow discharge rate (m*m/sec) if calculated
Note: Specify IWET = -1 or -3 to save swell or local sea data in selhts.out (swell is shown in Columns 7 to 9, and local sea in Columns 10 to 12) and extra swell or local sea wave field files (swell.wav, sea.wav).
- In the DOS window, run pkcmswave1.exe
- Responding to the on-screen input, type the CMS-Wave monitoring station output filename (e.g., selhts.out)
- Type the year (last two digits of a calendar year) for the data, e.g. type ‘11’ for 2011
- Type the local shoreline orientation (the CMS-Wave grid y axis) in clockwise polar coordinates (deg, positive from North covering the sea, e.g., 180 deg for St Mary’s Entrance, FL/GA, or 360 deg - the wave grid orientation angle in *.sim)
- Type single cell i and j indices (need to be a monitoring sta-tion cell given in *.std)
- Type the starting timestamp (default value is 0) and ending timestamp (default is 99999999) for saving output files. See Figure 19 to run pkcmswave1 to extract wave information for Cell (69, 92) from selhts.out.
Fig1set.m (or fig1set.exe): This MATLAB and FORTRAN code reads a WIS short format file and plots the time series of wind and wave parameter data.
- In the MATLAB console, go to the folder with the fig1set.m code, type ‘fig1set’ and press Enter to run (or in the DOS folder, run fig1set.exe)
- Responding to the on-screen input window, browse and open (read) the WIS sort format file of interest (e.g., 4602509d.dat)
- Enter 1 for plots shown in the Metric system (m, m/sec) or 2 in English system (ft, knot)
- Type the year (last two digits of a calendar year) for the data, e.g. ‘11’ for 2011
- Type starting month id number in the plot, e.g. 1 for January, 2 for February, etc.
- Type ending month id in the plot, e.g. 3 for March, 13 for January of the following year, or enter 0 to input starting and ending dates in the same month
- Type starting and ending days to display the data plot or type “0 0” and Enter to skip this option
- Type the title (text) for the plot or simply press Enter to skip this option, to complete the run. See Fig. 20 to run fig1set.m or fig1set.exe to plot NDBC Buoy 44025 data (2009-ndbc.out) for December 2009.
Fig2sets.m (or fig2sets.exe): This code is similar to fig1set.m except it is capable of reading and plotting the time series of wind wave data from two or three WIS short format files. Run fig2sets.m following similar steps as for fig1set.m. See Fig. 21 to plot NDBC 44025 and CDIP 154 (2009-sp154.out) for December 2009.
Fig4sets.m (or fig4sets.exe): This code is similar to fig1set.m and fig2sets.m except it is capable of reading and plotting the time series of wind and wave data from three or four WIS short format files. Run fig4sets.m following similar steps similar as for fig1set.m and fig2sets.m. See Fig. 22 to plot NDBC 44025, CDIP 154, and these two sets of data transformed to the CMS-Wave grid offshore boundary (2009-ndbc.dat and 2009-sp154.dat).