Metadata-Version: 2.4
Name: amunpy
Version: 1.2.0
Summary: A high-performance Python interface for the analysis of AMUN code simulations
Author-email: Grzegorz Kowal <grzegorz@amuncode.org>
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://gitlab.com/gkowal/amunpy
Project-URL: Bug Tracker, https://gitlab.com/gkowal/amunpy/-/issues
Project-URL: Main Code, https://gitlab.com/gkowal/amun-code
Project-URL: Documentation, https://amuncode.org/
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: h5py
Requires-Dist: xxhash
Requires-Dist: lz4
Requires-Dist: zstandard
Dynamic: license-file

# AmunPy

## Copyright (C) 2018-2026 Grzegorz Kowal

[![PyPI version](https://img.shields.io/pypi/v/amunpy.svg)](https://pypi.org/project/amunpy/)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Field: Astrophysics](https://img.shields.io/badge/field-astrophysics-blueviolet.svg)](https://en.wikipedia.org/wiki/Astrophysics)
[![Build Status](https://drone.amuncode.org/api/badges/gkowal/amunpy/status.svg)](https://drone.amuncode.org/gkowal/amunpy)

**AmunPy** is the official Python interface for handling *snapshot
datasets* produced by the [**AMUN code**](https://amuncode.org). 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](https://pypi.org/project/amunpy)) and
can be installed via `pip`:

```bash
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](docs/API.md#digest-verification-amunxml)).
* **`AmunH5`**: Interface for HDF5-formatted snapshots.

```python
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.

```python
# 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](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](docs/API.md#dataset-availability-and-physical-models).

---

## 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](https://amuncode.org).
