pyafv 0.3.9__cp312-cp312-musllinux_1_2_aarch64.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 value of the small cutoff :math:`\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-0.3.9.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: pyafv
+Version: 0.3.9
+Summary: Python implementation of the active-finite-Voronoi (AFV) model
+Project-URL: Homepage, https://github.com/wwang721/pyafv
+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
+```
+
+
+## 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.3.9.dist-info/RECORD

@@ -0,0 +1,13 @@
+pyafv/__init__.py,sha256=i6DtniJfMN8_wiOWpNGhPCU7OdQhOANfJfF56oGguVM,426
+pyafv/_version.py,sha256=MtcRvCNzt93nWiO-J1vZqECrdCt8hCDfnoD9cjIQb5o,42
+pyafv/backend.py,sha256=O15-rtzPQvTl_fIyZu4L0LU8UG4uRnAuq4bi5HBlKy8,418
+pyafv/cell_geom.cpython-310-aarch64-linux-gnu.so,sha256=YW8lhLxaqM-nyt00j75uupPPToDnodekBZEMDvbU8gI,1440976
+pyafv/cell_geom.cpython-311-aarch64-linux-musl.so,sha256=0xRO0lftXNp3tCkwX12Tt65pKAIQvKBGVhk02klBrrg,1514616
+pyafv/cell_geom.cpython-312-aarch64-linux-musl.so,sha256=BPZ6Hb53-HroUa7PguJ94tkqQPsDSPwxNATgDtQDppQ,1594448
+pyafv/cell_geom_fallback.py,sha256=XeafJJFV-ykAaKT-UoDnX7FIbmNXChzJn1AwVgQIM-8,9142
+pyafv/finite_voronoi.py,sha256=SZS4VY4bGTUBUBHc8Zqtw0CpTalFZoc3ExDMVo7jbfc,44873
+pyafv/physical_params.py,sha256=XL3f4jYb8ltOfdFowXBcc2aauyyNHW5avOBRagg4jzI,5192
+pyafv-0.3.9.dist-info/METADATA,sha256=WknbQMcrco00NHz9261rM0lk-uhGkeSJITy9RM9J41E,8461
+pyafv-0.3.9.dist-info/WHEEL,sha256=dhN-x1_awsBUMQblQjs8plMLHwphdjrL5H1eYKLTr8o,110
+pyafv-0.3.9.dist-info/RECORD,,
+pyafv-0.3.9.dist-info/licenses/LICENSE,sha256=TNjxBxdiOzyewn2FP7g1FjW3CJoxiGCY6ShPVFv02G8,1065

pyafv-0.3.9.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: false
+Tag: cp312-cp312-musllinux_1_2_aarch64
+

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