pyFracAggregate 0.1.0__tar.gz

pyfracaggregate-0.1.0/.gitignore

@@ -0,0 +1,169 @@
+# Claude Code
+.claude/worktrees/
+docs/superpowers/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+bin/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.pytest_cache/
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the Python version is
+#   usually managed by the user.
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#1181, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or even
+#   not install all dependencies needed on a specific platform.
+# Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+# poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+# pdm.lock
+
+# PEP 582; used by e.g. github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Project specific
+debug_cca.py
+debug_pca.py
+*.py.bak
+
+# Output data and artifacts
+output/

pyfracaggregate-0.1.0/CLAUDE.md

@@ -0,0 +1,58 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Development Commands
+
+```bash
+pip install -e ".[dev]"        # Editable install with dev tools (pytest, ruff, mypy)
+pip install -e ".[plot]"       # Include matplotlib for plotting
+pytest                        # Run all tests
+pytest tests/test_core/test_aggregate.py  # Run a single test file
+pytest -k "test_pca"          # Run tests matching a name pattern
+ruff check src/               # Lint source code
+mypy src/                     # Static type checking
+```
+
+No CLI entry point exists — the package is a library used via `import pyFracAggregate as pfa`.
+
+## Architecture
+
+**Four-layer design**: core → generators → analysis → io
+
+### Core (`src/pyFracAggregate/core/`)
+- **Aggregate**: Central data structure. Pre-allocated `(max_particles, 5)` NumPy array storing `[x, y, z, radius, mass]`. Properties `positions`, `radii`, `masses` return zero-copy views into the backing array.
+- **ParticleDistribution**: ABC with `Monodisperse(radius)` and `LognormalDistribution(mean, std)` implementations. Generators call `sample(n)` to get particle sizes.
+
+### Generators (`src/pyFracAggregate/generators/`)
+- **BaseGenerator**: ABC accepting `(n_particles, df, kf, particle_dist, overlap_tolerance, placement='algebraic')`. All generators produce an `Aggregate` via `generate()`.
+- **Factory**: `get_generator(method, ...)` dispatches to:
+  - `'pca'` → `PCAGenerator` — particle-cluster aggregation
+  - `'cca'` → `CCAGenerator` — cluster-cluster aggregation
+  - `'fracval'` → `FracVALGenerator` — FracVAL algorithm
+  - `'tdcca'` → `ThouyJullienGenerator` — Thouy & Jullien (2004) algorithm
+- All generators share the same constructor signature from `BaseGenerator`.
+
+#### Placement Strategy Layer (`src/pyFracAggregate/generators/placement/`)
+- **PlacementStrategy** ABC with `place_particle()` (PCA stage) and `merge_clusters()` (CCA stage).
+- **AlgebraicPlacement** (FLAGE, Skorupski et al., 2014): Algebraic touching-point computation with random Monte Carlo fallback. Default strategy.
+- **RandomPlacement** (Filippov et al., 2000): Pure random Monte Carlo sampling with tolerance relaxation.
+- **`get_placement(name)`** factory returns a `PlacementStrategy` by name (`'algebraic'` or `'random'`).
+- **`_helpers.py`**: Shared Monte Carlo helpers (`random_monte_carlo_place`, `random_monte_carlo_merge`) used by both strategies.
+
+### Analysis (`src/pyFracAggregate/analysis/`)
+- `morphology`: `radius_of_gyration()`, `center_of_mass()`
+- `correlation`: `pair_correlation_function()`, `estimate_fractal_dimension()`, `plot_pair_correlation()`
+
+### IO (`src/pyFracAggregate/io/`)
+- **data.py**: `export_yaml()` — full aggregate snapshot (data, generation params, analysis results)
+- **vtk.py**: `export_vtm()` (MultiBlock) and `export_vtk()` (point cloud) via pyvista
+
+### Top-level API (`__init__.py`)
+`pfa.generate(n_particles, df, kf, method, placement='algebraic')` and `pfa.analyze(aggregate)` are the primary entry points. `generate()` delegates to the factory. The `placement` parameter selects the placement strategy (`'algebraic'` or `'random'`). IO exports include `export_yaml()` (full snapshot), `export_vtk()` (point cloud), and `export_vtm()` (MultiBlock).
+
+## Key Conventions
+- Python 3.9+, type hints throughout
+- Physical units (`length_unit`, `mass_unit`, `density`) are part of `Aggregate` and `BaseGenerator`
+- `mathutils` package used for 3D math (with scipy fallback)
+- Tests live in `tests/` mirroring the source layout (`test_core/`, `test_generators/`, `test_analysis/`, `test_io/`)

pyfracaggregate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Fan Zhang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyfracaggregate-0.1.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: pyFracAggregate
+Version: 0.1.0
+Summary: 通用分形团簇生成框架 (General Fractal Aggregate Generation Framework)
+Author-email: Fan Zhang <vanvonzhang@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.9
+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: plot
+Requires-Dist: imageio[ffmpeg]>=2.9.0; extra == 'plot'
+Requires-Dist: matplotlib>=3.5.0; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# pyFracAggregate
+
+通用分形团簇生成框架 (General Fractal Aggregate Generation Framework).

pyfracaggregate-0.1.0/README.md

@@ -0,0 +1,3 @@
+# pyFracAggregate
+
+通用分形团簇生成框架 (General Fractal Aggregate Generation Framework).