pyafv 0.3.3__cp39-cp39-macosx_10_9_x86_64.whl

pyafv/physical_params.py

@@ -0,0 +1,117 @@
+import numpy as np
+from scipy.optimize import minimize
+from dataclasses import dataclass, replace
+
+
+def sigmoid(x):
+    # stable sigmoid that handles large |x|
+    if x >= 0:
+        z = np.exp(-x)
+        return 1 / (1 + z)
+    else:
+        z = np.exp(x)
+        return z / (1 + z)
+
+
+@dataclass(frozen=True)
+class PhysicalParams:
+    # Radius (maximal) of the Voronoi cells
+    r: float = 1.0
+    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
+    KP: float = 1.0                      # Perimeter elasticity
+    lambda_tension: float = 0.2          # Tension difference
+    delta: float = 0.                    # Small offset to avoid singularities
+
+    def get_steady_state(self):
+        # compute steady-state (l,d) given physical params
+        params = [self.KA, self.KP, self.A0, self.P0, self.lambda_tension]
+        result = self._minimize_energy(params, restarts=10)
+        l, d = result[0]
+        return l, d
+
+    def with_optimal_radius(self):
+        """Returns a new instance with the radius updated to steady state."""
+        l, d = self.get_steady_state()
+        new_params = replace(self, r=l)
+        return new_params
+
+    def with_delta(self, delta_new: float):
+        """Returns a new instance with the specified delta."""
+        return replace(self, delta=delta_new)
+
+    def _energy_unconstrained(self, z, params):
+        v, u = float(z[0]), float(z[1])
+        l = np.exp(v)                              # l > 0
+        phi = 0.5*np.pi * sigmoid(u)               # phi in (0, pi/2)
+        s, c = np.sin(phi), np.cos(phi)
+        theta = np.pi + 2.0*phi
+        A = 0.5*l*l*(theta + np.sin(2.0*phi))
+        P = 2.0*l*c + l*theta
+        ln = l*theta
+
+        KA, KP, A0, P0, Lambda = params
+        return KA * (A - A0)**2 + KP * (P - P0)**2 + Lambda * ln
+
+    def _minimize_energy(self, params, restarts=10, seed=None):
+        rng = np.random.default_rng(seed)
+        best = None
+        for _ in range(restarts):
+            z0 = rng.normal(size=2)
+
+            res = minimize(lambda z: self._energy_unconstrained(z, params), z0, method="BFGS",
+                           options={"gtol": 1e-8, "maxiter": 1e4})
+            val = res.fun
+            z = res.x
+
+            if (best is None) or (val < best[0]):
+                best = (val, z)
+
+        # map back to (l,d)
+        val, z = best
+        v, u = float(z[0]), float(z[1])
+        l = np.exp(v)
+        phi = 0.5*np.pi * sigmoid(u)
+        d = l*np.sin(phi)
+
+        return [l, d], val
+
+
+def target_delta(params: PhysicalParams, target_force: float) -> float:
+    """
+    Given physical parameters and a target detachment force, compute the corresponding delta.
+    """
+    KP, A0, P0, Lambda = params.KP, params.A0, params.P0, params.lambda_tension
+    l = params.r
+
+    distances = np.linspace(1e-6, 2*l-(1e-6), 10_000)
+    detachment_forces = []
+    for distance in distances:
+        epsilon = l - (distance/2.)
+
+        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
+
+        f = 4. * np.sqrt((2-epsilon) * epsilon) * (A - A0 + KP * ((P - P0)/(2 - epsilon)) 
+                                                   + (Lambda/2) * (1./((2-epsilon)*epsilon)))
+        detachment_forces.append(f)
+
+    # print(detachment_forces)
+
+    detachment_forces = np.array(detachment_forces)
+
+    idx = np.abs(detachment_forces[None, :] - target_force).argmin()
+    target_distances = distances[idx]
+
+    delta = np.sqrt(4*(l**2) - target_distances**2)
+
+    return delta
+
+
+__all__ = [
+    "PhysicalParams",
+    "target_delta",
+]

pyafv/simulator.py

