PyAFV

Python code that implements the active-finite-Voronoi (AFV) model in 2D. The AFV framework was introduced and developed in, for example, Refs. [1–3].

Installation

PyAFV is available on PyPI and can be installed using pip:

pip install pyafv

The package supports Python ≥ 3.9 and < 3.15. To verify that the installation was successful and that the correct version is installed, run the following in Python:

import pyafv
print(pyafv.__version__)

If you only intend to use the package, skip the #Local development section and proceed directly to the #Usage section.

Local development

This project uses uv for Python package management – a single tool to replace pip (⚡️10-100x faster) and venv.

If you'd like to use your own Python, ensure the which python version meets the requirement (>=3.9) so uv doesn't automatically download a different interpreter; otherwise, I recommend letting uv manage everything, including the Python interpreter.

After cloning the repository, Linux/macOS users (Windows users: see below) can install PyAFV in "editable" mode and synchronize the dependencies with

uv sync

or use uv sync --no-dev if you only intend to run the core Python code without development dependencies (like pytest for running tests).

Notes:

• You can install additional packages as needed using uv add <package_name>.
• In some environments (like HPC clusters), global Python path can contaminate the project environment. You may need to add the PYTHONPATH="" prefix to all uv commands to isolate the project.
• The current version uses Cython to translate .pyx files into .cpp, (and therefore requires a working C/C++ compiler), though a fallback backend (based on early pure-Python release) is also implemented.
• For the old pure-Python implementation with no C/C++ compiled dependencies, see v0.1.0 (also on GitLab). Alternatively, remove setup.py in the root folder before running uv sync; for PyAFV v0.3.4 and later, the pure-Python backend can be selected by passing backend="python" when creating the simulator instance.

Windows MinGW GCC

• If you are using MinGW GCC (rather than MSVC) on Windows, add a setup.cfg at the repository root

  # setup.cfg
  [build_ext]
  compiler=mingw32

  It will then work in the same way.

Editing the Cython file

• If you modify the Cython source file pyafv/cell_geom.pyx, you must reinstall the package to ensure the changes take effect: uv sync --reinstall-package pyafv --inexact (the --inexact flag prevents uv from removing any installed packages).
• If the compiled C/C++ extension is accidentally removed or corrupted (you will see a RuntimeWarning about falling back to the pure-Python implementation), you can also reinstall the package.

Running tests

Current CI status of the test suite, run via GitHub Actions on Python 3.12, is shown in the badge at the top of this file.

• To run the full test suite locally (located in tests):

  uv run pytest

  You can also include coverage options such as --cov if desired.

Notes:

• A comparison against the MATLAB implementation from Ref. [1] is included in test_core.py.
• Unlike v0.1.0, the current test suite is designed to raise errors if the Cython-compiled C/C++ backend is not available, even though a pure-Python fallback implementation is provided and tested.

Usage

The following example demonstrates how to construct a finite-Voronoi diagram:

import numpy as np
import pyafv as afv

N = 100                                          # number of cells
pts = np.random.rand(N, 2) * 10                  # initial positions
params = afv.PhysicalParams()                    # use default parameter values
sim = afv.FiniteVoronoiSimulator(pts, params)    # initialize the simulator
sim.plot_2d(show=True)                           # visualize the Voronoi diagram

To compute the conservative forces and extract detailed geometric information (e.g., cell areas, vertices, and edges), call:

diag = sim.build()

The returned object diag is a Python dict containing these quantities.

Featured examples

To run the example scripts and notebooks in examples, you need to install at least one additional dependency tqdm for progress bars.

For local development using uv: in the project root, run uv add tqdm or uv pip install tqdm. Then you can simply run any script in examples with

uv run <script_name>.py

You can also install all optional dependencies (e.g., tqdm, jupyter) via uv sync --extra examples or uv sync --all-extras.

• For developers to launch Jupyter Notebook: after uv has synced all extra dependencies, start Jupyter with uv run jupyter notebook. Do not use your system-level Jupyter, as the Python kernel of the current uv environment is not registered there.

  Jupyter notebooks and media are stored via Git LFS. If you clone the repository without Git LFS installed, these files will appear as small text pointers. You can either install Git LFS to fetch them automatically or download the files manually (or download the repository as a ZIP archive) from the GitHub web interface.

Simulation previews

Below are representative simulation snapshots generated using the code:

Model illustration	Periodic boundary conditions*

Initial configuration	After relaxation	Active dynamics enabled

More information

See important issues for additional context, such as:

• QhullError when 3+ points are collinear #1 [Closed - see comments]
• Add customized plotting to examples illustrating access to vertices and edges #5 [Completed in PR #7]
• Time step dependence of intercellular adhesion in simulations #8 [Closed in PR #9]

Full documentation on readthedocs!

Zenodo

The releases of this repository are cross-listed on Zenodo.

License

This project is licensed under the MIT License, which permits free use, modification, and distribution of the code for nearly any purpose.

References

[1]	J. Huang, H. Levine, and D. Bi, Bridging the gap between collective motility and epithelial-mesenchymal transitions through the active finite Voronoi model, Soft Matter 19, 9389 (2023).
[2]	E. Teomy, D. A. Kessler, and H. Levine, Confluent and nonconfluent phases in a model of cell tissue, Phys. Rev. E 98, 042418 (2018).
[3]	W. Wang (汪巍) and B. A. Camley, Divergence of detachment forces in the finite-Voronoi model, manuscript in preparation (2026).