# ADCIRCPy
### Python library for automating ADCIRC model runs.
[](https://github.com/noaa-ocs-modeling/adcircpy/actions?query=workflow%3Atests)
[](https://github.com/noaa-ocs-modeling/adcircpy/actions?query=workflow%3Abuild)
[](https://codecov.io/gh/noaa-ocs-modeling/adcircpy)
[](https://pypi.org/project/adcircpy)
[](https://opensource.org/licenses/gpl-license)
[](https://sourceforge.net/p/oitnb/code)
[](https://adcircpy.readthedocs.io/en/latest/?badge=latest)
Documentation can be found at https://adcircpy.readthedocs.io
## Organization / Responsibility
ADCIRCpy is currently maintained by the [Coastal Marine Modeling Branch (CMMB)](https://coastaloceanmodels.noaa.gov) of the
Office of Coast Survey (OCS), a part of the [National Oceanic and Atmospheric Administration (NOAA)](https://www.noaa.gov), an
agency of the United States federal government. It was majorly developed by [@jreniel](https://github.com/jreniel).
- Zachary Burnett (**lead**) - zachary.burnett@noaa.gov
- Jaime Calzada - jrcalzada@vims.edu
## Installation
Please use a virtual environment with Python>=3.6. You may use conda or the OS's Python to provide a virtual environment for
the application.
You may install the application though pip. This will install the latest tagged version.
<!--pytest-codeblocks:skip-->
```bash
pip install adcircpy
```
Alternatively, you many manually install the repo by cloning it and then running
<!--pytest-codeblocks:skip-->
```bash
pip install .
```
## Usage
### Command Line Interface (CLI)
This program exposes a few commands available from the command line interface. You may pass the `-h` flag to any of this
commands to explore their functionality.
* `tide_gen`
* `plot_mesh`
* `tidal_run`
* `best_track_run`
* `best_track_file`
* `plot_maxele`
* `plot_fort61`
* `fort63`
#### examples
##### generate tidal constituent template
You can quickly create a tidal component table for your your mesh by executing the `tide_gen` command and by passing a mesh, a
start date and number of run days as arguments. This functions sources data from
the [HAMTIDE](https://icdc.cen.uni-hamburg.de/en/hamtide.html) database by default.
<!--pytest-codeblocks:skip-->
```bash
tide_gen \
/path/to/your/fort.14 \
2021-02-26T00:00:00 \
15 \
--mesh-crs='epsg:4326'
```
##### run best-track run for Hurricane Sandy (AL182012)
To create the ADCIRC input files includes both tides and storm data for Hurricane Sandy:
<!--pytest-codeblocks:skip-->
```bash
best_track_run \
/path/to/your/fort.14 \
Sandy2012 \
--fort13=/path/to/your/fort.13 \
--crs=EPSG:4326 \
--output-directory=/path/where/you/want/the/files \
--constituents=all \
--spinup-days=15.0 \
--elev=30. \
--mete=30. \
--velo=30. \
--skip-run
```
Note that the --crs flag is required due to the fort.14 not containing Coordinate Reference System information which is
required for correct operation. [EPSG:4326](https://spatialreference.org/ref/epsg/wgs-84/) means that the mesh is in WGS84 (
lat/lon). Note that the backlash represents "continue on next line" for the shell. You may write the command above on a single
line after excluding the backslashes.
##### plot results
These are two examples for doing quick plots with the package. These are given here as illustrative examples only. There is
support for more file types than this examples, but the program does not yet support every output input/output file type. As a
user, you are encouraged to explore what's available and suggest and contribute your improvements.
<!--pytest-codeblocks:skip-->
```bash
plot_fort61 /path/to/fort.61.nc MSL --show --coops-only
```
<!--pytest-codeblocks:skip-->
```bash
plot_mesh /path/to/fort.14 --show-elements
```
### Python API
See the [examples](./examples) directory for usage examples.
#### `example_1.py`
The following code builds a simple ADCIRC run configuration by doing the following:
1. reads a `fort.14` mesh file (specifically a test mesh for Shinnecock Inlet)
2. adds tidal forcing to the mesh
3. creates an `AdcircRun` driver object with the mesh, including start and end dates
4. overrides default model options in the resulting `fort.15`
5. runs ADCIRC if present, otherwise writes configuration to disk
```python
from datetime import datetime, timedelta
from pathlib import Path
import shutil
from adcircpy import AdcircMesh, AdcircRun, Tides
from adcircpy.utilities import download_mesh, get_logger
LOGGER = get_logger(__name__)
DATA_DIRECTORY = Path(__file__).parent.absolute() / 'data'
INPUT_DIRECTORY = DATA_DIRECTORY / 'input' / 'shinnecock'
OUTPUT_DIRECTORY = DATA_DIRECTORY / 'output' / 'example_1'
MESH_DIRECTORY = INPUT_DIRECTORY / 'shinnecock'
download_mesh(
url='https://www.dropbox.com/s/1wk91r67cacf132/NetCDF_shinnecock_inlet.tar.bz2?dl=1',
directory=MESH_DIRECTORY,
known_hash='99d764541983bfee60d4176af48ed803d427dea61243fa22d3f4003ebcec98f4',
)
# open mesh file
mesh = AdcircMesh.open(MESH_DIRECTORY / 'fort.14', crs=4326)
# initialize tidal forcing and constituents
tidal_forcing = Tides()
tidal_forcing.use_constituent('M2')
tidal_forcing.use_constituent('N2')
tidal_forcing.use_constituent('S2')
tidal_forcing.use_constituent('K1')
tidal_forcing.use_constituent('O1')
mesh.add_forcing(tidal_forcing)
# set simulation dates
duration = timedelta(days=5)
start_date = datetime(2015, 12, 14)
end_date = start_date + duration
# instantiate driver object
driver = AdcircRun(mesh, start_date, end_date)
# request outputs
driver.set_elevation_surface_output(sampling_rate=timedelta(minutes=30))
driver.set_velocity_surface_output(sampling_rate=timedelta(minutes=30))
# override default options so the resulting `fort.15` matches the original Shinnecock test case options
driver.timestep = 6.0
driver.DRAMP = 2.0
driver.TOUTGE = 3.8
driver.TOUTGV = 3.8
driver.smagorinsky = False
driver.horizontal_mixing_coefficient = 5.0
driver.gwce_solution_scheme = 'semi-implicit-legacy'
if shutil.which('padcirc') is not None:
driver.run(OUTPUT_DIRECTORY, overwrite=True)
elif shutil.which('adcirc') is not None:
driver.run(OUTPUT_DIRECTORY, overwrite=True, nproc=1)
else:
LOGGER.warning(
'ADCIRC binaries were not found in PATH. '
'ADCIRC will not run. Writing files to disk...'
)
driver.write(OUTPUT_DIRECTORY, overwrite=True)
```
#### `example_2.py`
The following code is similar to `example_1.py`, above, except it adds a static Manning's N coefficient to the mesh.
```python
from datetime import datetime, timedelta
from pathlib import Path
import shutil
import numpy
from adcircpy import AdcircMesh, AdcircRun, Tides
from adcircpy.utilities import download_mesh, get_logger
LOGGER = get_logger(__name__)
DATA_DIRECTORY = Path(__file__).parent.absolute() / 'data'
INPUT_DIRECTORY = DATA_DIRECTORY / 'input'
OUTPUT_DIRECTORY = DATA_DIRECTORY / 'output' / 'example_2'
MESH_DIRECTORY = INPUT_DIRECTORY / 'shinnecock'
download_mesh(
url='https://www.dropbox.com/s/1wk91r67cacf132/NetCDF_shinnecock_inlet.tar.bz2?dl=1',
directory=MESH_DIRECTORY,
known_hash='99d764541983bfee60d4176af48ed803d427dea61243fa22d3f4003ebcec98f4',
)
# open mesh file
mesh = AdcircMesh.open(MESH_DIRECTORY / 'fort.14', crs=4326)
# generate tau0 factor
mesh.generate_tau0()
# also add Manning's N to the domain (constant for this example)
mesh.mannings_n_at_sea_floor = numpy.full(mesh.values.shape, 0.025)
# initialize tidal forcing and constituents
tidal_forcing = Tides()
tidal_forcing.use_constituent('M2')
tidal_forcing.use_constituent('N2')
tidal_forcing.use_constituent('S2')
tidal_forcing.use_constituent('K1')
tidal_forcing.use_constituent('O1')
mesh.add_forcing(tidal_forcing)
# set simulation dates
spinup_time = timedelta(days=2)
duration = timedelta(days=3)
start_date = datetime(2015, 12, 14) + spinup_time
end_date = start_date + duration
# instantiate driver object
driver = AdcircRun(mesh, start_date, end_date, spinup_time)
# request outputs
driver.set_elevation_surface_output(sampling_rate=timedelta(minutes=30))
driver.set_velocity_surface_output(sampling_rate=timedelta(minutes=30))
# override default options
driver.timestep = 4.0
if shutil.which('padcirc') is not None:
driver.run(OUTPUT_DIRECTORY, overwrite=True)
elif shutil.which('adcirc') is not None:
driver.run(OUTPUT_DIRECTORY, overwrite=True, nproc=1)
else:
LOGGER.warning(
'ADCIRC binaries were not found in PATH. '
'ADCIRC will not run. Writing files to disk...'
)
driver.write(OUTPUT_DIRECTORY, overwrite=True)
```
#### `example_3.py`
The following code is similar to `example_1.py`, above, except it adds HURDAT BestTrack wind forcing and also builds a Slurm
job script for submission to a job manager.
```python
from datetime import datetime, timedelta
from pathlib import Path
from adcircpy import AdcircMesh, AdcircRun, Tides
from adcircpy.forcing.winds import BestTrackForcing
from adcircpy.server import SlurmConfig
from adcircpy.utilities import download_mesh
DATA_DIRECTORY = Path(__file__).parent.absolute() / 'data'
INPUT_DIRECTORY = DATA_DIRECTORY / 'input'
OUTPUT_DIRECTORY = DATA_DIRECTORY / 'output' / 'example_3'
MESH_DIRECTORY = INPUT_DIRECTORY / 'shinnecock'
download_mesh(
url='https://www.dropbox.com/s/1wk91r67cacf132/NetCDF_shinnecock_inlet.tar.bz2?dl=1',
directory=MESH_DIRECTORY,
known_hash='99d764541983bfee60d4176af48ed803d427dea61243fa22d3f4003ebcec98f4',
)
# open mesh file
mesh = AdcircMesh.open(MESH_DIRECTORY / 'fort.14', crs=4326)
# initialize tidal forcing and constituents
tidal_forcing = Tides()
tidal_forcing.use_all()
mesh.add_forcing(tidal_forcing)
# initialize wind forcing
wind_forcing = BestTrackForcing('Sandy2012')
mesh.add_forcing(wind_forcing)
# initialize Slurm configuration
slurm = SlurmConfig(
account='account',
ntasks=1000,
run_name='adcircpy/examples/example_3.py',
partition='partition',
walltime=timedelta(hours=8),
mail_type='all',
mail_user='example@email.gov',
log_filename='example_3.log',
modules=['intel/2020', 'impi/2020', 'netcdf/4.7.2-parallel'],
path_prefix='$HOME/adcirc/build',
)
# set simulation dates
spinup_time = timedelta(days=15)
duration = timedelta(days=3)
start_date = datetime(2012, 10, 21, 18)
end_date = start_date + duration
# instantiate driver object
driver = AdcircRun(mesh, start_date, end_date, spinup_time, server_config=slurm)
# write driver state to disk
driver.write(OUTPUT_DIRECTORY, overwrite=True)
```
#### `example_4.py`
The following code is similar to `example_3.py`, above, except it uses ATMESH wind forcing and WW3DATA wave forcing.
```python
from datetime import datetime, timedelta
from pathlib import Path
from adcircpy import AdcircMesh, AdcircRun, Tides
from adcircpy.forcing.waves.ww3 import WaveWatch3DataForcing
from adcircpy.forcing.winds.atmesh import AtmosphericMeshForcing
from adcircpy.server import SlurmConfig
from adcircpy.utilities import download_mesh
DATA_DIRECTORY = Path(__file__).parent.absolute() / 'data'
INPUT_DIRECTORY = DATA_DIRECTORY / 'input'
OUTPUT_DIRECTORY = DATA_DIRECTORY / 'output' / 'example_4'
MESH_DIRECTORY = INPUT_DIRECTORY / 'shinnecock'
download_mesh(
url='https://www.dropbox.com/s/1wk91r67cacf132/NetCDF_shinnecock_inlet.tar.bz2?dl=1',
directory=MESH_DIRECTORY,
known_hash='99d764541983bfee60d4176af48ed803d427dea61243fa22d3f4003ebcec98f4',
)
# open mesh file
mesh = AdcircMesh.open(MESH_DIRECTORY / 'fort.14', crs=4326)
# initialize tidal forcing and constituents
tidal_forcing = Tides()
tidal_forcing.use_all()
mesh.add_forcing(tidal_forcing)
# initialize atmospheric mesh forcings (for NUOPC coupling)
wind_forcing = AtmosphericMeshForcing(
filename='Wind_HWRF_SANDY_Nov2018_ExtendedSmoothT.nc', nws=17, interval_seconds=3600,
)
mesh.add_forcing(wind_forcing)
# initialize wave mesh forcings (for NUOPC coupling)
wave_forcing = WaveWatch3DataForcing(
filename='ww3.HWRF.NOV2018.2012_sxy.nc', nrs=5, interval_seconds=3600,
)
mesh.add_forcing(wave_forcing)
# initialize Slurm configuration
slurm = SlurmConfig(
account='account',
ntasks=1000,
run_name='adcircpy/examples/example_4.py',
partition='partition',
walltime=timedelta(hours=8),
mail_type='all',
mail_user='example@email.gov',
log_filename='example_4.log',
modules=['intel/2020', 'impi/2020', 'netcdf/4.7.2-parallel'],
path_prefix='$HOME/adcirc/build',
)
# instantiate driver object
driver = AdcircRun(
mesh=mesh,
start_date=datetime.now(),
end_date=timedelta(days=7),
spinup_time=timedelta(days=5),
server_config=slurm,
)
# write driver state to disk
driver.write(OUTPUT_DIRECTORY, overwrite=True)
```
## Citation
```
Calzada, J., Burnett, Z., Moghimi, S., Myers, E., & Pe’eri, S. (2021). ADCIRCpy: A Python API to generate ADCIRC model input files (Technical Memorandum No. 41; NOAA NOS OCS). National Oceanic and Atmospheric Administation.
```
```bibtex
@techreport{calzadaADCIRCpyPythonAPI2021,
type = {Technical {{Memorandum}}},
title = {{{ADCIRCpy}}: A {{Python API}} to Generate {{ADCIRC}} Model Input Files},
author = {Calzada, Jaime and Burnett, Zachary and Moghimi, Saeed and Myers, Edward and Pe'eri, Shachak},
year = {2021},
month = dec,
number = {41},
institution = {{National Oceanic and Atmospheric Administation}},
abstract = {The Advanced Circulation Model (ADCIRC) 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, 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.}
}
```
## Acknowledgements
The majority of ADCIRCpy was written by Jaime Calzada [@jreniel](https://github.com/jreniel).
Raw data
{
"_id": null,
"home_page": "https://github.com/noaa-ocs-modeling/adcircpy.git",
"name": "adcircpy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Zach Burnett",
"author_email": "zachary.burnett@noaa.gov",
"download_url": "https://files.pythonhosted.org/packages/ce/96/b9b1eb4728d44e94f0ee4e38b6f3a6135cde4111d735349271853d10e77b/adcircpy-1.2.7.tar.gz",
"platform": null,
"description": "# ADCIRCPy\n\n### Python library for automating ADCIRC model runs.\n\n[](https://github.com/noaa-ocs-modeling/adcircpy/actions?query=workflow%3Atests)\n[](https://github.com/noaa-ocs-modeling/adcircpy/actions?query=workflow%3Abuild)\n[](https://codecov.io/gh/noaa-ocs-modeling/adcircpy)\n[](https://pypi.org/project/adcircpy)\n[](https://opensource.org/licenses/gpl-license)\n[](https://sourceforge.net/p/oitnb/code)\n[](https://adcircpy.readthedocs.io/en/latest/?badge=latest)\n\nDocumentation can be found at https://adcircpy.readthedocs.io\n\n## Organization / Responsibility\n\nADCIRCpy is currently maintained by the [Coastal Marine Modeling Branch (CMMB)](https://coastaloceanmodels.noaa.gov) of the\nOffice of Coast Survey (OCS), a part of the [National Oceanic and Atmospheric Administration (NOAA)](https://www.noaa.gov), an\nagency of the United States federal government. It was majorly developed by [@jreniel](https://github.com/jreniel).\n\n- Zachary Burnett (**lead**) - zachary.burnett@noaa.gov\n- Jaime Calzada - jrcalzada@vims.edu\n\n## Installation\n\nPlease use a virtual environment with Python>=3.6. You may use conda or the OS's Python to provide a virtual environment for\nthe application.\n\nYou may install the application though pip. This will install the latest tagged version.\n<!--pytest-codeblocks:skip-->\n\n```bash\npip install adcircpy\n```\n\nAlternatively, you many manually install the repo by cloning it and then running\n<!--pytest-codeblocks:skip-->\n\n```bash\npip install .\n```\n\n## Usage\n\n### Command Line Interface (CLI)\n\nThis program exposes a few commands available from the command line interface. You may pass the `-h` flag to any of this\ncommands to explore their functionality.\n\n* `tide_gen`\n* `plot_mesh`\n* `tidal_run`\n* `best_track_run`\n* `best_track_file`\n* `plot_maxele`\n* `plot_fort61`\n* `fort63`\n\n#### examples\n\n##### generate tidal constituent template\n\nYou can quickly create a tidal component table for your your mesh by executing the `tide_gen` command and by passing a mesh, a\nstart date and number of run days as arguments. This functions sources data from\nthe [HAMTIDE](https://icdc.cen.uni-hamburg.de/en/hamtide.html) database by default.\n<!--pytest-codeblocks:skip-->\n\n```bash\ntide_gen \\\n /path/to/your/fort.14 \\\n 2021-02-26T00:00:00 \\\n 15 \\\n --mesh-crs='epsg:4326'\n```\n\n##### run best-track run for Hurricane Sandy (AL182012)\n\nTo create the ADCIRC input files includes both tides and storm data for Hurricane Sandy:\n<!--pytest-codeblocks:skip-->\n\n```bash\nbest_track_run \\\n /path/to/your/fort.14 \\\n Sandy2012 \\\n --fort13=/path/to/your/fort.13 \\\n --crs=EPSG:4326 \\\n --output-directory=/path/where/you/want/the/files \\\n --constituents=all \\\n --spinup-days=15.0 \\\n --elev=30. \\\n --mete=30. \\\n --velo=30. \\\n --skip-run\n```\n\nNote that the --crs flag is required due to the fort.14 not containing Coordinate Reference System information which is\nrequired for correct operation. [EPSG:4326](https://spatialreference.org/ref/epsg/wgs-84/) means that the mesh is in WGS84 (\nlat/lon). Note that the backlash represents \"continue on next line\" for the shell. You may write the command above on a single\nline after excluding the backslashes.\n\n##### plot results\n\nThese are two examples for doing quick plots with the package. These are given here as illustrative examples only. There is\nsupport for more file types than this examples, but the program does not yet support every output input/output file type. As a\nuser, you are encouraged to explore what's available and suggest and contribute your improvements.\n<!--pytest-codeblocks:skip-->\n\n```bash\nplot_fort61 /path/to/fort.61.nc MSL --show --coops-only\n```\n\n<!--pytest-codeblocks:skip-->\n\n```bash\nplot_mesh /path/to/fort.14 --show-elements\n```\n\n### Python API\n\nSee the [examples](./examples) directory for usage examples.\n\n#### `example_1.py`\n\nThe following code builds a simple ADCIRC run configuration by doing the following:\n\n1. reads a `fort.14` mesh file (specifically a test mesh for Shinnecock Inlet)\n2. adds tidal forcing to the mesh\n3. creates an `AdcircRun` driver object with the mesh, including start and end dates\n4. overrides default model options in the resulting `fort.15`\n5. runs ADCIRC if present, otherwise writes configuration to disk\n\n```python\nfrom datetime import datetime, timedelta\nfrom pathlib import Path\nimport shutil\n\nfrom adcircpy import AdcircMesh, AdcircRun, Tides\nfrom adcircpy.utilities import download_mesh, get_logger\n\nLOGGER = get_logger(__name__)\n\nDATA_DIRECTORY = Path(__file__).parent.absolute() / 'data'\nINPUT_DIRECTORY = DATA_DIRECTORY / 'input' / 'shinnecock'\nOUTPUT_DIRECTORY = DATA_DIRECTORY / 'output' / 'example_1'\n\nMESH_DIRECTORY = INPUT_DIRECTORY / 'shinnecock'\n\ndownload_mesh(\n url='https://www.dropbox.com/s/1wk91r67cacf132/NetCDF_shinnecock_inlet.tar.bz2?dl=1',\n directory=MESH_DIRECTORY,\n known_hash='99d764541983bfee60d4176af48ed803d427dea61243fa22d3f4003ebcec98f4',\n)\n\n# open mesh file\nmesh = AdcircMesh.open(MESH_DIRECTORY / 'fort.14', crs=4326)\n\n# initialize tidal forcing and constituents\ntidal_forcing = Tides()\ntidal_forcing.use_constituent('M2')\ntidal_forcing.use_constituent('N2')\ntidal_forcing.use_constituent('S2')\ntidal_forcing.use_constituent('K1')\ntidal_forcing.use_constituent('O1')\nmesh.add_forcing(tidal_forcing)\n\n# set simulation dates\nduration = timedelta(days=5)\nstart_date = datetime(2015, 12, 14)\nend_date = start_date + duration\n\n# instantiate driver object\ndriver = AdcircRun(mesh, start_date, end_date)\n\n# request outputs\ndriver.set_elevation_surface_output(sampling_rate=timedelta(minutes=30))\ndriver.set_velocity_surface_output(sampling_rate=timedelta(minutes=30))\n\n# override default options so the resulting `fort.15` matches the original Shinnecock test case options\ndriver.timestep = 6.0\ndriver.DRAMP = 2.0\ndriver.TOUTGE = 3.8\ndriver.TOUTGV = 3.8\ndriver.smagorinsky = False\ndriver.horizontal_mixing_coefficient = 5.0\ndriver.gwce_solution_scheme = 'semi-implicit-legacy'\n\nif shutil.which('padcirc') is not None:\n driver.run(OUTPUT_DIRECTORY, overwrite=True)\nelif shutil.which('adcirc') is not None:\n driver.run(OUTPUT_DIRECTORY, overwrite=True, nproc=1)\nelse:\n LOGGER.warning(\n 'ADCIRC binaries were not found in PATH. '\n 'ADCIRC will not run. Writing files to disk...'\n )\n driver.write(OUTPUT_DIRECTORY, overwrite=True)\n```\n\n#### `example_2.py`\n\nThe following code is similar to `example_1.py`, above, except it adds a static Manning's N coefficient to the mesh.\n\n```python\nfrom datetime import datetime, timedelta\nfrom pathlib import Path\nimport shutil\n\nimport numpy\n\nfrom adcircpy import AdcircMesh, AdcircRun, Tides\nfrom adcircpy.utilities import download_mesh, get_logger\n\nLOGGER = get_logger(__name__)\n\nDATA_DIRECTORY = Path(__file__).parent.absolute() / 'data'\nINPUT_DIRECTORY = DATA_DIRECTORY / 'input'\nOUTPUT_DIRECTORY = DATA_DIRECTORY / 'output' / 'example_2'\n\nMESH_DIRECTORY = INPUT_DIRECTORY / 'shinnecock'\n\ndownload_mesh(\n url='https://www.dropbox.com/s/1wk91r67cacf132/NetCDF_shinnecock_inlet.tar.bz2?dl=1',\n directory=MESH_DIRECTORY,\n known_hash='99d764541983bfee60d4176af48ed803d427dea61243fa22d3f4003ebcec98f4',\n)\n\n# open mesh file\nmesh = AdcircMesh.open(MESH_DIRECTORY / 'fort.14', crs=4326)\n\n# generate tau0 factor\nmesh.generate_tau0()\n\n# also add Manning's N to the domain (constant for this example)\nmesh.mannings_n_at_sea_floor = numpy.full(mesh.values.shape, 0.025)\n\n# initialize tidal forcing and constituents\ntidal_forcing = Tides()\ntidal_forcing.use_constituent('M2')\ntidal_forcing.use_constituent('N2')\ntidal_forcing.use_constituent('S2')\ntidal_forcing.use_constituent('K1')\ntidal_forcing.use_constituent('O1')\nmesh.add_forcing(tidal_forcing)\n\n# set simulation dates\nspinup_time = timedelta(days=2)\nduration = timedelta(days=3)\nstart_date = datetime(2015, 12, 14) + spinup_time\nend_date = start_date + duration\n\n# instantiate driver object\ndriver = AdcircRun(mesh, start_date, end_date, spinup_time)\n\n# request outputs\ndriver.set_elevation_surface_output(sampling_rate=timedelta(minutes=30))\ndriver.set_velocity_surface_output(sampling_rate=timedelta(minutes=30))\n\n# override default options\ndriver.timestep = 4.0\n\nif shutil.which('padcirc') is not None:\n driver.run(OUTPUT_DIRECTORY, overwrite=True)\nelif shutil.which('adcirc') is not None:\n driver.run(OUTPUT_DIRECTORY, overwrite=True, nproc=1)\nelse:\n LOGGER.warning(\n 'ADCIRC binaries were not found in PATH. '\n 'ADCIRC will not run. Writing files to disk...'\n )\n driver.write(OUTPUT_DIRECTORY, overwrite=True)\n```\n\n#### `example_3.py`\n\nThe following code is similar to `example_1.py`, above, except it adds HURDAT BestTrack wind forcing and also builds a Slurm\njob script for submission to a job manager.\n\n```python\nfrom datetime import datetime, timedelta\nfrom pathlib import Path\n\nfrom adcircpy import AdcircMesh, AdcircRun, Tides\nfrom adcircpy.forcing.winds import BestTrackForcing\nfrom adcircpy.server import SlurmConfig\nfrom adcircpy.utilities import download_mesh\n\nDATA_DIRECTORY = Path(__file__).parent.absolute() / 'data'\nINPUT_DIRECTORY = DATA_DIRECTORY / 'input'\nOUTPUT_DIRECTORY = DATA_DIRECTORY / 'output' / 'example_3'\n\nMESH_DIRECTORY = INPUT_DIRECTORY / 'shinnecock'\n\ndownload_mesh(\n url='https://www.dropbox.com/s/1wk91r67cacf132/NetCDF_shinnecock_inlet.tar.bz2?dl=1',\n directory=MESH_DIRECTORY,\n known_hash='99d764541983bfee60d4176af48ed803d427dea61243fa22d3f4003ebcec98f4',\n)\n\n# open mesh file\nmesh = AdcircMesh.open(MESH_DIRECTORY / 'fort.14', crs=4326)\n\n# initialize tidal forcing and constituents\ntidal_forcing = Tides()\ntidal_forcing.use_all()\nmesh.add_forcing(tidal_forcing)\n\n# initialize wind forcing\nwind_forcing = BestTrackForcing('Sandy2012')\nmesh.add_forcing(wind_forcing)\n\n# initialize Slurm configuration\nslurm = SlurmConfig(\n account='account',\n ntasks=1000,\n run_name='adcircpy/examples/example_3.py',\n partition='partition',\n walltime=timedelta(hours=8),\n mail_type='all',\n mail_user='example@email.gov',\n log_filename='example_3.log',\n modules=['intel/2020', 'impi/2020', 'netcdf/4.7.2-parallel'],\n path_prefix='$HOME/adcirc/build',\n)\n\n# set simulation dates\nspinup_time = timedelta(days=15)\nduration = timedelta(days=3)\nstart_date = datetime(2012, 10, 21, 18)\nend_date = start_date + duration\n\n# instantiate driver object\ndriver = AdcircRun(mesh, start_date, end_date, spinup_time, server_config=slurm)\n\n# write driver state to disk\ndriver.write(OUTPUT_DIRECTORY, overwrite=True)\n```\n\n#### `example_4.py`\n\nThe following code is similar to `example_3.py`, above, except it uses ATMESH wind forcing and WW3DATA wave forcing.\n\n```python\nfrom datetime import datetime, timedelta\nfrom pathlib import Path\n\nfrom adcircpy import AdcircMesh, AdcircRun, Tides\nfrom adcircpy.forcing.waves.ww3 import WaveWatch3DataForcing\nfrom adcircpy.forcing.winds.atmesh import AtmosphericMeshForcing\nfrom adcircpy.server import SlurmConfig\nfrom adcircpy.utilities import download_mesh\n\nDATA_DIRECTORY = Path(__file__).parent.absolute() / 'data'\nINPUT_DIRECTORY = DATA_DIRECTORY / 'input'\nOUTPUT_DIRECTORY = DATA_DIRECTORY / 'output' / 'example_4'\n\nMESH_DIRECTORY = INPUT_DIRECTORY / 'shinnecock'\n\ndownload_mesh(\n url='https://www.dropbox.com/s/1wk91r67cacf132/NetCDF_shinnecock_inlet.tar.bz2?dl=1',\n directory=MESH_DIRECTORY,\n known_hash='99d764541983bfee60d4176af48ed803d427dea61243fa22d3f4003ebcec98f4',\n)\n\n# open mesh file\nmesh = AdcircMesh.open(MESH_DIRECTORY / 'fort.14', crs=4326)\n\n# initialize tidal forcing and constituents\ntidal_forcing = Tides()\ntidal_forcing.use_all()\nmesh.add_forcing(tidal_forcing)\n\n# initialize atmospheric mesh forcings (for NUOPC coupling)\nwind_forcing = AtmosphericMeshForcing(\n filename='Wind_HWRF_SANDY_Nov2018_ExtendedSmoothT.nc', nws=17, interval_seconds=3600,\n)\nmesh.add_forcing(wind_forcing)\n\n# initialize wave mesh forcings (for NUOPC coupling)\nwave_forcing = WaveWatch3DataForcing(\n filename='ww3.HWRF.NOV2018.2012_sxy.nc', nrs=5, interval_seconds=3600,\n)\nmesh.add_forcing(wave_forcing)\n\n# initialize Slurm configuration\nslurm = SlurmConfig(\n account='account',\n ntasks=1000,\n run_name='adcircpy/examples/example_4.py',\n partition='partition',\n walltime=timedelta(hours=8),\n mail_type='all',\n mail_user='example@email.gov',\n log_filename='example_4.log',\n modules=['intel/2020', 'impi/2020', 'netcdf/4.7.2-parallel'],\n path_prefix='$HOME/adcirc/build',\n)\n\n# instantiate driver object\ndriver = AdcircRun(\n mesh=mesh,\n start_date=datetime.now(),\n end_date=timedelta(days=7),\n spinup_time=timedelta(days=5),\n server_config=slurm,\n)\n\n# write driver state to disk\ndriver.write(OUTPUT_DIRECTORY, overwrite=True)\n```\n\n## Citation\n\n```\nCalzada, J., Burnett, Z., Moghimi, S., Myers, E., & Pe\u2019eri, S. (2021). ADCIRCpy: A Python API to generate ADCIRC model input files (Technical Memorandum No. 41; NOAA NOS OCS). National Oceanic and Atmospheric Administation.\n```\n\n```bibtex\n@techreport{calzadaADCIRCpyPythonAPI2021,\n type = {Technical {{Memorandum}}},\n title = {{{ADCIRCpy}}: A {{Python API}} to Generate {{ADCIRC}} Model Input Files},\n author = {Calzada, Jaime and Burnett, Zachary and Moghimi, Saeed and Myers, Edward and Pe'eri, Shachak},\n year = {2021},\n month = dec,\n number = {41},\n institution = {{National Oceanic and Atmospheric Administation}},\n abstract = {The Advanced Circulation Model (ADCIRC) 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, 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.}\n}\n```\n\n## Acknowledgements\n\nThe majority of ADCIRCpy was written by Jaime Calzada [@jreniel](https://github.com/jreniel).\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "Python package for working with ADCIRC input and output files",
"version": "1.2.7",
"project_urls": {
"Documentation": "https://adcircpy.readthedocs.io",
"Homepage": "https://github.com/noaa-ocs-modeling/adcircpy.git",
"Repository": "https://github.com/noaa-ocs-modeling/adcircpy.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9993cc1d922aa3e036cfdcbcedc7552061cf88a11ae5b37edda39411960976e2",
"md5": "b93a56e393401a5818fabb19e5c8fb19",
"sha256": "d77792ab77a4e48127ba8aeacca52f277013f5b1dd23db4f0bd7da77c25ed7a7"
},
"downloads": -1,
"filename": "adcircpy-1.2.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b93a56e393401a5818fabb19e5c8fb19",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 110441,
"upload_time": "2023-10-02T13:46:58",
"upload_time_iso_8601": "2023-10-02T13:46:58.202806Z",
"url": "https://files.pythonhosted.org/packages/99/93/cc1d922aa3e036cfdcbcedc7552061cf88a11ae5b37edda39411960976e2/adcircpy-1.2.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ce96b9b1eb4728d44e94f0ee4e38b6f3a6135cde4111d735349271853d10e77b",
"md5": "ab17dd41a26bd1d9ba7a651c71d23f5d",
"sha256": "20afd532e0427d928b3080f6f9a85618570147746ff463e0dd6eb43a3c2576db"
},
"downloads": -1,
"filename": "adcircpy-1.2.7.tar.gz",
"has_sig": false,
"md5_digest": "ab17dd41a26bd1d9ba7a651c71d23f5d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 96757,
"upload_time": "2023-10-02T13:47:00",
"upload_time_iso_8601": "2023-10-02T13:47:00.148320Z",
"url": "https://files.pythonhosted.org/packages/ce/96/b9b1eb4728d44e94f0ee4e38b6f3a6135cde4111d735349271853d10e77b/adcircpy-1.2.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-02 13:47:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "noaa-ocs-modeling",
"github_project": "adcircpy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "adcircpy"
}
JSON
