ADCIRCPy

用于自动化ADCIRC模型运行的Python库。

文档可以在https://adcircpy.readthedocs.io找到

组织/责任

ADCIRCpy目前由美国联邦政府机构国家海洋和大气管理局（NOAA）的一部分——海岸测量局（OCS）的海岸海洋建模分支（CMMB）维护，主要由@jreniel开发。

• Zachary Burnett（负责人） - zachary.burnett@noaa.gov
• Jaime Calzada - jrcalzada@vims.edu

安装

请使用Python>=3.6的虚拟环境。您可以使用conda或操作系统的Python为应用程序提供虚拟环境。

您可以通过pip安装应用程序。这将安装最新标记的版本。

pip install adcircpy

或者，您可以通过克隆它并运行以下命令手动安装存储库

pip install .

用法

命令行界面（CLI）

此程序公开了一些通过命令行界面可用的命令。您可以将-h标志传递给这些命令中的任何命令以探索其功能。

• tide_gen
• plot_mesh
• tidal_run
• best_track_run
• best_track_file
• plot_maxele
• plot_fort61
• fort63

示例

生成潮汐成分模板

您可以通过执行tide_gen命令并传递网格、开始日期和运行天数作为参数来快速为您的网格创建潮汐组件表。此功能默认从HAMTIDE数据库中获取数据。

tide_gen \
    /path/to/your/fort.14 \
    2021-02-26T00:00:00 \
    15 \
    --mesh-crs='epsg:4326'

运行飓风桑迪（AL182012）的最佳轨迹运行

创建ADCIRC输入文件包括飓风桑迪的潮汐和风暴数据

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

注意，由于fort.14不包含坐标参考系统信息，因此需要使用--crs标志才能正确运行。EPSG:4326表示网格位于WGS84（经纬度）。注意，反斜杠表示“继续到下一行”的shell。您可以删除反斜杠后，将上述命令写在一行上。

绘制结果

以下是使用该软件包进行快速绘图的两个示例。这些只是作为示例提供。支持比这些示例更多的文件类型，但程序尚未支持所有输出输入/输出文件类型。鼓励用户探索可用的选项，并提出和贡献改进。

plot_fort61 /path/to/fort.61.nc MSL --show --coops-only

plot_mesh /path/to/fort.14 --show-elements

Python API

有关用法示例，请参阅示例目录。

example_1.py

以下代码通过以下方式构建简单的ADCIRC运行配置：

1. 读取fort.14网格文件（具体为Shinnecock湾的测试网格）
2. 向网格添加潮汐强迫
3. 使用网格创建一个包含起始和结束日期的AdcircRun驱动对象
4. 覆盖默认模型选项中的fort.15
5. 如果存在则运行ADCIRC，否则将配置写入磁盘

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

以下代码与上面的example_1.py类似，但添加了网格的静态曼宁N系数。

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

以下代码与上面的example_1.py类似，但添加了HURDAT最佳轨迹风强迫，并构建了Slurm作业脚本以提交给作业管理器。

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

以下代码与上面的example_3.py类似，但使用ATMESH风强迫和WW3DATA波浪强迫。

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)

引用

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.

@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.}
}

致谢

ADCIRCpy的大部分代码由Jaime Calzada编写@jreniel。