SURFACE WATER MODELING SYSTEM

ADCIRC Analysis

Introduction
This lesson will teach you how to prepare a mesh for analysis and run a solution for
ADCIRC. It will cover preparation of the necessary input files for the ADCIRC
circulation model and visualization of the output. You will start by reading in a coastline
file and then a SHOALS file.
The data used for this tutorial are from Shinnecock Bay off of Long Island in New York.
All files for this tutorial are found in ADCIRC Data Files directory.

Reading in a Coastline File

For this tutorial, you will first read in a coastline file, which has already been set up for
you. This sample coastline will form the boundary for your mesh. To set up your
coverage for ADCIRC and open the coastline file:
1. Change the coverage type to ADCIRC by right clicking on default coverage,
selecting Type, and choosing ADCIRC (in the models subcategory).
2. Select File | Open.
3. Select the file shin.cst in the Data Files Folder for this tutorial and click the Open
button.
Coastline files include lists of two-dimensional polylines that may be closed or open. The
open polylines are converted to Feature Arcs and are interpreted as open sections of
coastline. Closed polylines are converted to arcs and are assigned the attributes of islands.

Last Edited May 9, 2012

Page 1 of 18

Aquaveo

2.1

Defining the Domain

We need to assign a boundary type to the coastline arc, and then we can define the region
to be modeled. To do this:
1. Make sure you are in the Map

module, if not already selected.

tool from the Toolbox and click on the

2. Choose the Select Feature Arc

coastline arc to select it.

3. Select Feature Objects | Define Domain.

4. Select the Semi-circular option and click OK.
5. Frame

the display.

A semi-circular arc is created to define the region.

2.2

Assigning Boundary Types

Boundary types for arcs are specified in the Map module. Boundary types are prescribed
by setting attributes to Feature Arcs. To set the boundary types:
1. Choose the Select Feature Arc

tool from the Toolbox.

2. Double click the arc representing the ocean boundary, shown in Figure 1. In the
ADCIRC Arc / Nodestring Attributes dialog, assign this arc to be of type Ocean.
3. Click the OK button to close the dialog.

Figure 1

Feature Arcs after boundary types have been assigned.

Page 2 of 18

Aquaveo

Editing the Coastline File

Now that the coastline file has been read in, several modifications must be made to the
data before the SHOALS file is read in.

3.1

Coordinate Conversions
The current coordinates of the coastline file are in a latitude/longitude geographic
coordinate system. We need to convert the coordinates to UTM to read in the SHOALS
file, since the SHOALS file is in UTM coordinates. To convert the coordinates:
1. Choose Edit | Reproject.
2. In the Reproject Current dialog that appears, click the Specify toggle in the
Current projection (left side) to define the projection the data is currently in. Set
the Horizontal to use a Global projection. This will bring up the Select
Projection dialog. Select Geographic (latitude/longitude) as the projection and
NAD 27 as the datum. Click OK to complete the projection selection.
3. In the New projection (right) side of the dialog, also set the Horizontal to Global
projection. Choose UTM as the projection and NAD 27 as the datum. Set the
Zone is set to Zone 18 ( 78W to 72W Northern Hemisphere). Click OK.
4. Ensure that the vertical units for both projections are set to Meters.
5. Click the OK button to exit the dialog.
The coastline data has now been converted from Geographic coordinates to UTM
coordinates. The coastline should now look skewed from the original coastline.

Reading in a SHOALS File

You will now read in a SHOALS file, shin.pts, which contains data at various locations
along the coastline and throughout the region you are modeling.
1. Choose File | Open.
2. Select the file shin.pts.
The File Import Wizard dialog will open, allowing you to specify how the data will be
read into SMS. For Step 1 of the dialog, the first line in the File preview box is the file
header. The next line shows the name of each respective column of data. In this case, the
file has three data columns. The first column is the X Coordinate, the second column is
the Y Coordinate, and the third column is the depth/bathymetry.

