pyafv 0.3.5__cp312-cp312-win_amd64.whl → 0.4.1__cp312-cp312-win_amd64.whl

pyafv/finite_voronoi.py

@@ -12,14 +12,18 @@ Key public entry points:
 - update_params(): update physical parameters.
 """
 
-from typing import Literal
-import numpy as np
-from scipy.spatial import Voronoi
-from matplotlib import pyplot as plt
-from matplotlib.axes import Axes
+# Enable postponed evaluation of annotations
+from __future__ import annotations
+
+# Only import typing modules when type checking, e.g., in VS Code or IDEs.
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:                             # pragma: no cover
+    from scipy.spatial import Voronoi
+    import matplotlib.axes
+    import typing
 
+import numpy as np
 from .physical_params import PhysicalParams
-from .backend import backend_impl, _BACKEND_NAME
 
 
 # ---- tiny helpers to avoid tiny allocations in hot loops ----
@@ -36,19 +40,26 @@ class FiniteVoronoiSimulator:
     either a Cython-accelerated version or a pure Python fallback.
 
     Args:
-        pts: (N,2) array of initial cell center positions.
+        pts (numpy.ndarray): (N,2) array of initial cell center positions.
         phys: Physical parameters used within this simulator.
         backend: Optional, specify "python" to force the use of the pure Python fallback implementation.
 
     Raises:
         ValueError: If *pts* does not have shape (N,2).
-        TypeError: If *phys* is not an instance of PhysicalParams.
+        TypeError: If *phys* is not an instance of :py:class:`PhysicalParams`.
+    
+    Warnings:
+        If the Cython backend cannot be imported (unless *backend* is set to "python"),
+        a **RuntimeWarning** is raised and the pure Python implementation is used instead.
     """
 
-    def __init__(self, pts: np.ndarray, phys: PhysicalParams, backend: Literal["cython", "python"] | None = None):
+    def __init__(self, pts: np.ndarray, phys: PhysicalParams, backend: typing.Literal["cython", "python"] | None = None):
         """
         Constructor of the simulator.
         """
+        from scipy.spatial import Voronoi
+        self._voronoi = Voronoi
+        
         pts = np.asarray(pts, dtype=float)
         if pts.ndim != 2 or pts.shape[1] != 2:
             raise ValueError("pts must have shape (N,2)")
@@ -61,6 +72,7 @@ class FiniteVoronoiSimulator:
         self._preferred_areas = np.full(self.N, phys.A0, dtype=float)    # (N,) preferred areas A0
         
         if backend != "python":
+            from .backend import backend_impl, _BACKEND_NAME
             self._BACKEND = _BACKEND_NAME
             self._impl = backend_impl
 
@@ -93,15 +105,18 @@ class FiniteVoronoiSimulator:
             This is an internal method. Use with caution.
 
         Returns: 
-            tuple[scipy.spatial.Voronoi, numpy.ndarray, list[list[int]], int, dict[tuple[int,int], int], dict[int, list[int]]] : A tuple containing:
+            tuple[scipy.spatial.Voronoi, numpy.ndarray, list[list[int]], int, dict[tuple[int,int], int], dict[int, list[int]]] : A *tuple* containing:
             
                 - **vor**: SciPy Voronoi object for current points with extensions.
                 - **vertices_all**: (M,2) array of all Voronoi vertices including extensions.
-                - **ridge_vertices_all**: list of lists of vertex indices for each ridge, including extensions.
+                - **ridge_vertices_all**: List of lists of vertex indices for each ridge, including extensions.
                 - **num_vertices**: Number of Voronoi vertices before adding extension.
