CMS-Flow Geospatial Information

Horizontal Coordinate Systems and Conventions

Figure 1. CMS-Flow local coordinate system and grid angle conventions used in the Card and Telescoping Grid Files. The I and J axis indicate the CMS grid axis, while the X and Y axis indicate the global coordinate system.

CMS-Flow uses a local coordinate system in which all vector values are positive along the I and J axis (Figure 1). All output vector arrays are specified in the local coordinate system. Any input that is specified on the local grid must be specified in the local coordinate system (e.g. initial condition for currents, interpolated wave forcing, etc). If input vector arrays are specified on a different grid, such as a spatially variable wind field or waves on a CMS-Wave grid, then the vectors are assumed to follow the coordinate system of their native grid. The grid is always created in SMS with the origin is by default always at the lower left hand corner of the grid.

In the SMS, the term “projection” refers to a horizontal map projection such as “State Plane” or “Geographic”. Within the software, a global projection can be associated with a project. Individual datasets may also have their own projections, which if properly associated with their original reference, can be displayed without the global projection reference. Previous versions of the SMS software referred to projections as “coordinate systems” and reprojection as “coordinate conversion”. The projection for the project can be specified from the Edit | Projection pull-down menu command. Changing the projection does not alter the coordinates of the project data. To change the projection of the individual project data, the dataset must be reprojected to the common reference system. The CMS models operate in a Cartesian coordinate system such as State Plane or UTM. Currently in SMS 11.1 the horizontal projection information in the grid file (*_grid.h5). The projection of the CMS-Flow simulation may be different from that of the grid and is specified in the CMS-Flow Control File. Specifying the projection information in the Control File is only necessary if any model input (such as wind or parent grids) is specified in any other projections. Otherwise the CMS assumes that all the horizontal projections are the same and no internal conversions are necessary. The table below describes the CMS-Flow cards used to specify the horizontal projection.

Table 11. CMS-Flow cards related to the single tidal water level boundary condition.

Input	Card Format	Notes
Start of Horizontal Projection Block	[begin=HORIZONTAL_PROJECTION_BEGIN, version=4.0, block=HorizProj, children=(HorizDatum,HorizCoord,HorizZone,HorizUnits)]	Begins the block structure for specifying the horizontal projection.
Horizontal Datum	[card=DATUM, parent=HorizProj] [arg=HorizDatum, type=char, options=(NAD27,NAD83,LOCAL), default=LOCAL]	Specifies the horizontal datum.
Horizontal Coordinate System	[card=SYSTEM] [arg=HorizCoord, type=char, options=(STATE_PLANE,UTM,GEOGRAPHIC,LOCAL), default=LOCAL, parent=HorizProj]	Specifies the horizontal coordinate system.
Horizontal Zone	[card=ZONE] [arg=HorizZone, type=int, default=none, parent=HorizProj]	Specifies the horizontal zone (only valid for UTM and State Plane Coordinate Systems).
Horizontal Units	[card=UNITS] [name=HorizUnits, type=char, options=(METERS,FEET,DEGREES,RADIANS),default=METERS, parent=HorizProj]	Specifies the units of the horizontal coordinate system.
End of Horizontal Projection Block	[end_block=HORIZONTAL_PROJECTION_END, version=4.0, block=HorizProj,childs=(HorizDatum,HorizCoord,HorizZone,HorizUnits)]	Ends the block structure for specifying the vertical projection.

Example of how to specify the horizontal projection information:

HORIZONTAL_PROJECTION_BEGIN !Optional
  DATUM           NAD83        !NAD27 | NAD83 | LOCAL 
  SYSTEM          STATE_PLANE  !UTM | STATE_PLANE | GEOGRAPHIC | LOCAL 
  UNITS           METERS       !METERS | FEET 
  ZONE            3104         !!Long Island, New York, Only if necessary 
HORIZONTAL_PROJECTION_END

A list of the supported horizontal datums, coordinate systems, or units are described in the following tables.

