Quick Start

This guide walks you through running your first NeuralPOM simulation and training a hybrid AI-physics model.

Prerequisites

• Python 3.10+
• CUDA-capable GPU (recommended; 8×A100 80GB for DDP training)
• PyTorch 2.0+

Installation

git clone https://github.com/ChiyodaMomo01/NeuralPOM.git
cd NeuralPOM
pip install -r requirements.txt

See the Installation page for detailed environment setup.

Run a Physics-Only Simulation

NeuralPOM ships with several pre-configured cases. To run a Double Gyre simulation with the explicit core:

# Explicit core — Double Gyre
python src/neuralpom/cases/explicit/double_gyre.py

# Implicit core — Double Gyre
python src/neuralpom/cases/implicit/double_gyre.py

Each case script initializes the core, sets up the Arakawa-C grid, applies forcing, and runs the time loop. Output fields include $u$, $v$, $T$, $S$, $\eta$, $u_a$, $v_a$, and turbulence quantities ($q^2$, $q^{2}l$, $K_M$, $K_H$).

Generate Training Data

Training data is generated by running the physics core to produce reference trajectories, then downsampling:

# Generate an ensemble of Double Gyre simulations
python scripts/data_generation/generate_double_gyre_ensemble.py

# Downsample reference data
python scripts/data_generation/downsample_reference.py

Data is stored in NPZ format. See Data Pipeline for details.

Train a Hybrid AI-Physics Model

Training is configured via JSON and launched with torchrun:

# Single-node multi-GPU DDP training
torchrun --nproc_per_node=8 \
  scripts/training/train_npom.py \
  --config configs/train_decoder_only.json

Key configuration parameters:

Parameter	Description
core_name	"explicit" or "implicit"
use_decoder	Enable CorrectorNet
supervision_mode	"pointwise", "multiscale_lowpass", or "horizon_decay"
batch_size	Per-GPU batch size
epochs	Number of training epochs

Run Inference

python scripts/inference/inference_npom.py --config configs/inference_default.json

The inference pipeline loads a trained CorrectorNet checkpoint, runs the hybrid model for a specified forecast period, and compares against reference solutions.

Next Steps

• Read about the dual-core architecture
• Understand the governing equations
• Learn about hybrid AI-physics training
• Browse available cases