Troubleshooting for SWAN+ADCIRC

Updated 2016/08/02: Added the issue 5.

As we gain more experience with SWAN+ADCIRC, we have noticed a few minor issues with respect to actually running the coupled model. I have listed a few of them here, and I have described how to fix (or at least work around) each problem. Hopefully this page will be useful to new users of SWAN+ADCIRC.

This page will be updated as we encounter new issues. If you encounter an issue that belongs on this page, then please let me know. We want all simulations to step right along:

Time-Stepping

1. The pre-processor adcprep was not compiled for use with the coupled SWAN+ADCIRC.

This is a tricky error to debug when you first encounter it, because the code will write the following error message:

Input file missing

into either the screen output or the Errfile within each sub-directory. However, it is likely that all of the input files will be present in the run directory, including the SWAN input files (fort.26 and swaninit).

The first thing to check is whether the fort.26 file was copied into the local sub-directories. Each core needs its own copy of the SWAN control file. If this file is not located in each of the sub-directories, then adcprep did not process it correctly.

In the instructions on how to compile and run SWAN+ADCIRC, step 4 describes how to compile a special version of adcprep that is compatible with the coupled model. The trick is to add the -DADCSWAN compiler flag to the appropriate line in the cmplrflags.mk file:

Changes-For-ADCPREP

This modified version of adcprep will do two things:

  1. It will number the mesh boundaries in the global fort.14 file, and then it will carry forward those global numbers to the local sub-meshes. This is helpful when the user wants to specify boundary conditions within SWAN. The global boundary number can be used within the fort.26 file to identify where the incoming wave information should be applied.
     
  2. It will copy the SWAN control file (fort.26) into the sub-directories, so that each core can have its own copy.

Thus, to fix this problem, you can re-compile adcprep and use the modified version to pre-process your input files. The fort.26 file should be copied into each of the local sub-directories.

2. The swaninit file was not located in the run directory.

The code will write the same error message:

Input file missing

into either the screen output or the Errfile within each sub-directory. An examination of the run directory will find that the SWAN input files (fort.26 and swaninit) are present. The rest of the ADCIRC files will probably be fine, too. And the fort.26 file was copied into each of the local sub-directories.

However, it is likely that the swaninit file was not located in the run directory when the simulation was started. If SWAN does not find that file when it starts, then it will create it from scratch, and it will populate it with default values. The control file is given the default name of INPUT, and then SWAN tries to find and read that default file.

This is a problem for the coupled SWAN+ADCIRC, in which the control file should be named fort.26. (There should not be an INPUT file.) So, even though it looks like there is a swaninit file in the run directory, that file may not be correct. To fix this problem, either edit the new swaninit file so that it points to the fort.26 file, or else copy a good swaninit file into the run directory.

3. SWAN does not seem to start or end at the dates/times specified in its fort.26 control file.

This is also an extremely tricky error to debug, because the simulation does not crash or end unexpectedly. The coupled model will run and produce output. A common result of this error is that the maximum files (swan_HS_max.63, etc.) will not be written at the end of the simulation.

A closer inspection of the screen output will reveal that the dates/times do not match to those specified in the input file. This error is related to the datestrings used by SWAN. These datestrings have the format:

YYYYMMDD.HHMMSS

That decimal in the middle of the datestring can be misleading to first-time users of SWAN. The decimal only serves as a visual break in the middle of what would otherwise be a 14-character string. It does not indicate that fractional days can be specified.

For example, noon on my birthday would be specified as:

19810118.120000

where the 12 to the right of the decimal indicates noon on a 24-hour clock. This is completely different from the incorrect specification of:

19810118.500000

which looks like it should also specify the middle of the day. This is wrong. Sometimes SWAN will choke on this incorrect specification, but usually it will muscle through the error. In this case, SWAN would start on 1981/01/18 + 50hr, or 19810120.0200000. This is more than two days later than the intended start date/time. The same format holds for the ending datestrings.

To fix this problem, the datestrings need to be formatted correctly in the fort.26 file.

4. The simulation finished successfully, but it did not write any output files with station data for the SWAN wave parameters.

As part of the coupling of SWAN+ADCIRC, I linked the output of the wave parameters (such as significant wave heights, mean and peak periods, etc.) to the output of the wind field. So, if the user asks for output of pressures (fort.73) and wind velocities (fort.74), then the code will also write the radiation stress gradients (rads.64) and several files with the wave parameters (swan_*.63).

