Metadata-Version: 2.4
Name: xmetai-inference
Version: 0.1.1
Summary: Configuration-driven weather model inference and evaluation
Author-email: XMetAI Lab <douzsh@gmail.com>
License-Expression: GPL-3.0-or-later
Keywords: meteorology,AI,deep learning,weather,inference
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: xmetai-core
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: torch
Requires-Dist: xarray
Provides-Extra: netcdf
Requires-Dist: h5netcdf; extra == "netcdf"
Requires-Dist: netCDF4; extra == "netcdf"
Provides-Extra: zarr
Requires-Dist: zarr; extra == "zarr"
Provides-Extra: onnx
Requires-Dist: onnxruntime; extra == "onnx"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: ruff>=0.0.250; extra == "dev"
Requires-Dist: zarr; extra == "dev"
Requires-Dist: h5netcdf; extra == "dev"
Requires-Dist: netCDF4; extra == "dev"
Requires-Dist: onnxruntime; extra == "dev"
Dynamic: license-file

# xmetai-inference

[English](README.md) | [简体中文](README.zh-CN.md)

Inference framework for autoregressive weather forecasting models. It reads ERA5 / CRA-40
reanalysis from Zarr stores, feeds each model the channel set and history window its contract
declares, runs the rollout, and writes the forecast as NetCDF.

- Runs ONNX and `torch.export` (`.pt2`) graphs behind one interface
- Supports Zarr, NetCDF, and other input data formats
- Ships a run config per model, selected with `--config <name>`
- Multi-GPU by sharding initialization times × members across cards

Release version: **0.1.1**.

## Related projects