@@ -0,0 +1,37 @@
+# API-facing wrapper
+
+from .backend import backend_simulator, _BACKEND_NAME
+
+
+class FiniteVoronoiSimulator(backend_simulator):
+    """Finite Voronoi Simulator.
+
+    This class provides an interface to simulate finite Voronoi models.
+    It wraps around the backend simulator implementation, which may be
+    either a Cython-accelerated version or a pure Python fallback.
+
+    Attributes:
+        See `backend_simulator` for details.
+    """
+    # Define as a class attribute
+    _BACKEND = _BACKEND_NAME
+
+    def __init__(self, *args, **kwargs):
+        # Ensure you call the parent constructor
+        super().__init__(*args, **kwargs)
+
+        if self._BACKEND not in {"cython", "numba"}:                 # pragma: no cover
+            # raise warning to inform user about fallback
+            import warnings
+            warnings.warn(
+                "Could not import the Cython-built extension module. "
+                "Falling back to the pure Python implementation, which may be slower. "
+                "To enable the accelerated version, ensure that all dependencies are installed.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+
+
+__all__ = [
+    "FiniteVoronoiSimulator",
+]

pyafv-0.3.3.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: pyafv
+Version: 0.3.3
+Summary: Python implementation of the active-finite-Voronoi (AFV) model
+Author-email: "Wei Wang (汪巍)" <ww000721@gmail.com>
+License-Expression: MIT
+Project-URL: Download, https://pypi.org/project/pyafv/#files
+Project-URL: Source Code, https://github.com/wwang721/pyafv
+Keywords: voronoi-model,cellular-patterns,biological-modeling
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: <3.15,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: scipy>=1.13.1
+Requires-Dist: matplotlib>=3.8.4
+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"
+Dynamic: license-file
+
+[![PyPi](https://img.shields.io/pypi/v/pyafv)](https://pypi.org/project/pyafv/)
+[![Downloads](https://img.shields.io/pypi/dm/pyafv.svg)](https://pypi.org/project/pyafv/)
+[![Zenodo](https://zenodo.org/badge/1124385738.svg)](https://doi.org/10.5281/zenodo.18091659)
+<!--[![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)-->
+[![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)
+
+
+# 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
+
+Install **PyAFV** with:
+```bash
+pip install pyafv
+```
+This package requires Python ≥ 3.9 and < 3.15.
+
+
+## Usage
+
+<!--Using `uv run python`, you should be able to import `pyafv` from anywhere within the repository directory.-->
+The following example demonstrates 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.
+
+
+## More information
+
+GitHub: [https://github.com/wwang721/pyafv](https://github.com/wwang721/pyafv)
+
+See 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)]
+
+
+## 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>

pyafv-0.3.3.dist-info/RECORD

@@ -0,0 +1,12 @@
+pyafv-0.3.3.dist-info/RECORD,,
+pyafv-0.3.3.dist-info/WHEEL,sha256=Prymy4iewnr2C3GLPmIomJyLIRtmCgaf6MSAdd7b500,135
+pyafv-0.3.3.dist-info/top_level.txt,sha256=mrKQNqc4GQxuZ7hd5UrKxbA_AJsuSqiJyMxL7Nu7va0,6
+pyafv-0.3.3.dist-info/METADATA,sha256=kgjVhTWWgdBpTa-dOvL96pIhMeML5_iLYHBjPEj3QbE,5128
+pyafv-0.3.3.dist-info/licenses/LICENSE,sha256=TNjxBxdiOzyewn2FP7g1FjW3CJoxiGCY6ShPVFv02G8,1065
+pyafv/finite_voronoi_fast.py,sha256=tjzzPpCCNlQ_5cnglTsdBV2IV6Zw-GKpGiS_x81dBNY,36095
+pyafv/backend.py,sha256=p0gXsoZdNxytiBhg-txa9nD1HLzSZUwKPFE8BdWAHAY,395
+pyafv/__init__.py,sha256=A42X5OaACYmVnWGnSDHxg9h-63NnadocQbOuZ6yRnq0,379
+pyafv/physical_params.py,sha256=QPM1CCLx_dlof1WsykHwMLfRMctr5ALlMLVmrpiSp_c,3901
+pyafv/cell_geom.cpython-39-darwin.so,sha256=BpbdoqjSnS7nILpkugR4vUaw0DtdVbXs9RzEPEhMVe8,319456
+pyafv/simulator.py,sha256=foVqh3vKp7-IFqcd3gd6FUIbw-xcXAxVAeUwosHVHS4,1218
+pyafv/finite_voronoi_fallback.py,sha256=NiguvSeLUbDQ2wOH3bnx0rxzQWBEbuP5-sjkWruQigg,42827

pyafv-0.3.3.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: false
+Tag: cp39-cp39-macosx_10_9_x86_64
+Generator: delocate 0.13.0
+

pyafv-0.3.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Wei Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyafv-0.3.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyafv