PyFracVAL

A Python implementation of the FracVAL algorithm for generating 3D fractal-like aggregates with tunable properties (Df, kf) from mono- or polydisperse primary particles using Particle-Cluster and Cluster-Cluster Aggregation. Based on the work of Morán, J. et al. (2019).
Explore the docs »

· Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap & Known Issues
5. Contributing
6. License
7. Citation
8. Contact
9. Acknowledgments

About The Project

PyFracVAL is a Python implementation of the FracVAL algorithm [1] for generating realistic 3D structures of particle aggregates, often encountered in fields like aerosol science, combustion, materials science, and colloid physics.

This implementation is based on the improved tunable algorithm originally presented in Fortran by Morán et al. [1], which allows for precise control over the resulting aggregate's fractal dimension (Df) and prefactor (kf). This is crucial for studying how these structural parameters influence the physical and optical properties of aggregates.

Key features:

• Generates aggregates from lognormally distributed polydisperse or monodisperse primary particles.
• Uses a hierarchical approach: Particle-Cluster Aggregation (PCA) to form subclusters, followed by Cluster-Cluster Aggregation (CCA).
• Allows specification of target Df (1 < Df < 3) and kf.
• Includes overlap control during aggregation steps.
• Provides a command-line interface for easy generation and options for programmatic use.

The goal is to provide a robust and validated Python alternative to the original Fortran code for researchers needing to generate these complex structures.

[1] J. Morán, A. Fuentes, F. Liu, J. Yon, FracVAL: An improved tunable algorithm of cluster-cluster aggregation for generation of fractal structures formed by polydisperse primary particles, Computer Physics Communications 239 (2019) 225–237. https://doi.org/10.1016/j.cpc.2019.01.015

(back to top)

Built With

This project primarily relies on the Python scientific stack.

• 
• 
• 
• 
• 
• 
• 

Optional dependencies for plotting/visualization/dev:

• 
• 
• 
• 
• 

(back to top)

Getting Started

Follow these steps to set up pyfracval for use or development.

Prerequisites

• Python: Version 3.10 to 3.12 recommended (Numba does not yet support 3.13 as of early 2024). Check with python --version.
• Pip or UV: A Python package installer. Check with pip --version or uv --version. uv is recommended for faster environment management.
• (Optional) Git: Required for cloning the repository if installing from source.

Installation

1. From PyPI (Recommended): (Once published)

   pip install pyfracval
   # or using uv
   uv pip install pyfracval

2. From Source (for Development):

   a. Clone the repository:

   git clone https://github.com/aetherspritee/PyFracVAL.git
   cd PyFracVAL

   b. Create and activate a virtual environment (using UV is recommended):

   # Using UV (recommended)
   uv venv --python 3.12 # Specify compatible Python version
   source .venv/bin/activate # Linux/macOS
   # .\venv\Scripts\activate # Windows
   
   # Using venv (built-in)
   # python3.12 -m venv .venv # Specify compatible Python version
   # source .venv/bin/activate # Linux/macOS
   # .\venv\Scripts\activate # Windows

   c. Install in editable mode with development dependencies:

   # Using UV (recommended)
   uv sync -e .[dev,test,docs]
   
   # Using pip
   # pip install -e .[dev,test,docs]

   (Adjust optional dependencies [dev,test,docs] based on your pyproject.toml)

(back to top)

Usage

Use the command-line interface pyfracval to generate aggregates.

Generate a default aggregate (N=128, Df=2.0, kf=1.0, rp_g=100, rp_gstd=1.5):

pyfracval

Generate a specific aggregate (N=256, Df=1.8, kf=1.3, monodisperse):

pyfracval -n 256 --df 1.8 --kf 1.3 --rp-gstd 1.0

Generate 5 aggregates with plotting:

pyfracval -n 100 --df 1.7 --kf 1.1 --num-aggregates 5 -p

See all options:

pyfracval --help

For more detailed examples and programmatic usage, please refer to the Documentation

(back to top)

Roadmap & Known Issues

• Fix Known Issues: (Inherited from original FracVAL and implementation details)
  • Low fractal dimensions (e.g., Df < ~1.7) can fail during PCA, potentially due to geometric constraints in Gamma_pc calculation or sticking. (Mitigation: try slightly higher kf).
  • High fractal dimensions / prefactors (e.g., Df > ~2.1 or high kf) can fail during PCA, potentially due to Gamma_pc calculation instability or overlap impossibility. (Mitigation: try slightly lower kf or Df).
  • High fractal dimensions can be noticeably slow. (Inherited behavior).
• Allow different distribution functions for monomer radii (e.g., normal).
• Further parallelization exploration (beyond Numba JIT).
• Add option for user-defined PCA parameters (Df_pca, kf_pca) via CLI.
• Publish package to PyPI.
• Add more examples and potentially tutorials to documentation.
• Investigate remaining differences compared to original Fortran behavior for edge cases.

See the open issues for a full list of proposed features and known issues.

(back to top)

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/YourFeature)
3. Install development dependencies (see Installation)
4. Make your changes
5. Run tests (pytest) and linters/formatters (ruff check ., ruff format .)
6. Commit your Changes (git commit -m 'Add some YourFeature')
7. Push to the Branch (git push origin feature/YourFeature)
8. Open a Pull Request

(back to top)

Profiling

Use py-spy to profile the code:

uv run py-spy record --format speedscope -o profile.speedscope.json -- pyfracval -n 512 --df 1.6 --kf 1.1 --rp-gstd 1.2

Upload the resulting profile.speedscope.json file to speedscope and inspect the runtimes.

Top contributors:

License

Distributed under the GPL v3 License. See LICENSE file for more information.

(back to top)

Citation

If you use PyFracVAL in your research, please cite the original FracVAL paper:

@article{Moran2019FracVAL,
    author  = {J. Morán and A. Fuentes and F. Liu and J. Yon},
    title   = {{FracVAL: An improved tunable algorithm of cluster-cluster aggregation for generation of fractal structures formed by polydisperse primary particles}},
    journal = {Computer Physics Communications},
    year    = {2019},
    volume  = {239},
    pages   = {225--237},
    doi     = {10.1016/j.cpc.2019.01.015},
}

(Optional: Add citation for this specific Python implementation if appropriate)

(back to top)

Acknowledgments

• Based on the original FracVAL algorithm and Fortran code by Morán et al. (2019).
• Uses the algorithm concepts developed by Filippov et al. (2000).
• README template adapted from Best-README-Template.
• Python scientific libraries (NumPy, Numba, etc.).

(back to top)