Upload folder using huggingface_hub

README.md

@@ -0,0 +1,149 @@
+---
+frameworks: ONNX Runtime
+language:
+- en
+license: cc-by-nc-nd-4.0
+tags:
+- OneScience
+- Earth Science
+- Weather Forecast
+- Subseasonal Forecast
+- Ensemble Forecasting
+- ERA5
+- ONNX
+tasks: []
+datasets:
+- OneScience/ERA5
+---
+<p align="center">
+  <strong>
+    <span style="font-size: 30px;">FuXi-S2S</span>
+  </strong>
+</p>
+
+# Model Introduction
+
+FuXi-S2S is a global subseasonal forecasting model proposed by researchers from Fudan University and collaborating institutions.
+
+Paper: A machine learning model that outperforms conventional global subseasonal forecast models
+
+https://doi.org/10.1038/s41467-024-50714-1
+
+# Model Description
+
+FuXi-S2S takes two consecutive daily mean atmospheric states as input and targets the two-week to two-month forecast range, where conventional numerical models remain challenging to use effectively. This model package exposes the official ONNX inference graph through a small ONNX Runtime adapter.
+
+# Use Cases
+
+| Scenario | Description |
+| :---: | :--- |
+| Global subseasonal forecasting | Run the official FuXi-S2S ONNX weights with ERA5 inputs following the fixed 76-channel order. |
+| Local quick validation | Use synthetic HDF5 data to check data loading, ONNX Runtime execution, and visualization. |
+| ModelScope / OneCode execution | Download the standalone model package, configure an ONNX Runtime provider, and run the scripts directly. |
+
+# Usage Guide
+
+## 1. OneCode Usage
+
+Experience intelligent one-click AI4S programming through the OneCode online environment:
+
+[Click to Experience Intelligent One-Click AI4S Programming](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)
+
+## 2. Manual Installation and Usage
+
+**Hardware Requirements**
+
+- A GPU or DCU is recommended for practical inference. CPU can be used for import and small-scale connectivity checks, but full-resolution inference will be slow.
+- Install the ONNX Runtime build that provides the execution provider required by your hardware.
+- DCU users must install DTK in advance. DTK 25.04.2 or above, or the OneScience recommended version matching your cluster, is recommended.
+
+### Download the Model Package
+
+```bash
+hf download OneScience-Group/FuXi-S2S --local-dir ./FuXi-S2S
+cd FuXi-S2S
+```
+
+### Install the Runtime Environment
+
+**DCU Environment**
+
+```bash
+# Please activate DTK and CONDA first
+conda create -n onescience311 python=3.11 -y
+conda activate onescience311
+# uv installation is supported
+pip install onescience[earth-dcu] -i http://mirrors.onescience.ai:3141/pypi/simple/  --trusted-host mirrors.onescience.ai
+```
+
+**GPU Environment**
+```bash
+# Please activate CONDA first
+conda create -n onescience311 python=3.11 -y libstdcxx-ng=12 libgcc-ng=12 gcc_linux-64=12 gxx_linux-64=12
+conda activate onescience311
+# uv installation is supported
+pip install onescience[earth-gpu] -i http://mirrors.onescience.ai:3141/pypi/simple/  --trusted-host mirrors.onescience.ai
+```
+
+Install or select an ONNX Runtime provider matching the target hardware, then update `model.providers` in `conf/config.yaml` if necessary. The default configuration targets a DCU-compatible provider list.
+
+### Training Data Introduction
+
+The official model uses daily mean ERA5 states with a fixed 76-channel order. The OneScience community provides an ERA5 data slice:
+
+```bash
+hf download --repo-type dataset OneScience-Group/ERA5 --local-dir ./data
+```
+
+The adapter expects yearly files under `data/data/` and normalization arrays under `data/stats/`. Confirm the variable order in `conf/config.yaml` before inference.
+
+### Generate Synthetic Data
+
+When real ERA5 data is unavailable, generate native-grid HDF5 files for interface checks:
+
+```bash
+python scripts/fake_data.py
+```
+
+For a smaller smoke fixture, pass `--height 32 --width 64`; synthetic data does not reproduce the official forecast quality.
+
+### Pre-trained Weights
+
+The official ONNX graph requires both files below:
+
+```text
+weight/fuxi_s2s.onnx
+weight/fuxi_s2s
+```
+
+The large weight files are not bundled in this working copy and must be supplied from the authorized release. The `weight/` directory is reserved for these files.
+
+### Inference
+
+Inference reads `weight/fuxi_s2s.onnx` and its external data file by default. It converts ERA5 fields to the model's `121x240` grid and writes ONNX outputs to `result/output/`:
+
+```bash
+python scripts/inference.py
+```
+
+Use `--device cpu`, `--device cuda`, or `--device dcu` and configure `model.providers` for the selected runtime.
+
+### Evaluation and Visualization
+
+```bash
+python scripts/result.py
+```
+
+The result script reads the newest NPY output and writes multi-variable forecast figures to `result/visualization/`.
+
+# Official OneScience Resources
+
+| Platform | OneScience Main Repository | Skills Repository |
+| --- | --- | --- |
+| Gitee | https://gitee.com/onescience-ai/onescience | https://gitee.com/onescience-ai/oneskills |
+| GitHub | https://github.com/onescience-ai/OneScience | https://github.com/onescience-ai/oneskills |
+
+# Citation and License
+
+- This model package contains an adapter for the official FuXi-S2S ONNX release.
+- The official ONNX graph, external data file, and related data are subject to the CC BY-NC-ND 4.0 terms stated by the authorized release.