-                - **vertexpair2ridge**: dict mapping vertex index pairs to ridge index.
-                - **vertex_points**: dict mapping vertex index to list of associated point indices.
+                - **vertexpair2ridge**: *dict* mapping vertex index pairs to ridge index.
+                - **vertex_points**: *dict* mapping vertex index to list of associated point indices.
         """
+
+        Voronoi = self._voronoi
+
         r = self.phys.r
         pts = self.pts
         N = self.N
@@ -271,26 +286,26 @@ class FiniteVoronoiSimulator:
         Args:
             vor: SciPy Voronoi object for current points with extensions.
             vertices_all: (M,2) array of all Voronoi vertices including extensions.
-            ridge_vertices_all: list of lists of vertex indices for each ridge, including extensions.
+            ridge_vertices_all: (R,2) array of vertex indices for each ridge.
             num_vertices: Number of Voronoi vertices before adding extension.
-            vertexpair2ridge: dict mapping vertex index pairs to ridge index.
+            vertexpair2ridge: *dict* mapping vertex index pairs to ridge index.
         
         Returns:
             dict[str, object]: A diagnostics dictionary containing:
 
-                - **vertex_in_id**: set of inner vertex ids.
-                - **vertex_out_id**: set of outer vertex ids.
+                - **vertex_in_id**: *set* of inner vertex ids.
+                - **vertex_out_id**: *set* of outer vertex ids.
                 - **vertices_out**: (L,2) array of outer vertex coordinates.
                 - **vertex_out_points**: (L,2) array of point index pairs associated with each outer vertex.
-                - **vertex_out_da_dtheta**: array of dA/dtheta for all outer vertices.
-                - **vertex_out_dl_dtheta**: array of dL/dtheta for all outer vertices.
-                - **dA_poly_dh**: array of dA_polygon/dh for each vertex.
-                - **dP_poly_dh**: array of dP_polygon/dh for each vertex.
-                - **area_list**: array of polygon areas for each cell.
-                - **perimeter_list**: array of polygon perimeters for each cell.
-                - **point_edges_type**: list of lists of edge types per cell.
-                - **point_vertices_f_idx**: list of lists of vertex ids per cell.
-                - **num_vertices_ext**: number of vertices including infinite extension vertices.
+                - **vertex_out_da_dtheta**: Array of dA/dtheta for all outer vertices.
+                - **vertex_out_dl_dtheta**: Array of dL/dtheta for all outer vertices.
+                - **dA_poly_dh**: Array of dA_polygon/dh for each vertex.
+                - **dP_poly_dh**: Array of dP_polygon/dh for each vertex.
+                - **area_list**: Array of polygon areas for each cell.
+                - **perimeter_list**: Array of polygon perimeters for each cell.
+                - **point_edges_type**: List of lists of edge types per cell.
+                - **point_vertices_f_idx**: List of lists of vertex ids per cell.
+                - **num_vertices_ext**: Number of vertices including infinite extension vertices.
         """
         N = self.N
         r = self.phys.r
@@ -696,7 +711,7 @@ class FiniteVoronoiSimulator:
         return F
 
     # --------------------- One integration step ---------------------
-    def build(self) -> dict[str, object]:
+    def build(self, connect: bool = True) -> dict[str, object]:
         """ Build the finite-Voronoi structure and compute forces, returning a dictionary of diagnostics.
 
         Do the following:
@@ -705,6 +720,10 @@ class FiniteVoronoiSimulator:
           - Compute per-cell quantities and derivatives
           - Assemble forces
         
+        Args:
+            connect: Whether to compute cell connectivity information.
+                Setting this to ``False`` saves some computation time (though
+                very marginal) when connectivity is not needed.
           
         Returns:
             dict[str, object]: A dictionary containing geometric properties with keys:
@@ -713,14 +732,18 @@ class FiniteVoronoiSimulator:
                 - **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**: (M',2) array of connected cell index pairs
+                - **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
         """
         (vor, vertices_all, ridge_vertices_all, num_vertices,
             vertexpair2ridge, vertex_points) = self._build_voronoi_with_extensions()
         
-        connections = self._get_connections(vor.ridge_points, vertices_all, ridge_vertices_all)
+        # Get connectivity info
+        if connect:
+            connections = self._get_connections(vor.ridge_points, vertices_all, ridge_vertices_all)
+        else:           # pragma: no cover
+            connections = np.empty((0,2), dtype=int)
 
         geom, vertices_all = self._per_cell_geometry(vor, vertices_all, ridge_vertices_all, num_vertices, vertexpair2ridge)
 
@@ -750,11 +773,11 @@ class FiniteVoronoiSimulator:
         )
 
     # --------------------- 2D plotting utilities ---------------------