The trick is that these files contain global information, i.e., significant wave heights at every vertex in the unstructured mesh. Often, we want to compare time series of computed values to specific measurement locations, and we are less interested in the results everywhere in the domain. ADCIRC allows for the output of computed results at specific locations. By adding the lon,lat coordinates to the list of stations in the fort.15, the user can receive local files with water levels (fort.61), currents (fort.62), etc.

So it would also be nice to have local station files for the wave parameters, i.e., with a swan_HS.61 file, for example. Unfortunately, the coupling does not yet have that feature. In the meantime, there are two possible work-arounds:

  1. Use the SWAN output commands in the fort.26 file. As described in its online User Manual, SWAN has several commands to specify output locally or globally. As an example, the user could create a text file called Stations.loc and populate it with the lon,lat coordinates of the stations:
     

    -79.9791376572 32.6585224446
    -79.9980006794 32.6906422936
    ...

    Then the following commands in the fort.26 file would tell SWAN to read that text file and write output files with results at those stations:

    POINTS 'Stations' FILE 'Stations.loc'
    TABLE 'Stations' HEAD 'Stations.out' DIR HS TMM10 TPS OUTPUT 20110915.000000 1200 SEC

    where the computed results for four wave parameters (DIR, HS, TMM10 and TPS) would be written to the file Stations.out, starting at 2011/09/15/0000 UTC and repeating every 1200 seconds.

    The disadvantage to this method is that each core will write its own station output file into its own sub-directory. If the local sub-mesh happens to contain a station, then SWAN will interpolate the computed results to that station location, and then it will write them to the output file. However, if the local sub-mesh does not contain the station, then SWAN will populate the output file with N/A or something similar. So the user must determine which sub-mesh contains the stations, and then post-process the correct output file.

    However, the advantage to this method is that the user can ask SWAN to output any of its wave parameters, not just the four that are written as global files by SWAN+ADCIRC. If the user wants to see a different definition for mean period, or the directional spreading, or mean wavelength, or any of the parameters described in the SWAN User Manual, then it is fairly easy to request their output.

  2. The other method is to post-process the global output by using the PullTimeSeries.f90 program. This program will read a text file containing lon,lat coordinates of stations, interpolate their locations in the mesh, and then read a global output file like the swan_HS.63 file. It will then write a station output file that is formatted like the ADCIRC station files (fort.61, fort.71). The text file has the format:
     

    NumStations
    1 -79.9791376572 32.6585224446
    2 -79.9980006794 32.6906422936
    ...

    The user will need to give the name of this text file, the name of the mesh, the name of the existing global output file, and the name of the new station output file.

    The disadvantage to this method is that it is obviously a post-processing step, so the user has to run this program after the simulation has finished. Also, the time increment in the new station output file will be limited to the time increment in the existing global output file. For example, if your existing swan_HS.63 file has significant wave heights at hourly intervals, then your new swan_HS.61 file will also have information at hourly intervals.

    However, the advantage to this method is that you can go back to existing results and pull results at new stations, without having to re-do the simulation. This can be very useful if you decide later to add new stations to your post-processing. Just run this program and generate a new station output file.

Neither of these work-arounds is perfect, but they can provide meaningful SWAN results at station locations. Eventually this capability will be added to SWAN+ADCIRC, and these work-arounds will no longer be necessary.

5. The job hangs or fails during the second SWAN time step.

There are many possible causes for this type of error, but one cause may be the quality of the unstructured mesh. As with its other mesh-quality checks, it is possible for a mesh to work fine with ADCIRC, but to fail with SWAN.

In this example, SWAN is very sensitive to unassigned boundaries in the mesh. We found a few places in the NC9 mesh where islands had been implemented, but the island boundary condition had not been assigned. Instead, the islands were in the mesh as holes, without any nodestring or boundary condition. These islands were located along the SC coast, which has lower resolution because it is not the region of interest.

As an example, please see the image below. SWAN gave errors at vertices 311146 and 311145. These are nodes forming the hole in red color. It was not defined as a node string. But the opening formed by node numbers 311146, 311147, 315795, 320378 and 315794 (shown in green) did not give the error, because it was defined as a node string.

This mesh worked fine with ADCIRC, but failed with SWAN. The message in the Errfile (in the PE subdirectories where the error was detected) was:

   Area of centroid dual is negative or zero in vertex

The solution is to add a nodestring around the island, and then assign a boundary condition. After doing this, the new version of SWAN worked fine.

Example of assigned (green) and unassigned (red) island boundaries in an unstructured mesh.

Example of assigned (green) and unassigned (red) island boundaries in an unstructured mesh.