conf/config.yaml

@@ -0,0 +1,107 @@
+project:
+  name: fuxi_s2s
+
+data:
+  virtual_dir: ./data
+  raw_height: 721
+  raw_width: 1440
+  model_height: 121
+  model_width: 240
+  time_step_hours: 24
+  input_steps: 2
+  output_steps: 1
+  virtual_time_steps: 3
+  virtual_dtype: float16
+  variables:
+    - z1000
+    - z925
+    - z850
+    - z700
+    - z600
+    - z500
+    - z400
+    - z300
+    - z250
+    - z200
+    - z150
+    - z100
+    - z50
+    - t1000
+    - t925
+    - t850
+    - t700
+    - t600
+    - t500
+    - t400
+    - t300
+    - t250
+    - t200
+    - t150
+    - t100
+    - t50
+    - u1000
+    - u925
+    - u850
+    - u700
+    - u600
+    - u500
+    - u400
+    - u300
+    - u250
+    - u200
+    - u150
+    - u100
+    - u50
+    - v1000
+    - v925
+    - v850
+    - v700
+    - v600
+    - v500
+    - v400
+    - v300
+    - v250
+    - v200
+    - v150
+    - v100
+    - v50
+    - q1000
+    - q925
+    - q850
+    - q700
+    - q600
+    - q500
+    - q400
+    - q300
+    - q250
+    - q200
+    - q150
+    - q100
+    - q50
+    - t2m
+    - d2m
+    - sst
+    - ttr
+    - 10u
+    - 10v
+    - 100u
+    - 100v
+    - msl
+    - tcwv
+    - tp
+
+model:
+  path: ./weight/fuxi_s2s.onnx
+  device: dcu
+  # Replace DCUExecutionProvider with the provider name supplied by the installed DCU ONNX Runtime build.
+  providers: [ROCMExecutionProvider, CPUExecutionProvider]
+
+runtime:
+  seed: 42
+
+inference:
+  year: 2000
+  sample_index: 0
+  output_dir: ./result/output
+  visualization_dir: ./result/visualization
+  visualization_title: FuXi-S2S output

config.json