Click the Next > button to move on to Step 2 of the File Import Wizard.

Page 3 of 18

Aquaveo

The second step of the File Import Wizard allows you to change other specifications as
you read in the SHOALS file.

Click the Finish button.

Figure 2 shows the plot of the points read in from the shin.pts file.

Figure 2

Display of shin.pts.

Shallow Wavelength Functions

The next step before you build your finite-element mesh is to create several functions for
creating the finite element mesh. For this tutorial, the mesh will be generated according
to the wavelength at each node. Large elements will be created in regions of long
wavelengths. Conversely, smaller elements are needed closer to the shore to correctly
model the smaller wavelengths.
To create this shallow wavelength function from the bathymetric data:
1. In the Scatter

module, select Data | Data Set Toolbox.

2. In the Data Set Toolbox dialog, select the Wavelength and Celerity tool in the
Coastal section. This enables the wavelength options on the dialog.
3. Make sure the options for creating a Wavelength and Celerity function are
checked. Leave the period at 20 seconds and enter a name 20 sec in the Output
data set names edit field.
Page 4 of 18

Aquaveo

4. Click the Compute button to create the data sets and the Done button to close the
dialog.
Two functions are created: celerity and wavelength at each node using the shallow water
wavelength equation. The celerity is calculated as:

Celerity = (Gravity * Nodal Elevation)0.5.

The wavelength is calculated as:

Wavelength = Period * Celerity.

Creating Size Functions

Now that you have created the wavelength function, you must make a few more
conversions before you are ready to create your mesh. A size function is a multiple that
guides the size of elements to be created in SMS. Any data set may be used for this
purpose. If you were to generate your mesh using the original wavelength function
alone, you would get a decent mesh to work with, but we want a mesh whose density
radiates out from a point in the inlet. This allows you to get more accurate results in the
inlet where we are most concerned with the outcome of the ADCIRC run. Therefore, we
will now need to create a size function based on the wavelength to attain this end. The
final size function you use for modeling applications varies and is found through trial and
error to give a nicely formed mesh. This example illustrates one method of building a size
function.

6.1

Finding the Central Point for the Mesh

Since the mesh will be generated in a radial fashion, the distance from a central point
must be found. The first step is to locate the central point and then use the Data
Calculator to compute the distances of all points from this center point. To do this:
1. Still in the Scatterpoint
Figure 3 with the Zoom

module, zoom in to the area of the inlet shown in

tool until your screen looks like Figure 4.

2. Click on one of scatter points in the middle of the inlet using the Select
Scatterpoints
tool. Make note of this points X and Y coordinates in the Edit
Window at the top of the screen.
3. Frame the data by clicking the Frame

Page 5 of 18

tool in the Toolbox.

Aquaveo

Figure 3

Inlet location to zoom in on.

Figure 4

Choose a center point.

For now, turn off the scatterpoint display. However, you may turn it back on at any time
during the tutorial if you so desire. To turn off the visibility of the shin.pts data unselect
shin dataset in the Project Explorer.
the box next to the
You are now ready to proceed. We will use the Data Calculator to compute new data
sets by performing operations with scalar values and existing data sets. The Data
Calculator will be used to create the size function.

6.2

Distance Function
For consistency, we will use the (x,y) location of (712768.675, 4523969.712) as the
center scatterpoint for our mesh.
Page 6 of 18

Aquaveo

1. Select Data | Data Calculator. This brings up the Dataset Toolbox, with the
data calculator active.
2. Click the sqrt(x) button.
3. In the Expression field, using the keyboard replace ??so the expression looks
like:

sqrt((d4 712768)^2 + (d5 4523950)^2)

This expression takes the x and y locations of each scatter point, which correspond to the
d and e data sets respectively, and computes its distance to the point designated as
the mesh center.
4. In the Output data set name field, enter the name of distance for the data set
and click the Compute button.

6.3

Initial Size Function