Exported ONNX models require GPU inference support. Use
[xmetai-onnx-plugins](https://github.com/XMetAI-Lab/xmetai-onnx-plugins) to provide the custom GPU
operators required by the corresponding models.

| Project | Purpose |
| --- | --- |
| [xmetai-core](https://github.com/XMetAI-Lab/xmetai-core) | Core framework for meteorological AI model training and inference |
| [xmetai-skills](https://github.com/XMetAI-Lab/xmetai-skills) | Skills for model development |
| [xmetai-datakit](https://github.com/XMetAI-Lab/xmetai-datakit) | Data processing and evaluation |
| [xmetai-onnx-plugins](https://github.com/XMetAI-Lab/xmetai-onnx-plugins) | Custom GPU operators for exported ONNX models |

## Table of Contents

- [Related projects](#related-projects)
- [Quick Start](#quick-start)
  - [Requirements](#requirements)
  - [Install](#install)
  - [Examples](#examples)
  - [Override Parameters](#override-parameters)
- [Supported Models](#supported-models)
  - [Channel Sets and Order](#channel-sets-and-order)
- [Supported Datasets](#supported-datasets)
  - [processed_multi_zarr](#processed_multi_zarr)
  - [netcdf_data](#netcdf_data)
- [Project Structure](#project-structure)
- [How It Works](#how-it-works)
- [License and contact](#license-and-contact)

## Quick Start

### Requirements

- Linux (or WSL2 / Git Bash on Windows)
- An NVIDIA GPU with CUDA
- Model weights and input data

### Install

From PyPI:

```bash
pip install xmetai-inference
pip install "xmetai-inference[netcdf,zarr,onnx]"
pip install "xmetai-inference[netcdf,zarr]"
```

From a source checkout, for development:

```bash
pip install -e .
pip install -e ".[netcdf,zarr,onnx]"
pip install -e ".[netcdf,zarr]"
```

`torch` comes in with the base install. The `netcdf` extra brings `netCDF4` / `h5netcdf`
(reading `mean.nc`/`std.nc`, writing output), `zarr` powers store reads in `xmetai-core`, and
`onnx` pulls in `onnxruntime`.

> PyPI's `onnxruntime` is the **CPU** build. For GPU inference install `onnxruntime-gpu`
> instead (the `onnx` extra and `onnxruntime-gpu` conflict; use one or the other). The loader
> logs a warning when it has to fall back to the CPU provider.

> **XMetAI ONNX Runtime plugin (custom operators).** Configs that set `ops_library` (the
> Tongyun configs) load custom operators through the XMetAI ONNX Runtime
> plugin. Download the build matching your ONNX Runtime / CUDA version from
> https://github.com/XMetAI-Lab/xmetai-onnx-plugins/releases/ and point the config's
> `ops_library` at the downloaded `.so` (for example
> `xmetai_onnx_plugins.ort1_24.cuda12.so`). Without the plugin the graph fails to load with
> an unknown-operator error.

### Examples

`weather_nc_tongyun` is a self-contained example: it infers straight from **one given `.nc`**
(`dataset.type="netcdf_data"`).

Use the upstream Hugging Face repository [tpys/fuxi-2.1](https://huggingface.co/tpys/fuxi-2.1)
(part of the [FuXi Single collection](https://huggingface.co/collections/tpys/fuxi-single)), which
provides `input.nc` (2 × 85 × 721 × 1440, initialization 2024-09-29 00Z) together with `mean.nc`
and `std.nc`; this repository does not host those files.

Point `SAMPLE_ROOT` at the directory holding the FuXi-2.1 release files, and `TONGYUN_ONNX` /
`OPS_LIBRARY` at your Tongyun weights and the plugin build:

- `SAMPLE_ROOT` — `input.nc`, `mean.nc`, `std.nc`.
- Tongyun — the deterministic ONNX graph and the plugin `.so` from
  [xmetai-onnx-plugins](https://github.com/XMetAI-Lab/xmetai-onnx-plugins/releases/).

Then one command:

```bash
xmetai-infer --config weather_nc_tongyun --out <output_dir>
```

Output lands at `{out}/{YYYYMMDD|YYYYMMDDHH}/[member_XXX/]{step:03d}.nc`.

### Override Parameters

```bash
xmetai-infer --config weather_era_0p25_tongyun \
  --times "2025010600..2025011200:24" \
  --steps 60 --gpus 2 --cuda-devices 0,1 \
  --vars z500,u200,v200,msl,tp \
  --out <output_dir>
```

- `--times` follows the `parse_times` syntax in `xmetai_inference/configs/base.py`: a single
  `2025010600`, a comma-separated list, a closed interval `A..B` (24 h step by default), or
  `:N` to override the step.
- `--config` takes a built-in config name or any external `.py` config; the positional argument
  is the same thing for a file path. See `configs/` for examples.
- `--model-path` swaps the weight file without touching the config.

## Supported Models

| Model | Config (`--config`) | Type / Grid | Channels | Paper | Model link |
|------|------|------|------|------|------|
| Tongyun | `weather_era_0p25_tongyun` | Deterministic · `GRID_025` | 78 | - | Hugging Face (coming soon) |
| FengQing V1.5Beta | `weather_era_0p25_fengqing` | Deterministic · `GRID_025` | 70 | - | [GitHub](https://github.com/nmcdev/CMA-AIM-GFS-Fengqing) |
| FuXi-2.1 | `weather_era_0p25_fuxi21` | Deterministic · `GRID_025` | 85 | Chen, L., Zhong, X., Zhang, F., et al. FuXi: a cascade machine learning forecasting system for 15-day global weather forecast. *npj Clim. Atmos. Sci.* 6, 190 (2023). [doi](https://doi.org/10.1038/s41612-023-00512-1) | [Hugging Face](https://huggingface.co/tpys/fuxi-2.1) |
| Pangu-Weather | `weather_era_0p25_pangu` | Deterministic · `GRID_025` | 69 | Bi, K., Xie, L., Zhang, H., et al. Accurate medium-range global weather forecasting with 3D neural networks. *Nature* 619, 533–538 (2023). [doi](https://doi.org/10.1038/s41586-023-06185-3) | [GitHub](https://github.com/198808xc/Pangu-Weather) |

`weather_nc_tongyun` is a demo config, not a production model: it runs the Tongyun graph on
the FuXi-2.1 example `.nc` (see [Examples](#examples)).

### Channel Sets and Order

Every model's `input_channels` (also `output_channels`) is the flattened list below; the order is
part of the contract. A wrong order does **not** raise — it silently forecasts the wrong field.

```
upper = [f"{var}{level}" for var in PL_VARS for level in LEVELS]      # 65 channels

Tongyun   (78): PL z,t,u,v,q × [50,100,150,200,250,300,400,500,600,700,850,925,1000]
                + [t2m, d2m, sst, u10m, v10m, u100m, v100m, msl, ssr, ssrd, fdir, ttr, tp]
FengQing  (70): PL z,q,t,u,v × [1000,925,850,700,600,500,400,300,250,200,150,100,50]
                + [tp, msl, u10m, v10m, t2m]
FuXi-2.1  (85): PL z,t,u,v,q × same levels
                + [msl, t2m, d2m, sst, ws10m, ws100m, u10m, v10m, u100m, v100m,
                   lcc, mcc, hcc, tcc, ssr, ssrd, fdir, ttr, tcw, tp]
Pangu     (69): PL z,q,t,u,v × same descending-pressure levels
                + [msl, u10m, v10m, t2m]
```

Channel names are matched against store names by `_raw_channel_name`: exact match first, then
`z50` → `z_50`. A store may be a superset of the model channels — every requested channel must
exist, or construction fails loudly. Two processors read names differently: `denormalize`
aligns store stats by underscore-insensitive, lower-cased name and tolerates a superset;
`normalize` requires stats that match `input_channels` in count **and order** exactly.

> **Model naming.** Config names follow `<domain>_<source>_<resolution>_<model>`:
> `domain` = `weather` (15-day, 6-hourly) or `s2s` (subseasonal, daily steps); `source` = `era`
> (ERA5) or `cra` (CRA-40); `resolution` = `0p25` (0.25°) or `1p5`. Examples:
> `weather_era_0p25_tongyun`, `weather_era_0p25_fengqing`, `weather_era_0p25_fuxi21`,
> `weather_era_0p25_pangu`. Each maps to the eponymous config under `configs/`.
> **Model-class registry names** (the `model_class=` in configs — `iwc_tongyun_gdn2_onnx`
> (the Tongyun graph), `fengqing_pre_onnx`, `fuxi21_pt2`, `pangu_onnx`) map to
> `MODEL_REGISTRY` in `utils/model_factory.py`.

## Supported Datasets

Two dataset types: `processed_multi_zarr` (the production path, backed by `xmetai-core`'s
`MultiZarrDataset`) and `netcdf_data` (one given `.nc` per initialization, for demos and
business-supplied inputs).

### processed_multi_zarr

The stores are Zarr products built to the xmetai-datakit data contract. The contract defines the
array structure, channel order, units, normalization, masks, and metadata a product must satisfy:
see [`config/dataset_specs`](https://github.com/XMetAI-Lab/xmetai-datakit/tree/main/config/dataset_specs).

```python
dataset = {
    "type": "processed_multi_zarr",
    "paths": ["<store_root>/store_a.zarr", "<store_root>/store_b.zarr"],
    "processors": [ ... ],          # executed in the DataLoader worker, in order
}
```

- `paths` may list several stores. Each is opened and sliced to the requested time range; their
  time coordinates are aligned to the **intersection** and to `freq`, then the arrays are
  concatenated along `channel`. **The first store listed wins on duplicate channel names.**
- One sample is `hist_frames` consecutive frames ending at the init time, read as
  `(hist_frames, C, lat, lon)` float32 (e.g. 2 × 78 × 721 × 1440 for Tongyun). The init time is
  the last history frame; the store must contain at least one frame after it. A requested init
  time without enough history raises.
- The framework derives `hist_frames`, `fcst_frames=1`, `freq`, `interval=1`,
  `inference_only=True`, `years`, and `in_names=[]` from the model contract and the requested
  init times. Do not repeat these keys in `dataset` (duplicate keyword arguments); any **other**
  key is forwarded to `MultiZarrDataset` as-is (e.g. `bbox`, `lat_flip`).

### netcdf_data

Infer straight from given `.nc` files, one file per initialization:

```python
dataset = {
    "type": "netcdf_data",
    "paths": ["/abs/input.nc"],
    "processors": [ ... ],          # optional; same processors as processed_multi_zarr
}
```

Each file holds the full model input window `[time, channel, lat, lon]`; all history frames live
inside the nc itself (the engine never reads back into a store). The init time is the last `time`
frame's value, so `cfg.times` is not consulted for this type. The channel axis is verified and
rewritten to `input_channels` by name (underscore-insensitive, case-insensitive); the nc may
carry a **superset** (e.g. 85 channels feeding a 78-channel model), while a missing channel or a
count mismatch without `channel` coordinates fails at build time. Values pass through
**untouched** unless `dataset.processors` declares a chain — e.g. `denormalize` with
`mean_file`/`std_file` to restore physical units from a z-score-normalized nc:

```python
"processors": [{
    "name": "denormalize",
    "mean_file": "/abs/mean.nc", "std_file": "/abs/std.nc",
    "expm1_channels": ["tp"],
}]
```

Samples are built eagerly once at dataset build time, so this type is single-process-only.

## Project Structure

```
.
├── pyproject.toml           # PyPI build metadata and CLI entry
├── xmetai_inference/        # The installable Python package (package name: xmetai-inference)
│   ├── cli.py               # Config loading, multi-GPU scheduling, the autoregressive main loop, async disk-write
│   ├── data/                # Dataset implementations, grouped into subpackages by category (weather/)
│   ├── utils/               # dataloader_factory (config -> DataLoader, dispatched by dataset.type),
│   │                        #   runner (Rollout / Trajectory autoregressive orchestration),
│   │                        #   model_factory (MODEL_REGISTRY / get_model_class / create_model),
│   │                        #   model-side pipeline (recurrent/output), data-side tensor processors, logging
│   ├── backends/            # BaseInferModel + onnx / pt2 execution engines
│   └── configs/             # Run configs (`--config <name>`) + declared model contracts;
│                            #   base.py = shared GRID/channels + InferConfig/load_config
├── tests/                   # Unit + integration tests (integration runs only with `-m realdata`)
└── model_artifacts/         # Local model artifacts; absent in a fresh clone and excluded from Git
```

## How It Works

One forecast, from store to disk:

```
zarr store  →  xmetai-core MultiZarrDataset          (read history frames, select variables by model channel)
            →  dataset.processors                    (in DataLoader worker, torch; chain depends on store layout)
                 unit_convert → geometry → normalize → fill_missing     ← raw store (ERA5)
                 denormalize (stats_path=store, ± expm1) → …            ← normalized store (CRA / c87 / v3)
            →  prepare_dataset_batch                 ([B,T,C,H,W] tensor)
            →  Rollout (autoregressive)              (state = result feedback)
                 recurrent processors (zero_channels)
            →  output processors (denormalize)       (workspace → physical units)
            →  to_dataset                            (xarray, non-negative fallback for tp)
            →  _AsyncWriter                          (single background thread writes NetCDF)
```

- **Contract-driven models**: channels, grid, history window, member semantics, and state
  representation are declared by the model class, so backends stay interchangeable.
- **Pluggable backends**: `onnx` and `pt2` execution engines are decoupled from model semantics.
- **One config per run**: the config declares `dataset` (incl. `processors`), `dataloader`, and
  `model_processing` (the `recurrent` and `output` stages).
- **Unified autoregression**: `utils/runner.py`'s `Rollout`/`Trajectory` chain single-step
  `forward` into a multi-trajectory loop with `state = result` feedback.
- **Async disk-write**: one background thread writes NetCDF; on failure it falls back to per-step
  `raw_step_XXX.npy`.
- **Multi-GPU data parallelism**: work is sharded by "initialization time × member"; each worker
  process is pinned to one card via `CUDA_VISIBLE_DEVICES`.

> Input preprocessing goes through `dataset.processors`; `model_processing.input` must be empty
> (misconfiguring it errors out). Normalization already fused into the model file is not
> re-executed by the framework.

## License and contact

Licensed under **GPL-3.0-or-later**; see [LICENSE](LICENSE). Model weights, data, and third-party
assets may have separate terms.

XMetAI Team: douzsh@gmail.com.
