Python API

The main idea of ADCIRCpy is to encompass all necessary implementation into an object-oriented framework reusable over many different modeling scenarios. The core library is designed such that it can operate over an arbitrary mesh and avoid “hard-coding” of paths and project components. Instead, all user-defined data sets are given as inputs to relevant API components. The current discussion will be limited to the most common library components used by users. Most “private” library components will not be discussed in this document.

adcircpy.mesh module

The adcircpy.mesh module contains all methods and functions related to input and output of an arbitrary AdcircMesh UML diagram (fort.13, fort.14). The main user interface of the mesh module is the adcircpy.mesh.AdcircMesh class, which inherits from adcircpy.mesh.Fort14. An AdcircMesh object can read an AdcircMesh UML diagram (fort.14), configure model forcings, hold nodal attribute information (fort.13), and generate select parameters via additional methods. For example, the primitive_weighting_in_continuity_equation parameter can be generated via the .generate_tau0() method. This method is a pythonic implementation of the tau0_gen.f90 [1]. Another nodal attribute that can be set using a built-in method is the mannings_n_at_sea_floor, which can be set via the .generate_constant_mannings_n() or .generate_linear_mannings_n() methods. This elucidates the convenience of the object-oriented implementation; all necessary tools exist in the same workspace and are accessible via the same object on a per-instance basis. The mesh module also contains parsers that can read and convert between fort.14 and *.2dm files.

Grd class

The Grd class is used as a base class that containing multiple useful functions and methods related to the specific format for an unstructured mesh in 2-dimensional space used by ADCIRC. In the context of ADCIRCpy, the Grd class can be instantiated with a properly constructed nodes and elements dictionary, but it is also used as a base class for other ADCIRC objects that can be represented as conforming to a euclidean graph in 2-dimensional space (for example, the output file maxele.63.nc).

class adcircpy.mesh.base.Grd(nodes: DataFrame, elements: DataFrame | None = None, description: str | None = None, crs: CRS | None = None)

transform_to(dst_crs: CRS)

Transforms coordinate system of mesh in-place.

Example 2 shows a demonstration of how this class can be instantiated with a test graph structure, while the Grd UML diagram (Unified Modeling Language) shows the output plot of the graph.

from adcircpy.mesh.base import Grd

nodes = {
    '1': ((0., 0.), -5.),
    '2': ((.5, 0.), -4.),
    '3': ((1., 0.), -3.),
    '4': ((1., 1.), -2.),
    '5': ((0., 1.), -1.),
    '6': ((.5, 1.5), 0.),
    '7': ((.33, .33), 1.),
    '8': ((.66, .33), 2.),
    '9': ((.5, .66), 3.),
    '10': ((-1., 1.), 4.),
    '11': ((-1., 0.), 5.),
}

elements = {
    '1': ['5', '7', '9'],
    '2': ['1', '2', '7'],
    '3': ['2', '3', '8'],
    '4': ['8', '7', '2'],
    '5': ['3', '4', '8'],
    '6': ['4', '9', '8'],
    '7': ['4', '6', '5'],
    '8': ['5', '10', '11', '1'],
    '9': ['9', '4', '5'],
    '10': ['5', '1', '7']
}

fort14 = Grd(nodes, elements)

fort14.triplot(linewidth=1, show=True)

Plotting result of Example 2

UML component diagram for the Grd class

Fort14 class

The Fort14 class is a subclass of the Grd class, which is used specifically for fort.14 file types.

class adcircpy.mesh.fort14.Fort14(*args, boundaries=None, **kwargs)

Class that represents the unstructured planar mesh used by SCHISM.

transform_to(dst_crs: CRS)

Transforms coordinate system of mesh in-place.

As can be seen from Fort14 UML diagram diagram, the Fort14 class essentially extends the Grd class by adding model boundaries. While the Hull instances in the Grd provides geometrical boundaries for the Grd types (which are derived from the connectivity table), the Fort14Boundaries instance provides an API to interact with the model’s boundary types: ocean, land, interior, inflow, outflow, weir and culvert.

