snapy 2.9.0

Compressible Finite Volume Solver for Atmospheric Dynamics, Chemistry and Thermodynamics

Snapy

Compressible Finite Volume Solver for Atmospheric Dynamics, Chemistry and Thermodynamics

Snapy is the dynamic core for simulating atmospheric and planetary dynamics using PyTorch tensors and GPU acceleration.

Features

• GPU-Accelerated: Built on PyTorch for efficient GPU computation
• Flexible Interfaces: Both Python and C++ APIs available
• Compressible Flow: Finite volume solver for atmospheric dynamics
• Multi-platform: Support for Linux and macOS
• NetCDF Output: Standard output format for scientific data

Installation

Quick Install (Python Interface)

The easiest way to get started is to install via pip:

pip install snapy

This will install the Python interface with pre-built binaries for Python 3.9-3.13 on Linux (x86_64) and macOS (ARM64).

Parallel run

pd-run 6 ./test_exchange.release

list listening port

lsof -i:29500

kill listening port

pkill -9 XXXXX

Requirements:

• Python 3.9 or higher
• PyTorch 2.7.x
• NumPy
• kintera >= 1.1.5

Build from Source (Advanced)

Building from source is recommended only for advanced users who need to:

• Modify the C++ core
• Use custom PyTorch versions
• Access the C++ interface directly
• Develop new features

Prerequisites:

• CMake 3.20+
• C++17 compatible compiler
• Autoconf, Automake, Libtool, and pkg-config on Linux (for fetched UCX)
• PyTorch 2.7.x with C++ libraries
• NetCDF C library
• kintera >= 1.1.5

Build steps:

1. Clone the repository:

git clone https://github.com/chengcli/snapy.git
cd snapy

2. Install dependencies:

pip install numpy kintera torch==2.7.1

3. Install NetCDF:
   • Linux (Ubuntu/Debian):

     sudo apt-get install libnetcdf-dev
     

   • macOS:

     brew install netcdf
     

UCX support is provided by the Python package commux. Install snapy's Python dependencies in the active environment before configuring; use -DUCX=OFF only when building a Gloo-only configuration.

4. Configure and build:

cmake -B build -DCMAKE_BUILD_TYPE=Release -DNETCDF=ON
cmake --build build --parallel 3

5. Install the Python package:

pip install .

Examples

The examples/ directory contains several working examples:

Python Examples:

• shock.py - Sod shock tube with internal boundary
• straka.py - Straka cold bubble convection test
• robert.py - Robert warm bubble convection test

C++ Examples:

• shock.cpp - Sod shock tube (C++)
• straka.cpp - Straka cold bubble (C++)

Run a Python example:

cd examples
python shock.py

Run a C++ example (after building):

cd build/examples
./shock

See examples/README for detailed documentation on the code structure and available examples.

Configuration

Simulations are configured using YAML files that specify:

• Grid dimensions and domain size
• Time integration settings (RK stages, CFL number)
• Boundary conditions
• Output settings (frequency, variables, format)
• Equation of state and thermodynamics

Example configuration files (.yaml) are provided alongside the examples.

Development

Testing

Run tests after building:

cd build/tests
ctest --output-on-failure

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contact

• Author: Cheng Li
• Email: [e-mail]
• GitHub: https://github.com/chengcli/snapy