Installation

pyFracAggregate is a library (no CLI): after installation you use it from Python with import pyFracAggregate as pfa.

Requirements

pyFracAggregate requires Python 3.13 or newer.

Note

The Python ≥ 3.13 floor is not stylistic — it comes from the mathutils dependency used for 3D vector/quaternion math. Its C extension targets the 3.13 ABI, and on several platforms no usable wheel exists for older interpreters, so older Pythons fail at install time with compilation errors. If you see such errors, switch to Python 3.13+ rather than fighting the build. The core runtime dependencies (mathutils, NumPy, SciPy, pyvista, PyYAML, imageio) are installed automatically.

Install from PyPI

$ pip install pyFracAggregate

Optional extras:

Extra	Installs	Needed for
`[plot]`	matplotlib	plotting helpers such as `plot_pair_correlation` and `plot_sandbox`
`[dev]`	pytest, ruff, mypy	running the test suite and linters
`[docs]`	Sphinx, MyST, RTD theme	building this documentation

$ pip install "pyFracAggregate[plot]"

Install from source

For development (editable install with all tools):

$ git clone https://github.com/vanvonzhang/pyFracAggregate.git
$ cd pyFracAggregate
$ pip install -e ".[dev,plot]"

Building `mathutils` from source

Depending on your platform and Python build, pip may need to compile mathutils from source (this also happens inside virtual environments where no matching wheel is published). That requires a working C/C++ toolchain and Eigen headers:

$ sudo apt install build-essential libeigen3-dev   # Debian/Ubuntu

On macOS, xcode-select --install plus a Homebrew Eigen (brew install eigen) covers the same need; on other systems install the equivalent gcc/clang and eigen3 packages.

Verify the installation

A 16-particle aggregate generates in well under a second, so this is a complete smoke test:

>>> import pyFracAggregate as pfa
>>> agg = pfa.generate(n_particles=16, df=1.8, kf=1.9, method="pca")
>>> agg.current_size
16

If this prints 16, generation, the placement layer, and the core data structure are all working. Continue with Generating aggregates.