PyAPD is a Python library for generating anisotropic power diagrams (APDs) and polynomial diagrams — GPU-accelerated generalisations of Voronoi diagrams applicable to any problem requiring optimal assignment of regions with prescribed volumes, shapes, and anisotropy. The main application is geometric modelling of polycrystalline microstructures, but the framework extends naturally to other domain decomposition and geometric modelling problems.
- Optimal APDs and polynomial diagrams in 2D and 3D
- Prescribed-volume region generation with fine control over shape and orientation
- Arbitrary domain support (non-rectangular EBSD scans, masked grids)
- EBSD data loading, fitting, and export (
.ang,.h5oina, MTEX validation) - GPU-accelerated via KeOps; CPU fallback supported
Install with pip:
pip install PyAPD
Requires PyTorch and KeOps; see setup.py for full dependencies.
-
Core tutorial —
apd_systemAPI, weight optimisation, Lloyd's algorithm, 2D/3D examples:
example_usage.ipynb
-
Arbitrary domains — non-rectangular pixel clouds, masked grids,
set_pixels/mask_pixels:
arbitrary_domains.ipynb -
EBSD interoperability — loading EBSD grain data, APD fitting,
.angexport,.h5oinaimport, MTEX validation:
ebsd_interoperability.ipynb
Google Colab: notebooks run on CPU by default. To enable GPU: Runtime > Change runtime type > T4 GPU (free) or A100 (subscription). Without a GPU you will see a KeOps warning but the library remains fully functional.
M. Buze, J. Feydy, S.M. Roper, K. Sedighiani, D.P. Bourne, Anisotropic power diagrams for polycrystal modelling: Efficient generation of curved grains via optimal transport, Computational Materials Science, 245, 2024. DOI · Link
Companion notebooks
The examples from the paper can be found in notebooks/paper_examples/, including all notebooks as run, generated data, and figures. Notebooks that load pre-computed data will not run out of the box in Google Colab — the relevant data files would need to be uploaded manually.
- Runtime tests
- APD generation
- Gathering data
- Plotting the data for the 2D case
and for the 3D case
- Gathering data
- Finding optimal APDs
- Gathering data
- Plotting the data for the 3D multi-phase case
- Gathering data
- EBSD data examples
- Fitting to data and artificial sample generation
- Pixel level comparison
- Fitting to data and artificial sample generation
- Additive manufacturing example
- APD generation
v0.2.0 accompanies a preprint on polynomial diagrams (generalisations of APDs):
D.P. Bourne, M. Buze, T. Gallouët, Q. Mérigot, Polynomial diagrams for microstructure modelling, arXiv:2605.20816 (2026). arXiv
The companion notebooks (EBSD benchmark on Tata Steel data, synthetic APD reconstruction) can be found in notebooks/paper_examples/pmd_paper/:
- Large EBSD benchmark
- Small EBSD benchmark
- Synthetic APD reconstruction
Results shown are pre-computed on an A100 GPU; result pkl files are not included in the repository.
If you use PyAPD for academic research, please cite the paper to which our library is tied:
@article{PyAPD,
title = {Anisotropic power diagrams for polycrystal modelling: Efficient generation of curved grains via optimal transport},
journal = {Computational Materials Science},
volume = {245},
pages = {113317},
year = {2024},
issn = {0927-0256},
doi = {https://doi.org/10.1016/j.commatsci.2024.113317},
url = {https://www.sciencedirect.com/science/article/pii/S092702562400538X},
author = {M. Buze and J. Feydy and S.M. Roper and K. Sedighiani and D.P. Bourne},
keywords = {Anisotropic power diagrams, Polycrystalline materials, Microstructure generation, Optimal transport},
}
If you use the polynomial diagram functionality (min_diagram_system) or the EBSD interoperability features introduced in v0.2.0, please also cite:
@misc{PyAPD_PMD,
author = {David P. Bourne and Maciej Buze and Thomas Gallouët and Quentin Mérigot},
title = {Polynomial diagrams for microstructure modelling},
year = {2026},
eprint = {2605.20816},
archivePrefix = {arXiv},
}