Metadata-Version: 2.4
Name: pymhd
Version: 0.1.1
Summary: A Python package for post-processing MHD turbulence simulations
Project-URL: Homepage, https://github.com/PlasmaHua/PyMHD
Project-URL: Repository, https://github.com/PlasmaHua/PyMHD.git
Project-URL: Issues, https://github.com/PlasmaHua/PyMHD/issues
Author-email: "Yuyang Hua (华宇阳)" <yuyanghua@stu.pku.edu.cn>
License-Expression: MIT
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: h5py>=3.10
Requires-Dist: jax>=0.6
Requires-Dist: kdepy>=1.1
Requires-Dist: matplotlib>=3.10
Requires-Dist: numpy>=2.0
Requires-Dist: yt>=4.4
Description-Content-Type: text/markdown

# PyMHD

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20749062.svg)](https://doi.org/10.5281/zenodo.20749062)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/PlasmaHua/PyMHD/blob/main/LICENSE)


A Python package for post-processing magnetohydrodynamic (MHD) turbulence simulations.

## Features

- [x] High-fidelity ***a posteriori* estimation of numerical dissipation** in MHD turbulence simulations;
- [x] Computation and visualization of turbulent energy spectra;
- [x] Visualization of 2D slices of MHD variables;
- [x] Built-in support for simulations from the Athena family, including [Athena++](https://github.com/PrincetonUniversity/athena), [AthenaK](https://github.com/IAS-Astrophysics/athenak), and [AthenaPK](https://github.com/parthenon-hpc-lab/athenapk);
- [x] Support for **driven MHD turbulence** (e.g., Alfvénic turbulence and small-scale dynamos), driven hydrodynamic turbulence, and **MRI-driven turbulence** (from shearing-box simulations) with triply periodic boundary conditions;
- [ ] Support for adiabatic and isothermal equations of state (EoS); **TODO:** add support for incompressible EoS;
- [ ] **TODO:** Computation and visualization of correlation functions;
- [ ] **TODO:** Spectral energy transfer analysis following [Grete, Philipp, et al. Physics of Plasmas 24.9 (2017)](https://doi.org/10.1063/1.4990613).
- [ ] **TODO:** Support JAX acceleration on GPUs and multi-node CPUs (currently, certain algorithms support parallelism on single-node, multi-core CPUs).


## Quick Start

### Installation

Install **PyMHD** from [PyPI](https://pypi.org/) via:

```bash
pip install pymhd
```

This will automatically install PyMHD and its required dependencies, including:
- [NumPy](https://github.com/numpy/numpy) for core computation;
- [JAX](https://github.com/jax-ml/jax) for parallel acceleration on single-node, multi-core CPUs; therefore, [the CPU version of JAX](https://docs.jax.dev/en/latest/installation.html#pip-installation-cpu) is required;
- [yt](https://github.com/yt-project/yt) and [h5py](https://github.com/h5py/h5py) for extracting data from HDF5 output files, specifically Athena++ `.athdf` files, AthenaK `.bin` files, and AthenaPK `.phdf` files;
- [Matplotlib](https://github.com/matplotlib/matplotlib) for plotting functionality in the `pymhd.plot` modules;
- [KDEpy](https://github.com/tommyod/KDEpy) for plotting smoothed histograms of numerical dissipation data in the `pymhd.plot.nd` module.

### Built-in Examples

For a quick start, clone the source repository, for example:

```bash
git clone https://github.com/PlasmaHua/PyMHD.git
```

Then navigate to the `./examples` subdirectory using `cd PyMHD/examples`, where two AthenaK simulation examples are provided.

Under construction.

### Analyze Your Own Athena Simulations

PyMHD natively supports simulations from Athena++, AthenaK, and AthenaPK. Use the `pymhd.output2turbulence` function to extract output data and input-file metadata, then construct a PyMHD `Turbulence` object for further analysis.

## API Documentation

Under construction.

## Citation

If PyMHD contributes to your work in any way, please consider citing the package via:

```bibtex
@misc{Hua2026,
  doi = {10.5281/zenodo.20749062},
  url = {https://zenodo.org/doi/10.5281/zenodo.20749062},
  author = {Hua, Yuyang},
  title = {PyMHD: Python package for post-processing MHD turbulence simulations},
  publisher = {Zenodo},
  year = {2026},
  copyright = {MIT License}
}
```

If you specifically use the framework for numerical dissipation estimation, please cite our method paper via:

```bibtex

```