1. Highlight the 20 sec_Wavelength data set and click the Add to Expression
button. You now should see the letter and number d2 in the Expression field.
2. In the Expression field, make the equation look like d2*7.
3. Enter the name size for this data set in the Result area and click the Compute
button. This creates a function of 7 times the wavelength.

6.4

Scale Function
The last separate function before computing the final size function will be a scale factor
out from the center point. It will take on the following format:

scale = (distance/max distance)^0.5.

This scale function will range between 0 and 1, 0 being at the center point and 1 at the
farthest point from the center of the mesh. This will allow the mesh to radiate out in
density from the middle of the inlet. Taking the square root of the scale factor forces the
elements to grow larger more quickly as one moves away from the center. To compute
this function:
1. Highlight the distance function in the Data Sets window and click the Data Set
Info... button. Notice that the Maximum value is 65607.9.
2. Click the X in the corner of the dialog window to close the info dialog.
3. Enter sqrt(d6 / 65607.9) in the Expression field. This assumes that d6 is the
distance function.
Page 7 of 18

Aquaveo

4. Enter the name scale and click the Compute button.

6.5

Final Size Function

You are now ready to create the final size function that your mesh will be based on.
1. Click the max(x,y) button.
2. Replace ??,?? so the equation reads max(50, (d7*d8)). This will multiply the
scale factor (which varies from very small by the center of the domain up to one
at the edges) by the size (which is seven times that of the wavelength). The
result will be a value that varies from vary small to seven times that of the
wavelength that is truncated to a minimum size of 50 meters to prevent infinitely
small elements from being created around the mesh center.
3. Enter the name radial size in the Result field and click the Compute button.
The data calculator gives you many options for building the size function. The size
function created in this tutorial was created through several steps. This was done to show
the many possibilities that exist for defining the size function, and ultimately for defining
the finite element mesh. Other options that could be used for this or other meshes include:

6.6

Use the wavelength multiplied by a scale factor (without using distance).

Dont take the square root of the scale factor for a denser mesh.

Use a value other than 50 meters as the minimum size for a denser mesh in the
channel, etc.

Smooth Size Function

The final step in creating a size function is to smooth the size function. Smoothing
modifies the size function so the size function values do not change too quickly. Size
functions that change too quickly can create poor transitions in element size.
1. In the Dataset Toolbox, select Smooth data sets from the tool list on the left..
2. Select the scatter data set named radial size.
3. Change the Element area change limit to 0.5. This will modify the size function
so the elements created by the size function are at most twice as big or half as
small as their adjacent elements.
4. Enter the name radial size smoothed 0.5 and click the Compute button.
5. Click Done to exit the Dataset Toolbox.

Page 8 of 18

Aquaveo

(Note: If desired, the differences between the data set radial size and radial size
smoothed 0.5 can be visualized by using the data calculator to subtract radial size
from radial size smoothed 0.5 and contouring the resulting data set.)

Creating Polygons
A polygon is defined by a closed loop of Feature Arcs and can consist of a single Feature
Arc or multiple Feature Arcs, as long as a closed loop is formed. For initial mesh
generation, polygons are a means for defining the mesh domain.

7.1

Building Polygons
To create polygons from the arcs on the screen:
1. Switch to the Map

module.

2. Make sure that no arcs are currently selected.

3. Select Feature Objects | Build Polygons.
4. Now a polygon has been created out of all the arcs.

7.2

Polygon Attributes
Next each polygon (this case only has one) must be assigned proper attributes.
1. Choose the Select Feature Polygon
polygon.

tool from the Toolbox and click inside the

2. Select Feature Objects | Attributes. (Double-clicking inside the polygon will

perform this same step.) The 2D Mesh Polygon Properties dialog will open.

7.3

Assigning the Meshing Type

