Skip to main content

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.

PyPI version License: MIT

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.10.x
  • NumPy
  • kintera >= 2.6.9

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.10.x with C++ libraries
  • NetCDF C library
  • kintera >= 2.6.9

Build steps:

  1. Clone the repository:
git clone https://github.com/chengcli/snapy.git
cd snapy
  1. Install dependencies:
pip install numpy "kintera>=2.6.9" torch==2.10.0

Kintera 2.6.9 introduces the perturbation-pressure helper required by this branch. Until a compatible wheel is published, build and install tag v2.6.9 from source before building snapy, using the commands in FP32_PROGRESS.md. CI builds the pinned source commit; package releases still require a compatible published or preinstalled dependency.

  1. 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.

  1. Configure and build:
cmake -B build -DCMAKE_BUILD_TYPE=Release -DNETCDF=ON
cmake --build build --parallel 3
  1. 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.

Scheme choices are deck keys under dynamics:, read per block; every block of a run must make the same choice, which blocks built from one deck do:

key default what it does
flux-covariance true the x2/x3 face-flux covariance correction (#289, docs/derivations/289-covariance-x3-curved.md)
x1-mass-covariance false subtract the x1 rho-w covariance from the reconstructed cell velocity; needs at least 3 x1 cells per block

They replace the environment switches SNAP_FLUX_COVARIANCE and SNAP_X1_MASS_COVARIANCE, which are no longer read. Defaults are the same whether options come from a deck without the key or are built in code: EOS floors density-floor: 1.e-6, pressure-floor: 1.e-3, temperature-floor: 20.; a riemann-solver without type is hllc.

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

Metadata

Release files for snapy 2.13.27

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for snapy 2.13.27
File Actions
snapy-2.13.27-cp313-cp313-manylinux_2_27_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.27+ x86-64 Details for snapy-2.13.27-cp313-cp313-manylinux_2_27_x86_64.whl
snapy-2.13.27-cp313-cp313-macosx_15_0_arm64.whl CPython 3.13 CPython 3.13 macOS 15.0+ ARM64 Details for snapy-2.13.27-cp313-cp313-macosx_15_0_arm64.whl
snapy-2.13.27-cp312-cp312-manylinux_2_27_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.27+ x86-64 Details for snapy-2.13.27-cp312-cp312-manylinux_2_27_x86_64.whl
snapy-2.13.27-cp312-cp312-macosx_15_0_arm64.whl CPython 3.12 CPython 3.12 macOS 15.0+ ARM64 Details for snapy-2.13.27-cp312-cp312-macosx_15_0_arm64.whl
snapy-2.13.27-cp311-cp311-manylinux_2_27_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.27+ x86-64 Details for snapy-2.13.27-cp311-cp311-manylinux_2_27_x86_64.whl
snapy-2.13.27-cp311-cp311-macosx_15_0_arm64.whl CPython 3.11 CPython 3.11 macOS 15.0+ ARM64 Details for snapy-2.13.27-cp311-cp311-macosx_15_0_arm64.whl
snapy-2.13.27-cp310-cp310-manylinux_2_27_x86_64.whl CPython 3.10 CPython 3.10 Linux glibc 2.27+ x86-64 Details for snapy-2.13.27-cp310-cp310-manylinux_2_27_x86_64.whl
snapy-2.13.27-cp310-cp310-macosx_15_0_arm64.whl CPython 3.10 CPython 3.10 macOS 15.0+ ARM64 Details for snapy-2.13.27-cp310-cp310-macosx_15_0_arm64.whl

Total release size: 292.2 MB

Release files / snapy-2.13.27-cp313-cp313-manylinux_2_27_x86_64.whl

Download URL snapy-2.13.27-cp313-cp313-manylinux_2_27_x86_64.whl
Size 68.0 MB
Tags CPython 3.13 Linux glibc 2.27+ x86-64
SHA-256 checksum
How to use checksums
f2880103c2dfce148c32d233d9017268c0b827839062d735f46eb2d6cc01b7d3
BLAKE2b-256 checksum
How to use checksums
ce9feec119086e4441167130b539427f2f3ce072af01e6711e23cc57687ad4e2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / snapy-2.13.27-cp313-cp313-macosx_15_0_arm64.whl

Download URL snapy-2.13.27-cp313-cp313-macosx_15_0_arm64.whl
Size 5.2 MB
Tags CPython 3.13 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
b57488a22ce703c1a773481f4f6d20ca3f904c29897050b9e76132592c1ea8dc
BLAKE2b-256 checksum
How to use checksums
5148a091a839a08ebfd03c80631e90af8b2860509ab8914dee3d4ad701119da7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / snapy-2.13.27-cp312-cp312-manylinux_2_27_x86_64.whl

Download URL snapy-2.13.27-cp312-cp312-manylinux_2_27_x86_64.whl
Size 68.0 MB
Tags CPython 3.12 Linux glibc 2.27+ x86-64
SHA-256 checksum
How to use checksums
e524ea03e773ce54a465de78cf2c93ab4bc5dd30c64d887112938806b07da3ef
BLAKE2b-256 checksum
How to use checksums
91df4a5513a87ae27c598162813859c82dac2c491043d991f33b39d6eca2270c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / snapy-2.13.27-cp312-cp312-macosx_15_0_arm64.whl

Download URL snapy-2.13.27-cp312-cp312-macosx_15_0_arm64.whl
Size 5.2 MB
Tags CPython 3.12 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
baa35165b833f999b9abb5db41c27b86fa3fcbb0ed7b9005ffe0d03c4d517e73
BLAKE2b-256 checksum
How to use checksums
d9dcdbe97792df5a88190b7e66a88f70337d3d6ae9da191cd2a1e7f8ff6a1114
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / snapy-2.13.27-cp311-cp311-manylinux_2_27_x86_64.whl

Download URL snapy-2.13.27-cp311-cp311-manylinux_2_27_x86_64.whl
Size 67.8 MB
Tags CPython 3.11 Linux glibc 2.27+ x86-64
SHA-256 checksum
How to use checksums
eefad198b8be7df7393480e4fb5ca5f73e4ecbe3f0f3a9a980bc15abfdea833d
BLAKE2b-256 checksum
How to use checksums
4b8b416e012ae5891f9d55c4bb38e94dd221f78e2acd635bc12e671f6eb21576
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / snapy-2.13.27-cp311-cp311-macosx_15_0_arm64.whl

Download URL snapy-2.13.27-cp311-cp311-macosx_15_0_arm64.whl
Size 5.2 MB
Tags CPython 3.11 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
466c7aa564d40bd87074ddedcb4d675fcd601990350f5f46c189815def3a2509
BLAKE2b-256 checksum
How to use checksums
9192df5d31fb0699963172b418918e012a97aeba60fa251f79fcc312a757da7a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / snapy-2.13.27-cp310-cp310-manylinux_2_27_x86_64.whl

Download URL snapy-2.13.27-cp310-cp310-manylinux_2_27_x86_64.whl
Size 67.6 MB
Tags CPython 3.10 Linux glibc 2.27+ x86-64
SHA-256 checksum
How to use checksums
81274fec1291c38e743c30db74c0317b020fdab12979142717cefb8855ab6c3f
BLAKE2b-256 checksum
How to use checksums
567772905b9d4cf7ae942fef18572c544878987a0fd0805286d575b27a2d29d2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / snapy-2.13.27-cp310-cp310-macosx_15_0_arm64.whl

Download URL snapy-2.13.27-cp310-cp310-macosx_15_0_arm64.whl
Size 5.2 MB
Tags CPython 3.10 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
c7498dba825512a8c984a61588c5f927f041e265bb59cc78b3d7f0d523db0e78
BLAKE2b-256 checksum
How to use checksums
30469a6ad824e6734bf9cfc5f642c11aa81453d336740ec093194e083a0cd3c4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for snapy 2.13.27

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A 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.

Release history Release notifications | RSS feed

This release

2.13.27 This release

8 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page