Table 2 12. Horizontal datums currently supported by CMS.

Datum	Description
LOCAL	Local datum. Set as the default datum. May be used when a coordinate system is not defined or working with idealized cases.
NAD27	Geographic coordinate system.
NAD83	Universal Transverse Mercator (UTM) coordinate system. 2D Cartesian coordinate system.

Table 2 13. Horizontal coordinate systems currently supported by CMS.

Coordinate Systems	Description
LOCAL	Local coordinate system. Set as the default coordinate system. May be used when a coordinate system is not defined or working with idealized cases.
UTM	Universal Transverse Mercator (UTM) coordinate system. 2D Cartesian coordinate system.
STATE_PLANE	State Plane coordinate system (also SPS or SPCS). Is divided into 124 geographic zones or coordinate systems designed for specific regions of the United States. Each State contains at least one zone.
GEOGRAPHIC	Geographic latitude and longitude coordinate system.

Table 2 14. Horizontal coordinate units (HorizUnits) currently supported by CMS.

Horizontal Units (HorizUnits)	Description
METERS	Units of meters only valid for State Plane and UTM coordinate system.
FEET	Units of feet only valid for State Plane and UTM coordinate system.
DEGREES	Units of degrees only valid for the Geographic coordinate system.
RADIANS	Units of radians only valid for the Geographic coordinate system.
SECONDS	Units of seconds only valid for the Geographic coordinate system.

Notes:

1. In the CMS V4.1, it is not possible to convert between datums NAD27 and NAD83, therefore all of the input horizontal projections must have the same datum.
2. Since the difference between the International Foot and US Survey Foot is 6.0960×10-7 m, the difference can be ignored for the purposes of coastal modeling modeling and not differentiation is made in CMS between the International Foot and US Survey Foot.

Vertical Coordinate System and Conventions

Figure 2. Schematic of showing the difference between MSL (tidal) and geodetic datums.

Water depths in CMS are positive and land elevations are negative. The vertical reference Datum in CMS is a local datum. Therefore, any vertical datum can be used by the user. However, it is important to note that the default initial water surface elevation is set to zero with respect to the local datum. In choosing the vertical datum for CMS it is important to understand the differences between tidal and geodetic datums. It is common to use both types of datums. However, the most appropriate datum type depends on the project application. Tidal datums are a standard elevation defined by a tidal statistic such as the arithmetic mean of mean high water and mean low water over a tidal epoch known as the Mean Tide Level or MTL. Therefore, tidal datums vary spatially and in time. This is an important difference with respect to Geodetic datums such NAVD88 which are fixed reference elevations determined by geodetic leveling. Tidal datums should not be used for projects where the tidal datums vary spatially. It is common for bays to have tidal setup or super elevation of the mean water level caused by wind, fresh water inflow, and bottom friction. This will cause a difference in the MTL in the bay with respect to the ocean as illustrated in Figure 4-3.