1. Select Scalar Paving Density as the Mesh Type.
2. Click the Scatter Options... button below the Mesh Type.
3. In the Interpolation dialog, in the dataset tree under Scatter Set To Interpolate
From, make sure the radial size smoothed 0.5 function is highlighted.
4. In the Extrapolation section, set the Single Value to 50.
5. Turn on the Truncate values option and set the Min to 50 and the Max to 5000.
6. Click the OK button to return to the 2D Mesh Polygon Properties dialog.
Page 9 of 18

Aquaveo

7.4

Assigning the Bathymetry Type

Next, the bathymetry type is selected. In this case the imported bathymetry is in the form
of a scatter set.
1. Select Scatter Set as the Bathymetry Type.
2. Click the Scatter Options... button below the Bathymetry Type option.
3. In the Interpolation dialog, highlight Z under Scatter Set To Interpolate From,
leave the Single Value at 0.000, and make sure the Truncate values option is
turned off.
4. Click the OK button.

7.5

Assigning the Polygon Type

1. Make sure the Polygon Type is set to Ocean.
2. Click the OK button to close the 2D Mesh Polygon Properties dialog.

Creating the Mesh

Once the polygon attributes are set, the mesh can be generated automatically based on the
options that were selected. To generate the mesh:
1. Select Feature Objects | Map -> 2D Mesh.
2. Turn off the toggle for Copy coverage before meshing and click OK.

8.1

Mesh Display Options

After SMS has completed generation of the mesh, you should be able to view the
bathymetry, nodes, and elements. To set the display:
1. Switch to the Mesh

module.

2. Select Display | Display Options... or select the

macro from the Toolbox.

3. Make sure the Nodes and Contours are turned off and the Elements are turned on.
4. Click the OK button to close the Display Options dialog.

Page 10 of 18

Aquaveo

Figure 5

View of elements after automatic mesh generation.

Figure 5 shows the final mesh. Notice how the elements are smaller closer to the coast
and within the inlet. Once the mesh has been created and refined, final preparations must
be done in order to run ADCIRC. These items are renumbering of the mesh nodes and
saving the grid.

8.2

Minimizing Mesh Bandwidth

Before running ADCIRC, the mesh nodes must be renumbered to minimize the bandwidth
of the mesh. This allows the ADCIRC model to run efficiently. SMS has done this
automatically as the mesh was generated. However, if you edit the mesh, you would
need to renumber again. To do this:
1. Select the Select Nodestring
along the ocean boundary.

tool from the Toolbox and select the nodestring

2. Select Nodestrings | Renumber.

The nodes have now been renumbered for the entire mesh starting with those along the
ocean boundary.

Building the ADCIRC Control File

The control file specifies values corresponding to different parameters for ADCIRC runs.
These parameters include specifications for tidal forcing, selection of terms to include,
hot start options, model timing, numerical settings, and output control. In order for
ADCIRC to run properly, the mesh must be converted to Latitude/Longitude coordinates.

Page 11 of 18

Aquaveo

9.1

Converting Back to Lat/Lon

The model control expects the coordinates to be in latitude/longitude. The initial
conversion was made to UTM coordinates for the meshing. The size function was
calculated in meters, so the mesh could not be created while the coordinates were in
degrees without performing more conversions (i.e. degrees <-> meters). To convert back
to Geographic coordinates:
1. Select Edit | Reproject .
2. In the New projection section, select Set Projection in the Horizontal section.
Set the Projection to Geographic and leave the datum as NAD 27. Click OK.
3. Make sure the Vertical units are in Meters.
4. Click the OK button.

9.2

Main Model Control Screen

To set up the model control for ADCIRC:
1. Select ADCIRC | Model Control.
2. In the General tab, turn on the following options under Terms in the center of the
dialog: Finite Amplitude Terms, Wetting/Drying, Advective Terms, and Time
Derivative Terms.
3. Click the Options... button below the Wetting/Drying option.
4. Make sure the following values are entered in the Wetting/Drying Parameters
dialog:

Minimum Water Depth.................................

Minimum # of Dry Timesteps.......................
Number of Rewetting Timesteps...................
Minimum Velocity for Wetting.....................

