Metadata-Version: 2.1
Name: dustpy-gpu
Version: 1.0.9.2
Summary: Dust evolution in protoplanetary disks
Keywords: numerical,simulation,science,physics,astrophysics,astronomy
Author-Email: Rixin Li <rixin.li.astro@gmail.com>, Sebastian Stammler <sebastian.stammler@gmail.com>, Til Birnstiel <til.birnstiel@lmu.de>, León-Alexander Hühn <huehn@uni-heidelberg.de>
Maintainer-Email: Rixin Li <rixin.li.astro@gmail.com>
License: GPLv3
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Fortran
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Project-URL: Repository, https://github.com/astroboylrx/dustpy-gpu/
Project-URL: Documentation, https://github.com/astroboylrx/dustpy-gpu/
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: requests
Requires-Dist: simframe-gpu>=1.0.6.1
Description-Content-Type: text/markdown

# DustPy-GPU

`dustpy-gpu` is a GPU-enabled fork of [DustPy](https://github.com/stammler/dustpy), a Python package for simulating gas and dust evolution in protoplanetary disks.

Designed as a drop-in replacement, it retains the upstream `dustpy` import name and original API, so migrating existing scripts requires minimal changes (mainly backend selection, see below).

## Installation

To avoid package conflicts, please install this drop-in replacement in a fresh virtual environment:

```bash
python -m venv .venv && source .venv/bin/activate
python -m pip install --upgrade pip

# For GPU runs: Install CuPy matching your CUDA version (e.g., CUDA 13)
python -m pip install cupy-cuda13x

# Install dustpy-gpu (automatically installs the required simframe-gpu fork)
# Alternatively: python -m pip install dustpy-gpu
python -m pip install git+https://github.com/astroboylrx/dustpy-gpu.git
```

## Backends

Select your backend when initializing a simulation:

```python
import dustpy

sim_cpu = dustpy.Simulation(backend="numpy") # Default (preserves upstream behavior)
sim_gpu = dustpy.Simulation(backend="cupy")
sim_auto = dustpy.Simulation(backend="auto") # Uses CuPy if available, else NumPy
```

When using the `cupy` backend, remember to convert CuPy arrays back to NumPy with `cupy.asnumpy()` for plotting or analysis. For those new to CuPy, we recommend checking out the [Basics of CuPy](https://docs.cupy.dev/en/stable/user_guide/basic.html).

Multiple backends can be used together in a single script if run sequentially, but concurrent execution is not supported due to process-global bindings.


## Documentation

Most official tutorials from the [upstream DustPy documentation](https://stammler.github.io/dustpy/) have been adapted for the GPU backend. These examples, alongside the validation benchmarks, are available in [`gpu_examples`](https://github.com/astroboylrx/dustpy-gpu/tree/master/gpu_examples).

### Parity and benchmarks

Users should expect **numerical and scientific parity**, though not strictly identical arrays across long or repeated GPU runs.

* **NumPy Backend:** Reproduces upstream `DustPy` results bitwise.
* **CuPy Backend:** Agrees with NumPy to strict FP64 tolerances initially. Long-run differences remain quite small and non-accumulating. Official examples (ice lines, planetary gaps, planetesimal formation, etc.) are visually indistinguishable.
* **GPU Determinism:** CuPy runs are not bitwise deterministic. The use of an iterative solver (sparse GMRES) — necessitated because CuPy's direct sparse solver API currently falls back to the CPU — combined with parallel GPU accumulation, can produce tiny run-to-run differences.

For detailed comparisons and performance results, see the [parity and benchmark notebook](https://github.com/astroboylrx/dustpy-gpu/blob/master/gpu_examples/backend_parity_and_benchmarks.ipynb).
