1. Getting started

1.1. Installation

PyAFV supports Python >= 3.10, < 3.15, and has been tested on major operating systems including Linux, macOS, and Windows, for both x86-64 and ARM64 architectures.

Note

Python 3.14t, the free-threaded build that runs without the Global Interpreter Lock (GIL), is also supported starting with PyAFV v0.3.8.
Python 3.10 and 3.14t (free-threaded) on Windows ARM64 (not x86-64) are the only untested configurations. The builds succeed and the wheels are available on PyPI, but automated testing is unavailable due to the absence of a supported GitHub Actions runners for these configurations.

1.1.1. Install using pip/conda

The package is available on PyPI, so you should be able to install it using pip directly:

(.venv) $ pip install pyafv

After installation, verify that it was successful by importing the package in Python and checking the version:

>>> import pyafv
>>> pyafv.__version__
'0.4.7'

Note

On some HPC clusters, global Python path can contaminate the runtime environment. You may need to clear it explicitly using unset PYTHONPATH or prefixing the pip command with PYTHONPATH="".

As an alternative, you can install PyAFV via conda from the conda-forge channel:

(.venv) $ conda install -c conda-forge pyafv

If you go this route, note that for Python 3.14 the package currently supports only the GIL-enabled build.

1.1.2. Install from source

Installing from source can be necessary if pip installation does not work. First, download the source code of pyafv from GitHub or PyPI.

1.1.2.1. Required prerequisites

In general, you do not need to manually install the dependencies, as pip will handle them automatically. We list the required packages and minimum versions below for reference:

Package	Minimum version	Usage
numpy	1.26.4	Numerical computations
scipy	1.13.1	Miscellaneous scientific functions
matplotlib	3.8.4	Plotting and visualization

Unzip the downloaded source code and navigate to the root directory of the package. Then, run the following command to install:

(.venv) $ pip install .

Note

A C/C++ compiler is required if you are building from source, since some components of PyAFV are implemented in Cython for performance optimization.

1.1.2.2. Windows MinGW GCC

If you are using MinGW GCC (rather than MSVC) on Windows, to build from the source code, add a setup.cfg file at the repository root before running pip install . with the following content:

# setup.cfg
[build_ext]
compiler=mingw32

1.1.3. Install offline

If you need to install PyAFV on a machine without internet access, you can download the corresponding wheel file from PyPI on another machine with internet access. Transfer the wheel file to the target machine, and then run the following command to install it using pip (make sure the required prerequisites listed above are already installed):

(.venv) $ pip install pyafv-<version>-<platform>.whl

Alternatively, you can build PyAFV from source as described in the previous section. In this case, in addition to the required prerequisites listed above, the build-time dependencies hatchling and hatch-cython must also be available.

1.1.4. Install using Docker

Pull the Docker image from Docker Hub:

(.venv) $ docker pull wwang721/pyafv:latest

It’s also available in the GitHub Container Registry (GHCR) under GitHub Packages; use ghcr.io/wwang721/pyafv to pull from GHCR instead. Then run Python scripts with pyafv using:

(.venv) $ docker run --rm -v $(pwd):/app wwang721/pyafv python <script_name>.py

Use ${PWD} on Windows PowerShell instead of $(pwd).

1.2. A simple example

Now that you have installed PyAFV, here is a simple example to get you started (click the Google Colab badge above to run the notebook directly). Begin by importing the required libraries and generating 100 random points in two dimensions:

import numpy as np
import pyafv

N = 100                                           # number of cells
pts = np.random.rand(N, 2) * 10                   # initial positions

Next, create a pyafv.PhysicalParams object to specify the physical parameters of the simulation:

params = pyafv.PhysicalParams(r=1.0)              # use default parameter values

class PhysicalParams(r=1.0, A0=3.141592653589793, P0=4.8, KA=1.0, KP=1.0, Lambda=0.2, delta=None)[source]

Physical parameters for the active-finite-Voronoi (AFV) model.

Warning

Frozen dataclass is used for PhysicalParams to ensure immutability of instances.
Do not set delta unless you know what you are doing.

Parameters:

r (float) – Radius (maximal) of the Voronoi cells, sometimes denoted as $\ell$.
A0 (float) – Preferred area of the Voronoi cells.
P0 (float) – Preferred perimeter of the Voronoi cells.
KA (float) – Area elasticity constant.
KP (float) – Perimeter elasticity constant.
Lambda (float) – Tension difference between non-contacting edges and contacting edges.
delta (float | None) – Contact truncation threshold to avoid singularities in computations; if None, set to 0.45*r.

Finally, initialize the simulator by constructing a pyafv.FiniteVoronoiSimulator instance and visualize the resulting Voronoi diagram:

sim = pyafv.FiniteVoronoiSimulator(pts, params)   # initialize the simulator
sim.plot_2d(show=True)                            # visualize the Voronoi diagram

The plotting routine plot_2d() is provided by:

FiniteVoronoiSimulator.plot_2d(ax=None, show=False, **kw)[source]

Build the finite-Voronoi structure and render a 2D snapshot. The plotting style follows scipy.spatial.voronoi_plot_2d().

This method is basically a wrapper of _build_voronoi_with_extensions() and _per_cell_geometry() functions + plot.

Parameters:

ax (Axes | None) – If provided, draw into this axes; otherwise get the current axes.
show (bool) – Whether to call plt.show() at the end.
show_points (bool, optional) – Add the Voronoi points to the plot, default True.
point_size (float, optional) – Specifies the marker size for Voronoi points, default 2.
show_inner_vertices (bool, optional) – Add inner vertices to the plot, default False.
show_outer_vertices (bool, optional) – Add outer vertices to the plot, default False.
line_color_in (str, optional) – Specifies the color for inner-vertex edges, default ‘b’.
line_color_out (str, optional) – Specifies the color for outer-vertex edges, default ‘C6’.
line_width (float, optional) – Specifies the line width for cell boundaries, default 1.5.
line_alpha (float, optional) – Specifies the line alpha for cell boundaries, default 1.0.
show_voronoi (bool, optional) – Add the Voronoi edges to the plot, default True.

Returns:

The matplotlib axes containing the plot.

Return type:

Axes

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

diag = sim.build()                                       # compute forces and geometry

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

FiniteVoronoiSimulator.build(connect=True)[source]

Build the finite-Voronoi structure and compute forces, returning a dictionary of diagnostics.

Do the following:

Build Voronoi (+ extensions)
Get cell connectivity
Compute per-cell quantities and derivatives
Assemble forces

Parameters:

connect (bool) – Whether to compute cell connectivity information. Setting this to False saves some computation time (though very marginal) when connectivity is not needed.

Returns:

A dictionary containing forces and geometric properties with keys:

forces: (N,2) array of forces on cell centers

areas: (N,) array of cell areas

perimeters: (N,) array of cell perimeters

vertices: (M,2) array of all Voronoi + extension vertices

edges_type: List-of-lists of edge types per cell (1=straight, 0=circular arc)

regions: List-of-lists of vertex indices per cell

connections: (K,2) array of connected cell index pairs

Return type:

dict[str, object]

For more examples and detailed usage instructions, please refer to the Examples and API reference sections.