pyafv 0.3.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
pyafv-0.3.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Wei Wang
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
pyafv-0.3.1/PKG-INFO ADDED
@@ -0,0 +1,83 @@
1
+ Metadata-Version: 2.4
2
+ Name: pyafv
3
+ Version: 0.3.1
4
+ Summary: Python implementation of the active-finite-Voronoi (AFV) model
5
+ Author-email: "Wei Wang (汪巍)" <ww000721@gmail.com>
6
+ License: MIT License
7
+
8
+ Copyright (c) 2025 Wei Wang
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+
28
+ Project-URL: Download, https://test.pypi.org/project/pyafv/#files
29
+ Project-URL: Source Code, https://github.com/wwang721/pyafv
30
+ Requires-Python: >=3.11.11
31
+ Description-Content-Type: text/markdown
32
+ License-File: LICENSE
33
+ Requires-Dist: numpy>=2.1.3
34
+ Requires-Dist: scipy>=1.15.3
35
+ Requires-Dist: matplotlib>=3.10.7
36
+ Provides-Extra: examples
37
+ Requires-Dist: ipywidgets>=8.1.5; extra == "examples"
38
+ Requires-Dist: jupyter>=1.1.0; extra == "examples"
39
+ Requires-Dist: tqdm>=4.67.1; extra == "examples"
40
+ Dynamic: license-file
41
+
42
+ <!--[![Tests](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)-->
43
+ [![pytest](https://github.com/wwang721/pyafv/actions/workflows/tests.yml/badge.svg)](https://github.com/wwang721/pyafv/actions/workflows/tests.yml)
44
+ [![codecov](https://codecov.io/github/wwang721/pyafv/branch/main/graph/badge.svg?token=VSXSOX8HVS)](https://codecov.io/github/wwang721/pyafv/tree/main)
45
+ [![DOI](https://zenodo.org/badge/1124385738.svg)](https://doi.org/10.5281/zenodo.18091659)
46
+
47
+ Python code that implements the **active-finite-Voronoi (AFV) model**.
48
+ The AFV framework was introduced and developed in, for example, Refs. [[1](#huang2023bridging)&ndash;[3](#wang2026divergence)].
49
+
50
+
51
+ ## More information
52
+
53
+ GitHub: [https://github.com/wwang721/pyafv](https://github.com/wwang721/pyafv)
54
+
55
+ See important [**issues**](https://github.com/wwang721/pyafv/issues?q=is%3Aissue%20state%3Aclosed) for additional context, such as:
56
+ * [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)]
57
+ * [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)]
58
+ * [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)]
59
+
60
+
61
+ ## References
62
+
63
+ <table>
64
+ <tr>
65
+ <td id="huang2023bridging" valign="top">[1]</td>
66
+ <td>
67
+ 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>.
68
+ </td>
69
+ </tr>
70
+ <tr>
71
+ <td id="teomy2018confluent" valign="top">[2]</td>
72
+ <td>
73
+ 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>.
74
+ </td>
75
+ </tr>
76
+ <tr>
77
+ <td id="wang2026divergence" valign="top">[3]</td>
78
+ <td>
79
+ W. Wang (汪巍) and B. A. Camley, <em>Divergence of detachment forces in the finite-Voronoi model</em>, manuscript in preparation (2026).
80
+ </td>
81
+ </tr>
82
+ </table>
83
+
pyafv-0.3.1/README.md ADDED
@@ -0,0 +1,140 @@
1
+ <!--[![Tests](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)-->
2
+ [![pytest](https://github.com/wwang721/pyafv/actions/workflows/tests.yml/badge.svg)](https://github.com/wwang721/pyafv/actions/workflows/tests.yml)
3
+ [![codecov](https://codecov.io/github/wwang721/pyafv/branch/main/graph/badge.svg?token=VSXSOX8HVS)](https://codecov.io/github/wwang721/pyafv/tree/main)
4
+ [![DOI](https://zenodo.org/badge/1124385738.svg)](https://doi.org/10.5281/zenodo.18091659)
5
+
6
+ # PyAFV
7
+
8
+ Python code that implements the **active-finite-Voronoi (AFV) model**.
9
+ The AFV framework was introduced and developed in, for example, Refs. [[1](#huang2023bridging)&ndash;[3](#wang2026divergence)].
10
+
11
+
12
+ ## Installation
13
+
14
+ This project uses [`uv`](https://docs.astral.sh/uv/) for Python package management &ndash; a single tool to replace `pip` (⚡️10-100x faster) and `venv`.
15
+
16
+ > Python 3.11.11 is my local development version, so it is set as the minimum requirement; if you'd like to use your own Python, ensure the `which python` version meets this requirement so `uv` doesn't automatically download a different interpreter; otherwise, I recommend letting `uv` manage everything, including the Python interpreter.
17
+
18
+ After cloning the repository, Linux/macOS users (Windows users: see [below](#windows-mingw-gcc)) can synchronize the dependencies with
19
+ ```bash
20
+ uv sync
21
+ ```
22
+ or use `uv sync --no-dev` if you only intend to run the core code without development dependencies (like `pytest` for running tests).
23
+
24
+ **Notes:**
25
+ > * You can install additional packages as needed using `uv add <package_name>`.
26
+ > * In some environments (like HPC clusters), global Python path can contaminate the project environment. You may need to add the `PYTHONPATH=""` prefix to all `uv` commands to isolate the project.
27
+ > * The current version requires **Cython** (and therefore a working C/C++ compiler), though [a fallback backend](/pyafv/finite_voronoi_fallback.py) (based on early pure-Python release) is also implemented. If the Cython compiled extension is accidentally removed or corrupted (you will see a **RuntimeWarning**), you can reinstall the package with `uv sync --reinstall-package pyafv --inexact` (the `--inexact` flag prevents uv from removing any installed packages).
28
+ > * For the old pure-Python implementation with no C/C++ compiled dependencies, see [v0.1.0](https://github.com/wwang721/pyafv/releases/tag/v0.1.0) (also on [GitLab](https://gitlab.com/wwang721/py-afv/-/releases/v0.1.0)). Alternatively, remove [setup.py](/setup.py) in the root folder before running `uv sync`.
29
+
30
+
31
+ #### Windows MinGW GCC
32
+
33
+ * If you are using **MinGW GCC** (rather than MSVC) on Windows, add a `setup.cfg` at the repository root
34
+ ```ini
35
+ # setup.cfg
36
+ [build_ext]
37
+ compiler=mingw32
38
+ ```
39
+ It will then work in the same way.
40
+ <!--With this configuration in place, you even no longer need to pass the `--compiler=mingw32` flag when trying to compile with `uv run python setup.py build_ext --inplace`.-->
41
+
42
+
43
+ ## Running tests
44
+
45
+ Current CI status of the test suite, run via [GitHub Actions](/.github/workflows/tests.yml) on Python 3.12, is shown in the badge at the top of this file.
46
+
47
+ * To run the full test suite locally (located in [`tests`](/tests/)):
48
+ ```bash
49
+ uv run pytest
50
+ ```
51
+ You can also include coverage options such as `--cov` if desired. If you previously use `uv sync --no-dev`, you will need to run `uv sync` again to install the packages in the *dev* dependency group.
52
+
53
+ **Notes:**
54
+ > * A comparison against the MATLAB implementation from Ref. [[1](#huang2023bridging)] is included in [test_core.py](/tests/test_core.py).
55
+ > * Unlike [v0.1.0](https://github.com/wwang721/pyafv/releases/tag/v0.1.0), the current test suite is designed to raise errors if the Cython backend is not available, even though a pure-Python fallback implementation is provided and tested.
56
+
57
+
58
+ ## Usage
59
+
60
+ Using `uv run python`, you should be able to import `pyafv` from anywhere within the repository directory.
61
+ The following example demonstrates how to construct a finite-Voronoi diagram:
62
+ ```python
63
+ import numpy as np
64
+ import pyafv as afv
65
+
66
+ N = 100 # number of cells
67
+ pts = np.random.rand(N, 2) * 10 # initial positions
68
+ params = afv.PhysicalParams() # use default parameter values
69
+ sim = afv.FiniteVoronoiSimulator(pts, params) # initialize the simulator
70
+ sim.plot_2d(show=True) # visualize the Voronoi diagram
71
+ ```
72
+ To compute the conservative forces and extract detailed geometric information (e.g., cell areas, vertices, and edges), call:
73
+ ```python
74
+ diag = sim.build()
75
+ ```
76
+ The returned object `diag` is a Python `dict` containing these quantities.
77
+
78
+ #### More example scripts
79
+ To run the example scripts in [`examples`](/examples), you need to install at least one additional dependency, `tqdm`, via `uv add tqdm`. Then you can simply run any script in [`examples`](/examples/) with
80
+ ```bash
81
+ uv run <script_name>.py
82
+ ```
83
+ You can also install all optional dependencies (e.g., `tqdm`, `jupyter`) via `uv sync --extra examples` or `uv sync --all-extras`.
84
+
85
+ * To launch Jupyter Notebook: after `uv` has synced all extra dependencies, start Jupyter with `uv run jupyter notebook`. Do not use your system-level Jupyter, as the Python kernel of the current `uv` environment is not registered there.
86
+
87
+ > Jupyter notebooks and media are stored via [**Git LFS**](https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-git-large-file-storage). If you clone the repository without **Git LFS** installed, these files will appear as small text pointers. You can either install Git LFS to fetch them automatically or download the files manually (or download the repository as a ZIP archive) from the GitHub web interface.
88
+
89
+ * Below are representative simulation snapshots generated using the code:
90
+
91
+ | Model illustration | Periodic boundary conditions[*](/examples/jupyter/periodic_plotting.ipynb) |
92
+ |-----------------|-----------------|
93
+ | <img src="./assets/model_illustration.png" height="373"> | <img src="./assets/pbc.png" height="385">|
94
+
95
+ | Initial configuration | After relaxation | Active dynamics enabled |
96
+ |-----------------------|-----------------------|-----------------------|
97
+ | <img src="./assets/initial_configuration.png" height="300"> | <img src="./assets/relaxed_configuration.png" height="300"> | <img src="./assets/active_FV.png" height="300"> |
98
+
99
+
100
+ ## More information
101
+
102
+ See important [**issues**](https://github.com/wwang721/pyafv/issues?q=is%3Aissue%20state%3Aclosed) for additional context, such as:
103
+ * [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)]
104
+ * [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)]
105
+ * [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)]
106
+
107
+
108
+ ## Zenodo
109
+
110
+ The releases of this repository is cross-listed on [Zenodo](https://doi.org/10.5281/zenodo.18091659).
111
+
112
+
113
+ ## License
114
+
115
+ This project is licensed under the [MIT License](/LICENSE), which permits free use, modification, and distribution of the code for nearly any purpose.
116
+
117
+
118
+ ## References
119
+
120
+ <table>
121
+ <tr>
122
+ <td id="huang2023bridging" valign="top">[1]</td>
123
+ <td>
124
+ 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>.
125
+ </td>
126
+ </tr>
127
+ <tr>
128
+ <td id="teomy2018confluent" valign="top">[2]</td>
129
+ <td>
130
+ 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>.
131
+ </td>
132
+ </tr>
133
+ <tr>
134
+ <td id="wang2026divergence" valign="top">[3]</td>
135
+ <td>
136
+ W. Wang (汪巍) and B. A. Camley, <em>Divergence of detachment forces in the finite-Voronoi model</em>, manuscript in preparation (2026).
137
+ </td>
138
+ </tr>
139
+ </table>
140
+
@@ -0,0 +1,42 @@
1
+ <!--[![Tests](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)-->
2
+ [![pytest](https://github.com/wwang721/pyafv/actions/workflows/tests.yml/badge.svg)](https://github.com/wwang721/pyafv/actions/workflows/tests.yml)
3
+ [![codecov](https://codecov.io/github/wwang721/pyafv/branch/main/graph/badge.svg?token=VSXSOX8HVS)](https://codecov.io/github/wwang721/pyafv/tree/main)
4
+ [![DOI](https://zenodo.org/badge/1124385738.svg)](https://doi.org/10.5281/zenodo.18091659)
5
+
6
+ Python code that implements the **active-finite-Voronoi (AFV) model**.
7
+ The AFV framework was introduced and developed in, for example, Refs. [[1](#huang2023bridging)&ndash;[3](#wang2026divergence)].
8
+
9
+
10
+ ## More information
11
+
12
+ GitHub: [https://github.com/wwang721/pyafv](https://github.com/wwang721/pyafv)
13
+
14
+ See important [**issues**](https://github.com/wwang721/pyafv/issues?q=is%3Aissue%20state%3Aclosed) for additional context, such as:
15
+ * [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)]
16
+ * [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)]
17
+ * [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)]
18
+
19
+
20
+ ## References
21
+
22
+ <table>
23
+ <tr>
24
+ <td id="huang2023bridging" valign="top">[1]</td>
25
+ <td>
26
+ 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>.
27
+ </td>
28
+ </tr>
29
+ <tr>
30
+ <td id="teomy2018confluent" valign="top">[2]</td>
31
+ <td>
32
+ 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>.
33
+ </td>
34
+ </tr>
35
+ <tr>
36
+ <td id="wang2026divergence" valign="top">[3]</td>
37
+ <td>
38
+ W. Wang (汪巍) and B. A. Camley, <em>Divergence of detachment forces in the finite-Voronoi model</em>, manuscript in preparation (2026).
39
+ </td>
40
+ </tr>
41
+ </table>
42
+
@@ -0,0 +1,11 @@
1
+ from .physical_params import PhysicalParams, target_delta
2
+ from .simulator import FiniteVoronoiSimulator
3
+
4
+
5
+ __version__ = "0.3.1"
6
+
7
+ __all__ = [
8
+ "PhysicalParams",
9
+ "FiniteVoronoiSimulator",
10
+ "target_delta",
11
+ ]
@@ -0,0 +1,16 @@
1
+ # chooses fast vs fallback implementation
2
+
3
+ try:
4
+ from . import finite_voronoi_fast as _impl
5
+ _BACKEND_NAME = "cython"
6
+ except ImportError: # pragma: no cover
7
+ _BACKEND_NAME = "python"
8
+ from . import finite_voronoi_fallback as _impl
9
+
10
+ # ---- for explicit API ----
11
+ backend_simulator = _impl.FiniteVoronoiSimulator
12
+
13
+ __all__ = [
14
+ "backend_simulator",
15
+ "_BACKEND_NAME",
16
+ ]