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.

1.1.1. Install using pip

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.3.5'

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

The required packages are listed in the table below:

Package

Minimum Version

Usage

numpy

1.26.4

Numerical computations

scipy

1.13.1

Scientific computations

matplotlib

3.8.4

Plotting and visualization

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

(.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 at the repository root before running the installation command above, with the following content:

# setup.cfg
[build_ext]
compiler=mingw32

1.2. A simple example

Now that you have installed PyAFV, here is a simple example to get you started. 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 pyafv.PhysicalParams(r=1.0, A0=3.141592653589793, P0=4.8, KA=1.0, KP=1.0, lambda_tension=0.2, delta=0.0)

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

Caveat:

Frozen dataclass is used for PhysicalParams to ensure immutability of instances.

Parameters:

  • r (float) – Radius (maximal) of the Voronoi cells.

  • 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_tension (float) – Tension difference between non-contacting edges and contacting edges.

  • delta (float) – Small offset to avoid singularities in computations.

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)

Build the finite-Voronoi structure and render a 2D snapshot.

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.

Returns:

The matplotlib axes containing the plot.

Return type:

Axes

A simple example