-    def plot_2d(self, ax: Axes | None = None, show: bool = False) -> Axes:
+    def plot_2d(self, ax: matplotlib.axes.Axes | None = None, show: bool = False) -> matplotlib.axes.Axes:
         """
         Build the finite-Voronoi structure and render a 2D snapshot.
 
-        Basically a wrapper of :py:func:`_build_voronoi_with_extensions` and :py:func:`_per_cell_geometry` functions + plot.
+        Basically a wrapper of :py:meth:`_build_voronoi_with_extensions` and :py:meth:`_per_cell_geometry` functions + plot.
 
         Args:
             ax: If provided, draw into this axes; otherwise get the current axes.
@@ -768,6 +791,8 @@ class FiniteVoronoiSimulator:
 
         geom, vertices_all = self._per_cell_geometry(vor, vertices_all, ridge_vertices_all, num_vertices, vertexpair2ridge)
 
+        from matplotlib import pyplot as plt
+
         if ax is None:
             ax = plt.gca()
         
@@ -779,7 +804,7 @@ class FiniteVoronoiSimulator:
         return ax
 
     # --------------------- Paradigm of plotting ---------------------
-    def _plot_routine(self, ax: Axes, vor: Voronoi, vertices_all: np.ndarray, ridge_vertices_all: list[list[int]],
+    def _plot_routine(self, ax: matplotlib.axes.Axes, vor: Voronoi, vertices_all: np.ndarray, ridge_vertices_all: list[list[int]],
                       point_edges_type: list[list[int]], point_vertices_f_idx: list[list[int]]) -> None:
         """
         Low-level plot routine. Draws:
@@ -887,13 +912,12 @@ class FiniteVoronoiSimulator:
         Update cell center positions.
 
         .. note::
-            If the number of points changes, the preferred areas for all cells
-            are reset to the default value (set when initializing the simulator
-            instance or by :py:func:`update_params`) unless specified via the
-            *A0* argument.
+            If the number of cells changes, the preferred areas for all cells
+            are reset to the default value---defined either at simulator instantiation 
+            or by :py:meth:`update_params`---unless *A0* is explicitly specified.
 
         Args:
-            pts: New cell center positions.
+            pts : New cell center positions.
             A0: Optional, set new preferred area(s).
 
         Raises:
@@ -923,10 +947,10 @@ class FiniteVoronoiSimulator:
         Update physical parameters.
 
         Args:
-            phys: New PhysicalParams object.
+            phys: New :py:class:`PhysicalParams` object.
         
         Raises:
-            TypeError: If *phys* is not an instance of PhysicalParams.
+            TypeError: If *phys* is not an instance of :py:class:`PhysicalParams`.
 
         .. warning::
             This also resets all preferred cell areas to the new value of *A0*.
@@ -943,7 +967,8 @@ class FiniteVoronoiSimulator:
         Update the preferred areas for all cells.
 
         Args:
-            A0: New preferred area(s) for all cells.
+            A0: New preferred area(s) for all cells, either as a scalar or
+                as an array of shape (N,).
 
         Raises:
             ValueError: If *A0* does not match cell number.
@@ -963,8 +988,8 @@ class FiniteVoronoiSimulator:
 
     @property
     def preferred_areas(self) -> np.ndarray:
-        """
-        Preferred areas for all cells (read-only).
+        r"""
+        Preferred areas :math:`\{A_{0,i}\}` for all cells (read-only).
 
         Returns:
             numpy.ndarray: A copy of the internal preferred area array.

pyafv/physical_params.py

@@ -1,9 +1,27 @@
 from __future__ import annotations
 import numpy as np
-from scipy.optimize import minimize
 from dataclasses import dataclass, replace
 
 
+def _require_float_scalar(x: object, name: str) -> float:       # pragma: no cover
+    """
+    Accept Python real scalars (int/float) and NumPy real scalars.
+    Reject other types (including bool).
+    Return a normalized Python float.
+    """
+    # Reject bool explicitly (since bool is a subclass of int)
+    if isinstance(x, bool):
+        raise TypeError(f"{name} must be a real scalar (float-like), got bool")
+    elif isinstance(x, (int, float, np.integer, np.floating)):
+        xf = float(x)
+        if not np.isfinite(xf):
+            raise ValueError(f"{name} must be finite, got {x}")
+        return xf
+
+    # Reject everything else
+    raise TypeError(f"{name} must be a real scalar (float-like), got {type(x).__name__}")
+
+
 def sigmoid(x):
     # stable sigmoid that handles large |x|
     if x >= 0:
@@ -16,35 +34,55 @@ def sigmoid(x):
 
 @dataclass(frozen=True)
 class PhysicalParams:
-    """Physical parameters for the active-finite-Voronoi (AFV) model.
+    r"""Physical parameters for the active-finite-Voronoi (AFV) model.
 
-    Caveat:
-        Frozen dataclass is used for :py:class:`PhysicalParams` to ensure immutability of instances.
+    .. warning::
+        * **Frozen dataclass** is used for :py:class:`PhysicalParams` to ensure immutability of instances.
+        * Do not set :py:attr:`delta` unless you know what you are doing.
 
     Args:
-        r: Radius (maximal) of the Voronoi cells.
+        r: Radius (maximal) of the Voronoi cells, sometimes denoted as :math:`\ell`.
         A0: Preferred area of the Voronoi cells.
         P0: Preferred perimeter of the Voronoi cells.
         KA: Area elasticity constant.
         KP: Perimeter elasticity constant.
         lambda_tension: Tension difference between non-contacting edges and contacting edges.
-        delta: Small offset to avoid singularities in computations.
+        delta: Contact truncation threshold to avoid singularities in computations; if None, set to 0.45*r.
     """
     
-    r: float = 1.0               #: Radius (maximal) of the Voronoi cells.
+    r: float = 1.0               #: Radius (maximal) of the Voronoi cells, sometimes denoted as :math:`\ell`.
     A0: float = np.pi            #: Preferred area of the Voronoi cells.
     P0: float = 4.8              #: Preferred perimeter of the Voronoi cells.
     KA: float = 1.0              #: Area elasticity constant.
     KP: float = 1.0              #: Perimeter elasticity constant.
     lambda_tension: float = 0.2  #: Tension difference between non-contacting edges and contacting edges.
-    delta: float = 0.0           #: Small offset to avoid singularities in computations.
-
+    delta: float | None = None   #: Contact truncation threshold to avoid singularities in computations.
+
+    def __post_init__(self):
+        # Normalize and validate required scalar floats
+        object.__setattr__(self, "r", _require_float_scalar(self.r, "r"))
+        object.__setattr__(self, "A0", _require_float_scalar(self.A0, "A0"))
+        object.__setattr__(self, "P0", _require_float_scalar(self.P0, "P0"))
+        object.__setattr__(self, "KA", _require_float_scalar(self.KA, "KA"))
+        object.__setattr__(self, "KP", _require_float_scalar(self.KP, "KP"))
+        object.__setattr__(self, "lambda_tension", _require_float_scalar(self.lambda_tension, "lambda_tension"))
+
+        if self.delta is None:
+            object.__setattr__(self, "delta", 0.45 * self.r)
+        else:
+            try:
+                object.__setattr__(self, "delta", _require_float_scalar(self.delta, "delta"))
+            except TypeError:       # pragma: no cover
+                raise TypeError(f"delta must be a real scalar (float-like) or None, got {type(self.delta).__name__}") from None
 
     def get_steady_state(self) -> tuple[float, float]:
-        r"""Compute steady-state (l,d) for the given physical parameters.
-        
+        r"""Search for the steady-state :math:`(\ell,d)` of a cell doublet for the given physical parameters (by minimizing total energy).
+
         Returns:
-            Steady-state :math:`(\ell,d)` values.
+            Steady-state (optimal) :math:`(\ell_0,d_0)` values.
+
+        .. note::
+            :math:`\ell` is the maximal cell radius, and :math:`2d` is the cell-center distance of a doublet (rather than :math:`d`).        
         """
         params = [self.KA, self.KP, self.A0, self.P0, self.lambda_tension]
         result = self._minimize_energy(params, restarts=10)
@@ -52,23 +90,30 @@ class PhysicalParams:
         return l, d
 
     def with_optimal_radius(self) -> PhysicalParams:
-        """Returns a new instance with the radius updated to steady state.
+        r"""Returns a new instance of :py:class:`PhysicalParams` with the maximum radius :math:`\ell` (or :py:attr:`r`) updated to the steady state value :math:`\ell_0` of cell doublets.
+        Other parameters (except :py:attr:`delta`) remain unchanged.
         
+        Basically a wrapper around :py:meth:`get_steady_state` + creating a new instance.
+
         Returns:
             New instance with optimal radius.
