Metadata-Version: 2.4
Name: recast-woof
Version: 1.0.0
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-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/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.0
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.

## Install

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

```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, verification record, hardware
  guidance and data sources.
- `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. Its numerical comparisons apply to documented configurations and test
cases; they do not establish general equivalence with WRF or forecast skill for
every combination of physics, input data and hardware. 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 1.0.0 continues an engine released before under another name: it 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/).
