Metadata-Version: 2.4
Name: phipict
Version: 0.1.0
Summary: Differentiable multi-block PISO MHD solver for PyTorch
Author-email: Jannis Becktepe <jannis.becktepe@tu-dortmund.de>
License-Expression: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch==2.10.*
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pyamg>=4.0
Requires-Dist: matplotlib>=3.9
Requires-Dist: imageio
Requires-Dist: psutil
Provides-Extra: dev
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pybind11-stubgen; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: types-setuptools; extra == "dev"
Requires-Dist: types-psutil; extra == "dev"
Requires-Dist: scipy-stubs; extra == "dev"
Requires-Dist: pyvista>=0.43; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: requires-dist

<p align="center">
    <a href="https://raw.githubusercontent.com/upb-sciml/phiPICT/main/docs/source/_static/img/logo_lm.png">
        <img src="https://raw.githubusercontent.com/upb-sciml/phiPICT/main/docs/source/_static/img/logo_lm.png" alt="phiPICT Logo" width="40%"/>
    </a>
</p>

<div align="center">

![Python](https://img.shields.io/badge/Python-3.11%20%7C%203.12%20%7C%203.13-blue)
![PyTorch](https://img.shields.io/badge/PyTorch-2.10-EE4C2C?logo=pytorch&logoColor=white)
![CUDA](https://img.shields.io/badge/CUDA-12.8-%2376B900)
![License](https://img.shields.io/badge/License-Apache--2.0-orange)
[![Release](https://github.com/upb-sciml/phiPICT/actions/workflows/release.yml/badge.svg)](https://github.com/upb-sciml/phiPICT/actions/workflows/release.yml)

</div>

<h1 align="center">φ-PICT: Differentiable GPU-Accelerated Solver for Hydrodynamic &amp; Magnetohydrodynamic Flows</h1>

<table align="center">
  <tr>
    <th width="30%">Flow Past a Cylinder</th>
    <th width="20%">Rayleigh-Bénard Convection</th>
    <th width="28%">Airfoil</th>
    <th width="22%">Turbulent Channel Flow</th>
  </tr>
  <tr>
    <td align="center"><img src="https://raw.githubusercontent.com/upb-sciml/phiPICT/main/docs/source/_static/example_fields/cylinder.png" alt="Vortex structures in the wake of a cylinder"/></td>
    <td align="center"><img src="https://raw.githubusercontent.com/upb-sciml/phiPICT/main/docs/source/_static/example_fields/rbc.png" alt="Temperature in 3D Rayleigh-Bénard convection"/></td>
    <td align="center"><img src="https://raw.githubusercontent.com/upb-sciml/phiPICT/main/docs/source/_static/example_fields/airfoil.png" alt="Vortex structures behind an airfoil"/></td>
    <td align="center"><img src="https://raw.githubusercontent.com/upb-sciml/phiPICT/main/docs/source/_static/example_fields/tcf.png" alt="Vortex structures in turbulent channel flow"/></td>
  </tr>
  <tr>
    <th colspan="3">Fusion Reactor Blanket Cooling (MHD)</th>
    <th>MHD Rayleigh-Bénard Convection</th>
  </tr>
  <tr>
    <td align="center" colspan="3"><img src="https://raw.githubusercontent.com/upb-sciml/phiPICT/main/docs/source/_static/example_fields/blanket.png" alt="Temperature in a fusion reactor blanket cooling duct"/></td>
    <td align="center"><img src="https://raw.githubusercontent.com/upb-sciml/phiPICT/main/docs/source/_static/example_fields/rbc_medium.png" alt="Temperature in Rayleigh-Bénard magnetoconvection"/></td>
  </tr>
</table>

---

## Key Features

- **Differentiable Physics:** Fully end-to-end differentiable solver supporting Backpropagation Through Time (BPTT/APG), Short-Horizon Actor-Critic (SHAC) and more.
- **Massively Batched Execution:** Efficiently parallelize over 100 of independent fluid environments on a single GPU.
- **MHD & Standard Hydrodynamics:** Simulates both magnetohydrodynamic (MHD) flows and standard hydrodynamic fluid mechanics.
- **RL Framework Integration:** Seamlessly integrated into [FluidGym](https://github.com/upb-sciml/fluidgym) for plug-and-play benchmarking of control algorithms.

## Installation

phiPICT needs Linux, an NVIDIA GPU with a driver for CUDA 12.8 (≥ 570) and
Python 3.11–3.13.

### 📦 Installation from PyPI

```bash
pip install phipict
```

This also installs the matching PyTorch (2.10, built with CUDA 12.8), pyamg, and
the remaining runtime dependencies (NumPy, SciPy, matplotlib, imageio, psutil).
There is no need to install PyTorch first: the compiled extension only works with
the PyTorch version it was built against, so pip replaces any other version.
To use another PyTorch or CUDA version, build from source (see below).

Optional extras:

```bash
pip install "phipict[dev]"   # linters, type checking, and tests
pip install "phipict[docs]"  # Sphinx, to build the documentation
```

Reading VTK formats other than `.vts`/`.vtm` needs `pip install pyvista`.

### 🧱 Build from Source

Building from source compiles the CUDA kernels against the PyTorch installed in
your environment. Here is an example for Python 3.12 and CUDA 12.8.

1. Create a new conda environment and activate it:
```bash
conda create -n phipict python=3.12
conda activate phipict
```

2. Install the CUDA toolkit from conda-forge. This also installs a gcc/g++ that
   the chosen nvcc supports, so no separate compiler install is needed. The CUDA
   major version must match the one your PyTorch build uses (12 here):
```bash
conda install -c conda-forge pip cuda-toolkit cuda-version=12.8
conda env config vars set CUDA_HOME="$CONDA_PREFIX"
conda activate phipict  # re-activate so CUDA_HOME takes effect
```

3. Install PyTorch for the same CUDA version via pip. Any version ≥ 2.9 works;
   the extension is then bound to this version:
```bash
pip install "torch==2.10.*" --index-url https://download.pytorch.org/whl/cu128
pip install "setuptools>=77"  # the build uses the environment's setuptools
```

4. Clone the repository and enter the directory, then compile the custom CUDA
   kernels and install the package (this might take several minutes):
```bash
make install
```

For development, use `make install-dev` instead, which installs the package in
editable mode together with the development dependencies.

The documentation dependencies are installed via `pip install ".[docs]"`.

## Getting Started

See the [`examples`](examples) directory for example simulations.

## License

This repository is published under the Apache-2.0 license.