+        
+        .. important::
+            In the returned instance, the contact truncation threshold :py:attr:`delta` is set to 0.45*r by default.
         """
         l, d = self.get_steady_state()
-        new_params = replace(self, r=l)
+        new_params = replace(self, r=l, delta=0.45*l)
         return new_params
 
     def with_delta(self, delta_new: float) -> PhysicalParams:
-        """Returns a new instance with the specified delta.
-        
+        """Returns a new instance of :py:class:`PhysicalParams` with the new contact truncation threshold *delta_new*.
+        Other parameters remain unchanged.
+
         Args:
-            delta_new: New delta value.
+            delta_new: New :py:attr:`delta` value.
 
         Returns:
-            New instance with updated delta.
+            New instance with the updated delta value.
         """
         return replace(self, delta=delta_new)
 
@@ -86,6 +131,9 @@ class PhysicalParams:
         return KA * (A - A0)**2 + KP * (P - P0)**2 + Lambda * ln
 
     def _minimize_energy(self, params, restarts=10, seed=None):
+
+        from scipy.optimize import minimize
+        
         rng = np.random.default_rng(seed)
         best = None
         for _ in range(restarts):
@@ -117,34 +165,56 @@ def target_delta(params: PhysicalParams, target_force: float) -> float:
         params: Physical parameters of the AFV model.
         target_force: Target detachment force.
 
-    Returns:
-        Corresponding small cutoff :math:`\delta`'s value.
-    """
-    KP, A0, P0, Lambda = params.KP, params.A0, params.P0, params.lambda_tension
-    l = params.r
+    Raises:
+        TypeError: If *params* is not an instance of :py:class:`PhysicalParams`.
+        ValueError: If the target force is not within the achievable range.
 
-    distances = np.linspace(1e-6, 2*l-(1e-6), 10_000)
-    detachment_forces = []
-    for distance in distances:
-        epsilon = l - (distance/2.)
+    Returns:
+        Corresponding value of the truncation threshold :math:`\delta`.
 
-        theta = 2 * np.pi - 2 * np.arctan2(np.sqrt(l**2 - (l - epsilon)**2), l - epsilon)
-        A = (l - epsilon) * np.sqrt(l**2 -
-                                    (l - epsilon)**2) + 0.5 * (l**2 * theta)
-        P = 2 * np.sqrt(l**2 - (l - epsilon)**2) + l * theta
+    .. note::
+        We search for the cell-cell separation at which the intercellular force
+        equals the target force, scanning distances from :math:`10^{-6}\ell` to
+        :math:`(2-10^{-6})\ell` in steps of :math:`10^{-6}\ell`, and select the
+        **largest distance** at which the match occurs.
+    """
 
-        f = 4. * np.sqrt((2-epsilon) * epsilon) * (A - A0 + KP * ((P - P0)/(2 - epsilon)) 
-                                                   + (Lambda/2) * (1./((2-epsilon)*epsilon)))
-        detachment_forces.append(f)
+    if not isinstance(params, PhysicalParams):      # pragma: no cover
+        raise TypeError("params must be an instance of PhysicalParams")
 
-    # print(detachment_forces)
+    KA, KP, A0, P0, Lambda = params.KA, params.KP, params.A0, params.P0, params.lambda_tension
+    l = params.r
 
-    detachment_forces = np.array(detachment_forces)
+    distances = np.linspace(1e-6, 2.-(1e-6), 10**6) * l
+    
+    epsilon = l - (distances/2.)
 
-    idx = np.abs(detachment_forces[None, :] - target_force).argmin()
-    target_distances = distances[idx]
+    theta = 2 * np.pi - 2 * np.arctan2(np.sqrt(l**2 - (l - epsilon)**2), l - epsilon)
+    A = (l - epsilon) * np.sqrt(l**2 -
+                                (l - epsilon)**2) + 0.5 * (l**2 * theta)
+    P = 2 * np.sqrt(l**2 - (l - epsilon)**2) + l * theta
 
-    delta = np.sqrt(4*(l**2) - target_distances**2)
+    detachment_forces = 4. * np.sqrt((2 * l - epsilon) * epsilon) * (KA * (A - A0) + KP * ((P - P0)/(2 * l - epsilon)) 
+                                                + (Lambda/2) * l /((2 * l - epsilon) * epsilon))
+    
+    # idx = np.abs(detachment_forces[None, :] - target_force).argmin()
+    # target_distances = distances[idx]
+
+    # ---------------------- Better way to search foot ----------------------------
+    f = detachment_forces - target_force    # find root of f=0
+    cross = (f[:-1] == 0) | (np.signbit(f[:-1]) != np.signbit(f[1:]))   # crossing points
+
+    if np.any(cross):
+        i = np.flatnonzero(cross)[-1]  # last crossing interval [i, i+1]
+        # optional: linear interpolation for a better distance estimate
+        x0, x1 = distances[i], distances[i+1]
+        f0, f1 = f[i], f[i+1]
+        target_distance = x0 if f1 == f0 else x0 + (0 - f0) * (x1 - x0) / (f1 - f0)
+    else:
+        raise ValueError("No valid delta found for the given target force.")
+    # ------------------------------------------------------------------------------
+    
+    delta = np.sqrt(4*(l**2) - target_distance**2)
 
     return delta
 

