Skip to main content

xmetai-inference

English | 简体中文

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.

Exported ONNX models require GPU inference support. Use xmetai-onnx-plugins to provide the custom GPU operators required by the corresponding models.

Project Purpose
xmetai-core Core framework for meteorological AI model training and inference
xmetai-skills Skills for model development
xmetai-datakit Data processing and evaluation
xmetai-onnx-plugins Custom GPU operators for exported ONNX models

Table of Contents

Quick Start

Requirements

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

Install

From PyPI:

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

From a source checkout, for development:

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 (part of the FuXi Single collection), 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.

Then one command:

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

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

Override Parameters

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
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 Hugging Face
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 GitHub

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).

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.

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:

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:

"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. Model weights, data, and third-party assets may have separate terms.

XMetAI Team: douzsh@gmail.com.

Metadata

Release files for xmetai-inference 0.1.1

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

Source distribution (sdist)

Source distribution for xmetai-inference 0.1.1
File Size Uploaded Provenance Actions
xmetai_inference-0.1.1.tar.gz 80.1 kB With provenance Details for xmetai_inference-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for xmetai-inference 0.1.1
File Interpreter ABI Platform Actions
xmetai_inference-0.1.1-py3-none-any.whl Python 3 none any Details for xmetai_inference-0.1.1-py3-none-any.whl

Total release size: 162.8 kB

Release files / xmetai_inference-0.1.1.tar.gz

Download URL xmetai_inference-0.1.1.tar.gz
Size 80.1 kB
Tags Source
SHA-256 checksum
How to use checksums
8a4641edcb964eef63713180e473842cbd2c73eea112facaaf1ffd3209549adb
BLAKE2b-256 checksum
How to use checksums
0e77513541e65e5ef392566beac85e7cfb4a5af3da92c1a512fc6441bad989e9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / xmetai_inference-0.1.1-py3-none-any.whl

Download URL xmetai_inference-0.1.1-py3-none-any.whl
Size 82.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7640db9a3570cb5ca12b115b8055a77f8890793239cb42662106b7fe47597ec9
BLAKE2b-256 checksum
How to use checksums
63b31ded9ed9d89bab680552af404d869a8f36ce951ccbf8f7bc46614dc5501b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for xmetai-inference 0.1.1

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for xmetai_inference-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

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.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page