amunpy 1.0.1

A high-performance Python interface for the analysis of AMUN code simulations

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

---

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.
• AmunH5: Interface for HDF5-formatted snapshots.

from amunpy import AmunXML, AmunH5

# Load a native XML snapshot
snapshot = AmunXML("./snapshot_dir")

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

Data Retrieval

Use the dataset() method to retrieve physical fields. By default, variables are regridded to a uniform mesh, but they can also be returned as raw AMR blocks.

# 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) 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.

• "pchip" (monotone cubic) Monotonicity-preserving cubic (PCHIP-style) prolongation based on Hermite interpolation with slope limiting. This method provides smooth, high-quality prolongation while avoiding overshoots on monotone data.

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)
• 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 available data and automatically computes derived diagnostics:

• Fluid Dynamics: Density (linear/log), Pressure, Internal Energy, Temperature, and Lorentz factor.
• Vector Fields: Velocity, Magnetic Field, Electric Field, Current Density, and Vorticity (available as full vectors or individual Cartesian components).
• Diagnostics: Kinetic/Magnetic Energy, Magnetic Pressure, and Divergence.
• Grid Metadata: Refinement levels and coordinate arrays.

---

Authorship & License

• Author/Maintainer: Grzegorz Kowal [e-mail]
• License: Distributed under the GNU General Public License v3.0.

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