0.05
12
12
0.02

5. Click OK to return to the Model Control dialog.

6. Enter a value of 3.0 for the Lateral Viscosity in the Generalized Properties
section on the right side of the dialog.
7. Change the Bottom Stress/Friction method to Constant Quadratic and set the
Friction coefficient to 0.005.

9.3

Time Control
Next, values for the Timing must be set. To set these values:
Page 12 of 18

Aquaveo

1. Click on the Timing tab.

2. Set the following values:

9.4

Ramp function value: 1.0 days. (This is a time period for the model to ramp
from no circulation to full tidal amplitude. This enhances stability. The
results from these calculations do not match physical reality and are normally
not even saved.
Time Step: 2.0 seconds
Run Time: 1.5 days (Normal simulations last for several days up to a full
lunar month. This is set to 36 hours just to get past the ramp time and show a
tidal cycle.)

Output Files
ADCIRC will generate two global output files, water-surface elevation and velocity. To
set the time for the two files:
1. Click on the Files tab.
2. In the Output Files Created by Adcirc section scroll down to Elevation Time
Series (Global) and turn the Output checkbox on.
3. Make sure the Start (day) is set to 1.0 and set the End (day) to 1.5 and the
Frequency (min) to 30.
4. Repeat steps 2 and 3 for the Velocity Time Series (Global).

9.5

Tidal Forces
For this run of ADCIRC, tidal forcing will be used. To define the tidal constituents that
ADCIRC will apply at the ocean boundaries:
1. Click on the Tidal/Harmonics tab.
2. Check the Use forcing constituents and Use potential constituents boxes in the
Tidal Constituents section.
3. Click the New button next to the checkboxes.
4. In the New Constituent dialog, make sure the LeProvost constituent database is
selected. Select the K1, M2, N2, O1, and S2 constituents in the Constituents
section.
5. Set the Starting Day as 0.0 hours on February 1, 2000 (Hour: 0.0, Day: 1, Month:
2, and Year: 2000). This is the date from which the tides will start.
6. Click the OK button to return to the ADCIRC Model Control dialog.
Page 13 of 18

Aquaveo

SMS takes each constituent, extracts the values it needs from the LeProvost
constituent database, and places them into the spreadsheet in the lower left corner.
The amplitude and phase values may then be adjusted for each node.
If a message appears indicating that SMS cannot find one of the constituent files,
click OK and find the file. The file should be located with the tutorial files.
7. Click the OK button to exit the ADCIRC Model Control dialog.
8. Click Edit and Reproject. Click on Set Projection under the New projection area.
9. Change the Projection combo box to Geographic (Latitude/Longitude) and verify
that the Datum combo box reads NAD27. Press OK.

9.6

Saving the Mesh and Control Files

To save the mesh and control files:
1. Select File | Save New Project
2. Enter the name shinfinal.sms and click the Save button.

10

Running ADCIRC
You are now ready to run ADCIRC. Presently, ADCIRC uses a specific naming
convention for its input and output files. Therefore, before ADCIRC can start, the basic
input files must be present in the working directory, which SMS takes care of
automatically. SMS makes a copy of the active mesh file and names it fort.14, then
makes a copy of the model control information file and names it fort.15.
To run ADCIRC:
1. Select ADCIRC | Model Control.
2. Select the General Tab. Name your project "test" in the Project title: and Run
ID: "test" as well. Press OK.
3. Select ADCIRC | Run ADCIRC.
4. If the name of the ADCIRC executable does not appear, click the folder icon
locate the ADCIRC executable, and click OK.

The ADCIRC model wrapper appears and gives status for 64800 timesteps while the
model runs. On a typical desktop machine, this will take around 15 minutes. Once the
ADCIRC run has completed, there will be several new files created. SMS copied the
shinfinal.grd file (the mesh file saved when the project file was saved) to fort.14 and
shinfinal.ctl file to fort.15, the filenames needed by ADCIRC. ADCIRC created the
fort.63 (global elevation) and the fort.64 (global velocity) files. There are a couple of
Page 14 of 18

Aquaveo

other files that hold basic output information, but we will only focus on the elevation and
velocity files for the remainder of this tutorial.
When ADCIRC finishes running, click Exit.

11

Importing ADCIRC Global Output Files

Each output file from ADCIRC is imported into SMS as a Dataset. There are two types
of datasets, scalar and vector. The global elevation file is an example of a scalar dataset,
while the global velocity file is a vector dataset. You will import the global elevation file
and the global velocity file simultaneously. To do this:
1. Select File | Open.
2. Hold the Shift key down and select both the fort.63 and fort.64 files.
3. Click the Open button.
4. Click OK in the Convert to XMDF dialog to convert both solution files.
SMS reads in the files and adds Water Surface Elevation (63) and Velocity (64) mag
as Scalar datasets and Velocity (64) as a Vector dataset in the Mesh Data of the Project
Explorer.

12

Viewing ADCIRC Output

Once both ADCIRC output files have been imported, the user must decide on how to
view the data. The Project Explorer may be used to select the desired Scalar and Vector
datasets.

12.1

Activate the Water Surface Elevation (63) Scalar dataset by clicking on it

in the Project Explorer.

Scalar Dataset Options

A good way to view the output is to edit the contour display options. To change the
contour properties:
1. Select the Display Options

macro in the Toolbox.

2. In the 2D Mesh tab, click the All off button to turn off current display options.
3. Turn on the Contours, and Mesh boundary.
4. Under the Contours Options tab, change the Contour Method to Color Fill.
Page 15 of 18

Aquaveo

5. For the Number of contours, enter 25.

6. Click OK to exit the dialog box, and SMS will redraw the screen similar to
Figure 6 (it will look about the same for the Time step 1 1:00:00).
To view the data at different time steps, select the desired time steps in the Time Steps
window. The Time Step value is in hours, minutes and seconds from the start of the
ADCIRC run.

Figure 6

12.2

ADCIRC output from the fort.63 file.

Vector Dataset Options

You can display velocity vectors several different ways.
displayed at each node, and then on a normalized grid.

We will first view them

Vectors at Each Node

1. Using the Zoom tool

, zoom in on the mesh so only the bay area is visible.

2. Select the Display Options

macro in the Toolbox.

3. In the Display Options dialog under the 2D Mesh tab, turn on the Vectors toggle.
4. In the Vectors tab, under the Arrows Options section, make sure the Shaft length
is set to Define min and max length.
5. Change the Min length to 15 and the Max length to 40.
Page 16 of 18

Aquaveo

6. Click the OK button to exit.

The screen should now look similar to that shown in Figure 7. You can now visualize the
flow at each node through Shinnecock Bay at this particular time step.

Figure 7

View of velocity vectors at each node.

Vectors on a Normalized Grid

1. Open the Display Options

and go to the Vectors tab.

2. Under Vector Display Placement and Filter, change the Display to the on a
grid.option.
3. For both the x pix and y pix, enter a value of 15 and click the OK button.
This method of displaying vectors is useful when displaying areas with both coarse and
refined areas, such as the entire mesh in this case.

13

Film Loop Visualization

In addition to single time steps of contours and vectors, animations can be generated and
saved. SMS enables the user to generate and save animations by using the Film Loop.
To create a film loop of the ADCIRC analysis:
1. Select Data | Film Loop.
2. In the Film Loop dialog, click the Next> button.
3. Click the Next> button, then the Finish button.
Page 17 of 18

Aquaveo

SMS now starts the film loop, adding one frame at a time. Once the last frame has been
added to the loop, an AVI Application will open and the animation will start
automatically.
You may continue to experiment with the film loop features if you desire. Click the
Close button when finished. The film loop has been saved as sms.avi.

14

Conclusion
This concludes the ADCIRC Analysis tutorial.

Page 18 of 18

Aquaveo