Metadata-Version: 2.4
Name: recast-woof
Version: 1.0.2
Summary: Recast WOOF: GPU-native regional weather forecasting with WRF-class physics, data assimilation and native preprocessing, plus preview hex and global models
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/recastsystems/woof
Project-URL: Repository, https://github.com/recastsystems/woof
Project-URL: Changelog, https://github.com/recastsystems/woof/blob/main/CHANGELOG.md
Keywords: WRF,WPS,GRIB,NetCDF,weather,CUDA,MPAS,data-assimilation
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: licenses/LICENSE-AER-RRTMG-BSD-3-Clause.txt
License-File: licenses/LICENSE-Arm-optimized-routines-MIT.txt
License-File: licenses/LICENSE-CORE-MATH-MIT.txt
License-File: licenses/LICENSE-CORE-MATH-binary64-MIT.txt
License-File: licenses/LICENSE-CORE-MATH-rw-libm-MIT.txt
License-File: licenses/LICENSE-FDLIBM-SunPro-globe.txt
License-File: licenses/LICENSE-FDLIBM-SunPro.txt
License-File: licenses/LICENSE-MPAS-BSD-3-Clause.txt
License-File: licenses/LICENSE-NumPy-BSD-3-Clause.txt
License-File: licenses/LICENSE-PyART-Argonne-BSD-3-Clause.txt
License-File: licenses/LICENSE-RTE-RRTMGP-BSD-3-Clause.txt
License-File: licenses/LICENSE-SIL-OFL-1.1-SourceSans3.txt
License-File: licenses/LICENSE-WRF-public-domain.txt
License-File: licenses/LICENSE-rust-libm.txt
License-File: licenses/NOTICE-AER-RRTMG-as-distributed-with-WRF.txt
License-File: licenses/NOTICE-Numerical-Recipes.txt
License-File: licenses/THIRD-PARTY-LICENSES-bridge-binaries.txt
License-File: licenses/THIRD-PARTY-LICENSES-zarr-binary.txt
Requires-Dist: numpy>=2.0
Requires-Dist: netCDF4>=1.6
Requires-Dist: matplotlib>=3.8
Requires-Dist: jsonschema>=4.0
Requires-Dist: scipy>=1.11
Requires-Dist: pyshp>=2.3
Requires-Dist: cdsapi>=0.7.7
Requires-Dist: recast-woof-data==1.0.2
Provides-Extra: gpu-cu12
Requires-Dist: cupy-cuda12x[ctk]>=14.0; extra == "gpu-cu12"
Provides-Extra: gpu-cu13
Requires-Dist: cupy-cuda13x[ctk]>=14.0; extra == "gpu-cu13"
Provides-Extra: gpu
Requires-Dist: recast-woof[gpu-cu12]; extra == "gpu"
Provides-Extra: render
Requires-Dist: wrf-rust<0.3,>=0.2.39; extra == "render"
Provides-Extra: geog
Requires-Dist: rasterio>=1.3; extra == "geog"
Requires-Dist: pyproj>=3.6; extra == "geog"
Provides-Extra: obs
Provides-Extra: dealias
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.5; extra == "dev"
Requires-Dist: psutil>=5.9; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Provides-Extra: publish
Requires-Dist: huggingface_hub>=0.23; extra == "publish"
Requires-Dist: h5py>=3.10; extra == "publish"
Provides-Extra: all-cu12
Requires-Dist: recast-woof[gpu-cu12]; extra == "all-cu12"
Requires-Dist: recast-woof[render]; extra == "all-cu12"
Provides-Extra: all-cu13
Requires-Dist: recast-woof[gpu-cu13]; extra == "all-cu13"
Requires-Dist: recast-woof[render]; extra == "all-cu13"
Provides-Extra: all
Requires-Dist: recast-woof[all-cu12]; extra == "all"
Dynamic: license-file

# Recast WOOF

**Weather Observations and Open Forecasting: a GPU-native weather model you run on your own card.**

WOOF is a regional weather model with WRF-class physics that runs on one
NVIDIA GPU, with its own preprocessing, data assimilation and plots. One
install carries three models:

| Model | Command | Status |
| --- | --- | --- |
| Regional (WRF-ARW class, nests, DA) | `woof` | Production |
| Hex (MPAS-style unstructured mesh) | `woof hex` | Preview |
| Global (spectral, with ensemble DA) | `woof global` | Preview |

