AmunPy
Copyright (C) 2018-2026 Grzegorz Kowal
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 (seeAmunXML.digest_policyin 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/srmhdonly). - 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/mhdonly), 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.