UML component diagram for the Fort14 class

AdcircMesh class

The AdcircMesh class is the center point of the ADCIRCpy interface. It consists of a mixin class that provides an API for reading and writing AdcircMesh UML diagram files, establishing the boundary and surface forcings, as well as establishing the model’s nodal attributes. The AdcircMesh class inherits properties and methods from Fort14, and acts as the main interface between the user and the ADCIRC model forcings and nodal attributes.

class adcircpy.mesh.mesh.AdcircMesh(*args, fort13=None, **kwargs)

Class used to configure ADCIRC model runs.

generate_tau0(default_value=0.03, threshold_distance=1750.0, shallow_tau0=0.02, deep_tau0=0.005, threshold_depth=-10.0, coldstart=True, hotstart=True)

Reimplementation of tau0_gen.f by Robert Weaver (2008) 1) computes distance to each neighboring node 2) averages all distances to find rep. distance @ each node. 3) Assigns a tau0 value based on depth and rep. distance. Asssumes threshold_distance is given in meters.

critical_timestep(cfl, maxvel=5.0, g=9.8)

http://swash.sourceforge.net/online_doc/swashuse/node47.html

transform_to(dst_crs: CRS)

Transforms coordinate system of mesh in-place.

Experienced ADCIRC users may also recognize familiar ADCIRC attribute and method names from AdcircMesh UML diagram, along with the attributes and methods inherited from Fort14. HSOFS mesh shows the output of the AdcircMesh.make_plot() method using the Hurricane Surge On-Demand Forecast System (HSOFS) mesh [2].

UML component diagram for the AdcircMesh class

HSOFS mesh plot using the AdcircMesh.make_plot() method

managing nodal attributes using the AdcircMesh class

The AdcircMesh UML diagram diagram shows that many attributes of the attributes defined in AdcircMesh class match the nodal attribute names allowed in the ADCIRC nodal attributes file (fort.13). These attributes have been defined explicitly in the AdcircMesh class so that the user can directly assign values to them. By doing so, these values are automatically enabled for the model and taken into account when generating the fort.15 file. The user just needs to generate the corresponding arrays. Alternatively, some nodal parameters can be populated through provided methods in the AdcircMesh class, for example the mannings_n_at_sea_floor can be set through the generate_linear_mannings_n() method. Additionally, the user can set custom patches of values to the nodal attributes by passing a Polygon or MultiPolygon instance to the AdcircMesh.add_nodal_attributes_patch() method.

adcircpy.Fort15 class

The Fort15 class meant to represent a fort.15 file instance. As shown in the UML diagram in Fort15 UML, this class contains attributes for all the configuration options for an ADCIRC model run. Most of these options can be directly overridden by the users, with the exception of a very few. However, most parameters that cannot be overridden directly by the users provide methods that will ultimately change their value to what the user requires. One example of an option that is not directly configurable through the class attributes are the A00, B00 and C00 factors. While the user cannot override any of these factors individually, the Fort15 class provides the set_time_weighting_factors_in_gcwe(A00, B00, C00) which will make sure that the input parameters are consistent with what ADCIRC expects.

