Introduction
The Advanced Circulation Model (ADCIRC) [1] is widely used to model tides, storm surge-related coastal inundation, and general ocean circulation. While it is one of the most popular coastal prediction models among coastal modelers, ADCIRC’s input files are highly complex and require high amounts of rote memorization. For example, the main model configuration (fort.15) file contains several interdependent entries; changing the value of a single line may drastically alter the contents of the rest of the file and even the locations of other configuration entries. Although the vast majority of the configuration file inputs are described in detail on the ADCIRC website, the configuration file itself has a relatively high level of cyclomatic complexity. Considering that, for the most part, the canonical ADCIRC workflow intends for users to modify configuration parameters “on-the-fly” in order to debug potential modeling issues, this complexity increases the difficulty of keeping the configuration options consistent with each other for even the simplest changes. For example, when the user changes the modeled timestep DTDP in the fort.15 file (perhaps the most common step when debugging convergence issues), they must also manually recompute several additional variables, namely NSPOOLE, NSPOOLV, NSPOOLM, NSPOOLC, etc., and enter them into the configuration alongside the initial change. This is but one of many examples of cyclomatically dependent configuration options in the fort.15 file. The issues and potential sources of human error arising from this interdependency, of parameters needing to change together in order to maintain configuration consistency, is one of the main issues ADCIRCpy aims to alleviate through it’s API.
Many ADCIRC input files (besides fort.15) require pre-processing before ADCIRC can parse them. To name one example, the parametric wind fields that ADCIRC computes depend on obtaining the relevant “best track” data from the National Hurricane Center (NHC) FTP archives. NHC provides these files in a format unreadable by ADCIRC; they must be sanitized before ADCIRC is able to parse them correctly. Several ADCIRC users have developed scripts for processing these files, but most of these are not user-friendly. For example, the official ADCIRC Surge Guidance System (ASGS) is comprised of a variety of scripts in and utilizes several languages. As such, it is not straightforward to install and use, particularly for custom workflows outside the scope of the design of the ASGS developers. To this end ADCIRCpy provides an advantage, in that the sanitized file can be generated with a single command from the shell or through a Python script calling the API, allowing the processing to be customized to virtually any modeling scenario.
ADCIRCpy provides another convenience when generating the spatially-varying TAU0 factor. In the conventional (non-ADCIRCpy) workflow, the user compiles and runs a separate Fortran application (tau0_gen.f90 [2]) to generate TAU0. In contrast, ADCIRCpy is able to both generate this data and integrate the results into model inputs without relying on the user to manually compile or invoke external tools. Other examples of external tools requiring separate compilation and execution on a typical ADCIRC workflow include tide_fac.f90 (TPXO interpolation), etc. ADCIRCpy offers “pythonic” equivalents to all of these tools within a single framework that does not require Fortran compilation.
ADCIRCpy was built with users and operational applications in mind, as a framework exposing both a Python API and a command line interface. The interface provides several ways to interact with ADCIRC, depending on the use case. The command line options offer a quick way of generating tidal-only hindcasts and forecasts, as well as “best track” configurations using parametric winds suitable for storm surge hindcasts. ADCIRCpy is open-source, hosted and maintained on GitHub by the Office of Coast Survey of NOAA National Ocean Service Coastal Marine Modeling Branch (CMMB), and can be installed from the Python Package Index (PyPI) by running the following command on a system with Python and pip:
pip install adcircpy