ADCIRC FAQ – v53

ADCIRC Frequently Asked Questions

=================================

Author: Jason Fleming
Email: jason.fleming@seahorsecoastal.com
Last updated: 2/1/2016

Introduction
————

*Q: What is ADCIRC and what can it do?*

ADCIRC is a system of computer programs for solving time dependent, free surface circulation and transport problems in two and three dimensions. These programs utilize the finite element method in space and therefore can be run on highly flexible, irregularly spaced grids. Typical ADCIRC applications have included: modeling tidally and wind driven circulation in coastal waters, forecasting hurricane storm surge and flooding, dredging feasibility and material disposal studies, larval transport studies, riverine modeling for currents and water levels, and baroclinic coastal modeling from lab scale to field scale.

*Q: What platforms does ADCIRC run on?*

ADCIRC runs on any operating system for which there is a working FORTRAN compiler. These include large commercial Unix systems (IBM Power & Blue Gene), Cray, SGI, Sun), Linux and FreeBSD based clusters, and personal workstations running Windows or Mac OSX. We are not aware of any platforms that support a working modern Fortran compiler that does not support ADCIRC. We routinely use the Intel, PGI, Intel, and GCC suites of compilers on a great variety of architectures. Network topology (Infiniband, GigE, shared memory MPI, etc) appropriate MPI libraries and C compilers are required in parallel environments. NetCDF libraries are optionally required in order to support this type of output. The coupled ADCIRC+SWAN model is available on all of the above platforms with the exception of Windows (as of March 2014). The coupled ADCIRC+STWAVE model is available on all the platforms including Windows PCs as part of the Coastal Storm Modeling System (CSTORM-MS).

*Q: What is the current version of ADCIRC?*

The ADCIRC version 51 series is the latest release version (specifically v51.52). It was officially released on 31 March 2015.

*Q: What are its main features?*

* Use of Cartesian or spherical coordinates
* Two dimensional depth integrated (2DDI) and 3D solution capabilities
* Full wetting/drying elements (2D and 3D)
* Barrier elements (e.g. levees)
* Conduits and porous barriers
* Harmonic analysis (“on the fly”)
* Cold or hot starts
* Well documented with web-served user’s manual
* Model design criteria
* Large domain – localized resolution strategy to simplify often very difficult boundary condition specification
* Very low numerical damping model allows model parameters to be based on physically relevant values
* Consistent with the governing equations
* Runs on single processor computers and parallel computers using MPI
* Ascii and NetCDF output formats

*Q: How can I engage with other ADCIRC users to ask questions and be
in touch with the latest developments?*

Contact Crystal Fulcher (cfulcher@email.unc.edu) and ask her to subscribe you to the ADCIRC listserv (adcirc@listserv.unc.edu).

*Q: How can I purchase ADCIRC for Windows?*

ADCIRC is commerically available from Aquaveo, LLC (www.aquaveo.com) bundled with their software package SMS (Surface water Modeling System). SMS and ADCIRC are also available from Veri-Tech, Inc (www.veritechinc.com).

*Q: I am a commercial user. How can I legally access the copyrighted ADCIRC source code?*

Contact Crystal Fulcher (cfulcher@email.unc.edu).

*Q: How do I compile and build ADCIRC?*
A: Step-by-step instructions for building ADCIRC are provided in the ADCIRC Devleoper’s Guide on this site and in the doc subdirectory of the ADCIRC source code.

Q: How can I compile ADCIRC+SWAN on Windows?

One possible way is to use MinGW and MSYS (see www.mingw.org). MinGW will give you GNU compilers in Windows, while MSYS gives you a bash like shell, make, and other tools. Once you have MinGW and MSYS working you open a MSYS shell and build ADCIRC just like you would on Linux.

*Q: What does ADCIRC need as input?*

A set of files which defines such things as: bathymetry, topography, boundary information, tidal characteristics, nodal attributes (often based on land use data), river inflow, meteorological forcing input, wave radiation stress forcing, and others depending on the geographical area of interest.

*Q: What software packages are available for developing ADCIRC input (meshes in particular)?*