Another example of an important parameter that should not be directly overridden, but for which public methods are provided that will modify the options is the IM parameter. This parameter is essentially a six digit integer that encodes multiple distinct configuration options. Additionally, this parameter has both single and double digit “shortcuts” to encode some of the most used options. These single and double digit codes can be expressed as six digit codes, therefore ADCIRCpy will only output the six digit version. This parameter is a very important one, and it might be difficult to memorize which digit does what, and which digit position relates which option. To deal with this, the Fort15 class attributes modify the final value of the IM parameter, as configured by the users. To illustrate this, consider the case where the user instantiates the Fort15 class like this: fort15 = Fort15(). Then the user can set the GWCE solver by setting fort15.gwce_solution_scheme = `implicit'. By doing this setting, several parameters will change: the values of A00, B00 and C00, and the values of IM. This particular parameter shows another example of how multiple lines in the fort.15 need to change in order to keep consistency of the inputs. Other class attributes that affect the IM parameter are: vertical_mode, lateral_stress_in_gwce, advection_in_gwce, lateral_stress_in_momentum and area_integration_in_momentum, among others.

Although not recommended, if the user still wishes to bypass any sanity checks, all the fort.15 parameters can be set directly by prefixing a single underscore in front of their corresponding Fort15 attribute. For example, the IM parameter can be set directly by simply fort15._IM = 11111. Note that using the single underscore prefix does not perform any sanity checks on the inputs, therefore by setting the values this way, fort.15 output consistency, nor Fort15 functionality can be guaranteed, therefore it still advisable to use the provided public methods to set the configuration options for the fort.15 file.

GWCE solution scheme selection options

gwce.solution.scheme	A00	B00	C00	IM
semi-implicit-legacy	0.35	0.3	0.35	511111
semi-explicit	0	1	0	511112
semi-implicit	0.5	0.5	0	511113

UML component diagram for the Fort15 class

adcircpy.forcing module

The adcircpy.forcing module contains a collection of modules, methods, functions, classes and procedures that directly relate to the different types of forcing that can be applied to the ADCIRC model. At the current state, the adcircpy.forcing module contains two main modules that are of major interest to the users: the adcircpy.forcing.tides module, and the adcircpy.forcing.winds module. These will be discussed in sections ADCIRCpy tides and ADCIRCpy winds respectively.

adcircpy.forcing.tides module

The adcircpy.forcing.tides module contains one main public interface class adcircpy.forcing.tides.Tides and two auxiliary classes for aggregating additional required tidal data: adcircpy.forcing.tides.HAMTIDE (ADCIRCpy HAMTIDE) and adcircpy.forcing.tides.TPXO (ADCIRCpy TPXO).

adcircpy.forcing.tides.Tides class

The adcircpy.forcing.tides.Tides class (abbreviated here as Tides) provides the main interface for instantiating tidal elevation amplitudes and phases for a model run. This public class has methods such as use_constituent(), use_all() and use_major() which can be used to enable the desired tidal constituents as forcings for the model. The Tides class implements the computation of the initial conditions for tidal boundary. This class implements the same functionality as the ADCIRC ` tide_fac.f90 <https://www.dropbox.com/s/t2c1a6zo6tracs8/tide_fac.f>`_ program, which implements the equations of [3] and it can be considered a direct “pythonic” port of this program. These equations provide the time dependent initial condition of the harmonic constituents of the tidal signal.

The Tides class also implements the usage of helper classes (derived from the TidalDatabase abstract class) in order to interpolate the harmonic elevation amplitude and phase for each tidal constituent at each boundary nodes. The concrete classes derived from TidalDatabase class implement a get_amplitude(constituent, vertices) and get_phase(constituent, vertices) method that returns the sea surface elevation amplitude and phase for the ADCIRC model. The user can choose between the HAMTIDE database [4] or the TPXO database [5] by using the database keyword argument during instantiation of the Tides class.

adcircpy.forcing.tides.HAMTIDE class

The adcircpy.forcing.tides.HAMTIDE class is used by the Tides class in order to interpolate harmonic constants to the boundary nodes, which are required for tidal model initialization. HAMTIDE database to obtain the information from the outputs of the Hamburg direct data Assimilation Methods for TIDEs model, which implements a methodology based on dynamical residuals as a component of the assimilation method to represent missing physics and their role in tidal dissipation by combination with measurements. This database includes amplitude and phase for sea-surface elevation and transport for the eight primary tidal constituents (N2, S2, M2, K2, P1, O1, K1, Q1). The data is provided as NetCDF files and through a live OpenDaP server.

adcircpy.forcing.tides.TPXO class