Preview means the model is in the package, documented and tested on CPU, and
its command says preview each time it runs; its config and checkpoint formats
may change in a minor release. The major-version promise covers the regional
model.

Production means the regional commands and their config and checkpoint
formats are covered by that promise. It is not a statement about forecast
accuracy; see Science and limits below.

## Install

Linux on x86_64, Python 3.11 or newer, an NVIDIA GPU and driver. WOOF has
no Windows build of the native tools yet.

```bash
python3 -m venv ~/woof-env
~/woof-env/bin/python -m pip install 'recast-woof[all-cu12]'
~/woof-env/bin/woof fetch-tables
~/woof-env/bin/woof fetch-geog --datasets wrf
~/woof-env/bin/woof doctor
```

For a CUDA 13 setup use `all-cu13`. The hex model runs only on CUDA 13, so
install `all-cu13` to use it. Install one CuPy/CUDA major per environment.
The Linux wheel carries the native tools (GRIB and NetCDF decoding, the
WPS-equivalent preprocessor, the renderer).

`fetch-geog` downloads the global geography every forecast builds its
terrain, land use and soil from: about 1.3 GB, 17 GB unpacked, once per
computer. `fetch-tables` adds two Thompson microphysics tables (about 314 MiB).
Reference tables and map assets arrive with the `recast-woof-data` package.

## Run a forecast

```bash
woof domain --point 35.3,-97.5 --source hrrr --cycle latest --hours 3 \
     --root-dx 3 --point-extent-km 300 --out forecast.toml
woof go forecast.toml --dry-run
woof go forecast.toml
```

`--dry-run` reviews the route, sizes it for your card and names anything
missing; the second line fetches, prepares, runs and draws. Pictures are drawn
as each history frame lands, beside the running forecast.

Compare two runs, any product, as run A minus run B:

```bash
woof render --diff runA/ runB/ --out diff/
```

The pair must share the grid and the valid times; a mismatch is refused by
name.

## Documentation

- `docs/public/`: the CLI manual, physics, hardware guidance and data sources.
  The [code verification record](docs/public/VERIFICATION.md) documents
  historical WRF v4.6.1 comparisons and their configuration and coverage
  limits.
- `components/hex/` and `components/globe/`: the hex and global models' manuals,
  tests and tools.
- `woof --help-all` lists every command; `woof hex --help` and
  `woof global --help` list the preview models' commands.

## Science and limits

WOOF implements a WRF-ARW-class regional model and WRF-derived physics on the
GPU. Comparisons against WRF Fortran, ULP and byte-identity checks, and the
matched-run and ensemble consistency comparisons are **code verification**:
evidence that the tested code computes its intended equations. Each result
belongs to the build, reference version and configuration it tested. None
establishes general equivalence with WRF or skill for every combination of
physics, input data and hardware.

**Solution verification** estimates numerical error in a particular run.
Routine numerical-error budgets for weather forecasts remain a gap.
**Validation** compares model results with observations. Meteorology calls
that scoring forecast verification; in computational-science V&V terms it is
validation. Matching WRF is code verification and never validates a model.
WOOF can inherit WRF's published validation record only to the extent the
two are statistically indistinguishable for the configuration in question.

Published observation evidence is limited to specific runs and variables,
including the ASOS snow/soil comparison, the station/ceilometer fog-suite
comparison and an MRMS model-top comparison. The observation scoreboard is
in development. These do not establish a broad validation record across
regions, seasons or forecast lengths. The
[evidence page](docs/public/VERIFICATION.md) documents historical WRF v4.6.1
code comparisons and their configuration and coverage limits.

The hex model is a port of the MPAS-A v8.4.1 dynamical core with this engine's
physics; it is not MPAS and is not endorsed by UCAR. Use official
meteorological services for forecasts and warnings.

WOOF continues an engine released before under another name: WOOF 1.0 is
that engine's release 2.8.0 and the fixes made since, under the WOOF name,
with the hex and global models inside it. Settings spelled `GPUWM_*` keep
working beside the new `WOOF_*` spelling.

## Licence

Apache License 2.0. Third-party code, tables and datasets keep their own
terms; see [NOTICE](NOTICE) and [licenses/](licenses/).
