pyafv 0.4.0__cp310-cp310-macosx_11_0_arm64.whl

pyafv/physical_params.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+import numpy as np
+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:
+        z = np.exp(-x)
+        return 1 / (1 + z)
+    else:
+        z = np.exp(x)
+        return z / (1 + z)
+
+
+@dataclass(frozen=True)
+class PhysicalParams:
+    r"""Physical parameters for the active-finite-Voronoi (AFV) model.
+
+    .. 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, 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: 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, 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 | 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 :math:`(\ell,d)` for the given physical parameters.
+
+        Returns:
+            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)
+        l, d = result[0]
+        return l, d
+
+    def with_optimal_radius(self) -> PhysicalParams:
+        """Returns a new instance with the radius updated to steady state.
+        Other parameters remain unchanged (with the exception that :py:attr:`delta` is scaled with :py:attr:`r`).
+        
+        Basically a wrapper around :py:meth:`get_steady_state` + creating a new instance.
+
+        Returns:
+            New instance with optimal radius.
+        """
+        l, d = self.get_steady_state()
+        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.
+        Other parameters remain unchanged.
+
+        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.
+
+    Raises:
+        TypeError: If *params* is not an instance of :py:class:`PhysicalParams`.
+        ValueError: If the target force is not within the achievable range.
+
+    Returns:
+        Corresponding value of the truncation threshold :math:`\delta`.
+
+    .. note::
+        We search for the cell-cell distance at which the intercellular force matches (last one) the target force, from :math:`10^{-6}\ell` to :math:`(2-10^{-6})\ell` with a step :math:`10^{-6}\ell`.
+    """
+
+    if not isinstance(params, PhysicalParams):      # pragma: no cover
+        raise TypeError("params must be an instance of PhysicalParams")
+
+    KA, KP, A0, P0, Lambda = params.KA, params.KP, params.A0, params.P0, params.lambda_tension
+    l = params.r
+
+    distances = np.linspace(1e-6, 2.-(1e-6), 10**6) * l
+    
+    epsilon = l - (distances/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
+
+    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
+
+
+__all__ = [
+    "PhysicalParams",
+    "target_delta",
+]

pyafv-0.4.0.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: pyafv
+Version: 0.4.0
+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/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>

pyafv-0.4.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+pyafv-0.4.0.dist-info/RECORD,,
+pyafv-0.4.0.dist-info/WHEEL,sha256=8gye15wTKSCqSQtfgS-BjXX53AznFEOl1uVSY24Nf68,133
+pyafv-0.4.0.dist-info/METADATA,sha256=Wdbczpu4vFcOrpxah8YCvwxB2ok21ArlOzaOiXP1dDo,9006
+pyafv-0.4.0.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=QLeUU1ztJ_1r8s8Lv1p30i_l6hfxrqPOsnadE6C46es,42
+pyafv/cell_geom.cpython-310-darwin.so,sha256=cdBB6q9H4xwVplQTO9ITn588_Mbr8s_U2sRRX16DrrU,331680
+pyafv/__init__.py,sha256=6gCRIilt_3jbXBu0UM5X3zbm8SNZha8HSU4Cy-JLjGg,467
+pyafv/finite_voronoi.py,sha256=RbSfY8jZEBNt9u9-fzaLcYtt-V4yA033u1cvtV45WvM,45180
+pyafv/physical_params.py,sha256=a0DP1xZnua_tq44kCDFwJygxUoi0mTm7g-OH6Mwb8QI,8697
+pyafv/calibrate/deformable_polygon.py,sha256=u3sfRmlCt6IuBGwGzM6jVAZ17CuiNShYrAMHLW0oOzE,12466
+pyafv/calibrate/__init__.py,sha256=_4Z0PbRa0QkyS43TXWYb4-nj36_ieY_rauvxU6ZSEbM,405
+pyafv/calibrate/core.py,sha256=xkGbtk2ZU4P_wC5s9NggaxpBV9qHdH1rCJTu4OgTsFw,4065

pyafv-0.4.0.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: false
+Tag: cp310-cp310-macosx_11_0_arm64
+Generator: delocate 0.13.0
+

pyafv-0.4.0.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.