The adcircpy.forcing.tides.TPXO provides amplitude and phase for sea-surface elevation and transport for the eight primary tidal constituents (N2, S2, M2, K2, P1, O1, K1, Q1), two long-period (Mf, Mm), and three non-linear (M4, MS4, MN4) harmonic components. The TPXO model uses a methodology based on least-squares best-fits of the Laplace Tidal Equation and with respect to observed altimetry data. The TPXO is a proprietary database that is provided in NetCDF and binary formats. The users are responsible for registering and provisioning a copy of the database for ADCIRCpy.

adcircpy.forcing.winds module

The adcircpy.forcing.winds module provides access to wind-related forcings for the model. In particular, the users might be interested in running a parametric wind field as a first approximation for the model and for stability checks. The class used to generate parametric wind fields in ADCIRC is described in ADCIRCpy Best Track Forcing.

adcircpy.forcing.winds.BestTrackForcing class

The term “best track winds” refers to the set of spatially and temporally varying pressure and speed wind fields that are used to approximate planetary boundary layer vortices (hurricanes/typhoons). These best track winds are computed from sparse observational data. ADCIRCpy supports the generation of the input files required by ADCIRC in order to generate model runs using parametric wind models. The input files generated by ADCIRCpy uses by default the asymmetric wind field equations by setting the NWS parameter to the value of 20 in the fort.15 file.

adcircpy.driver module

The adcircpy.driver module consists of all methods and functions relating to ADCIRC forcing to generate an overlying task submission framework and configuration directories. adcircpy.driver contains module adcircpy.driver.AdcircRun.

adcircpy.driver.AdcircRun class

adcircpy.driver.AdcircRun can determine the tidal constituents (phases and amplitudes) at either selected points in the domain for velocity and elevation or at all points in the domain for velocity and elevation.

adcircpy.outputs module

adcircpy.outputs module contain following output files OutputFactory, OutputStations, StationTimeseries, ElevationStationsTimeseries, HarmonicConstituentsElevationStations, HarmonicConstituentsSurface, Maxele, ScalarSurfaceExtrema, ScalarSurfaceTimeseries and VelocityStations. These files provide valuable information about the currents and tides at all points in a model domain. Regarding the output, ADCIRC gives excellent flexibility. For example, the user can define that water surface elevations and velocities be inscribed only at chosen points in the domain fort.61. Alternatively, output at all positions in the environment can be requested fort.63 for velocity and elevation output.

[1]

Robert Weiver. Tau0_gen.f. October 2008. URL: https://www.dropbox.com/s/zb7xjzun7nco384/tau0_gen.f.

[2]

Riverside Technology, Inc and AECOM. Mesh development, tidal validation, and hindcast skill assessment of an ADCIRC model for the Hurricane Storm Surge Operational Forecast System on the US Gulf-Atlantic Coast. Technical Report, Riverside Technology, Inc., 2015. URL: https://cdr.lib.unc.edu/concern/articles/8336h638c?locale=en, doi:10.17615/4Z19-Y130.

[3]

Paul Schureman. Manual of harmonic analysis and prediction of tides. [ revised 1940 edition reprinted 1958 with corrections, reprinted 2001]. 1958. Google-Books-ID: jI8TAAAAYAAJ. doi:10.25607/OBP-155.

[4]

E. Taguchi, D. Stammer, and W. Zahel. Inferring deep ocean tidal energy dissipation from the global high-resolution data-assimilative HAMTIDE model. Journal of Geophysical Research: Oceans, 119(7):4573–4592, jul 2014. doi:10.1002/2013jc009766.

[5]

Gary D. Egbert and Svetlana Y. Erofeeva. Efficient inverse modeling of barotropic ocean tides. Journal of Atmospheric and Oceanic Technology, 19(2):183–204, February 2002. URL: https://journals.ametsoc.org/view/journals/atot/19/2/1520-0426_2002_019_0183_eimobo_2_0_co_2.xml (visited on 2021-02-10), doi:10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2.