@@ -0,0 +1,45 @@
+{
+  "model_name": "FuXi-S2S",
+  "model_type": "fuxi_s2s",
+  "architectures": [
+    "FuXiS2SModel"
+  ],
+  "framework": "ONNX Runtime",
+  "domain": "atmosphere",
+  "task": "global-subseasonal-weather-forecasting",
+  "implementation": {
+    "entry_point": "model/fuxi_s2s.py",
+    "scope": "official FuXi-S2S ONNX inference adapter; both the ONNX graph and its external data file are required"
+  },
+  "architecture": {
+    "family": "ONNX autoregressive weather forecast model",
+    "input_steps": 2,
+    "output_steps": 1,
+    "input_channels": 76,
+    "spatial_source_shape": [
+      721,
+      1440
+    ],
+    "model_shape": [
+      121,
+      240
+    ],
+    "time_step_hours": 24,
+    "forecast_range": "two weeks to two months"
+  },
+  "data": {
+    "dataset": "ERA5",
+    "protocol": "fixed 76-channel daily-mean input order",
+    "normalization": "official FuXi-S2S preprocessing"
+  },
+  "weights": {
+    "onnx_graph": "weight/fuxi_s2s.onnx",
+    "external_data": "weight/fuxi_s2s"
+  },
+  "configuration_sources": [
+    "conf/config.yaml",
+    "model/fuxi_s2s.py",
+    "scripts/inference.py",
+    "scripts/config.py"
+  ]
+}

configuration.json

@@ -0,0 +1,11 @@
+{
+  "framework": "ONNX Runtime",
+  "task": "subseasonal_forecasting",
+  "model": "FuXi-S2S",
+  "input_format": "BTCHW",
+  "protocol": "official_onnx_inference",
+  "default_config": "conf/config.yaml",
+  "inference": "scripts/inference.py",
+  "evaluation": "scripts/result.py",
+  "visualization": "scripts/result.py"
+}

download.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+# Download files larger than 1MB, excluding .sh .py .md .yaml .yml
+# Total large files: 2
+modelscope download --model OneScience/FuXi-S2S weight/fuxi_s2s --local_dir ./
+modelscope download --model OneScience/FuXi-S2S weight/fuxi_s2s.onnx --local_dir ./

model/fuxi_s2s.py

@@ -0,0 +1,80 @@
+"""Official FuXi-S2S ONNX adapter.
+
+The public FuXi-S2S release contains an ONNX model and inference code. This
+module exposes the official inference contract through ONNX Runtime.
+"""
+
+from pathlib import Path
+
+import numpy as np
+
+
+class FuXiS2SModel:
+    def __init__(self, model_path, device="cpu", providers=None):
+        self.model_path = Path(model_path)
+        self.device = device
+        self.providers = list(providers) if providers else self._default_providers(device)
+        try:
+            import onnxruntime as ort
+        except ImportError as exc:
+            raise RuntimeError("onnxruntime is required for official FuXi-S2S inference") from exc
+        if not self.model_path.is_file():
+            raise FileNotFoundError(f"FuXi-S2S ONNX model not found: {self.model_path}")
+        external_data_path = self.model_path.parent / "fuxi_s2s"
+        if not external_data_path.is_file():
+            raise FileNotFoundError(
+                f"FuXi-S2S ONNX external data not found: {external_data_path}. "
+                "The official archive requires both fuxi_s2s.onnx and fuxi_s2s."
+            )
+        available_providers = ort.get_available_providers()
+        missing_providers = [provider for provider in self.providers if provider not in available_providers]
+        if missing_providers:
+            raise RuntimeError(
+                f"ONNX Runtime provider(s) unavailable: {missing_providers}. "
+                f"Available providers: {available_providers}. "
+                "Install the matching ONNX Runtime build and update model.providers."
+            )
+        session_options = ort.SessionOptions()
+        if device == "dcu":
+            # CPU constant folding can warn on kernels that are intended for the
+            # accelerator. Let the configured DCU provider execute the graph.
+            session_options.graph_optimization_level = ort.GraphOptimizationLevel.ORT_DISABLE_ALL
+        self.session = ort.InferenceSession(
+            str(self.model_path),
+            sess_options=session_options,
+            providers=self.providers,
+        )
+
+    @staticmethod
+    def _default_providers(device):
+        if device == "cpu":
+            return ["CPUExecutionProvider"]
+        if device == "cuda":
+            return ["CUDAExecutionProvider", "CPUExecutionProvider"]
+        if device == "dcu":
+            raise ValueError(
+                "DCU inference requires an explicit ONNX Runtime provider in "
+                "model.providers, for example ['DCUExecutionProvider', "
+                "'CPUExecutionProvider']"
+            )
+        raise ValueError("device must be 'cpu', 'cuda', or 'dcu'")
+
+    @property
+    def input_names(self):
+        return [item.name for item in self.session.get_inputs()]
+
+    @property
+    def output_names(self):
+        return [item.name for item in self.session.get_outputs()]
+
+    def step(self, inputs):
+        payload = {}
+        for name in self.input_names:
+            if name not in inputs:
+                raise KeyError(f"Missing FuXi-S2S ONNX input: {name}")
+            payload[name] = np.asarray(inputs[name], dtype=np.float32)
+        outputs = self.session.run(None, payload)
+        return dict(zip(self.output_names, outputs))
+
+    def __call__(self, inputs):
+        return self.step(inputs)

