# 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
```

---

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

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

```python
# Access variables as NumPy arrays
dn = snapshot.dataset("density")
vx = snapshot.dataset("x-velocity")
bx = snapshot.dataset("x-magnetic 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](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, 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 <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).