The tool of choice in the ADCIRC Community is the Surface water Modeling System (SMS) from Aquaveo, LLC (http://www.aquaveo.com). However, there are other possibilities, including the Blue Kenue package (https://www.nrc-cnrc.gc.ca/eng/solutions/advisory/blue_kenue_index.html).

*Q: What does ADCIRC create as output?*

Output files containing time varying and spatially varying water surface elevation, water velocity, wind velocity, and atmospheric pressure. These will be 2D or 3D as specified in the input.

*Q: How do I try it out?*

There are test problems that can be downloaded from the adcirc.org home page. Currently, there is no trial version of ADCIRC for download. It may be possible to obtain a trial version as part of the SMS software package (http://www.aquaveo.com/sms) which is commonly used for ADCIRC mesh development and editing as well as model output visualization.

*Q: Are there any restrictions on ADCIRC use?*

ADCIRC code cannot be redistributed. ADCIRC code is made freely available to academic, government, and other not-for-profit research purposes. Commercial use of ADCIRC is possible, but terms of use must be fully negotiated with the major software authors. If any results from ADCIRC, either direct or indirect, become published, the ADCIRC model should be acknowledged in print as well.

*Q: How do I visualize the results?*

ADCIRC output files are directly readable by the Surface water Modeling System (SMS) software package from Aquaveo (http://www.aquaveo.com). In addition, various users have developed utilities or scripts for visualizing ADCIRC output in ArcGIS, Tecplot, Paraview, Google Earth, and gnuplot. One of the most popular is a tool called FigureGen, which uses the Generic Mapping Tools (GMT) package to generate publication-quality figures and animations. It is developed by Casey Dietrich and is freely available from http://www.caseydietrich.com. For any of the other formats, you can request the latest version of an associated conversion utility from the ADCIRC mailing list.

*Q: Who wrote ADCIRC?*

ADCIRC has been developed by Dr. Rick Luettich at the University of North Carolina at Chapel Hill, Institute of Marine Sciences and by Dr. Joannes Westerink at the University of Notre Dame, Department of Civil Engineering and Geologic Sciences.

*Q: Has ADCIRC been validated?*

The ADCIRC developers focused on proving that they are correctly solving the governing partial differential equations without introducing artificial damping or artificial modes that alter the stated physics. They proved consistency and convergence rates by examining problems with a range of dynamic balances so that their analytical tests mimic real world applications. They based error estimates on comparisons to simplified problems with analytical solutions or on Richardson extrapolation.

They used their models to solve real world problems applying observed geometry and boundary conditions, universal air-sea momentum transfer coefficients and frictional dissipation parameters, ideally based on small scale process specific measurements, so that a thorough evaluation of the model’s performance could be made. They computed model to measurement error estimates and when possible measurement error estimates to define
model errors.

Interested readers are referred to the substantial publication list at the ADCIRC homepage.

*Q: What if I find a bug in the code?*

There is a list serve (adcirc@listserv.unc.edu) where bugs can be reported. The primary contributors (Joannes Westerink and Rick Luettich) welcome bug reports.

*Q: How can I contribute to the development of ADCIRC?*

The list serve (adcirc@listserv.unc.edu) is good place to start connecting with people who are currently active within the development community. There is an ADCIRC community workshop each year which is open to anyone. More information can be found on the list serve.

*Q: I’m getting a “divide-by-zero” error when ADCIRC calls the SWAN coupler during parallel execution. What does this mean?*

This is an issue with the presence, location, and subdomain preparation status of the coupled SWAN input file (fort.26). Make sure that the swan input file fort.26 is in the same directory with the other fulldomain input files and has been distributed to the subdomain directories by adcprep.

*Q: How do I resolve the error message “too many files open” when running adcprep for large numbers of subdomains in parallel?*

Most operating systems (OS) set limits on the number of concurrently open files. If the number of subdomains is large (>1000), then the operating system may run out of available file handles when running adcprep. Find out how to increase the open file limit. In Linux, this is something like “ulimit -n 8192”, which tells the OS that, for this shell session, allow up to 8192 open files.

*Q: When running ADCIRC, there are messages printed to the screen that say ‘WARNING: Elevation.gt.WarnElev’ … what does that mean?*

This means that the water surface elevation solution is farther above the geoid than the ‘warning’ threshold level.

Typically, this means that the water surface elevation solution is growing larger than expected which often indicates a growing instability. So why not just halt execution when this sort of solution begins to form? Well, due to very large tidal ranges in certain parts of the world, very high water elevations (e.g. 10 meters) are *possible*, and therefore ADCIRC will merely log a warning at this point—not shut down the run.

There is also an ‘error’ water level (e.g. 1000 meters) at which the solution is clearly erroneous, causing ADCIRC to halt execution. The details of this warning/error check behavior depend on certain hard coded threshold levels. The default values for warning/error are:

WarnElev = 20.0 meters
ErrorElev = 1000.0 meters.

*Q: I have made an ADCIRC mesh for my area of interest, but the resulting ADCIRC simulation is unstable, even with a very small time step. What should I do?*

Here are some places to start:

* Can you compute the CFL parameter for each of your elements and ensure that it is less that 1 globally?

* Can you compute the element quality (a measure of how ‘equilateral’ the element is) for each element? Low quality elements (even just one or two) can give you problems.

* Try running a test simulation with the nonlinearity/wetting-drying features turned off and then bring them back in (presuming you get a stable run) one at a time.

* You may be able to get a more stable run by adjusting tau0 (the weighting between the primitive equation and the wave equation in the overall continuity equation). For detailed information on how to do this, please see the documentation of tau0 (in the fort.15 file) in the Official ADCIRC Users Manual at http://www.adcirc.org.

*Q: I have received an error like “forrtl: severe (”x”): attempt to ”blah blah blah”” where ”x” is a number and ”blah blah blah” is some sort of error message. What does this mean?*

*A:* This message was not produced by ADCIRC. It was produced by the library that comes with the Intel Fortran Compiler.

*Q: What utilities are available for working with ADCIRC input and output?*

There are utilities available on the ADCIRC webpage at http://adcirc.org/Utility_programs.html. There are also many utilities that have been developed by various members of the ADCIRC community for their personal use. Please submit a question to the ADCIRC mailing list to find out what may already be available.

*Q: Can the passive scalar transport in ADCIRC be used? The user manual lists this option as “not fully implemented.” What, exactly, does this mean? Will it not give reliable results?*

(Jason Fleming): Passive scalar transport is not the preferred approach to doing tracking studies of conserved quantities in the production version of ADCIRC. Instead, ADCIRC users generally take current velocity output data and run it through a separate code that they have written to advect clouds of virtual drifters.

This approach is used because the production version of ADCIRC uses the Continuous Galerkin (CG) finite element formulation which guarantees mass conservation along the boundary, but not element-by-element mass conservation. Therefore, it is possible to have mass conservation errors when tracking a conserved scalar in CG ADCIRC.

There is also a Discontinuous Galerkin (DG) formulation, called DGSWEM, which does guarantee element-by-element mass conservation. This code is available from the Institute for Computation Engineering and Sciences (ICES) at the University of Texas at Austin.

(David Hill): We have written some scripts (matlab) to do this. They use a 4th order Runge-Kutta scheme to integrate the velocity fields and compute trajectories. We have wondered, however, about the appropriate (output) time interval in the fort.64 file. We have erred on the side of accuracy (we have very complicated domains) and use output every 5 or 10 minutes. For large domain simulations, if one wants to track particles over several days / weeks…we are talking about a huge file. Then, each time you wish to place and track particles, the integration process is very slow. With much
larger time intervals, however, too many particles seem to drift out of the domain. I have had, on my wish list (listen up, programmers!), a way in Adcirc to (some fort input file) to, at the start of a simulation, specify initial drifter locations and ‘on’ and ‘off’ times. Then, when the simulation is run, Adcirc would, on the fly, compute the trajectories and store the output in an output file. With the DG version of the code, will something like this be implemented in the future?

(John David Howlett): The model PTM may be of interest to you. An interface for PTM has been developed in SMS. PTM uses the hydrodynamic output from ADCIRC (and other models).

http://xmswiki.com/wiki/SMS:PTM

The Particle Tracking Model (PTM) is a Lagrangian particle tracker designed to allow the user to simulate particle transport processes. PTM is funded through two US Army Corps of Engineers Engineering Research and Development Center (ERDC) research programs, the Coastal Inlets Research Program (CIRP) and the Dredging Operations and Environmental Research (DOER) Program.

PTM has been developed for application to dredging and coastal projects including dredged material dispersion and fate, sediment pathway and fate, and constituent transport. The model contains algorithms that appropriately represent transport, settling, deposition, mixing, and resuspension processes in nearshore wave/current conditions. It uses waves and currents developed through other models and input directly to PTM as forcing functions.

(Nate Dill): Check out chapter 3 and the associated appendix http://etd.lsu.edu/docs/available/etd-06142007-084318/

Maybe too slow for a big ADCIRC grid, but it uses Scilab which is free so you don’t need $$$ for SMS or Matlab. Was working on a much faster fortran version but not quite finished yet, email me if interested.

*Q: What does ‘Failed to find prefix directory’ mean? I got this error message while attempting to run ADCIRC in parallel.*

The prefix directories are the PE000* directories that contain the subdomains for running in parallel. This error message is produced when PADCIRC is unable to find these subdomain directories. Possible causes include:

* starting the job in a directory that does not contain the PE000* directories
* failing to preprocess (i.e., run adcprep) before starting the parallel run
* failure of the underlying file system to provide access to the files.

*Q: What is tau0?*

The tau0 parameter is multiplied by the primitive continuity equation; ADCIRC uses the both the primitive continuity equation as well as the wave continuity equation in an overall formulation called the Generalized Wave Continuity Equation. The tau0 parameter can be thought of as a “weight” for the primitive continuity equation. This weighting value is used to balance the numerical properties of the continuity equations. A higher value is generally used in shallower water. See the fort.15 documentation on adcirc.org, and feel free to consult the ADCIRC mailing list for recommendations for your particular modeling scenario.

*Q: Is there a list of web-based resources where I can find out more about ADCIRC and ADCIRC+SWAN?*

Yes. Here is a partial list of links:

* Official adcirc.org website and documentation: http://www.adcirc.org
* Computational Hydraulics Laboratory: http://coast.nd.edu
* Casey Dietrich’s personal site: http://www.caseydietrich.com

*Q: How do I specify the tropical cyclone vortex parameters for the symmetric Holland model (NWS=8) in ADCIRC?

The issue with specifying these parameters is that they are dynamically related, that is, there isn’t a one-to-one relationship between any of them. If I wanted to create a storm parameter set out of thin air for NWS=8 (symmetric Holland model), here are the considerations:

Max Wind and Min Pressure: The relationship here is complex. But the curve fits that provide a rule-of-thumb correlation are actually quite simple. There are several, but I use a couple of published relationships for Vmax -> Pmin:

Dvorak: Pmin = 1015mb – (Vmax/3.92)^(1/0.644)
Knaff/Zehr: Pmin = 1010mb – (Vmax/2.3)^(1/0.76)

where Vmax is in m/s.

If the analyst needs to specify Pmin and then estimate Vmax, its easy to solve these equations for Vmax in terms of Pmin. In fact, we use the Knaff/Zehr relationship to do this in the ASGS in real time because the NHC doesn’t forecast Pmin. In any case, the analyst needs to be able to specify either Vmax or Pmin.

Once the Vmax and Pmin are established, the Holland B value—a curve fit parameter that indicates the steepness of the velocity profile and is not some sort of fundamental property of tropical cyclones as some seem to believe—can be computed according to the following formula:

B = (Vmax)^2 * rho_air * e / (Pn – Pmin)

where Vmax is in m/s, rho_air is set to 1.15 kg m^-3 in ADCIRC, e is Euler’s number, Pn is the “far field” atmospheric pressure, and Pmin is the central pressure (pressures in Pa, not mb).

The far field or background pressure is set to 1013mb in ADCIRC. In practice, the background pressure tends to be different in different basins, e.g., different in the tropical Pacific than it is in the tropical Atlantic, but ADCIRC always sets it to 1013mb.

ADCIRC reads the radius to the last closed isobar, which more or less represents the farthest extent of the storm winds, but it does not use it. I coded this up because the Holland curve fit does not taper to zero; as a result, a storm in the Gulf causes nonzero wind velocities in Maine, which is unrealistic to say the least. This problem becomes worse as the B value falls, because the velocity profile is more flat and this increases the spurious far field
velocity.

However, when I tried to use the radius to the last closed isobar to cut off the vortex wind in the far field, it created artificial jumps in ADCIRC’s wind speed record when comparing with measured meteorological stations. Not only was the wind fluctuating up and down, but the distance to the last closed isobar was fluctuating as well. So, as a storm would approach NC, for example, ADCIRC’s wind speed at a station might show the winds suddenly going from 0 to 10m/s and back several times, once the storm came within “range” of the met station. It just didn’t work well, so I removed the spatial cut off, but I didn’t change the way the code reads the fort.22 file, so it still reads the radius to the last closed isobar. My apologies for the confusion here.

*Q* How does ADCIRC version 52 decide at cold start what areas of the mesh are wet and what areas are dry?

The short answer is that by default, ADCIRC uses the bathy/topo from the mesh file (fort.14) to set vertices either a wet or dry state, assuming that a zero depth in the mesh represents mean sea level. In practice, the bathy/topo in the mesh file may not be relative to mean sea level, and several other parameters come into play. The exact process (with outtakes from the actual code) are as follows:

Step 1: ADCIRC sets the initial water surface elevation (array variable named eta2) to zero and sets all nodes wet:

ETA2(:) = 0.D0 ! water surface elevation (m)
NNODECODE(:)=1 ! nodal wet/dry state; 1=wet, 0=dry

Step 2. If the sea_surface_height_above_geoid nodal attribute was specified, the initial water surface elevation is set to the value of the nodal attribute so that ADCIRC can run relative to MSL:

IF (LoadGeoidOffset) THEN
ETA2(:)=GeoidOffset(:)
ENDIF

Step 3: If the initial_river_elevation nodal attribute was specified (implemented in prior versions as the fort.88 file), it is added to the initial water surface elevation, if the initial_river_elevation is positive at that node (to avoid adding -99999 values to the water surface elevation):

IF (River_above_MSL) THEN
WHERE (River_et_WSE.GT.0.d0)
ETA2 = ETA2 + River_et_WSE
END WHERE
ENDIF

Step 4: At each node, add the bathymetric depth from the mesh file to the water surface elevation, and compare the result with h0. H0 is the parameter from the fort.15 file that represents the minimum water depth for a node to be considered wet. If the result is less than or equal to h0, then the node is set to a dry state.

WHERE ( (DP + ETA2).le.H0 )
NNODECODE=0 ! wet/dry node state; 0 is dry and 1 is wet
END WHERE

Step 5: If the surface_submergence_state nodal attribute was specified, set nodes to a dry state if the nodal attribute value is 1.

IF (loadStartDry.eqv..true.) THEN
WHERE (STARTDRY.eq.1)
NNODECODE=0
END WHERE
ENDIF

Step 6: Perform “landlock” calculations to prevent a nonphysical situation where a single wet node is surrounded by elements that do not have three wet nodes.

! Dry any landlocked nodes by checking that they are connected to at
! least 1 functioning element.
DO I=1,NP ! loop over nodes
MJU(I)=0 ! initialize wet neighbor count for each node
ENDDO
DO I=1,NE ! loop over elements
NM1=NM(I,1) ! get node numbers around the element
NM2=NM(I,2)
NM3=NM(I,3)
NC1=NNODECODE(NM1) ! get wet/dry state at each node around the element
NC2=NNODECODE(NM2)
NC3=NNODECODE(NM3)
NCELE=NC1*NC2*NC3*NOFF(I) ! if a single node is dry, this is zero; if all nodes wet, this is 1
MJU(NM1)=MJU(NM1)+NCELE
MJU(NM2)=MJU(NM2)+NCELE
MJU(NM3)=MJU(NM3)+NCELE
ENDDO
DO I=1,NP
! if the node is wet and is surrounded by nonfunctioning elements, it is landlocked
IF((NNODECODE(I).EQ.1).AND.(MJU(I).EQ.0)) THEN
NNODECODE(I)=0
write(scratchMessage,9883) I
call allMessage(INFO,scratchMessage)
ENDIF
ENDDO
9883 FORMAT(‘Node ‘,i0,’ dried (landlocking).’)

Q: When I run the adcirc, it always logs the following message: “RE-SETTING GWCE SYSTEM MATRIX”. Should I be concerned?

The GWCE message you see is just an informational message, it is not a warning or error. The GWCE system matrix is on the left hand side of the equations and it must be constructed at the start of your simulation and then rebuilt each time there is a change in your domain, i.e., every time there is an occurrence of wetting or drying. It is normal.

Appendix A: Content
——————-
Please see also the ADCIRC information available at the Inundation Science and Engineering Cooperative (ISEC): http://isec.nacse.org.
Some of the general information about ADCIRC in this document was taken from this original source.