scripts/config.py

@@ -0,0 +1,19 @@
+"""Load project defaults from conf/config.yaml."""
+
+from pathlib import Path
+
+import yaml
+
+
+PROJECT_DIR = Path(__file__).resolve().parents[1]
+CONFIG_PATH = PROJECT_DIR / "conf" / "config.yaml"
+
+
+def load_config():
+    with CONFIG_PATH.open(encoding="utf-8") as handle:
+        return yaml.safe_load(handle)
+
+
+def project_path(value):
+    path = Path(value)
+    return path if path.is_absolute() else PROJECT_DIR / path

scripts/fake_data.py

@@ -0,0 +1,59 @@
+"""Generate native-grid virtual ERA5 data for OneScience ERA5Dataset."""
+
+import argparse
+from pathlib import Path
+
+import numpy as np
+
+from config import load_config, project_path
+
+def generate(dataset_dir, year, time_steps, height, width, variables, time_step_hours, seed, dtype):
+    import h5py
+
+    dataset_dir = Path(dataset_dir)
+    data_dir = dataset_dir / "data"
+    stats_dir = dataset_dir / "stats"
+    data_dir.mkdir(parents=True, exist_ok=True)
+    stats_dir.mkdir(parents=True, exist_ok=True)
+    path = data_dir / f"{year}.h5"
+    rng = np.random.default_rng(seed + year)
+    lat = np.linspace(90.0, -90.0, height, dtype=np.float32)[:, None]
+    lon = np.linspace(0.0, 360.0, width, endpoint=False, dtype=np.float32)[None, :]
+    with h5py.File(path, "w") as handle:
+        fields = handle.create_dataset(
+            "fields", shape=(time_steps, len(variables), height, width), dtype=dtype,
+            chunks=(1, 1, min(height, 64), min(width, 128)),
+        )
+        fields.attrs["variables"] = np.asarray(variables, dtype=h5py.string_dtype())
+        fields.attrs["time_step"] = time_step_hours
+        for step in range(time_steps):
+            phase = 2.0 * np.pi * (step / max(time_steps, 1))
+            base = np.sin(np.deg2rad(lat)) + 0.25 * np.cos(np.deg2rad(lon) + phase)
+            noise = rng.normal(0.0, 0.01, size=(len(variables), height, width)).astype(np.float32)
+            fields[step] = np.asarray([(index + 1) * base + noise[index] for index in range(len(variables))], dtype=dtype)
+    # ERA5Dataset always initializes these files, even when normalize=False.
+    np.save(stats_dir / "global_means.npy", np.zeros((1, len(variables), 1, 1), dtype=np.float32))
+    np.save(stats_dir / "global_stds.npy", np.ones((1, len(variables), 1, 1), dtype=np.float32))
+    return path
+
+
+def main():
+    config = load_config()
+    data_config = config["data"]
+    runtime_config = config["runtime"]
+    inference_config = config["inference"]
+    parser = argparse.ArgumentParser(description="Generate native-grid virtual ERA5 HDF5 data.")
+    parser.add_argument("--dataset-dir", default=str(project_path(data_config["virtual_dir"])))
+    parser.add_argument("--year", type=int, default=inference_config["year"])
+    parser.add_argument("--time-steps", type=int, default=data_config["virtual_time_steps"])
+    parser.add_argument("--height", type=int, default=data_config["raw_height"])
+    parser.add_argument("--width", type=int, default=data_config["raw_width"])
+    parser.add_argument("--seed", type=int, default=runtime_config["seed"])
+    parser.add_argument("--dtype", choices=["float16", "float32"], default=data_config["virtual_dtype"])
+    args = parser.parse_args()
+    print(generate(args.dataset_dir, args.year, args.time_steps, args.height, args.width,
+                   data_config["variables"], data_config["time_step_hours"], args.seed, args.dtype))
+
+
+if __name__ == "__main__":
+    main()

