PyAPD 0.2.0

A Python library for generating (optimal) anisotropic power diagrams

PyAPD

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

Installation

Install with pip:

pip install PyAPD

Requires PyTorch and KeOps; see setup.py for full dependencies.

Tutorials

• Core tutorial — apd_system API, 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, .ang export, .h5oina import, 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.

Publications

(1) CMS 2024:

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
  1. APD generation
     • Gathering data
     • Plotting the data for the 2D case and for the 3D case
  2. Finding optimal APDs
     • Gathering data
     • Plotting the data for the 3D multi-phase case
  3. EBSD data examples
     • Fitting to data and artificial sample generation
     • Pixel level comparison
  4. Additive manufacturing example

(2) Preprint:

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.

Citing this work

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},
}

Related projects

• DREAM.3D
• Kanapy
• Neper
• LPM: Laguerre-Polycrystalline-Microstructures
• SynthetMic
• SynthetMic-GUI