pyafv-0.4.1.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: pyafv
+Version: 0.4.1
+Summary: Python implementation of the active-finite-Voronoi (AFV) model
+Project-URL: Homepage, https://pyafv.github.io
+Project-URL: Download, https://pypi.org/project/pyafv/#files
+Project-URL: Source Code, https://github.com/wwang721/pyafv
+Project-URL: Documentation, https://pyafv.readthedocs.io/
+Project-URL: Changelog, https://github.com/wwang721/pyafv/releases/latest
+Author: Wei Wang
+Author-email: ww000721@gmail.com
+License-Expression: MIT
+License-File: LICENSE
+Keywords: biological-modeling,cellular-patterns,voronoi-model
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: <3.15,>=3.10
+Requires-Dist: matplotlib>=3.8.4
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: scipy>=1.13.1
+Provides-Extra: examples
+Requires-Dist: ipywidgets>=8.1.5; extra == 'examples'
+Requires-Dist: jupyter>=1.1.0; extra == 'examples'
+Requires-Dist: tqdm>=4.67.1; extra == 'examples'
+Description-Content-Type: text/markdown
+
+[![PyPi](https://img.shields.io/pypi/v/pyafv?cacheSeconds=300)](https://pypi.org/project/pyafv/)
+[![Downloads](https://img.shields.io/pypi/dm/pyafv.svg?cacheSeconds=43200)](https://pypi.org/project/pyafv/)
+[![Documentation](https://img.shields.io/badge/documentation-pyafv.readthedocs.io-yellow.svg?logo=readthedocs)](https://pyafv.readthedocs.io)
+<!--[![pytest](https://github.com/wwang721/pyafv/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/wwang721/pyafv/actions/workflows/tests.yml?query=branch:main)-->
+[![Tests on all platforms](https://github.com/wwang721/pyafv/actions/workflows/tests_all_platform.yml/badge.svg)](https://github.com/wwang721/pyafv/actions/workflows/tests_all_platform.yml)
+[![pytest](https://github.com/wwang721/pyafv/actions/workflows/tests.yml/badge.svg)](https://github.com/wwang721/pyafv/actions/workflows/tests.yml)
+[![Codecov](https://codecov.io/github/wwang721/pyafv/branch/main/graph/badge.svg?token=VSXSOX8HVS)](https://codecov.io/github/wwang721/pyafv/tree/main)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+<!--
+[![arXiv:2503.03126](https://img.shields.io/badge/arXiv-2503.03126-grey.svg?colorA=a42c25&colorB=grey&logo=arxiv)](https://doi.org/10.48550/arXiv.2503.03126)
+[![PhysRevE.109.054408](https://img.shields.io/badge/Phys.%20Rev.%20E-109.054408-grey.svg?colorA=8c6040)](https://doi.org/10.1103/PhysRevE.109.054408)
+[![Soft Matter](https://img.shields.io/badge/Soft%20Matter-XXXXX-63a7c2.svg?colorA=63a7c2&colorB=grey)](https://doi.org/10.1103/PhysRevE.109.054408)
+-->
+
+
+# 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](#huang2023bridging)&ndash;[3](#wang2026divergence)].
+
+
+## Installation
+
+**PyAFV** is available on **PyPI** and can be installed using *pip* directly:
+```bash
+pip install pyafv
+```
+The package supports Python ≥ 3.10 and < 3.15, including Python 3.14t (the free-threaded, no-GIL build).
+To verify that the installation was successful and that the correct version is installed, run the following in Python:
+```python
+import pyafv
+print(pyafv.__version__)
+```
+
+> On 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=""`.
+
+### Install from source
+
+Installing from source can be necessary if *pip* installation does not work. First, download and unzip the source code, then navigate to the root directory of the package and run:
+```bash
+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.
+
+
+#### 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 `pip install .` with the following content:
+```ini
+# setup.cfg
+[build_ext]
+compiler=mingw32
+```
+
+
+### Install offline
+
+If you need to install **PyAFV** on a machine without internet access, you can download the corresponding wheel file from **PyPI** and transfer it to the target machine, and then run the following command to install using *pip*:
+```bash
+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 of the package, the build-time dependencies **hatchling** and **hatch-cython** must also be available.
+
+
+## Usage
+
+Here is a simple example to get you started, demonstrating how to construct a finite-Voronoi diagram:
+```python
+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:
+```python
+diag = sim.build()
+```
+The returned object `diag` is a Python `dict` containing these quantities.
+
+
+## Simulation previews
+
+Below are representative simulation snapshots generated using the code:
+
+| Model illustration | Periodic boundary conditions |
+|-----------------|-----------------|
+| <img src="https://media.githubusercontent.com/media/wwang721/pyafv/main/assets/model_illustration.png" width="540"> | <img src="https://media.githubusercontent.com/media/wwang721/pyafv/main/assets/pbc.png" width="385">|
+
+| Initial configuration | After relaxation | Active dynamics enabled |
+|-----------------------|-----------------------|-----------------------|
+| <img src="https://media.githubusercontent.com/media/wwang721/pyafv/main/assets/initial_configuration.png" width="300"> | <img src="https://media.githubusercontent.com/media/wwang721/pyafv/main/assets/relaxed_configuration.png" width="300"> | <img src="https://media.githubusercontent.com/media/wwang721/pyafv/main/assets/active_FV.png" width="300"> |
+
+
+## More information
+
+- **Full documentation** on [readthedocs](https://pyafv.readthedocs.io) or as [a single PDF file](https://pyafv.readthedocs.io/_/downloads/en/latest/pdf/).
+
+- See [CONTRIBUTING.md](https://github.com/wwang721/pyafv/blob/main/.github/CONTRIBUTING.md) or the [documentation](https://pyafv.readthedocs.io/latest/contributing.html) for **local development instructions**.
+
+- See some important [**issues**](https://github.com/wwang721/pyafv/issues?q=is%3Aissue%20state%3Aclosed) for additional context, such as: 
+    * [QhullError when 3+ points are collinear #1](https://github.com/wwang721/pyafv/issues/1) [Closed - see [comments](https://github.com/wwang721/pyafv/issues/1#issuecomment-3701355742)]
+    *  [Add customized plotting to examples illustrating access to vertices and edges #5](https://github.com/wwang721/pyafv/issues/5) [Completed in PR [#7](https://github.com/wwang721/pyafv/pull/7)]
+    * [Time step dependence of intercellular adhesion in simulations #8](https://github.com/wwang721/pyafv/issues/8) [Closed in PR [#9](https://github.com/wwang721/pyafv/pull/9)]
+
+- Some releases of this repository are cross-listed on [Zenodo](https://doi.org/10.5281/zenodo.18091659):
+
+  [![Zenodo](https://zenodo.org/badge/1124385738.svg)](https://doi.org/10.5281/zenodo.18091659)
+
+
+## References
+
+<table>
+  <tr>
+    <td id="huang2023bridging" valign="top">[1]</td>
+    <td>
+      J. Huang, H. Levine, and D. Bi, <em>Bridging the gap between collective motility and epithelial-mesenchymal transitions through the active finite Voronoi model</em>, <a href="https://doi.org/10.1039/D3SM00327B">Soft Matter <strong>19</strong>, 9389 (2023)</a>.
+    </td>
+  </tr>
+  <tr>
+    <td id="teomy2018confluent" valign="top">[2]</td>
+    <td>
+      E. Teomy, D. A. Kessler, and H. Levine, <em>Confluent and nonconfluent phases in a model of cell tissue</em>, <a href="https://doi.org/10.1103/PhysRevE.98.042418">Phys. Rev. E <strong>98</strong>, 042418 (2018)</a>.
+    </td>
+  </tr>
+  <tr>
+    <td id="wang2026divergence" valign="top">[3]</td>
+    <td>
+      W. Wang (汪巍) and B. A. Camley, <em>Divergence of detachment forces in the finite-Voronoi model</em>, manuscript in preparation (2026).
+    </td>
+  </tr>
+</table>