Quickstart with an AI Agent

wrf_gpu is designed to be driven by an AI coding agent. Clone the repo, open Claude Code / Codex / OpenCode (or any agent that reads a project's instruction files), and simply say: "Here is my input, this is what I need — get it running." The agent auto-loads an operator runbook that ships in the repo and does the rest, narrating each step.

Two front doors

This page is the human-facing explanation. The agent-facing instructions live in the repo as AI_OPERATOR.md and a Claude Code skill at .claude/skills/run-wrf-gpu/. You do not read those — your agent does. If you prefer to run the commands yourself, use the manual Quickstart instead.

How the AI-native quickstart works¶

The repository ships a small set of files that common agents load automatically when they open the checkout:

File	Loaded by	Role
`AI_OPERATOR.md`	Any agent (referenced from the auto-load files)	The authoritative end-user operator runbook the agent follows.
`.claude/skills/run-wrf-gpu/`	Claude Code	A native skill that triggers when you ask to run/set up a forecast, and dispatches to the runbook.
`AGENTS.md` / `CLAUDE.md` banner	Codex, OpenCode, Claude Code, …	A routing banner at the top that sends an agent helping an end user to `AI_OPERATOR.md` (the rest of those files is the port's internal dev protocol).

Because the instructions are in the repo, the agent gets accurate, version-matched knowledge of the real CLI, the required environment, the physics support matrix, and the honest limits — without you having to teach it.

Using it¶

# 1. Clone and open an AI coding agent in the checkout
git clone https://github.com/wrf-gpu/wrf_gpu.git && cd wrf_gpu
# open Claude Code / Codex / OpenCode here

# 2. Tell the agent, in your own words:
#    "Here is my case in ./my_case (namelist.input + wrfinput/wrfbdy).
#     Run a 24 h forecast and get me the wrfout. Set everything up."

The agent then works through the operator runbook and keeps you informed at every step.

What the agent does — and narrates¶

The runbook is an explicit, ordered playbook. A good agent will tell you what it is doing and how long each wait should take, roughly like this:

Understand the request — detects your case directory, forecast length, single-domain vs nested (--max-dom), and output location.
Environment — "creating a Python 3.11 venv, installing the CUDA build of JAX and the package…"
GPU / driver check — "running nvidia-smi and jax.devices() to confirm the GPU is visible…"
Smoke test — "running the bundled Switzerland 1-hour case first to prove the toolchain before touching your data…"
Prepare your case — "setting GPUWRF_WRF_ROOT for the physics tables; validating your namelist (it fails closed on anything unsupported, with a named reason)…"
Run & narrate — "JAX is compiling the GPU kernels — for this grid that's a one-time ~N minutes with no output, it's compiling, not hung… now integrating at ~X s per forecast-hour, so ~Y minutes for your 24 h run…"
Deliver & verify — "your wrfout is in runs/…; here's the ncdump -h header."

Time estimates the agent will quote

A new geometry/source/target can require cold compilation. Estimate its wait from the actual run and distinguish compile, initialization and stepping. Compatible warm caches can reduce readiness work, but a cache hit is not guaranteed. Historical speed figures retain their version and clocks; see performance evidence.

Use source-specific evidence¶

The agent follows current native controls and the installed release's runbook. Prepared inputs, supported schemes, full history, automatic sound steps and memory admission have explicit scope. Original CPU-WRF is fidelity truth; selected 24/72-hour comparisons and all hourly plots are linked on validation. Historical W3 reports retain their dated raw failures and dispositions; no universal observational equivalence or old-source transfer is claimed.

Version-matched operator guide¶

The released v0.4.0 guide and AI_OPERATOR share current CLI controls. The v0.4.0 operator runbook and skill cover current controls, fp32 WRF REAL with DOUBLE islands, DFI1/2/3, GPU refusals and analysis tools. Use the installed version's matching evidence; source and tags are published, while GitHub release assets await owner authentication.