pyFracAggregate

A Python library for generating synthetic fractal aggregates — clusters of spherical primary particles with a tunable morphology, such as soot and other aerosols — behind one coordinate-system API: method × scaling × placement select among the classical generation algorithms (particle-cluster and cluster-cluster aggregation, count- or mass-weighted scaling, three contact-placement strategies), with built-in morphological analysis and export to common scientific formats.

Features

• Three orthogonal axes, one API — method ('pca' | 'cca') × scaling ('count' | 'mass') × placement ('solved' | 'sampled' | 'constructed'); every classical algorithm is a coordinate in this system.
• Three placement strategies — closed-form tangency solving (default), Monte Carlo sampling, or FracVAL-style contact construction.
• Reproducible generation — pass seed= for bit-identical reruns of any legal coordinate.
• Monodisperse and lognormal primary particles — Monodisperse and LognormalDistribution size distributions feed any generator.
• Built-in morphology analysis — radius of gyration, center of mass, pair correlation function, and fractal-dimension estimation with fit quality (pfa.analyze).
• Rich exports — YAML snapshot, VTK point cloud and VTM multiblock (via pyvista, ready for ParaView), off-screen static render, and rotation video.
• Fully typed library with tests — type hints throughout the source, and a pytest suite mirroring the package layout.

Installation

$ pip install pyFracAggregate

Requires Python ≥ 3.13. The 3D math dependency mathutils only has usable wheels for the 3.13 ABI on several platforms; older interpreters can fail at compile time. See the installation guide for details and platform notes.

To install from source for development:

$ pip install -e ".[dev]"

Quick start

import pyFracAggregate as pfa

agg = pfa.generate(200, 1.8, 1.9, method='pca', seed=0)  # N=200, Df=1.8, kf=1.9

summary = pfa.analyze(agg)              # MorphologyReport (sandbox default)
print(agg.current_size, summary.df_num_est, summary.df_mass_est)   # 200 1.8206754358246036 1.8206754358246036

pfa.export_yaml(agg, 'aggregate.yaml')
pfa.export_vtk(agg, 'aggregate.vtk')

Generation is stochastic; pass seed= for reproducible aggregates (generation never consults the global numpy.random state). The single-realization df_num_est (and df_mass_est) scatter around the requested df; average over realizations for ensemble statements.

The coordinate system

Every classical aggregate algorithm is a coordinate in a three-axis system (method, scaling, placement):

The two method families — pca (particle-cluster) and cca (cluster-cluster) — are introduced in the background chapter on the documentation site, which derives each algorithm's principle, guarantees, and limits. 'fracval' remains a deprecated alias for (cca, mass, constructed) until 1.0; 'tdcca' was removed in v0.4.

Documentation

Full documentation — background theory, user guide, tutorial, API reference, architecture notes, and contributing instructions — is hosted at:

Documentation

License

MIT