pyafv 0.3.6__cp314-cp314-macosx_11_0_arm64.whl

pyafv/physical_params.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+import numpy as np
+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:
+    """Physical parameters for the active-finite-Voronoi (AFV) model.
+
+    Caveat:
+        Frozen dataclass is used for :py:class:`PhysicalParams` to ensure immutability of instances.
+
+    Args:
+        r: Radius (maximal) of the Voronoi cells.
+        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.
+    """
+    
+    r: float = 1.0               #: Radius (maximal) of the Voronoi cells.
+    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.
+
+
+    def get_steady_state(self) -> tuple[float, float]:
+        r"""Compute steady-state (l,d) for the given physical parameters.
+        
+        Returns:
+            Steady-state :math:`(\ell,d)` values.
+        """
+        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) -> PhysicalParams:
+        """Returns a new instance with the radius updated to steady state.
+        
+        Returns:
+            New instance with optimal radius.
+        """
+        l, d = self.get_steady_state()
+        new_params = replace(self, r=l)
+        return new_params
+
+    def with_delta(self, delta_new: float) -> PhysicalParams:
+        """Returns a new instance with the specified delta.
+        
+        Args:
+            delta_new: New delta value.
+
+        Returns:
+            New instance with updated 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):
+
+        from scipy.optimize import minimize
+        
+        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:
+    r"""
+    Given the physical parameters and a target detachment force, compute the corresponding delta.
+
+    Args:
+        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
+
+    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-0.3.6.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: pyafv
+Version: 0.3.6
+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
+Project-URL: Documentation, https://pyafv.readthedocs.io/
+Project-URL: Changelog, https://github.com/wwang721/pyafv/releases/latest
+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.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.10
+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)-->
+[![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)
+
+
+# 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
+
+To install **PyAFV** with `pip`, run:
+```bash
+pip install pyafv
+```
+The package supports Python ≥ 3.10 and < 3.15.
+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__)
+```
+
+
+## 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)]
+
+Full documentation on [readthedocs](https://pyafv.readthedocs.io/en/latest/)!
+
+## 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.6.dist-info/RECORD

@@ -0,0 +1,12 @@
+pyafv-0.3.6.dist-info/RECORD,,
+pyafv-0.3.6.dist-info/WHEEL,sha256=2Id6qreet5t4wZv58bZfijJ58qrc2xkw6OVvWfeqxV0,136
+pyafv-0.3.6.dist-info/top_level.txt,sha256=mrKQNqc4GQxuZ7hd5UrKxbA_AJsuSqiJyMxL7Nu7va0,6
+pyafv-0.3.6.dist-info/METADATA,sha256=l-cKhjFiEp8K5Ku6Y2PuFVjOMx4iLdK6W0A4nT5o7YE,5664
+pyafv-0.3.6.dist-info/licenses/LICENSE,sha256=TNjxBxdiOzyewn2FP7g1FjW3CJoxiGCY6ShPVFv02G8,1065
+pyafv/cell_geom_fallback.py,sha256=XeafJJFV-ykAaKT-UoDnX7FIbmNXChzJn1AwVgQIM-8,9142
+pyafv/backend.py,sha256=O15-rtzPQvTl_fIyZu4L0LU8UG4uRnAuq4bi5HBlKy8,418
+pyafv/_version.py,sha256=td0yl-KXLJoMk9Xqi4IHgKZoN7BKWLkRiGBDmc3qB0g,42
+pyafv/__init__.py,sha256=i6DtniJfMN8_wiOWpNGhPCU7OdQhOANfJfF56oGguVM,426
+pyafv/finite_voronoi.py,sha256=tQg1lJbXnH4JDnmABJzh-wJ57W4-EcMFLD70H93ALK8,44464
+pyafv/physical_params.py,sha256=qyZFGsH9Hpk8pA4_RE95cLRSZOw1P9K5tPOK0hX8M4o,5187
+pyafv/cell_geom.cpython-314-darwin.so,sha256=9qMJRJzpC6xlObotRBMWKgY-sDk6W-O9VOm59Ut0CYE,327680

pyafv-0.3.6.dist-info/WHEEL

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

pyafv-0.3.6.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.6.dist-info/top_level.txt

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