From 609348f1060087a336267a0955fa74a40db46bcf Mon Sep 17 00:00:00 2001 From: Zachary Burnett Date: Thu, 2 Dec 2021 15:55:26 -0500 Subject: [PATCH] generate documentation automatically with Sphinx (#141) * remove submodule as it no longer exists * first draft of Sphinx docs * copy documentation from ADCIRCpy NOAA tech report * add figures * add references to TOC and also turn citations into footnotes * name abstract * use `coupledmodelvalidation` for `plot_fort61` * `:python:` is not a valid directive * add references to abstract, and fix references page to list all citations * add docs badge and link to docs Co-authored-by: zacharyburnett --- .gitattributes | 1 + .gitmodules | 3 - .readthedocs.yml | 20 ++ README.md | 3 + adcircpy/cmd/plot_fort61.py | 2 +- docs/Makefile | 20 ++ docs/NOAATechnicalReport2021 | 1 - docs/make.bat | 35 ++++ docs/source/abstract.rst | 11 ++ docs/source/acknowledgments.rst | 4 + docs/source/basic_usage.rst | 89 +++++++++ docs/source/cli.rst | 106 ++++++++++ docs/source/conf.py | 107 ++++++++++ docs/source/figures/Fort14_UML.png | 3 + docs/source/figures/Grd_UML.png | 3 + .../figures/classes_adcircpy.fort15.png | 3 + .../classes_adcircpy.mesh.AdcircMesh.png | 3 + .../source/figures/fort14_triplot_example.png | 3 + docs/source/figures/hsofs_mesh.png | 3 + docs/source/index.rst | 12 ++ docs/source/introduction.rst | 16 ++ docs/source/python_api.rst | 186 ++++++++++++++++++ docs/source/references.bib | 109 ++++++++++ docs/source/references.rst | 5 + setup.py | 9 + 25 files changed, 752 insertions(+), 5 deletions(-) create mode 100644 .gitattributes delete mode 100644 .gitmodules create mode 100644 .readthedocs.yml create mode 100644 docs/Makefile delete mode 160000 docs/NOAATechnicalReport2021 create mode 100644 docs/make.bat create mode 100644 docs/source/abstract.rst create mode 100644 docs/source/acknowledgments.rst create mode 100644 docs/source/basic_usage.rst create mode 100644 docs/source/cli.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/figures/Fort14_UML.png create mode 100644 docs/source/figures/Grd_UML.png create mode 100644 docs/source/figures/classes_adcircpy.fort15.png create mode 100644 docs/source/figures/classes_adcircpy.mesh.AdcircMesh.png create mode 100644 docs/source/figures/fort14_triplot_example.png create mode 100644 docs/source/figures/hsofs_mesh.png create mode 100644 docs/source/index.rst create mode 100644 docs/source/introduction.rst create mode 100644 docs/source/python_api.rst create mode 100644 docs/source/references.bib create mode 100644 docs/source/references.rst diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..24a8e879 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +*.png filter=lfs diff=lfs merge=lfs -text diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index f706f965..00000000 --- a/.gitmodules +++ /dev/null @@ -1,3 +0,0 @@ -[submodule "docs/NOAATechnicalReport2021"] - path = docs/NOAATechnicalReport2021 - url = git@github.com:jreniel/ADCIRCpyNOAATechReport.git diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 00000000..e0b4af0f --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,20 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + +build: + os: ubuntu-20.04 + tools: + python: "3.9" + +sphinx: + configuration: docs/source/conf.py + +python: + install: + - method: pip + path: . + extra_requirements: + - documentation diff --git a/README.md b/README.md index c3317c9b..dd6e6747 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,9 @@ [![version](https://img.shields.io/pypi/v/adcircpy)](https://pypi.org/project/adcircpy) [![license](https://img.shields.io/github/license/zacharyburnettNOAA/adcircpy)](https://opensource.org/licenses/gpl-license) [![style](https://sourceforge.net/p/oitnb/code/ci/default/tree/_doc/_static/oitnb.svg?format=raw)](https://sourceforge.net/p/oitnb/code) +[![documentation](https://readthedocs.org/projects/adcircpy/badge/?version=latest)](https://adcircpy.readthedocs.io/en/latest/?badge=latest) + +Documentation can be found at https://adcircpy.readthedocs.io ### Installation notes: diff --git a/adcircpy/cmd/plot_fort61.py b/adcircpy/cmd/plot_fort61.py index 4a863c06..af4e4728 100644 --- a/adcircpy/cmd/plot_fort61.py +++ b/adcircpy/cmd/plot_fort61.py @@ -3,11 +3,11 @@ import os from pathlib import Path +from coupledmodelvalidation import COOPS import matplotlib.pyplot as plt import numpy as np from adcircpy.outputs import Fort61 -from adcircpy.validation import COOPS def parse_args(): diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/NOAATechnicalReport2021 b/docs/NOAATechnicalReport2021 deleted file mode 160000 index 1429b896..00000000 --- a/docs/NOAATechnicalReport2021 +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 1429b896a4b746d8590b817660e506d21f2e87e3 diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..061f32f9 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/abstract.rst b/docs/source/abstract.rst new file mode 100644 index 00000000..ec65a76a --- /dev/null +++ b/docs/source/abstract.rst @@ -0,0 +1,11 @@ +Abstract +======== + +The Advanced Circulation Model (ADCIRC) :footcite:p:`Luettich1992` is a Fortran program used for modeling ocean circulation due to tides, surface waves and atmospheric forcings. +However, the input formats and configuration are inflexible and not straight forward for operational implementation, making rapid iteration of model testing, ensemble configuration, and model coupling complicated. +Here, we introduce a flexible abstraction of model inputs and outputs written in Python, called ADCIRCpy :footcite:p:`JaimeCalzadaNOAA2021`, that provides a simpler user interface for automatically generating ADCIRC configuration to a variety of inputs and model scenarios. +This documentation outlines 1. the needs for such an abstraction, 2. the peculiarities and challenges with the ADCIRC model that necessitate custom logic, and 3. methodologies for generalizing user input in such a way as to make generating model configurations consistent, fast, and efficient. + +`Python, ADCIRC, configuration generation, circulation modeling, user interface` + +.. footbibliography:: diff --git a/docs/source/acknowledgments.rst b/docs/source/acknowledgments.rst new file mode 100644 index 00000000..ce526768 --- /dev/null +++ b/docs/source/acknowledgments.rst @@ -0,0 +1,4 @@ +Acknowledgments +=============== + +The authors would like to express his acknowledgment to Dr. Joannes Westerink for motivating this work, and to all the ADCIRC developers who have worked to make the ADCIRC software possible. diff --git a/docs/source/basic_usage.rst b/docs/source/basic_usage.rst new file mode 100644 index 00000000..f9ba9fd7 --- /dev/null +++ b/docs/source/basic_usage.rst @@ -0,0 +1,89 @@ +Basic Usage +=========== + +`Example 1`_ (below) illustrates usage of the ADCIRCpy Python API to generate a "best track" parametric wind configuration for running ADCIRC on hurricane Sandy (2012). + +.. _Example 1: + +.. code-block:: python + + #!/usr/bin/env python + + from datetime import timedelta + + from adcircpy import AdcircMesh, AdcircRun, Tides + from adcircpy.forcing.winds import BestTrackForcing + from adcircpy.server import SlurmConfig + + # load an ADCIRC mesh grid from a `fort.14` file to a new mesh object + mesh = AdcircMesh.open('fort.14', crs='epsg:4326') + + # add nodal attributes from a `fort.13` file to the mesh object + mesh.import_nodal_attributes('fort.13') + + # create a tidal forcing object, using all constituents + tidal_forcing = Tides() + tidal_forcing.use_all() + + # add data from the tidal forcing object to the mesh object + mesh.add_forcing(tidal_forcing) + + # create a wind forcing object for Hurricane Sandy (2012) + wind_forcing = BestTrackForcing('Sandy2012') + + # add wind forcing data to the mesh object + mesh.add_forcing(wind_forcing) + + # create a Slurm (HPC job manager) configuration object. + slurm = SlurmConfig( + account='account', + ntasks=1000, + run_name='ADCIRCpy documentation example', + partition='partition', + walltime=timedelta(hours=8), + mail_type='all', + mail_user='example@email.gov', + log_filename='example.log', + modules=['intel/2020', 'impi/2020', 'netcdf/4.7.2-parallel'], + path_prefix='$HOME/adcirc/build', + ) + + # create an ADCIRC run driver object + driver = AdcircRun( + mesh=mesh, + server_config=slurm, + spinup_time=timedelta(days=15), + ) + + # write configuration files to the specified directory + driver.write(output_directory="./model_inputs") + +The set of files generated by this configuration (``fort.14``, ``fort.15.coldstart``, ``fort.15.hotstart``, ``fort.22``, and ``slurm.job``) represents the minimum working example for an ADCIRC run using parametric winds. To submit this configuration to the Slurm job manager, run the following command in a shell with access to the ADCIRC binaries: + +.. code-block:: shell + + sbatch slurm.job + +Note that this setup generates model inputs based on default values. These may not be necessarily optimal. For this reason, it is advisable that users perform checks of the outputs and introduce optimizations by modifying the parameters given to the Python API. For example, the user might want to check that the auto-computed timestep matches the expectations from experience. Instead of doing manual modifications to the ``fort.15`` file, the user makes use of the ADCIRCpy module to customize and optimize their modeling needs. If the user, for example, requires their model to use a specific timestep of two seconds, it would suffice to execute the following statement: + +.. code-block:: python + + driver.timestep = 2 + +before :code:`driver.write()`. Most of the ``fort.15`` options can be overridden directly by the user, with a very small exception of parameters that should be considered "private" in the context of the ``fort.15`` file. + +.. code-block:: python + + # Modify timestep to 2 seconds. + driver.timestep = 2. + + # Add a constant Mannings coefficient field to the mesh + mesh.mannings_n_at_sea_floor = mesh.coords.shape[0]*[0.025] + + # generate TAU0 factors + mesh.generate_tau0() + + # Write new model configuration to disk. + driver.write("model_inputs_modified", overwrite=True) + +After these modifications, the resulting directory contains ``fort.13``, ``fort.14``, ``fort.15.coldstart``, ``fort.15.hotstart``, ``fort.22``, and ``slurm.job``. The new ``fort.13`` includes the newly-added Manning's N and :code:`TAU0` factors. diff --git a/docs/source/cli.rst b/docs/source/cli.rst new file mode 100644 index 00000000..e0e9f0c4 --- /dev/null +++ b/docs/source/cli.rst @@ -0,0 +1,106 @@ +CLI Commands +============ + +The :code:`adcircpy` command line interface (CLI) provides commands accessible from the command line, allowing a smart way to produce forecasts, tidal-only hindcasts, "best track" hindcast operations, and practicing parametric winds appropriate for storm surge hindcasts, for rapid iteration and debugging. A single command generates a sanitized file through Python code, which is user-customized to the virtual model scenario. + +``tide_gen`` +------------ +The :code:`tide_gen` command generates the tidal forcing table required in the ``fort.15`` file. The generated table is suitable for being pasted onto a target ``fort.15`` file. In reality, this algorithm calls the same functions invoked when generating full model runs, so it can be used to check whether the tidal forcing outputs will look reasonable before running the entirety of the algorithm. + +.. code-block:: shell + + tide_gen /path/to/your/fort.14 '2021-02-26T00:00:00' 15 --mesh-crs='epsg:4326' + +.. program-output:: tide_gen -h + +``tidal_run`` +------------- +The :code:`tidal_run` entrypoint will generate the necessary set of input files for forecast and hindcast tidal-only runs with any mesh. Most of the options that tidal_run takes are also valid for other command line entry points, so getting familiar with the options on tidal_run is helpful to understand the options for more advanced CLI entry points. A tidal only run is perhaps the first step towards mesh validation, and mesh stability checks, therefore having an entrypoint that is able to generate ADCIRC input files for tidal only runs pays greatly for initial mesh stability checks. + +.. code-block:: shell + + tidal_run \ + /path/to/fort.14 \ + $(date +"%Y-%m-%dT%H:%M:%S") \ + 15 \ + --spinup-days=5 \ + --tau0-gen \ + --crs=EPSG:4326 \ + --constituents=all \ + --timestep=10. \ + --stations-file=stations.txt \ + --elev-stat=6. \ + --generate-linear-mannings + +.. program-output:: tidal_run -h + +``best_track_run`` +------------------ +The :code:`best_track_run` command line entry point was designed to be able to generate a full parametric wind run in ADCIRC from the command line. This entry point essentially encapsulates most of the :code:`adcircpy` functionality in a single command. The following is an example of how to invoke this functionality from the bash shell. + +.. code-block:: shell + + best_track_run \ + fort.14 \ + Ike2008 \ + --spinup-days=15 \ + --crs=EPSG:4326 \ + --fort13=fort.13 \ + --output-directory=Ike2008 \ + --constituents=major \ + --skip-run \ + --generate-linear-mannings \ + --tau0-gen \ + --timestep=1.0 \ + --elev=60. \ + --stations-file=coops.txt \ + --elev-stat=6. \ + --binaries-prefix=.python_env/bin \ + --overwrite \ + --use-slurm \ + --account=nosofs \ + --slurm-ntasks=800 \ + --partition=orion \ + --walltime=8 \ + --mail-type=all \ + --mail-user=jaime.calzada@noaa.gov \ + --module=intel/2020 \ + --module=impi/2020 \ + --module=netcdf/4.7.2-parallel \ + --log-level=info + +.. program-output:: best_track_run -h + +``best_track_file`` +------------------- +The :code:`best_track_file` entry point generates an ``aswip``-ready "best track" file. This uses the :code:`adcircpy.forcing.winds.BestTrackForcing` class. + +.. code-block:: shell + + best_track_file Sandy2012 + +.. program-output:: best_track_file -h + +``fort63`` +---------- +.. program-output:: fort63 -h + +``plot_maxele`` +--------------- +.. program-output:: plot_maxele -h + +``plot_fort61`` +--------------- +.. code-block:: shell + + plot_fort61 /path/to/fort.61.nc MSL --show --coops-only + +.. program-output:: plot_fort61 -h + +``plot_mesh`` +------------- +.. code-block:: shell + + plot_mesh /path/to/fort.14 --show-elements + +.. program-output:: plot_mesh -h diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..3cf0514b --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,107 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +import os +from os import PathLike +from pathlib import Path +import subprocess +import sys + +from dunamai import Version +from setuptools import config + + +def repository_root(path: PathLike = None) -> Path: + if path is None: + path = __file__ + if not isinstance(path, Path): + path = Path(path) + if path.is_file(): + path = path.parent + if '.git' in (child.name for child in path.iterdir()) or path == path.parent: + return path + else: + return repository_root(path.parent) + + +sys.path.insert(0, str(repository_root())) + +subprocess.run( + f'{sys.executable} -m pip install -U pip', + shell=True, + stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL, +) + +# -- Project information ----------------------------------------------------- +metadata = config.read_configuration('../../setup.cfg')['metadata'] + +project = metadata['name'] +author = metadata['author'] +copyright = f'2021, {author}' + +# The full version, including alpha/beta/rc tags +try: + release = Version.from_any_vcs().serialize() +except RuntimeError: + release = os.environ.get('VERSION') + +# -- General configuration --------------------------------------------------- + +autoclass_content = 'both' # include both class docstring and __init__ +autodoc_default_options = { + # Make sure that any autodoc declarations show the right members + 'members': True, + 'inherited-members': True, + 'private-members': True, + 'show-inheritance': True, +} +autosummary_generate = True # Make _autosummary files and include them +napoleon_numpy_docstring = False # Force consistency, leave only Google +napoleon_use_rtype = False # More legible + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinxcontrib.bibtex', + 'sphinxcontrib.programoutput', + # Need the autodoc and autosummary packages to generate our docs. + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + # The Napoleon extension allows for nicer argument formatting. + 'sphinx.ext.napoleon', + 'm2r2', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# -- Extension configuration ------------------------------------------------- +source_suffix = ['.rst', '.md'] +bibtex_bibfiles = ['references.bib'] diff --git a/docs/source/figures/Fort14_UML.png b/docs/source/figures/Fort14_UML.png new file mode 100644 index 00000000..c57d0640 --- /dev/null +++ b/docs/source/figures/Fort14_UML.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:de37394ac5f475658ffc7738ff5108d58a4f2d7c39dca62b5a704fc03e79d14e +size 132435 diff --git a/docs/source/figures/Grd_UML.png b/docs/source/figures/Grd_UML.png new file mode 100644 index 00000000..87fbc600 --- /dev/null +++ b/docs/source/figures/Grd_UML.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e3b1e2a831158103077610286e1c420d36f29e4b32a929b9fe77fb74d64bf829 +size 143448 diff --git a/docs/source/figures/classes_adcircpy.fort15.png b/docs/source/figures/classes_adcircpy.fort15.png new file mode 100644 index 00000000..5c3d2ae5 --- /dev/null +++ b/docs/source/figures/classes_adcircpy.fort15.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6d112d395ea7b67ef00e384ece27133910635a3ff1b44622d9be62ad7101d776 +size 246154 diff --git a/docs/source/figures/classes_adcircpy.mesh.AdcircMesh.png b/docs/source/figures/classes_adcircpy.mesh.AdcircMesh.png new file mode 100644 index 00000000..c1498d02 --- /dev/null +++ b/docs/source/figures/classes_adcircpy.mesh.AdcircMesh.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:da5ac0116ddba81c7910820411ac6bd08de84be9d6ebaeb7a1e64d0f8cc9d54c +size 335976 diff --git a/docs/source/figures/fort14_triplot_example.png b/docs/source/figures/fort14_triplot_example.png new file mode 100644 index 00000000..5e012801 --- /dev/null +++ b/docs/source/figures/fort14_triplot_example.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c419955fcbde2b9c20f72dda85f9c88ea1ce863324f92efb4c0bbfea4c046fdc +size 38055 diff --git a/docs/source/figures/hsofs_mesh.png b/docs/source/figures/hsofs_mesh.png new file mode 100644 index 00000000..22a6ff9f --- /dev/null +++ b/docs/source/figures/hsofs_mesh.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:713272729c04ea74763147b228ab5ad0754d3406fef5f8e4024e6bab0f3ffd6e +size 715420 diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..c0d37c59 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,12 @@ +.. mdinclude:: ../../README.md + +.. toctree:: + :hidden: + + abstract + introduction + basic_usage + python_api + cli + acknowledgments + references diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst new file mode 100644 index 00000000..df37e2d3 --- /dev/null +++ b/docs/source/introduction.rst @@ -0,0 +1,16 @@ +Introduction +============ + +The Advanced Circulation Model (ADCIRC) :footcite:p:`Luettich1992` 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 :code:`DTDP` in the ``fort.15`` file (perhaps the most common step when debugging convergence issues), they must also manually recompute several additional variables, namely :code:`NSPOOLE`, :code:`NSPOOLV`, :code:`NSPOOLM`, :code:`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 :code:`TAU0` factor. In the conventional (non-ADCIRCpy) workflow, the user compiles and runs a separate Fortran application (``tau0_gen.f90`` :footcite:p:`Weiver2008`) to generate :code:`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 :code:`pip`: + +.. code-block:: shell + + pip install adcircpy + +.. footbibliography:: diff --git a/docs/source/python_api.rst b/docs/source/python_api.rst new file mode 100644 index 00000000..6d50a024 --- /dev/null +++ b/docs/source/python_api.rst @@ -0,0 +1,186 @@ +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 :code:`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 :code:`mesh` module is the :code:`adcircpy.mesh.AdcircMesh` class, which inherits from :code:`adcircpy.mesh.Fort14`. An :code:`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 :code:`.generate_tau0()` method. This method is a pythonic implementation of the :code:`tau0_gen.f90` :footcite:p:`Weiver2008`. 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 :code:`.generate_constant_mannings_n()` or :code:`.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 :code:`mesh` module also contains parsers that can read and convert between ``fort.14`` and ``*.2dm`` files. + +``Grd`` class +^^^^^^^^^^^^^ +The :code:`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 :code:`Grd` class can be instantiated with a properly constructed :code:`nodes` and :code:`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``). + +.. autoclass:: adcircpy.mesh.base.Grd + +`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. + +.. _Example 2: + +.. code-block:: python + + 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) + +.. figure:: figures/fort14_triplot_example.png + :alt: Plotting result of above code + + Plotting result of `Example 2`_ + +.. _Grd UML diagram: + +.. figure:: figures/Grd_UML.png + :alt: UML component diagram for the :code:`Grd` class + + UML component diagram for the :code:`Grd` class + +``Fort14`` class +^^^^^^^^^^^^^^^^ +The :code:`Fort14` class is a subclass of the :code:`Grd` class, which is used specifically for ``fort.14`` file types. + +.. autoclass:: adcircpy.mesh.fort14.Fort14 + +As can be seen from `Fort14 UML diagram`_ diagram, the :code:`Fort14` class essentially extends the :code:`Grd` class by adding model boundaries. While the :code:`Hull` instances in the :code:`Grd` provides geometrical boundaries for the :code:`Grd` types (which are derived from the connectivity table), the :code:`Fort14Boundaries` instance provides an API to interact with the model's boundary types: ocean, land, interior, inflow, outflow, weir and culvert. + +.. _Fort14 UML diagram: + +.. figure:: figures/Fort14_UML.png + :alt: UML component diagram for the :code:`Fort14` class + + UML component diagram for the :code:`Fort14` class + +``AdcircMesh`` class +^^^^^^^^^^^^^^^^^^^^ +The :code:`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 :code:`AdcircMesh` class inherits properties and methods from :code:`Fort14`, and acts as the main interface between the user and the ADCIRC model forcings and nodal attributes. + +.. autoclass:: adcircpy.mesh.mesh.AdcircMesh + +Experienced ADCIRC users may also recognize familiar ADCIRC attribute and method names from `AdcircMesh UML diagram`_, along with the attributes and methods inherited from :code:`Fort14`. `HSOFS mesh`_ shows the output of the :code:`AdcircMesh.make_plot()` method using the Hurricane Surge On-Demand Forecast System (HSOFS) mesh :footcite:p:`Riverside2015`. + +.. _AdcircMesh UML diagram: + +.. figure:: figures/classes_adcircpy.mesh.AdcircMesh.png + :alt: UML component diagram for the :code:`AdcircMesh` class + + UML component diagram for the :code:`AdcircMesh` class + +.. _HSOFS mesh: + +.. figure:: figures/hsofs_mesh.png + :alt: HSOFS mesh plot using the :code:`AdcircMesh.make_plot()` method + + HSOFS mesh plot using the :code:`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 :code:`AdcircMesh` class match the nodal attribute names allowed in the ADCIRC nodal attributes file (fort.13). These attributes have been defined explicitly in the :code:`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 :code:`AdcircMesh` class, for example the :code:`mannings_n_at_sea_floor` can be set through the :code:`generate_linear_mannings_n()` method. Additionally, the user can set custom patches of values to the nodal attributes by passing a :code:`Polygon` or :code:`MultiPolygon` instance to the :code:`AdcircMesh.add_nodal_attributes_patch()` method. + +``adcircpy.Fort15`` class +------------------------- +The :code:`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 :code:`A00`, :code:`B00` and :code:`C00` factors. While the user cannot override any of these factors individually, the :code:`Fort15` class provides the :code:`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 :code:`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 :code:`Fort15` class attributes modify the final value of the :code:`IM` parameter, as configured by the users. To illustrate this, consider the case where the user instantiates the :code:`Fort15` class like this: :code:`fort15 = Fort15()`. Then the user can set the GWCE solver by setting :code:`fort15.gwce_solution_scheme = `implicit'`. By doing this setting, several parameters will change: the values of :code:`A00`, :code:`B00` and :code:`C00`, and the values of :code:`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 :code:`IM` parameter are: :code:`vertical_mode`, :code:`lateral_stress_in_gwce`, :code:`advection_in_gwce`, :code:`lateral_stress_in_momentum` and :code:`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 :code:`IM` parameter can be set directly by simply :code:`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. + +.. table:: 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 + ==================== ==== ==== ==== ====== + +.. _Fort15 UML: + +.. figure:: figures/classes_adcircpy.fort15.png + :alt: UML component diagram for the :code:`Fort15` class + + UML component diagram for the :code:`Fort15` class + +``adcircpy.forcing`` module +--------------------------- +The :code:`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 :code:`adcircpy.forcing` module contains two main modules that are of major interest to the users: the :code:`adcircpy.forcing.tides` module, and the :code:`adcircpy.forcing.winds` module. These will be discussed in sections `ADCIRCpy tides`_ and `ADCIRCpy winds`_ respectively. + +.. _ADCIRCpy tides: + +``adcircpy.forcing.tides`` module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The :code:`adcircpy.forcing.tides` module contains one main public interface class :code:`adcircpy.forcing.tides.Tides` and two auxiliary classes for aggregating additional required tidal data: :code:`adcircpy.forcing.tides.HAMTIDE` (`ADCIRCpy HAMTIDE`_) and :code:`adcircpy.forcing.tides.TPXO` (`ADCIRCpy TPXO`_). + +``adcircpy.forcing.tides.Tides`` class +"""""""""""""""""""""""""""""""""""""" +The :code:`adcircpy.forcing.tides.Tides` class (abbreviated here as :code:`Tides`) provides the main interface for instantiating tidal elevation amplitudes and phases for a model run. This public class has methods such as :code:`use_constituent()`, :code:`use_all()` and :code:`use_major()` which can be used to enable the desired tidal constituents as forcings for the model. The :code:`Tides` class implements the computation of the initial conditions for tidal boundary. This class implements the same functionality as the ADCIRC ` :code:`tide_fac.f90` `_ program, which implements the equations of :footcite:p:`Schureman1958` 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 :code:`Tides` class also implements the usage of helper classes (derived from the :code:`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 :code:`TidalDatabase` class implement a :code:`get_amplitude(constituent, vertices)` and :code:`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 :footcite:p:`Taguchi2014` or the TPXO database :footcite:p:`Egbert2002` by using the :code:`database` keyword argument during instantiation of the :code:`Tides` class. + +.. _ADCIRCpy HAMTIDE: + +``adcircpy.forcing.tides.HAMTIDE`` class +"""""""""""""""""""""""""""""""""""""""" +The :code:`adcircpy.forcing.tides.HAMTIDE` class is used by the :code:`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 TPXO: + +``adcircpy.forcing.tides.TPXO`` class +""""""""""""""""""""""""""""""""""""" +The :code:`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 winds: + +``adcircpy.forcing.winds`` module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The :code:`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 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 :code:`20` in the ``fort.15`` file. + +``adcircpy.driver`` module +--------------------------- +The :code:`adcircpy.driver` module consists of all methods and functions relating to ADCIRC forcing to generate an overlying task submission framework and configuration directories. :code:`adcircpy.driver` contains module :code:`adcircpy.driver.AdcircRun`. + +``adcircpy.driver.AdcircRun`` class +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:code:`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 +--------------------------- +:code:`adcircpy.outputs` module contain following output files :code:`OutputFactory`, :code:`OutputStations`, :code:`StationTimeseries`, :code:`ElevationStationsTimeseries`, :code:`HarmonicConstituentsElevationStations`, :code:`HarmonicConstituentsSurface`, :code:`Maxele`, :code:`ScalarSurfaceExtrema`, :code:`ScalarSurfaceTimeseries` and :code:`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. + +.. footbibliography:: diff --git a/docs/source/references.bib b/docs/source/references.bib new file mode 100644 index 00000000..b48c0ef1 --- /dev/null +++ b/docs/source/references.bib @@ -0,0 +1,109 @@ +% Encoding: UTF-8 + +@Article{Egbert2002, + author = {Egbert, Gary D. and Erofeeva, Svetlana Y.}, + journal = {Journal of Atmospheric and Oceanic Technology}, + title = {Efficient Inverse Modeling of Barotropic Ocean Tides}, + year = {2002}, + issn = {0739-0572, 1520-0426}, + month = feb, + number = {2}, + pages = {183--204}, + volume = {19}, + abstract = {Abstract A computationally efficient relocatable system for generalized inverse ({GI}) modeling of barotropic ocean tides is described. The {GI} penalty functional is minimized using a representer method, which requires repeated solution of the forward and adjoint linearized shallow water equations ({SWEs}). To make representer computations efficient, the {SWEs} are solved in the frequency domain by factoring the coefficient matrix for a finite-difference discretization of the second-order wave equation in elevation. Once this matrix is factored representers can be calculated rapidly. By retaining the first-order {SWE} system (defined in terms of both elevations and currents) in the definition of the discretized {GI} penalty functional, complete generality in the choice of dynamical error covariances is retained. This allows rational assumptions about errors in the {SWE}, with soft momentum balance constraints (e.g., to account for inaccurate parameterization of dissipation), but holds mass conservation constraints. While the dynamical calculations involve elevations alone, depth-averaged currents can be directly assimilated into the tidal model with this approach. The efficient representer calculation forms the basis for the Oregon State University ({OSU}) Tidal Inversion Software ({OTIS}). {OTIS} includes software for generating grids, prior model covariances, and boundary conditions; for time stepping the nonlinear shallow water equations to generate a first guess or prior solution; for preliminary processing of {TOPEX}/Poseidon altimeter data; for solution of the {GI} problem; and for computation of posterior error bars. Approximate {GI} solution methods, based on using a reduced set of representers, allow very large datasets to be inverted. {OTIS} regional and local {GI} tidal modeling (with grids containing up to 105 nodes) require only a few hours on a common desktop workstation. Use of {OTIS} is illustrated by developing a new regional-scale (1/6°) model of tides in the Indonesian Seas.}, + doi = {10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2}, + language = {EN}, + url = {https://journals.ametsoc.org/view/journals/atot/19/2/1520-0426_2002_019_0183_eimobo_2_0_co_2.xml}, + urldate = {2021-02-10}, + date = {2002-02-01}, + publisher = {American Meteorological Society}, +} + +@Misc{JaimeCalzadaNOAA2021, + author = {Calzada, Jaime and Burnett, Zachary}, + month = nov, + title = {ADCIRCpy}, + year = {2021}, + abstract = {Python library for managing input and output files for the ADCIRC model.}, + copyright = {GPL-3.0 License}, + url = {https://github.com/zacharyburnettNOAA/adcircpy}, +} + +@misc{noauthor_cyclomatic_2020, + title = {Cyclomatic complexity}, + copyright = {Creative Commons Attribution-ShareAlike License}, + url = {https://en.wikipedia.org/w/index.php?title=Cyclomatic_complexity&oldid=992651876}, + abstract = {Cyclomatic complexity is a software metric used to indicate the complexity of a program. It is a quantitative measure of the number of linearly independent paths through a program's source code. It was developed by Thomas J. McCabe, Sr. in 1976. +Cyclomatic complexity is computed using the control flow graph of the program: the nodes of the graph correspond to indivisible groups of commands of a program, and a directed edge connects two nodes if the second command might be executed immediately after the first command. Cyclomatic complexity may also be applied to individual functions, modules, methods or classes within a program. +One testing strategy, called basis path testing by McCabe who first proposed it, is to test each linearly independent path through the program; in this case, the number of test cases will equal the cyclomatic complexity of the program.}, + language = {en}, + urldate = {2021-02-10}, + journal = {Wikipedia}, + month = dec, + year = {2020}, + note = {Page Version ID: 992651876}, +} + +@Article{Luettich1992, + author = {Luettich, Richard, Jr and Westerink, J. and Scheffner, Norman}, + journal = {Dredging Research Program Tech. Rep. DRP-92-6}, + title = {{ADCIRC}: {An} {Advanced} {Three}-{Dimensional} {Circulation} {Model} for {Shelves}, {Coasts}, and {Estuaries}. {Report} 1. {Theory} and {Methodology} of {ADCIRC}-{2DDI} and {ADCIRC}-{3DL}}, + year = {1992}, + month = nov, + pages = {143}, + abstract = {This report describes the theory, methodology, and verification of the ADCIRC (ADvanced CIRCulation) finite element numerical models. ADCIRC-2DDI is a two-dimensional, depth-integrated hydrodynamic model. ADCIRC-3DL is a three-dimensional model that couples the external mode solution generated by ADCIRC2DDI to a locally one-dimensional internal mode solution. The numerical internal mode solution can be obtained using either velocity or stress as the dependent variable. ADCIRC has been developed to simulate hydrodynamic circulation along shelves, coasts, and within estuaries. To allow long numerical simulations (on the order of a year) over very large computational domains (for example, the entire east coast of the United States), ADCIRC has been designed to have high computational efficiency and has been tested extensively for both hydrodynamic accuracy and numerical stability. The results of these tests are included in this report.}, + shorttitle = {{ADCIRC}}, + rights = {Approved for public release; distribution is unlimited.}, + url = {https://erdc-library.erdc.dren.mil/jspui/handle/11681/4618}, + publisher = {Coastal Engineering Research Center (U.S.)}, +} + +@Article{Taguchi2014, + author = {E. Taguchi and D. Stammer and W. Zahel}, + journal = {Journal of Geophysical Research: Oceans}, + title = {Inferring deep ocean tidal energy dissipation from the global high-resolution data-assimilative {HAMTIDE} model}, + year = {2014}, + month = {jul}, + number = {7}, + pages = {4573--4592}, + volume = {119}, + doi = {10.1002/2013jc009766}, + publisher = {American Geophysical Union ({AGU})}, +} + +@Misc{Weiver2008, + author = {Robert Weiver}, + month = oct, + title = {tau0{\_}gen.f}, + year = {2008}, + abstract = {this program will generate data for tau0 base to be used in the fort.13 file +the data is formatted to be read in when the tau0 flag is set to -3.0 in the fort.15 file for versions fo {ADCIRC} later than 47.31 and older versions of the code which may have been modified seperately from that kept on the svn repository +For these versions, setting the flag of tau0 = -3.0 implies that a base value for tau0 will be read in from the fort.13 file.}, + url = {https://www.dropbox.com/s/zb7xjzun7nco384/tau0_gen.f}, +} + +@Misc{Schureman1958, + author = {Schureman, Paul}, + title = {Manual of Harmonic Analysis and Prediction of Tides. [ Revised 1940 edition reprinted 1958 with corrections, reprinted 2001]}, + pagetotal = {346}, + year = {1958}, + copyright = {CC0 1.0 Universal}, + doi = {10.25607/OBP-155}, + keywords = {Tidal analysis, Tidal currents, Harmonic analysis, Parameter Discipline::Physical oceanography}, + language = {en}, + publisher = {United States Government Printing Office}, + note = {Google-Books-{ID}: {jI}8TAAAAYAAJ}, +} + +@TechReport{Riverside2015, + author = {{Riverside Technology, Inc} and {AECOM}}, institution = {Riverside Technology, Inc.}, + title = {Mesh development, tidal validation, and hindcast skill assessment of an {ADCIRC} model for the {H}urricane {S}torm {S}urge {O}perational {F}orecast {S}ystem on the {US} {G}ulf-{A}tlantic {C}oast}, + rights = {In Copyright}, + year = {2015}, + abstract = {The Coast Survey Development Laboratory ({CSDL}) of the National Ocean Service ({NOS}) previously developed an Extratropical Surge and Tide Operational Forecast System ({ESTOFS}) for the {US} coastal waters (Funakoshi et al. 2013). Now, to extend the capability of {ESTOFS} to include tropical storm event simulation and ensemble prediction, {CSDL} is preparing a prototype Hurricane Storm Surge Operational Forecast System ({HSSOFS}). Under direction from {CSDL}, a technical team led by Riverside Technology, inc. has developed a hydrodynamic model of the {US} East Coast and Gulf of Mexico and has validated the model for 10 major tropical and extratropical events. Eventually, this model will form the basis for an operational system on National Centers for Environmental Prediction ({NCEP}) computers. The prototype model described in this document is called {NOMAD}: {NOAA} Operational Model with {ADCIRC}.}, + url = {https://cdr.lib.unc.edu/concern/articles/8336h638c?locale=en}, + doi = {10.17615/4Z19-Y130}, + publisher = {The University of North Carolina at Chapel Hill University Libraries}, +} + +@Comment{jabref-meta: databaseType:bibtex;} diff --git a/docs/source/references.rst b/docs/source/references.rst new file mode 100644 index 00000000..0a458380 --- /dev/null +++ b/docs/source/references.rst @@ -0,0 +1,5 @@ +References +========== + +.. bibliography:: references.bib + :all: diff --git a/setup.py b/setup.py index 3f594a39..ccc76831 100755 --- a/setup.py +++ b/setup.py @@ -10,6 +10,7 @@ DEPENDENCIES = { 'appdirs': [], 'bs4': [], + 'coupledmodelvalidation': [], 'eventlet': [], 'fiona': ['gdal'], 'geopandas': [], @@ -208,6 +209,14 @@ def missing_packages(required_packages: {str: [str]}) -> {str: [str]}: 'pytest-xdist', ], 'development': ['dunamai', 'flake8', 'isort', 'oitnb'], + 'documentation': [ + 'dunamai', + 'm2r2', + 'sphinx', + 'sphinx-rtd-theme', + 'sphinxcontrib-programoutput', + 'sphinxcontrib-bibtex', + ], }, entry_points={ 'console_scripts': [