scripts/inference.py

@@ -0,0 +1,101 @@
+import argparse
+from datetime import datetime, timedelta, timezone
+import sys
+from pathlib import Path
+
+import numpy as np
+
+PROJECT_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(PROJECT_DIR / "scripts"))
+from config import load_config, project_path
+
+
+VARIABLES = load_config()["data"]["variables"]
+
+
+def prepare_input(dataset_dir, year, sample_index, onescience_src, input_steps, output_steps, model_height, model_width):
+    import torch.nn.functional as F
+
+    dataset_dir = Path(dataset_dir)
+    required_paths = [
+        dataset_dir / "data" / f"{year}.h5",
+        dataset_dir / "stats" / "global_means.npy",
+        dataset_dir / "stats" / "global_stds.npy",
+    ]
+    missing_paths = [path for path in required_paths if not path.is_file()]
+    if missing_paths:
+        missing = ", ".join(str(path) for path in missing_paths)
+        raise FileNotFoundError(
+            f"ERA5Dataset files are missing: {missing}. "
+            "Run 'python scripts/fake_data.py' or update data.virtual_dir and "
+            "inference.year in conf/config.yaml."
+        )
+    if onescience_src:
+        sys.path.insert(0, onescience_src)
+    from onescience.datapipes.climate.era5 import ERA5Dataset
+
+    dataset = ERA5Dataset(
+        dataset_dir=dataset_dir,
+        used_years=[year],
+        used_variables=VARIABLES,
+        input_steps=input_steps,
+        output_steps=output_steps,
+        normalize=False,
+    )
+    fields, _, _, step_idx, _ = dataset[sample_index]
+    if fields.ndim != 4 or tuple(fields.shape[:2]) != (input_steps, len(VARIABLES)):
+        raise ValueError(f"Unexpected ERA5Dataset input shape: {tuple(fields.shape)}")
+    fields = fields.float()
+    fields[:, VARIABLES.index("tp")] = fields[:, VARIABLES.index("tp")].mul(1000.0).clamp(0.0, 1000.0)
+    fields[:, VARIABLES.index("ttr")] /= 3600.0
+    fields = F.interpolate(fields, size=(model_height, model_width), mode="bilinear", align_corners=False)
+    return fields.unsqueeze(0).numpy().astype(np.float32), step_idx
+
+
+def main():
+    config = load_config()
+    data_config = config["data"]
+    model_config = config["model"]
+    inference_config = config["inference"]
+    parser = argparse.ArgumentParser(description="Run FuXi-S2S inference from OneScience ERA5Dataset data.")
+    parser.add_argument("--model", default=str(project_path(model_config["path"])))
+    parser.add_argument("--dataset-dir", default=str(project_path(data_config["virtual_dir"])))
+    parser.add_argument("--year", type=int, default=inference_config["year"])
+    parser.add_argument("--sample-index", type=int, default=inference_config["sample_index"])
+    parser.add_argument("--onescience-src", help="Path containing the onescience Python package")
+    parser.add_argument("--output-dir", default=str(project_path(inference_config["output_dir"])))
+    parser.add_argument("--device", default=model_config["device"], choices=["cpu", "cuda", "dcu"])
+    args = parser.parse_args()
+    sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "model"))
+    from fuxi_s2s import FuXiS2SModel
+
+    model = FuXiS2SModel(args.model, device=args.device, providers=model_config["providers"])
+    fields, step_idx = prepare_input(
+        args.dataset_dir,
+        args.year,
+        args.sample_index,
+        args.onescience_src,
+        data_config["input_steps"],
+        data_config["output_steps"],
+        data_config["model_height"],
+        data_config["model_width"],
+    )
+    if fields.shape[-2:] != (data_config["model_height"], data_config["model_width"]):
+        raise ValueError(f"Unexpected FuXi-S2S input grid: {fields.shape[-2:]}")
+    inputs = {"input": fields}
+    if "step" in model.input_names:
+        inputs["step"] = np.asarray([step_idx], dtype=np.float32)
+    if "doy" in model.input_names:
+        valid_time = datetime(args.year, 1, 1, tzinfo=timezone.utc) + timedelta(days=step_idx + 1)
+        inputs["doy"] = np.asarray([min(365, valid_time.timetuple().tm_yday) / 365.0], dtype=np.float32)
+    outputs = model(inputs)
+    output_dir = Path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    for name, value in outputs.items():
+        np.save(output_dir / f"{name}.npy", value)
+    print("Inference completed")
+    print({name: tuple(value.shape) for name, value in outputs.items()})
+
+
+if __name__ == "__main__":
+    main()