Currently, in CMS V4.1 the vertical projection information is only specified for metadata purposes and no internal conversions are performed yet. In the future, the goal is to be able to read in the vertical datum conversion conversions either from the model input files or to get them from an external database such as VDatum (http://vdatum.noaa.gov/welcome.html). A description of the cards used to specify the vertical projection is provided in the table below.

Table 15. CMS-Flow cards related to the single tidal water level boundary condition.

Card	Arguments	Description
Begin Vertical Projection Block	[begin=VERTICAL_PROJECTION_BEGIN, block=VertProj,version=4.0, childs=(VertDatum,VertUnits,VertOffset)]	Begins the block structure for specifying the vertical projection.
Vertical Datum	[card=DATUM, parent=VertProj] [name=VertDatum, type=char, options=(NGVD27,NAVD88,LOCAL,MSL,MTL,MLW,MLLW,MHW,MHHW), default=LOCAL]	Specifies the vertical datum.
Vertical Units	[card=UNITS, parent=VertProj] [name=VertUnits, type=char, options=(‘m’,‘ft’), default=‘m’]	Specifies the units of the vertical coordinate.
Vertical Offset	[card=OFFSET, comment=”positive is upwards”] [name=VertOffset, type=float, limits=none, parent=VertProj]	Specifies the vertical offset from the datum specified. Useful for referencing a local datum to a known vertical datum. Positive is upwards and negative is downwards.
Ends Vertical Projection Block	[end=VERTICAL_PROJECTION_END, block=VertProj,version=4.0, childs=(VertDatum,VertUnits,VertOffset)]	Ends the block structure for specifying the vertical projection.

Example vertical projection specification:

VERTICAL_PROJECTION_BEGIN !Optional
 DATUM           NAVD88       !NGVD29 | NAVD88 | LOCAL
 UNITS           ‘m'       !‘m’ | ‘ft’
 OFFSET          0.0 ‘m’     !Positive is upwards
VERTICAL_PROJECTION_END

The vertical offset is useful for referencing a local datum to a known vertical datum as in the example above. In CMS, the default initial water level (can be specified otherwise using a hot start file) and therefore it is common practice to use a vertical datum which is close to MSL. However, because MSL is a tidal datum and therefore varies spatially, it is more accurate to use a geodetic datum with an offset, so that the zero reference elevation of the local datum is close to MSL.

Table 2-16. Horizontal datums currently supported by CMS.

Datum	Description
LOCAL	Local datum. Set as the default datum. May be used when a coordinate system is not defined or working with idealized cases.
NGVD29	National Geodetic Vertical Datum of 1929
NAVD88	National Geodetic Vertical Datum of 1988
MSL	Mean Sea Level
MTL	Mean Tidal Level
MLW	Mean Low Water
MLLW	Mean Lower Low Water
MHW	Mean High Water
MHHW	Mean Higher High Water

Table 2 17. Horizontal coordinate units currently supported by CMS.

Units	Description
METERS	Units of meters only valid for State Plane and UTM coordinate system.
FEET	Units of feet only valid for State Plane and UTM coordinate system.

Notes:

1. If the project site is a small section of coastline with a small harbor or structures, then it is generally ok to use a tidal datum.
2. If the project site includes an estuary, it is recommended to use a geodetic datum.
3. When using a geodetic datum in combination with tidal constituent forcing, it is recommended to offset the entire bathymetry so that the geodetic datum matches the offshore MSL. The reason for this is that tidal constituent boundary assumes that the reference datum is MSL. In CMS V4.1 it is possible to specify the MSL with respect to the CMS-Flow vertical datum.
4. When using a geodetic datum in combination with water level time series, it is important to make sure the time series has the same geodetic datum as the bathymetry. In addition, an initial water level may be specified which is close to MSL (see the Hot Start section for details).
5. The units of the horizontal coordinate system should always be set to meters. By default, in SMS the horizontal units are set to feet. It is recommended to change the units to meters and save this setting by clicking on the menu File | Save Settings. This will save the horizontal projection and will be set every time SMS opens.
6. A good merged bathymetric dataset is often the result of spending 50% of the time it takes to get the model up and running just on checking and cleaning up the bathymetry alone. If a significant amount of time is spent paying attention to detail, there will be less instability problems in the hydrodynamic model which are difficult to trace back to the source.
7. Always double check that you have calculated your datum corrections very carefully by analyzing and comparing to nearby datasets.
8. When merging bathymetry, try both methods to combine the datasets and evaluate for depth consistency and dataset coverage.
9. Save often, and occasionally save new versions of your merge-testing in new folders. If you delete too much of one dataset, its useful to have the older, datum converted and unaltered datasets.

Cartesian Grids

Figure 3. Types of Cartesian grids supported by the SMS interface and CMS-Flow.

SMS supports regular and nonuniform Cartesian grids as well as regular and stretched telescoping grids (see Figure 4-4). Figure 3.

Regular Cartesian grids are the easiest to generate making them useful for feasibility type studies, simple field cases, or test runs for more complicated field cases. Nonuniform Cartesian grids allow local refinement by gradually varying the grid spacing. These grids are offer more flexibility than regular Cartesian grids for a relatively low additional cost in generation. Nonuniform Cartesian grids are available for both CMS-Flow and CMS-Wave. For large complex modeling domains, Telescoping grids offer the most flexibility by providing local refine through the subdivision or splitting of cells into four. In many cases, the hydrodynamics can be aligned with one of the Cartesian coordinates. For these cases, the number of grid cells can be reduced by using a stretched Telescoping grid. Currently in SMS, the stretched Telescoping grids can only have a constant aspect ratio between the grid resolution in the x and y directions. When a CMS-Flow project is saved, SMS writes an XMDF Grid File named “*_grid.h5”. If the grid is non-telescoping, this file contains the x and y coordinates as well as the water depths. If a telescoping grid is saved, then the SMS saves multiple-grids in the CMS-Flow XMDF Grid File which correspond to different levels of resolution of the telescoping grid. This information is only used by SMS. The information used in CMS when saving a telescoping grid is saved in the Telescoping Grid File with the extension “*.tel”. The Telescoping Grid File contains the cell coordinates, resolution, connectivity and water depths. A description of XMDF Grid File and the Telescoping Grid File along with Matlab scripts for reading these files are provided in Grid File (*_grid.h5) and Telescoping Grid File (*.tel) sections of Appendix A: Description of Input Files. All Cartesian grids can be characterized by a grid angle (orientation), origin coordinates. These grid parameters are saved to the Card File. The table below provides a description of the CMS-Flow cards used to specify the grid information in CMS.

Table 2 18. CMS-Flow cards related to the grid files and datasets.

Input	Format	Notes
XMDF Grid File	[card=GRID_FILE] [name=GridFile, type=char, default=”CaseName_grid.h5”]	Specifies the XMDF grid file
Telescoping Grid File	[card=TELESCOPING, CMS_version=4.0, SMS_version=11.0] [name=TelFile, type=char, default=”CaseName.tel”]	Specifies the telescoping grid file name.
Bathymetric Dataset	[card=BATHYMETRIC_DATASET] [name=BathyFile, type=char, default=GridFile] [name=BathyPath, type=char, default=”CaseName/Datasets/Depth”]	Specifies the bathymetric dataset file and path.
Grid Angle or Orientation	[card=GRID_ANGLE] [name=GridAngle, type=float] [name=GridAngleUnits, type=char, default=’deg’]	Specifies the grid angle measured counter-clockwise from the East direction to the grid i-axis (x-axis).
Grid Origin (x-coordinate)	[card=GRID_ORIGIN_X] [name=GridOriginX, type=float] [name=GridOriginUnits, type=char, default=’m’]	Specifies the x-coordinate for the Cartesian grid
Grid Origin (y-coordinate)	[card=GRID_ORIGIN_Y] [name=GridOriginY, type=float] [name=GridOriginUnits, type=char, default=’m’]	Specifies the y-coordinate for the Cartesian grid
Cell Center Latitudes	[card=CELL_LATITUDES] [name=LatFile, type=char, default=MPfile] [name=LatPath, type=char, default=”CaseName/Datasets/Depth”]	Specifies the latitudes at the cell centers.
Average Latitude	[card=AVERAGE_LATITUDE] [name=AvgLat, type=float] [name=AvgLatUnits, type=char, default=’deg’]	Specifies the average latitude for the grid which is used for the Coriolis parameter.

Example grid geometry specification:

!Grid Geometry
BATHYMETRY_DATASET    "Flow_Shark_grid.h5" "Flow_Shark/Datasets/Depth" 
GRID_ANGLE            13.0 deg    !Clock-wise from X-axes 
GRID_ORIGIN_X         186102.986504 m
GRID_ORIGIN_Y         145761.404499 m
CELL_LATITUDES        "Flow_Shark_mp.h5" "PROPERTIES/Model Params/Lats" 

If specified and average latitude is calculated for the grid and used to estimate the Coriolis parameter. By default the cell latitudes are stored in the XMDF Model Parameters File. For additional details on this file see XMDF CMS-Flow Model Parameters File (*_mp.h5).

Notes:

1. The grid angle specified in the Card File and the Telescoping Grid File use different conventions (unfortunately). The angle in the Card file is measured counter-clockwise from the East direction to the grid x-axis, while the angle in the Telescoping Grid File is measured clock-wise also from the East direction to the grid x-axis.
2. By default the XMDF Grid File also contains the bathymetry and other spatial datasets including the bottom friction, hard bottom, D50, etc. However, these datasets can be specified in separate files.
3. If a telescoping grid is used, the bathymetry is included by default in both the XMDF Grid File and the Telescoping Grid File. However, the depths in the in Telescoping Grid have -999 values for inactive cells. These cells are internally removed from the computational grid. Therefore, when using telescoping grids, only the depth values in the Telescoping Grid File are used by CMS.

The SMS Cartesian Grid Module has several tools for creating and editing Cartesian grids. A brief description of the tools is provided below

Create 2D Grid Frame
The 2D Cartesian Grid Frame (purple box) creation tool allows the user to visually specify the location and orientation of the grid in space. To create a grid frame, simple click three times to the desired length and width dimensions. SMS will complete the rectangle.

Select 2D Grid Frame
A 2D Cartesian Grid Frame can be modified with this selection tool. Once the frame is generated, the edges can be modified, the grid can be rotated (by selecting a small circle usually found in the lower left part of the grid), and the grid can be selected (middle black square) for manipulating location or opening the Grid Properties dialog box.

Select Cell
The Select Cell tool is used to select a grid cell. A single cell is selected by clicking on it. A second cell can be added to the selection list by holding the SHIFT key while selecting it. Multiple cells can be selected at once by dragging a box around them. A selected cell can be de-selected by holding the SHIFT key as it is clicked. When a single cell is selected, its Z coordinate is shown in the Edit Window. The Z coordinate can be changed by typing a new value in the edit field, which updates the depth function. If multiple cells are selected, the Z coordinate field in the Edit Window shows the average depth of all selected cells. If this value is changed, the new value will be assigned to all selected cells. With one cell selected, the Edit Window shows the cells i,j location. With multiple cells selected, the Edit Window shows the number of selected cells.

Select Row

Select Column

The Select Row and Select Column tools are used to select cell rows and columns, respectively. Multiple rows and columns are selected in the same manner as selecting multiple individual cells: holding the SHIFT key, etc.

Insert Row

Insert Column

When the Insert Column or Insert Row tools are active, clicking within a cell splits the row/column containing the selected cell, creating a new row or column in the grid. The Z-values of all split cells are the same as the original cells’ values.

Drag Row

Drag Column

The position of the edge of rows or columns in a grid can be changed with the Drag Column or Drag Row tools. These tools make one column/row narrower while making its neighbor wider. These tools allow for manual specification of the resolution in specific portions of the grid. Note that depth values are not adjusted, so significant dragging of boundaries should be avoided or depths should be re-interpolated after the boundaries are modified.

Create Cell String

The Create Cell String tool allows the modeler to group a string of cells together for the purpose of assigning boundary conditions. Cell strings are created automatically around water boundaries when a grid is generated. The user may create others as desired or delete and replace the automatically generated cell strings. When the Create Cell String tool is active, the modeler selects each cell to be added to the string. By holding down the SHIFT key, all boundary cells between the previously selected cell and the selected cell are added to the cell string.

Select Cell String

To specify a boundary condition, the modeler must create a cell string along the desired boundary cells, and then select the cell string while the Select Cell String tool is active. Specification of a boundary condition for the selected cell string is conducted through the Assign BC dialog, which is accessed through the CMS-M2D pull-down menu.

---