WW3Tool

WAVEWATCH III workflow toolkit · WAVEWATCH III 工作流工具包

A pure-Python preprocessing & run-assist toolkit around WAVEWATCH III (third-generation ocean wave model). Works on Windows / Linux / macOS. Provides CLI / interactive Shell / Desktop GUI / MCP server. Bilingual UI (Chinese / English).

English

What it does

WW3Tool does not replace the WW3 executables (ww3_grid, ww3_prnc, ww3_shel, ...). It automates and chains them:

Forcing preprocessing: validate / fix / merge wind & current NetCDF forcing files (latitude sorting, variable renaming, time-axis repair).
Mesh generation: structured rectilinear meshes (arbitrary-depth two-way nesting), unstructured triangular meshes, and SMC meshes.
Automatic namelists: generate the full WW3 namelist set for v6.07.1 and v7.14 (ww3_grid.nml, ww3_prnc.nml, ww3_shel.nml, ww3_ounf.nml, ww3_multi.nml, ...).
Run scripts: generate scripts that correctly invoke ww3_grid / ww3_prnc / ww3_shel.
HPC integration: SSH upload of the workdir to clusters, Slurm configuration, job submission / monitoring / result download.
Post-processing: wave-height maps, directional spectra, Jason-3 satellite validation, NDBC buoy matching.

Install

One command on every platform (macOS / Linux / Windows). GUI dependencies are included, no extra extra to install:

pip install ww3tool

Requires Python 3.9+. The ww3tool command is ready right after install.

Quick start

ww3tool --help              # list all commands
ww3tool workdir my_run      # create a workdir from the built-in template
ww3tool config              # view / edit the configuration
ww3tool print-params        # print the current params.yml

⚠️ You MUST configure params.yml first

workdir creates params.yml from the built-in template. Edit it before running anything: set the wind/current forcing paths, mesh region and resolution, time steps, and output settings — then run the corresponding subcommand to generate the mesh, namelists, and run scripts. WW3Tool cannot know your case until params.yml is configured.

Desktop GUI

ww3tool          # no argument launches the desktop GUI

Interactive shell

ww3tool shell

Tab completion and history; shares the same configuration as the GUI.

MCP server (for AI clients)

The repo ships an MCP server (34 ww3tool_* tools + list_commands, stdio transport) for Claude / Cursor and other AI clients. See public/packaging/mcp/ in the GitHub repo.

中文

这是什么

WW3Tool 不替代 WW3 可执行文件（ww3_grid、ww3_prnc、ww3_shel 等），而是把这些流程串起来、自动化：

强迫场预处理：风场 / 流场 NetCDF 强迫文件的校验、修复与合并（纬度排序、变量重命名、时间轴修正）。
网格生成：结构化矩形网格（任意深度双向嵌套）、非结构化三角网格、SMC 网格。
自动配置：为 v6.07.1 与 v7.14 生成 WW3 全套 namelist（ww3_grid.nml、ww3_prnc.nml、ww3_shel.nml、ww3_ounf.nml、ww3_multi.nml 等）。
运行脚本：自动生成正确调用 ww3_grid / ww3_prnc / ww3_shel 的脚本。
HPC 对接：SSH 上传工作目录到超算、配置 Slurm、提交作业、监控状态、下载结果。
后处理绘图：波高填色图、方向谱、Jason-3 卫星验证、NDBC 浮标匹配。

安装

一条指令，所有平台相同（macOS / Linux / Windows），GUI 依赖已内置，无需额外安装：

pip install ww3tool

要求 Python 3.9+，安装后 ww3tool 命令直接可用。

快速开始

ww3tool --help              # 查看全部命令
ww3tool workdir my_run      # 从内置模板创建工作目录并进入
ww3tool config              # 查看 / 修改配置
ww3tool print-params        # 打印当前参数

⚠️ 必须配置 params.yml

workdir 会从内置模板生成 params.yml。运行前必须编辑它：配置风场 / 流场路径、网格区域与分辨率、时间步长、输出设置，再执行对应子命令生成网格、namelist 与运行脚本。不配置 params.yml，工具无法知道你的算例是什么。

桌面图形界面（GUI）

ww3tool          # 无参数默认启动桌面

交互式命令行（shell）

ww3tool shell

支持 Tab 补全与历史记录，与 GUI 共用同一套配置。

MCP server（供 AI 客户端调用）

仓库提供 MCP server（34 个 ww3tool_* 工具 + list_commands，stdio 传输），可直接接入 Claude / Cursor 等 AI 客户端。配置方法见 GitHub 仓库 public/packaging/mcp/ 目录。

Metadata

Release files for ww3tool 0.1.20

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ww3tool 0.1.20
File	Size	Uploaded	Provenance
ww3tool-0.1.20.tar.gz	6.5 MB	Aug 29, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for ww3tool 0.1.20
File	Interpreter	ABI	Platform	Reset
ww3tool-0.1.20-py3-none-any.whl 7.2 MB Aug 29, 2026 Without provenance	Python 3	none	any	Details

Total release size: 13.6 MB

Release files / ww3tool-0.1.20.tar.gz

Download URL	ww3tool-0.1.20.tar.gz
Size	6.5 MB
Tags	Source
SHA-256 checksum How to use checksums	`1e48e88dfd7e32e9cc320164ef3823349974b77242e119f28e2bfc9c2aa1ee92`
BLAKE2b-256 checksum How to use checksums	`565660f8dbcb1f641b1224e8c1c3b87ee4616e2d8a80c4495d30ed7d4fed0396`
Upload date	Aug 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.5`

Release files / ww3tool-0.1.20-py3-none-any.whl

Download URL	ww3tool-0.1.20-py3-none-any.whl
Size	7.2 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`6ff62edd9cf73493f2d51f8c1c1f0cc861f75c8edfd7f20c2293c2362ce43e48`
BLAKE2b-256 checksum How to use checksums	`f3d862e55f6f371f059d85dd3f6f0977eae72d320804c13c0ffc59b6f998ba76`
Upload date	Aug 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.5`

Security for ww3tool 0.1.20

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.