pyFracAggregate

A Python library for generating synthetic fractal aggregates — clusters of spherical primary particles with a tunable morphology, such as soot and other aerosols — unified across four classical generation algorithms behind one API, with built-in morphological analysis and export to common scientific formats.

Features

Four generation algorithms, one API — particle-cluster aggregation ('pca'), cluster-cluster aggregation ('cca'), FracVAL ('fracval'), and the Thouy & Jullien tunable CCA ('tdcca'), all selected with a single method= keyword.
Two placement strategies — FLAGE-style algebraic touching-point computation (default) or Monte Carlo random placement with tolerance relaxation.
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 numpy as np
import pyFracAggregate as pfa

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

summary = pfa.analyze(agg)   # Rg=13.274 nm, Df_estimated=1.714, R2=0.964
print(agg.current_size, summary['Df_estimated'])   # 200 1.714241520287105

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

Generation is stochastic and draws from NumPy's global legacy random state: call np.random.seed(...) immediately before pfa.generate(...) for reproducible aggregates. The single-realization Df_estimated scatters around the requested df; average over realizations for ensemble statements.

Methods

Keyword	Algorithm	Family	Polydispersity	Reference
`pca`	Particle-cluster aggregation	particle-cluster	approximate (mean radius)	Skorupski et al., 2014
`cca`	Cluster-cluster aggregation	cluster-cluster	approximate (number-weighted)	Filippov et al., 2000
`fracval`	FracVAL tunable CCA	cluster-cluster	native (mass-weighted)	Morán et al., 2019
`tdcca`	Thouy & Jullien tunable CCA	cluster-cluster	supported (mass-weighted Rg)	Thouy & Jullien, 1994

Each keyword links to the corresponding section of the background chapter on the documentation site, which derives each algorithm's principle, guarantees, and limits.

Documentation

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

Documentation

License

MIT

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyfracaggregate-0.3.0.tar.gz (384.1 kB view details)

Uploaded Sep 3, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

pyfracaggregate-0.3.0-py3-none-any.whl (33.8 kB view details)

Uploaded Sep 3, 2026 Python 3

File details

Details for the file pyfracaggregate-0.3.0.tar.gz.

File metadata

Download URL: pyfracaggregate-0.3.0.tar.gz
Upload date: Sep 3, 2026
Size: 384.1 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyfracaggregate-0.3.0.tar.gz
Algorithm	Hash digest
SHA256	`e6d23e46e3e4d8b9786d8172be314248786fd95a8d688966feb55a5d8fdee7df`
MD5	`470c669c68fa903fa7a62bba21dced94`
BLAKE2b-256	`20bd91550416c32e93745263559c1526c30303dd5ea8fede54b3da1601c2d187`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyfracaggregate-0.3.0.tar.gz:

Publisher: publish.yml on VANvonZHANG/pyFracAggregate

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pyfracaggregate-0.3.0.tar.gz
- Subject digest: e6d23e46e3e4d8b9786d8172be314248786fd95a8d688966feb55a5d8fdee7df
- Sigstore transparency entry: 2698979265
- Sigstore integration time: Sep 3, 2026
Source repository:
- Permalink: VANvonZHANG/pyFracAggregate@06c53d6bb9b087c9934d97971831a4c98fa10fed
- Branch / Tag: refs/tags/v0.3.0
- Owner: https://github.com/VANvonZHANG
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@06c53d6bb9b087c9934d97971831a4c98fa10fed
- Trigger Event: release