# FuXi-CFD Model

## Overview

This repository accompanies the paper:

**Reconstructing fine-scale 3D wind fields with terrain-informed machine learning**

It provides the pre-trained FuXi-CFD model used in the study, exported in ONNX format, together with a complete inference example.

**Version:** v1.0  
**Framework:** ONNX (runtime inference)  

---

## Model Description

FuXi-CFD is a terrain-informed deep learning model designed to reconstruct fine-scale three-dimensional wind fields from coarse atmospheric inputs and high-resolution terrain information.

### Model Inputs

The model expects an `inputs.npz` file containing:

- `dem` — terrain elevation (300 × 300, float32, meters)
- `roughness` — surface roughness length (300 × 300, float32, meters)
- `u_100m` — coarse zonal wind at 100 m (9 × 9, float32, m s⁻¹)
- `v_100m` — coarse meridional wind at 100 m (9 × 9, float32, m s⁻¹)

All variables must be provided in physical units (no normalization applied by the user).  
Normalization parameters used during training are included in `normalization/`.

### Model Outputs

The model produces a file `prediction.npz` containing:

- `u` — zonal wind component (27, 300, 300), m s⁻¹  
- `v` — meridional wind component (27, 300, 300), m s⁻¹  
- `w` — vertical wind component (27, 300, 300), m s⁻¹  
- `k` — turbulent kinetic energy (27, 300, 300), m² s⁻²  

The vertical levels correspond to the 27 non-uniform heights described in the associated dataset documentation.

---

## Quick Start (Inference Example)

```bash
cd inference_example
python scripts/infer.py \
  --model ../model/fuxicfd_model.onnx \
  --input data/inputs.npz \
  --output data/prediction.npz
```

Outputs are saved as `data/prediction.npz` with keys: `u, v, w, k`.

---

## Repository Structure

- `model/` — exported ONNX weights  
- `inference_example/` — complete preprocessing → inference → postprocessing pipeline  
  - `normalization/` — training-time normalization parameters  
  - `scripts/` — runnable inference scripts
  - `utils/` — helper functions

---

## License

CC BY-NC 4.0

---

## Citation

If you use this model, please cite:

Lin, C., et al. *Reconstructing fine-scale 3D wind fields with terrain-informed machine learning*, Nature Communications (2026).