xmetai-inference
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 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
- Related projects
- Quick Start
- Supported Models
- Supported Datasets
- Project Structure
- How It Works
- 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:
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
onnxruntimeis the CPU build. For GPU inference installonnxruntime-gpuinstead (theonnxextra andonnxruntime-gpuconflict; 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'sops_libraryat the downloaded.so(for examplexmetai_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
.sofrom 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>
--timesfollows theparse_timessyntax inxmetai_inference/configs/base.py: a single2025010600, a comma-separated list, a closed intervalA..B(24 h step by default), or:Nto override the step.--configtakes a built-in config name or any external.pyconfig; the positional argument is the same thing for a file path. Seeconfigs/for examples.--model-pathswaps 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) ors2s(subseasonal, daily steps);source=era(ERA5) orcra(CRA-40);resolution=0p25(0.25°) or1p5. Examples:weather_era_0p25_tongyun,weather_era_0p25_fengqing,weather_era_0p25_fuxi21,weather_era_0p25_pangu. Each maps to the eponymous config underconfigs/. Model-class registry names (themodel_class=in configs —iwc_tongyun_gdn2_onnx(the Tongyun graph),fengqing_pre_onnx,fuxi21_pt2,pangu_onnx) map toMODEL_REGISTRYinutils/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
}
pathsmay list several stores. Each is opened and sliced to the requested time range; their time coordinates are aligned to the intersection and tofreq, then the arrays are concatenated alongchannel. The first store listed wins on duplicate channel names.- One sample is
hist_framesconsecutive 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, andin_names=[]from the model contract and the requested init times. Do not repeat these keys indataset(duplicate keyword arguments); any other key is forwarded toMultiZarrDatasetas-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:
onnxandpt2execution engines are decoupled from model semantics. - One config per run: the config declares
dataset(incl.processors),dataloader, andmodel_processing(therecurrentandoutputstages). - Unified autoregression:
utils/runner.py'sRollout/Trajectorychain single-stepforwardinto a multi-trajectory loop withstate = resultfeedback. - 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.inputmust 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.