pyFracAggregate 0.2.0__tar.gz → 0.3.0__tar.gz

{pyfracaggregate-0.2.0 → pyfracaggregate-0.3.0}/.gitignore

@@ -168,3 +168,4 @@ debug_pca.py
 # Output data and artifacts
 output/
 benchmarks/results/
+.superpowers/

{pyfracaggregate-0.2.0 → pyfracaggregate-0.3.0}/CLAUDE.md

@@ -30,7 +30,7 @@ No CLI entry point exists — the package is a library used via `import pyFracAg
   - `'pca'` → `PCAGenerator` — particle-cluster aggregation
   - `'cca'` → `CCAGenerator` — cluster-cluster aggregation
   - `'fracval'` → `FracVALGenerator` — FracVAL algorithm
-  - `'tdcca'` → `ThouyJullienGenerator` — Thouy & Jullien (2004) algorithm
+  - `'tdcca'` → `ThouyJullienGenerator` — Thouy & Jullien (1994) algorithm
 - All generators share the same constructor signature from `BaseGenerator`.
 
 #### Placement Strategy Layer (`src/pyFracAggregate/generators/placement/`)

pyfracaggregate-0.3.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: pyFracAggregate
+Version: 0.3.0
+Summary: 通用分形团簇生成框架 (General Fractal Aggregate Generation Framework)
+Project-URL: Homepage, https://github.com/vanvonzhang/pyFracAggregate
+Project-URL: Documentation, https://vanvonzhang.github.io/pyFracAggregate/
+Project-URL: Repository, https://github.com/vanvonzhang/pyFracAggregate
+Project-URL: Issues, https://github.com/vanvonzhang/pyFracAggregate/issues
+Author-email: Fan Zhang <vanvonzhang@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: DLCA,aerosol,cluster-cluster aggregation,fractal aggregate,fractal dimension,nanoparticles,soot
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.13
+Requires-Dist: imageio[ffmpeg]>=2.9.0
+Requires-Dist: mathutils>=3.0.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: pyvista
+Requires-Dist: pyyaml
+Requires-Dist: scipy>=1.7.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: myst-parser>=2.0; extra == 'docs'
+Requires-Dist: sphinx-copybutton>=0.5.0; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'docs'
+Requires-Dist: sphinx>=7.0; extra == 'docs'
+Requires-Dist: sphinxcontrib-mermaid>=1.0; extra == 'docs'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.5.0; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# pyFracAggregate
+
+[![CI](https://github.com/vanvonzhang/pyFracAggregate/actions/workflows/test.yml/badge.svg)](https://github.com/vanvonzhang/pyFracAggregate/actions/workflows/test.yml)
+[![PyPI version](https://img.shields.io/pypi/v/pyFracAggregate)](https://pypi.org/project/pyFracAggregate/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyFracAggregate)](https://pypi.org/project/pyFracAggregate/)
+[![Docs](https://img.shields.io/badge/docs-online-blue)](https://vanvonzhang.github.io/pyFracAggregate/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+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
+
+```console
+$ 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](https://vanvonzhang.github.io/pyFracAggregate/user-guide/installation.html)
+> for details and platform notes.
+
+To install from source for development:
+
+```console
+$ pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+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`](https://vanvonzhang.github.io/pyFracAggregate/background/index.html#pca-particle-cluster-aggregation) | Particle-cluster aggregation | particle-cluster | approximate (mean radius) | Skorupski et al., 2014 |
+| [`cca`](https://vanvonzhang.github.io/pyFracAggregate/background/index.html#cca-cluster-cluster-aggregation) | Cluster-cluster aggregation | cluster-cluster | approximate (number-weighted) | Filippov et al., 2000 |
+| [`fracval`](https://vanvonzhang.github.io/pyFracAggregate/background/index.html#fracval-tunable-cca-for-polydisperse-primaries) | FracVAL tunable CCA | cluster-cluster | native (mass-weighted) | Morán et al., 2019 |
+| [`tdcca`](https://vanvonzhang.github.io/pyFracAggregate/background/index.html#tdcca-thouy-jullien-tunable-cca) | Thouy & Jullien tunable CCA | cluster-cluster | supported (mass-weighted Rg) | Thouy & Jullien, 1994 |
+
+Each keyword links to the corresponding section of the
+[background chapter](https://vanvonzhang.github.io/pyFracAggregate/background/index.html)
+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](https://vanvonzhang.github.io/pyFracAggregate/)
+
+## License
+
+[MIT](LICENSE)

pyfracaggregate-0.3.0/README.md

@@ -0,0 +1,95 @@
+# pyFracAggregate
+
+[![CI](https://github.com/vanvonzhang/pyFracAggregate/actions/workflows/test.yml/badge.svg)](https://github.com/vanvonzhang/pyFracAggregate/actions/workflows/test.yml)
+[![PyPI version](https://img.shields.io/pypi/v/pyFracAggregate)](https://pypi.org/project/pyFracAggregate/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyFracAggregate)](https://pypi.org/project/pyFracAggregate/)
+[![Docs](https://img.shields.io/badge/docs-online-blue)](https://vanvonzhang.github.io/pyFracAggregate/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+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
+
+```console
+$ 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](https://vanvonzhang.github.io/pyFracAggregate/user-guide/installation.html)
+> for details and platform notes.
+
+To install from source for development:
+
+```console
+$ pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+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`](https://vanvonzhang.github.io/pyFracAggregate/background/index.html#pca-particle-cluster-aggregation) | Particle-cluster aggregation | particle-cluster | approximate (mean radius) | Skorupski et al., 2014 |
+| [`cca`](https://vanvonzhang.github.io/pyFracAggregate/background/index.html#cca-cluster-cluster-aggregation) | Cluster-cluster aggregation | cluster-cluster | approximate (number-weighted) | Filippov et al., 2000 |
+| [`fracval`](https://vanvonzhang.github.io/pyFracAggregate/background/index.html#fracval-tunable-cca-for-polydisperse-primaries) | FracVAL tunable CCA | cluster-cluster | native (mass-weighted) | Morán et al., 2019 |
+| [`tdcca`](https://vanvonzhang.github.io/pyFracAggregate/background/index.html#tdcca-thouy-jullien-tunable-cca) | Thouy & Jullien tunable CCA | cluster-cluster | supported (mass-weighted Rg) | Thouy & Jullien, 1994 |
+
+Each keyword links to the corresponding section of the
+[background chapter](https://vanvonzhang.github.io/pyFracAggregate/background/index.html)
+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](https://vanvonzhang.github.io/pyFracAggregate/)
+
+## License
+
+[MIT](LICENSE)

pyfracaggregate-0.3.0/docs/api-reference/index.md

@@ -0,0 +1,116 @@
+# API Reference
+
+Complete reference for the 21 public symbols exported by `pyFracAggregate`
+(the package's `__all__`), grouped by layer: the top-level facade, the core
+data structures, the four generation algorithms, the analysis functions, the
+I/O exporters, and the placement strategies.
+
+## Top-level API
+
+The facade functions cover the common workflow: build an aggregate with
+`generate()` (which dispatches to one of the four generation methods), then
+summarize its morphology with `analyze()`.
+
+```{eval-rst}
+.. autofunction:: pyFracAggregate.generate
+
+.. autofunction:: pyFracAggregate.analyze
+```
+
+## Core
+
+`Aggregate` is the central data structure every other layer produces or
+consumes: a pre-allocated `(max_particles, 5)` NumPy array of
+`[x, y, z, radius, mass]` rows whose `positions`, `radii`, and `masses`
+properties are zero-copy views. The two distribution classes describe
+primary-particle sizes and are passed to generators via the `particle_dist`
+argument.
+
+```{eval-rst}
+.. autoclass:: pyFracAggregate.core.aggregate.Aggregate
+   :members:
+
+.. autoclass:: pyFracAggregate.core.distributions.Monodisperse
+   :members:
+
+.. autoclass:: pyFracAggregate.core.distributions.LognormalDistribution
+   :members:
+```
+
+## Generators
+
+Four algorithms share the `BaseGenerator` constructor contract
+`(n_particles, df, kf, particle_dist, overlap_tolerance, placement)` and each
+returns an `Aggregate` from its `generate()` method. Users normally reach them
+through `generate(method=...)`; the classes are public for direct use and
+subclassing.
+
+```{eval-rst}
+.. autoclass:: pyFracAggregate.generators.pca.PCAGenerator
+   :members:
+
+.. autoclass:: pyFracAggregate.generators.cca.CCAGenerator
+   :members:
+
+.. autoclass:: pyFracAggregate.generators.fracval.FracVALGenerator
+   :members:
+
+.. autoclass:: pyFracAggregate.generators.tdcca.ThouyJullienGenerator
+   :members:
+```
+
+## Analysis
+
+Morphological descriptors computed from an `Aggregate`: global quantities
+(radius of gyration, center of mass) and the two-point pair correlation
+function `C(r)`, from which the fractal dimension is estimated by log-log
+regression. `analyze()` bundles the main ones into a summary dict, and
+`plot_pair_correlation()` visualizes the fit (requires matplotlib).
+
+```{eval-rst}
+.. autofunction:: pyFracAggregate.analysis.morphology.radius_of_gyration
+
+.. autofunction:: pyFracAggregate.analysis.morphology.center_of_mass
+
+.. autofunction:: pyFracAggregate.analysis.correlation.pair_correlation_function
+
+.. autofunction:: pyFracAggregate.analysis.correlation.estimate_fractal_dimension
+
+.. autofunction:: pyFracAggregate.analysis.correlation.plot_pair_correlation
+```
+
+## I/O
+
+Export an `Aggregate` for downstream use: a YAML snapshot bundling the particle
+data with generation parameters and analysis results, VTK/VTM files built with
+pyvista for ParaView and other tools, and off-screen rendered PNG images or
+MP4 rotation videos. The render and video exporters require a working pyvista
+3D backend (see the user guide for headless-environment notes).
+
+```{eval-rst}
+.. autofunction:: pyFracAggregate.io.data.export_yaml
+
+.. autofunction:: pyFracAggregate.io.visualization.export_render
+
+.. autofunction:: pyFracAggregate.io.visualization.export_rotation_video
+
+.. autofunction:: pyFracAggregate.io.vtk.export_vtm
+
+.. autofunction:: pyFracAggregate.io.vtk.export_vtk
+```
+
+## Placement
+
+Placement strategies decide where a new particle or cluster touches the
+existing structure while respecting the overlap tolerance; every generator
+selects one via `placement=`. Both classes implement the same two entry
+points: `place_particle()` for particle-cluster stages and `merge_clusters()`
+for cluster-cluster stages.
+
+```{eval-rst}
+.. autoclass:: pyFracAggregate.generators.placement.algebraic.AlgebraicPlacement
+   :members:
+
+.. autoclass:: pyFracAggregate.generators.placement.random_.RandomPlacement
+   :members:
+```

pyfracaggregate-0.3.0/docs/architecture/index.md

@@ -0,0 +1,205 @@
+# Architecture
+
+pyFracAggregate is a four-layer library: a **core** data structure
+(`Aggregate`, primary-particle distributions), a **generators** layer holding
+the four aggregation algorithms and their shared placement sublayer, an
+**analysis** layer computing morphological descriptors, and an **io** layer
+exporting aggregates. A thin top-level facade (`pfa.generate` /
+`pfa.analyze`) ties the layers together, and a factory function dispatches
+generation requests to one of the four algorithm classes.
+
+```{mermaid}
+flowchart TB
+    user(["user code"])
+
+    facade["top-level facade<br/>generate() / analyze()"]
+    factory["generators/factory.py<br/>get_generator(method, ...)"]
+
+    subgraph GENLAYER ["generators/"]
+        BASE["BaseGenerator (ABC)"]
+        PCA["PCAGenerator"]
+        CCA["CCAGenerator"]
+        FRACVAL["FracVALGenerator"]
+        TJ["ThouyJullienGenerator"]
+        subgraph PLACE ["generators/placement/"]
+            PABC["PlacementStrategy (ABC)"]
+            ALG["AlgebraicPlacement<br/>(FLAGE, default)"]
+            RND["RandomPlacement<br/>(Monte Carlo)"]
+            MC["_helpers.py<br/>shared Monte Carlo"]
+        end
+    end
+
+    subgraph CORELAYER ["core/"]
+        AGG["Aggregate<br/>pre-allocated (max_particles, 5)<br/>[x, y, z, radius, mass]"]
+        DIST["ParticleDistribution<br/>Monodisperse / LognormalDistribution"]
+    end
+
+    subgraph ANALYSIS ["analysis/"]
+        MORPH["morphology.py<br/>radius_of_gyration / center_of_mass"]
+        CORR["correlation.py<br/>pair correlation / Df estimation"]
+    end
+
+    subgraph IOLAYER ["io/"]
+        YAMLIO["data.py<br/>export_yaml"]
+        VTKIO["vtk.py<br/>export_vtk / export_vtm"]
+        VISIO["visualization.py<br/>export_render / export_rotation_video"]
+    end
+
+    user --> facade
+    facade -->|"'method' keyword"| factory
+    factory --> PCA
+    factory --> CCA
+    factory --> FRACVAL
+    factory --> TJ
+
+    PCA & CCA & FRACVAL & TJ -.->|"subclass"| BASE
+    DIST -->|"sample() radii"| BASE
+    PCA -.->|"place_particle()"| PABC
+    CCA -.->|"merge_clusters()"| PABC
+    PABC --> ALG
+    PABC --> RND
+    ALG --> MC
+    RND --> MC
+
+    PCA & CCA & FRACVAL & TJ -->|"generate() returns"| AGG
+
+    AGG --> MORPH
+    AGG --> CORR
+    facade -.->|"analyze()"| MORPH
+    facade -.->|"analyze()"| CORR
+
+    AGG --> YAMLIO
+    AGG --> VTKIO
+    AGG --> VISIO
+```
+
+Only `pca` and `cca` route through the placement sublayer; `fracval` and
+`tdcca` embed their own contact logic (see below).
+
+## The `Aggregate` data structure
+
+Every layer produces or consumes one central type,
+[`Aggregate`](/api-reference/index.md#core). It stores all particle data in a
+**single pre-allocated NumPy array** of shape `(max_particles, 5)`, one row
+per particle holding `[x, y, z, radius, mass]`:
+
+- **Why pre-allocation.** The array is allocated once, contiguously, at
+  construction. Growing the cluster is a row write plus a counter increment
+  (`add_particle` is O(1)); there are no per-particle Python objects and no
+  list reallocations or copies during generation. Data locality keeps the
+  tight numeric loops in the generators and analysis fast.
+- **Zero-copy views.** The properties `positions` (`(N, 3)`), `radii`
+  (`(N,)`), and `masses` (`(N,)`) return NumPy *views* slicing that one
+  backing array, not copies — mutating them mutates the aggregate.
+  `to_numpy()` returns a copy of the valid `(N, 5)` block when ownership of
+  the data must leave the aggregate.
+- **`.current_size` semantics.** The backing array is over-provisioned to
+  `max_particles` rows; `.current_size` counts how many are valid. The views
+  always expose exactly the valid prefix, so `.current_size` is "the N of
+  the cluster" (the analysis helper `pfa.analyze` returns it as `"N"`). The
+  capacity is readable as `.max_size`.
+- **Units.** `length_unit`, `mass_unit`, and `density` travel with the
+  aggregate (set by the generator; defaults `'nm'`, `'g'`, `1.0`) so exports
+  and analysis can label quantities.
+
+Primary-particle sizes are supplied by a `ParticleDistribution` —
+`Monodisperse(radius)` or `LognormalDistribution(mean, std)` — whose
+`sample(n)` the generators call to draw radii.
+
+## The generator contract
+
+All four algorithms implement the abstract
+[`BaseGenerator`](/api-reference/index.md#generators) with a single
+constructor signature:
+
+```python
+BaseGenerator(
+    n_particles,        # target number of primary particles
+    df, kf,             # fractal dimension and prefactor
+    particle_dist,      # ParticleDistribution for primary radii
+    overlap_tolerance=0.0,
+    placement='algebraic',
+    # plus length_unit / mass_unit / density
+)
+```
+
+`generate()` then returns a populated `Aggregate`. Because the contract is
+identical, the factory `get_generator(method, ...)` (in
+`generators/factory.py`) can dispatch on a string — `'pca'`, `'cca'`,
+`'fracval'`, `'tdcca'` — and that factory is exactly what the top-level
+`pfa.generate()` wraps. Keyword-only extras (`surface_beta`) are validated
+there and rejected for methods that do not support them.
+
+`pfa.analyze()` is the facade's read-side: it bundles
+`radius_of_gyration`, `center_of_mass`, and the pair-correlation fit into
+one summary dict (`Rg`, `CoM`, `N`, `Df_estimated`, `R2`).
+
+## The placement strategy layer
+
+The scaling law fixes *where* the center of each added particle or cluster
+must sit (distance `L` or `Γ` from the cluster center) but not *which*
+particles touch. Resolving that contact problem is delegated to a strategy
+object, selected by name:
+
+- [`PlacementStrategy`](/api-reference/index.md#placement) — the ABC. Its two
+  abstract methods mirror the two aggregation stages: `place_particle()`
+  (single particle onto a cluster, the PCA stage) and `merge_clusters()`
+  (two clusters onto a common `Γ`, the CCA stage).
+- `AlgebraicPlacement` (default) — FLAGE, Skorupski et al. (2014). The
+  analytical solver in `generators/optimizer_flage.py` intersects the target
+  sphere with a reference particle's contact sphere to get exact touching
+  points; candidates are overlap-filtered, with a Monte Carlo fallback.
+- `RandomPlacement` — Filippov et al. (2000). Pure Monte Carlo sampling on
+  the target sphere with gradual tolerance relaxation until a candidate is
+  accepted (typically several times slower).
+- `get_placement(name)` — the factory. `BaseGenerator.__init__` resolves the
+  `placement` string through it and stores the strategy instance, injecting
+  the generator's `overlap_tolerance` into it.
+
+Both implementations share their Monte Carlo machinery
+(`random_monte_carlo_place`, `random_monte_carlo_merge`) through
+`generators/placement/_helpers.py`, so the strategies differ only in their
+deterministic precomputation, not in their fallbacks.
+
+`FracVALGenerator` and `ThouyJullienGenerator` do **not** route through the
+placement layer: FracVAL's merge has its own deterministic contact search
+(sphere-sphere intersection with overlap-resolving rotations), and Thouy &
+Jullien selects among lattice-seeded orientations directly. The `placement`
+argument is accepted for constructor uniformity but ignored by both.
+
+## Analysis
+
+The analysis layer is a set of pure functions over an `Aggregate`:
+`morphology.py` provides `radius_of_gyration` (mass-weighted, including each
+sphere's intrinsic gyration, per Morán et al. 2019 Eq. (3)) and
+`center_of_mass`; `correlation.py` provides `pair_correlation_function`,
+`estimate_fractal_dimension` (log-log regression of `C(r)` over the fractal
+regime), and the matplotlib-based `plot_pair_correlation` for diagnosing the
+fit. No function mutates the aggregate.
+
+## I/O
+
+The io layer serializes an `Aggregate` for downstream use: `data.py` writes
+a YAML snapshot bundling particle data with generation parameters and
+analysis results; `vtk.py` builds the pyvista point cloud (`export_vtk`) and
+MultiBlock dataset (`export_vtm`) for ParaView; `visualization.py` performs
+off-screen pyvista rendering (`export_render`) and assembles MP4 rotation
+videos (`export_rotation_video`). Rendering exporters need a working 3D
+backend — see the [io guide](/user-guide/io.md) for headless-environment
+notes.
+
+## Tests
+
+The test suite mirrors the source layout:
+
+- `tests/test_core/` — `Aggregate`, distributions, 3D math helpers
+- `tests/test_generators/` — the four algorithms, factory, placement
+  strategies, FLAGE optimizer
+- `tests/test_analysis/` — morphology and correlation functions
+- `tests/test_io/` — YAML and visualization exports
+- `tests/test_density.py` — root-level density test
+- `tests/fixtures/` — shared fixture data (`surface_beta_snapshot.npy`)
+
+Slow performance tests carry the `benchmark` pytest marker and can be
+deselected with `-m "not benchmark"` (see
+[Contributing](/contributing.md#running-the-tests)).