scripts/result.py

@@ -0,0 +1,182 @@
+import argparse
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+from config import load_config, project_path
+
+
+DEFAULT_VARIABLES = ("t2m", "msl", "tp", "tcwv")
+VARIABLE_STYLES = {
+    "t2m": ("2 m temperature", "Temperature (K)", "coolwarm"),
+    "d2m": ("2 m dew point", "Temperature (K)", "coolwarm"),
+    "sst": ("Sea-surface temperature", "Temperature (K)", "coolwarm"),
+    "msl": ("Mean sea-level pressure", "Pressure (model units)", "viridis"),
+    "tp": ("Total precipitation", "Precipitation (model units)", "Blues"),
+    "tcwv": ("Total column water vapour", "Water vapour (model units)", "YlGnBu"),
+}
+
+
+def find_input(output_dir):
+    candidates = sorted(Path(output_dir).glob("*.npy"), key=lambda path: path.stat().st_mtime)
+    if not candidates:
+        raise FileNotFoundError(
+            f"No inference result (*.npy) was found in {output_dir}. "
+            "Run scripts/inference.py first or pass --input explicitly."
+        )
+    return candidates[-1]
+
+
+def select_forecast(array, step, ensemble):
+    if array.ndim == 5:
+        if ensemble >= array.shape[0]:
+            raise IndexError(f"Ensemble index {ensemble} is outside array shape {array.shape}")
+        array = array[ensemble]
+    if array.ndim == 4:
+        if step >= array.shape[0]:
+            raise IndexError(f"Forecast step {step} is outside array shape {array.shape}")
+        array = array[step]
+    if array.ndim != 3:
+        raise ValueError(
+            "Expected an inference result shaped [time, channel, lat, lon], "
+            f"[channel, lat, lon], or [ensemble, time, channel, lat, lon], got {array.shape}"
+        )
+    return np.asarray(array, dtype=np.float32)
+
+
+def parse_variables(value, variables):
+    names = [name.strip() for name in value.split(",") if name.strip()]
+    if not names:
+        raise ValueError("At least one variable must be selected with --variables")
+    unknown = [name for name in names if name not in variables]
+    if unknown:
+        raise ValueError(f"Unknown variables: {unknown}. Available variables are configured in config.yaml")
+    return names
+
+
+def plot_field(axis, colorbar_axis, field, variable, latitudes, longitudes):
+    finite = field[np.isfinite(field)]
+    if finite.size == 0:
+        axis.set_title(f"{VARIABLE_STYLES.get(variable, (variable,))[0]} (no finite data)")
+        axis.set_facecolor("#d9dde3")
+        axis.text(
+            0.5,
+            0.5,
+            "No finite values",
+            transform=axis.transAxes,
+            ha="center",
+            va="center",
+            fontsize=12,
+            color="#263238",
+        )
+        axis.set_xlabel("Longitude (degrees)")
+        axis.set_ylabel("Latitude (degrees)")
+        axis.set_xticks(np.arange(0, 361, 60))
+        axis.set_yticks(np.arange(-90, 91, 30))
+        colorbar_axis.set_visible(False)
+        return
+    low, high = np.percentile(finite, [2, 98])
+    if low == high:
+        low, high = float(finite.min()), float(finite.max() + 1.0)
+    label, colorbar_label, colormap = VARIABLE_STYLES.get(
+        variable, (variable, "Model output", "viridis")
+    )
+    image = axis.imshow(
+        field,
+        cmap=colormap,
+        vmin=low,
+        vmax=high,
+        extent=(longitudes[0], longitudes[-1], latitudes[-1], latitudes[0]),
+        interpolation="nearest",
+        aspect="auto",
+    )
+    axis.set_title(label)
+    axis.set_xlabel("Longitude (degrees)")
+    axis.set_ylabel("Latitude (degrees)")
+    axis.set_xticks(np.arange(0, 361, 60))
+    axis.set_yticks(np.arange(-90, 91, 30))
+    axis.grid(color="white", alpha=0.3, linewidth=0.6)
+    axis.text(
+        0.02,
+        0.03,
+        f"range {finite.min():.3g} to {finite.max():.3g}\n"
+        f"mean {finite.mean():.3g} | p02-p98 {low:.3g}-{high:.3g}",
+        transform=axis.transAxes,
+        color="white",
+        fontsize=8,
+        va="bottom",
+        bbox={"facecolor": "black", "alpha": 0.55, "pad": 3, "edgecolor": "none"},
+    )
+    colorbar = plt.colorbar(image, cax=colorbar_axis, orientation="horizontal")
+    colorbar.set_label(colorbar_label)
+
+
+def main():
+    config = load_config()
+    data_config = config["data"]
+    inference_config = config["inference"]
+    variables = data_config["variables"]
+    parser = argparse.ArgumentParser(
+        description="Render FuXi-S2S forecast fields as a geographic multi-panel image."
+    )
+    parser.add_argument(
+        "--input",
+        default=None,
+        help="Inference .npy file; defaults to the newest file in inference.output_dir",
+    )
+    parser.add_argument(
+        "--output",
+        default=None,
+        help="PNG output path; defaults to inference.visualization_dir/<input-stem>.png",
+    )
+    parser.add_argument("--title", default=inference_config["visualization_title"])
+    parser.add_argument("--step", type=int, default=0, help="Forecast time index to display")
+    parser.add_argument("--ensemble", type=int, default=0, help="Ensemble member to display")
+    parser.add_argument(
+        "--variables",
+        default=",".join(name for name in DEFAULT_VARIABLES if name in variables),
+        help="Comma-separated variable names to display",
+    )
+    args = parser.parse_args()
+
+    input_path = Path(args.input) if args.input else find_input(project_path(inference_config["output_dir"]))
+    array = select_forecast(np.load(input_path), args.step, args.ensemble)
+    selected_variables = parse_variables(args.variables, variables)
+    if array.shape[0] != len(variables):
+        raise ValueError(
+            f"Inference result has {array.shape[0]} channels, but config.yaml defines {len(variables)} variables"
+        )
+    output = Path(args.output) if args.output else project_path(inference_config["visualization_dir"]) / f"{input_path.stem}.png"
+    output.parent.mkdir(parents=True, exist_ok=True)
+
+    height, width = array.shape[-2:]
+    latitudes = np.linspace(90.0, -90.0, height)
+    longitudes = np.linspace(0.0, 360.0, width, endpoint=False)
+    figure = plt.figure(figsize=(16, 9), constrained_layout=True)
+    layout = figure.add_gridspec(
+        2,
+        len(selected_variables),
+        height_ratios=[12, 1],
+        width_ratios=[1] * len(selected_variables),
+    )
+    figure.suptitle(
+        f"{args.title}\n{input_path.name} | forecast step {args.step} | ensemble {args.ensemble}",
+        fontsize=15,
+        fontweight="bold",
+    )
+    for index, variable in enumerate(selected_variables):
+        axis = figure.add_subplot(layout[0, index])
+        colorbar_axis = figure.add_subplot(layout[1, index])
+        variable_index = variables.index(variable)
+        plot_field(axis, colorbar_axis, array[variable_index], variable, latitudes, longitudes)
+        colorbar_axis.set_xticks([])
+        colorbar_axis.set_yticks([])
+    figure.savefig(output, dpi=180, facecolor="white")
+    plt.close(figure)
+    print(f"Input: {input_path}")
+    print(f"Output: {output}")
+
+
+if __name__ == "__main__":
+    main()