Skip to main content

AmunPy

PyPI version License: GPL v3 Field: Astrophysics Build Status

AmunPy is the official Python interface for handling snapshot datasets produced by the AMUN code. It provides robust, validated readers for AMUN XML and HDF5 snapshots and converts simulation output into uniform NumPy arrays with associated metadata.

Scope note. AmunPy is intentionally limited to snapshot I/O. It does not parse or manage time-series diagnostics, global integrals, mesh statistics, or other auxiliary outputs produced by AMUN. Such data are written by the code as self-describing plain-text files and are documented separately in the AMUN Code Wiki.


🚀 Installation

The package is available on PyPI (https://pypi.org/project/amunpy) and can be installed via pip:

pip install amunpy

AmunPy requires Python 3.10 or later. The codec and digest packages (zstandard, lz4, xxhash) are installed as dependencies.


Core API & Usage

AmunPy provides a unified high-level API while supporting multiple underlying data formats.

Loading Snapshots

The package includes specialized classes for native XML+binary and HDF5 formats:

  • AmunXML: Interface for the native format, supporting zstd, lz4, and lzma decompression and xxHash integrity verification (see AmunXML.digest_policy in docs/API.md).
  • AmunH5: Interface for HDF5-formatted snapshots.
from amunpy import AmunXML, AmunH5

# Load a native XML snapshot (the directory or its metadata.xml)
snapshot = AmunXML("./snapshot_dir")

# Load an HDF5 snapshot
snapshot = AmunH5("./snapshot.h5")

Data Retrieval

Use the dataset() method to retrieve physical fields. Variables are regridded from the AMR blocks to a uniform mesh over the requested region and refinement level.

# Access variables as NumPy arrays
dn = snapshot.dataset("density")
vx = snapshot.dataset("x-velocity")
bx = snapshot.dataset("x-magnetic field")
ex = snapshot.dataset("x-electric field")

Interpolation and AMR regridding

When assembling uniform-resolution datasets from AMR snapshots, AmunPy applies deterministic, AMR-aware interpolation rules. Interpolation is performed internally by the dataset() method and requires no external dependencies.

Available interpolation methods are:

  • "rebin" (conservative; default without ghost zones) Block-averaged restriction and nearest-neighbor prolongation. This method is strictly conservative and does not require ghost-cell information.

  • "tvd" (monotone linear) TVD piecewise-linear prolongation using slope limiters. This method uses ghost cells for stencil support and preserves monotonicity without introducing new extrema.

  • "quadratic" (conservative quadratic; default with ghost zones) Conservative quadratic prolongation: per axis and per coarse cell, the quadratic whose cell averages match the cell and its two neighbours is integrated over each fine sub-cell, so the fine values are cell averages whose mean equals the coarse value. This method is third order on smooth, well-resolved data and falls back to "tvd" where its guard fires; it never produces a fine value whose sign does not occur in the cell's three-cell stencil (non-negative data stay non-negative). It uses ghost cells for stencil support.

  • "monotone_cubic" (conservative, monotone cubic) Conservative cubic prolongation: per axis and per coarse cell, a cubic built from the five-cell stencil is integrated over each fine sub-cell, so the fine values are cell averages whose mean equals the coarse value. This method is fourth order on smooth, well-resolved data. Its fine values are monotone wherever the coarse data are monotone away from smooth extrema, and it never produces a fine value whose sign does not occur in the cell's three-cell stencil (non-negative data stay non-negative). It needs at least two ghost cells (nghosts >= 2).

All four methods conserve the coarse cell average. Only blocks coarser than the target level are prolonged with the chosen method; blocks at or finer than it are copied or restricted with "rebin".

By default (interpolation=None), dataset() uses "quadratic" when the snapshot has ghost zones (nghosts >= 1) and "rebin" otherwise. Earlier versions always defaulted to "rebin"; pass interpolation="rebin" to reproduce their output. The default matters only where blocks coarser than the target level are prolonged, so single-level snapshots and restricted blocks give the same result.

All interpolation methods are implemented using NumPy only and are designed for adaptive mesh refinement (AMR) workflows.


Detailed API Documentation

The full documentation of the public API, including:

  • dataset() parameters and resolution control
  • uniform-grid semantics and extent handling
  • dimensionality conventions (2D vs 3D)
  • variable catalog and availability rules (eqsys, eos)
  • digest verification and the exception hierarchy
  • notes on performance and correctness

is available in: docs/API.md.

This file defines the stable public interface of AmunPy and is the recommended reference for production use.


Supported Variables

AmunPy detects the stored variables and computes derived quantities from them. A dataset is listed in snapshot.variables only when the stored variables and the equation system (eqsys) and equation of state (eos) allow it:

  • Fluid: density, pressure (stored, or derived for isothermal snapshots), internal energy, temperature, total energy, and the Lorentz factor (srhd/srmhd only).
  • Vector fields: velocity, vorticity, magnetic field, current density, and electric field (stored, or derived for mhd/srmhd), each as a full vector, as Cartesian components, and as a magnitude.
  • Diagnostics: kinetic energy (hd/mhd only), magnetic energy and magnetic pressure (mhd/srmhd), the divergence of velocity and of the magnetic field, and the magnetic divergence potential.
  • Grid: the refinement level of each cell.

For srmhd, magnetic energy is the lab-frame electromagnetic energy density and magnetic pressure the comoving value b^2/2; for mhd both are B^2/2. Special-relativistic total energy excludes the rest-mass energy density, matching AMUN's conserved energy. For adiabatic mhd with a stored bpsi, total energy includes the divergence-cleaning term 1/2 psi^2, also as in AMUN. The full catalog, the conditions for each dataset and the formulas are in docs/API.md.


Authorship & License

  • Author/Maintainer: Grzegorz Kowal grzegorz@amuncode.org
  • License: Distributed under the GNU General Public License v3.0.

For more information on the simulation engine, visit amuncode.org.

Metadata

Release files for amunpy 1.2.0

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

Source distribution (sdist)

Source distribution for amunpy 1.2.0
File Size Uploaded Provenance Actions
amunpy-1.2.0.tar.gz 109.6 kB Without provenance Details for amunpy-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for amunpy 1.2.0
File Interpreter ABI Platform Actions
amunpy-1.2.0-py3-none-any.whl Python 3 none any Details for amunpy-1.2.0-py3-none-any.whl

Total release size: 173.1 kB

Release files / amunpy-1.2.0.tar.gz

Download URL amunpy-1.2.0.tar.gz
Size 109.6 kB
Tags Source
SHA-256 checksum
How to use checksums
1a63bef2ef669d3577dbbf874c244af52dd96c2b07abbe1ed3941c44860a8356
BLAKE2b-256 checksum
How to use checksums
58dc6b3e9f22b8565f4d4f34183f64c39af1e6748a3adf49acf48a1e37393101
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / amunpy-1.2.0-py3-none-any.whl

Download URL amunpy-1.2.0-py3-none-any.whl
Size 63.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
02d3b0d5b76d02306018ec4810cc1e03b1aa007b6545b228baa86d25540381af
BLAKE2b-256 checksum
How to use checksums
aebd88bc012ceb9c5500242c35e9442b34691279bce5c7529b5ebdb54d57ddbb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for amunpy 1.2.0

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.

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