Solving mesh collision (#263)

* Fix for Issues #261 - cell division failed at the border

* Fix Mesh creation

Surface mesh create wasn't create all faces. Now it is fixed. 
Also : -add two methods to Mesh to list faces and vertices. 
           -generalised coordinates
           -add `write_polygon_mesh` to export mesh into .ply to visualised with blinder

* Add 2D collision solver

Add class to solve collision in 2D or in 3D. 
3D collision solver need to be fixed

* Update README.md

Add `How to cite` section
Add `Geometry` section
Add `Publications` section
Update bibliography link

* Generalised wich vertex penetrate face

* Attempt to set out particular cases

* Detect and fix self-crossing face

Unable to make this algo works... https://europepmc.org/article/PMC/3660981
Use ordered vertices and their angle position.
     -> uncrossed face : angles are monotonically increasing
     -> crossed face : angles are not monotonically increasing

* Use `.apply()` 

Need to recalculate angle_e for twisted face
One fix which is only suitable for 2D lateral sheet...

* ENH: write `mean_XX` method in `Epithelium` class (Issue #224)

* Fix according to comments

* Fix Issue #258 ax argument not considered in `plt_draw.sheet_view`

* ENH: pass column name to `data_at_opposite` issue (#245)

* Add publication and remove bibtex reference

* Add check face convexity

* Use reset_index and code simplification

* yAdd to_mesh function (issue #221) and some test

* Remove the use of reset_index in face_self_intersect

* use ipv_draw with 2D data

* Fix solution after detection point inside polygon

* Remove solving collision for 2 same face...

* Abord vertex displacement if it creates twisted face

* New way to calculate the position of "penetrate" vertices

For now, it is the best way to fix collision (compare to what I tried before). So when a vertex is inside an other face. It is pullback by 10% of the length of the ([v-f1]+[v-f2]/2). with v, f1, f2 position of vertices and center of face 1 and face 2, which are the faces to which the vertex belongs.  It is not perfect and very arbitrary for now, but it avoids vertex displacement at strange place.

* WIP - use force field to fix collision

* Small fix

* Remove function duplication due to circular import

* Calculate "repulsion" gradient in the effector method. Remove loop

* Fix tests

Remove collisions tests
Fix method call in meshes test
Comment "update_repulstion" method in planar geometry

* Add lateralsheet shapes + test

* Update publication + add collapse texte

* Add test for Repulsion effector

* Add test update repulsion

* Remove unused import

* Add `drop_face` to allow hole (issues #220 and #141) (associate #221)

* Update readme.md

* Update publications in README.md

* Add `lineage` attribute to `Epithelium`

In order to keep track of cell lineage

* Remove memory oscillation

* dependency (#277)

* bug fixes

---------

Co-authored-by: Guillaume Gay <[email protected]>

.gitignore

@@ -81,3 +81,5 @@ dist/
 
 ## pytest
 .pytest_cacheflycheck_*
+
+.idea/

README.md

@@ -28,6 +28,8 @@ This commit to the **new default branch `main` is the official start of the 1.0
 
 <hr/>
 
+<<<<<<< HEAD
+=======
 
 [![Doc Status](https://readthedocs.org/projects/tyssue/badge/?version=latest)](http://tyssue.readthedocs.io/en/latest/
 )
@@ -36,33 +38,46 @@ This commit to the **new default branch `main` is the official start of the 1.0
 
 
 
+>>>>>>> main
 | Name | Downloads | Version | Platforms |
 | --- | --- | --- | --- |
 | [![Conda Recipe](https://img.shields.io/badge/recipe-tyssue-green.svg)](https://anaconda.org/conda-forge/tyssue) | [![Conda Downloads](https://img.shields.io/conda/dn/conda-forge/tyssue.svg)](https://anaconda.org/conda-forge/tyssue) | [![Conda Version](https://img.shields.io/conda/vn/conda-forge/tyssue.svg)](https://anaconda.org/conda-forge/tyssue) | [![Conda Platforms](https://img.shields.io/conda/pn/conda-forge/tyssue.svg)](https://anaconda.org/conda-forge/tyssue) |
 
-# tyssue is now published in the Journal of Open Source Software!
+| Coverage | Doc | CHAT |
+| --- | --- | --- |
+| [![Coverage Status](https://coveralls.io/repos/DamCB/tyssue/badge.svg)](https://coveralls.io/r/DamCB/tyssue) | [![Doc Status](https://readthedocs.org/projects/tyssue/badge/?version=latest)](http://tyssue.readthedocs.io/en/latest/) |  [![Join the chat at https://gitter.im/DamCB/tyssue](https://badges.gitter.im/DamCB/tyssue.svg)](https://gitter.im/DamCB/tyssue?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) |
 
-[![DOI](https://joss.theoj.org/papers/10.21105/joss.02973/status.svg)](https://doi.org/10.21105/joss.02973)
 
+# tyssue is now published in the Journal of Open Source Software!
 
+| ZENODO DOI | JOSS DOI | 
+| --- | --- |
+| [![DOI](https://zenodo.org/badge/32533164.svg)](https://zenodo.org/badge/latestdoi/32533164) | [![DOI](https://joss.theoj.org/papers/10.21105/joss.02973/status.svg)](https://doi.org/10.21105/joss.02973) |
 
 The `tyssue` library seeks to provide a unified interface to implement
-bio-mechanical models of living tissues.
+biomechanical models of living tissues.
 It's main focus is on **vertex based epithelium models**.
 
 ## Overview
 
 ### What kind of Models does it implement?
 
 The first model implemented is the one described in
-Monier et al. [monier2015apico]. It is an example of a vertex model,
+Monier et al.<sup id="a1">[1](#f1)</sup>. It is an example of a vertex model,
 where the interactions are only evaluated on the apical surface sheet
-of the epithelium. The second class of models is still at an
+of the epithelium. The second class of models is still at a
 stage. They implement a description of the tissue's rheology, within a
 dissipation function formalism.
 
 ![The two models considered](doc/illus/two_models.png)
 
+### What kind of geometry does it model ?
+`tyssue` allows to model different geometries in 2D and in 3D.  Presentation of the different geometries and how to create them are shown in this [notebook](https://github.com/DamCB/tyssue-demo/blob/master/01-Geometry.ipynb). 
+<p align="center">
+ <img src="doc/illus/geometry.png" width="500">
+</p>
+
+
 ### General Structure of the modeling API
 
 #### Design principles
@@ -71,7 +86,7 @@ dissipation function formalism.
 
 Each biological question, be it in morphogenesis or cancer studies is
 unique, and requires tweeking of the models developed by the
-physicists. Most of the modelling softwares follow an architecture
+physicists. Most of the modelling software follow an architecture
 based on a core C++ engine with a combinaison of markup or scripting
 capacities to run specific simulation.
 
@@ -82,13 +97,13 @@ possibilities as open as possible.
 > Separate structure, geometry and models
 
 We seek to have a design as modular as possible, to allow the same
-epithlium mesh to be fed to different physical models.
+epithelium mesh to be fed to different physical models.
 
 > Accessible, easy to use data structures
 
 The core of the tyssue library rests on two structures: a set of
 `pandas DataFrame` holding the tissue geometry and associated data,
-and nested dictionnaries holding the model parameters, variables and
+and nested dictionaries holding the model parameters, variables and
 default values.
 
 ![Tyssue data structure](doc/illus/tyssue_data_management.png)
@@ -100,7 +115,7 @@ methods to manipulate indexing of the dataframes to ease calculations.
 The mesh structure is heavily inspired by
 [CGAL Linear Cell Complexes](http://doc.cgal.org/latest/Linear_cell_complex/index.html),
 most importantly, in the case of a 2D vertex sheet for example, each
-junction edge between the cells is "splitted" between two oriented **half
+junction edge between the cells is "splited" between two oriented **half
 edges**.
 
 
@@ -121,27 +136,41 @@ sheet.sanitize()
 fig, ax = sheet_view(sheet)
 ```
 
-### Features
-
-* Easy data manipulation.
-* Multiple geometries (Sheets in 2D and 3D, monolayers, bulk).
-* Easy to extend.
-* 2D (matplotlib) and 3D (ipyvolume) customisable visualisation.
-* Easy quasistatic model definition.
-* Self collision detection. **new in 0.3**
-
-
 ### Documentation
 
 * The documentation is now browsable on [tyssue.io](http://tyssue.io)
 * The old documentation is still browsable online [here](http://tyssue.readthedocs.io/en/latest/)
 * Introduction notebooks are available [here](https://github.com/DamCB/tyssue-demo).
 
+## Visualisation
+Thanks to @kephale, there is a napari plugin to visualise tyssue simulation output.  
+You can find it [here](https://github.com/kephale/napari-tyssue).
+
+
+### What's new in 1.0 ? 
+* No collision in 2D (use effector `Repulsion`)
+* Add new geometry : 2D lateral geometry
+* Add mean calculation in `Epithelium`
+* Add `sheet` conversion to `mesh` from `Meshio`
+* Allow hole in 2D sheet
+* Fix some visualisation
+
+### Roadmap
+You are welcome to participate in the development of `Tyssue`.  
+What is planned for the future of `Tyssue`?
+* Solve collision in 2.5D & 3D
+* Use ZARR instead of HDF5 as base file format
+* Upgrade geometry creation 
+  * Compound geometry to form complex shape
+  * Use biological image as blueprint
+* Add rheology model
+* Switch to github-action for continuous integration
+
 ### Mailing list:
 
 [email protected] - https://framalistes.org/sympa/info/tyssue
 
-Subscribe ➙ https://framalistes.org/sympa/subscribe/tyssue
+Subscribe ➙ https://framalistes.org/sympa/subscribe/tyssue  
 Unsubscribe ➙ https://framalistes.org/sympa/sigrequest/tyssue
 
 
@@ -160,7 +189,9 @@ Unsubscribe ➙ https://framalistes.org/sympa/sigrequest/tyssue
 As all the dependencies are already completely supported in
 python 3.x, **we won't be maintaining a python 2.x version**, because
 it's time to move on...
-
+<details>
+  <summary>Show dependencies</summary>
+
 ### Core
 
 - CGAL > 4.7
@@ -184,6 +215,9 @@ it's time to move on...
 - coverage
 - pytest-cov
 
+</details>
+
+
 ## Install
 
 You can install the library with the conda package manager
@@ -204,29 +238,42 @@ You can also install tyssue from PyPi, this is a CGAL-less version (pure python)
 
 See [INSTALL.md](INSTALL.md) for a step by step install, including the necessary python environment.
 
+## How to cite 
+If you find `tyssue` useful please cite [this repository](https://github.com/DamCB/tyssue) using its DOI as follows:
 
-## Licence
+> Theis, Suzanne, Gay, (2021). Tyssue: an epithelium simulation library. Journal of Open Source Software, 6(62), 2973 doi:[https://doi.org/10.21105/joss.02973](https://doi.org/10.21105/joss.02973)
+> 
+> Zenodo doi:10.5281/zenodo.4817609
 
-Since version 0.3, this project is distributed under the terms of the [General Public Licence](https://www.gnu.org/licenses/gpl.html).
+## Publications
+If `tyssue` has made a substantial contribution to your work, please edit this file and open a PR.
 
+Lou Y, Rupprecht JF, Theis S, Hiraiwa T, and Saunders TE. Curvature-induced cell rearrangements in biological tissues. Phys. Rev. Lett. 2023. doi: [10.1103/PhysRevLett.130.108401](https://doi.org/10.1103/PhysRevLett.130.108401) 
 
-Versions 2.4 and earlier were distributed under the [Mozilla Public Licence](https://www.mozilla.org/en-US/MPL/2.0/).
+Rahman T, Peters F and Wan LQ. Cell Jamming Regulates Epithelial Chiral Morphogenesis. J Biomech. 2023. doi: [10.1016/j.jbiomech.2023.111435](https://doi.org/10.1016/j.jbiomech.2023.111435)
 
-If GPL licencing is too restrictive for your intended usage, please contact the maintainer.
+Fiorentino J and Scialdone A. The role of cell geometry and cell-cell communication in gradient sensing. PLoS Comput Biol. 2022 doi: [10.1371/journal.pcbi.1009552](10.1371/journal.pcbi.1009552)  
+Related repository: [https://github.com/ScialdoneLab/2DLEGI](https://github.com/ScialdoneLab/2DLEGI)
 
-## Bibliography
+Courcoubetis G, Xu C, Nuzhdin SV, Haas S. Avalanches during epithelial tissue growth; Uniform Growth and a drosophila eye disc model, PLoS Comput Biol 2022 doi: [10.1371/journal.pcbi.1009952](https://doi.org/10.1371/journal.pcbi.1009952)
 
-* There is a [Bibtex file here](doc/bibliography/tyssue.bib) with collected relevant publications.
+Martin E, Theis S, Gay G, Monier B, Rouvière C, Suzanne M. Arp2/3-dependent mechanical control of morphogenetic robustness in an inherently challenging environment. Dev Cell. 2021 doi: [10.1016/j.devcel.2021.01.005](https://doi.org/10.1016/j.devcel.2021.01.005)  
+Related repository: [https://github.com/suzannelab/polarity](https://github.com/suzannelab/polarity) 
 
-The tyssue library stemed from a refactoring of the `leg-joint` code used in [monier2015apico].
+Gracia M, Theis S, Proag A, Gay G, Benassayag C, Suzanne M. Mechanical impact of epithelial-mesenchymal transition on epithelial morphogenesis in Drosophila. Nat Commun. 2019 doi: [10.1038/s41467-019-10720-0](https://doi.org/10.1038/s41467-019-10720-0)  
+Related repository: [https://github.com/suzannelab/invagination](https://github.com/suzannelab/invagination)
+
+Monier B, Gettings M, Gay G, Mangeat T, Schott S, Guarner A, Suzanne M. Apico-basal forces exerted by apoptotic cells drive epithelium folding. Nature. 2015 doi: [10.1038/nature14152](https://doi.org/10.1038/nature14152)    
+Related repository: [https://github.com/glyg/leg-joint](https://github.com/glyg/leg-joint)
+
+## Licence
 
+Since version 0.3, this project is distributed under the terms of the [General Public Licence](https://www.gnu.org/licenses/gpl.html).
 
-[monier2015apico]: Monier, B. et al. Apico-basal forces exerted by
-  apoptotic cells drive epithelium folding. Nature 518, 245–248 (2015).
 
-[Tamulonis2013]: Tamulonis, C. Cell-based models. (Universiteit ven Amsterdam, 2013). doi:10.1177/1745691612459060.
+Versions 2.4 and earlier were distributed under the [Mozilla Public Licence](https://www.mozilla.org/en-US/MPL/2.0/).
 
-[Tlili2013]: Tlili,S. et al. Mechanical formalism for tissue dynamics. 6, 23 (2013).
+If GPL licencing is too restrictive for your intended usage, please contact the maintainer.
 
 ## Research notice
 Please note that this repository is participating in a study into sustainability
@@ -238,3 +285,7 @@ Data collected will include number of contributors, number of PRs, time taken to
 
 For more information, please visit
 [our informational page](https://sustainable-open-science-and-software.github.io/) or download our [participant information sheet](https://sustainable-open-science-and-software.github.io/assets/PIS_sustainable_software.pdf).
+
+<hr/>
+
+<b id="f1">1</b> : Monier B, Gettings M, Gay G, Mangeat T, Schott S, Guarner A, Suzanne M. Apico-basal forces exerted by apoptotic cells drive epithelium folding. Nature. 2015 doi: [10.1038/nature14152](https://doi.org/10.1038/nature14152) [↩](#a1)

doc/bibliography/tyssue.bib

@@ -4301,4 +4301,15 @@ @article{zhaoModelingTumorClonal2016
   file = {/home/guillaume/Zotero/storage/EDFS69XJ/Zhao et al. - 2016 - Modeling Tumor Clonal Evolution for Drug Combinati.pdf}
 }
 
+@article{rahman_cell_2022,
+	title = {Cell Jamming Regulates Epithelial Chiral Morphogenesis},
+	url = {https://papers.ssrn.com/abstract=4052248},
+	doi = {10.2139/ssrn.4052248},
+	number = {4052248},
+	author = {Rahman, Tasnif and Wan, Leo Q.},
+	urldate = {2022-11-15},
+	date = {2022-03-08},
+	keywords = {cell chirality, cell vertex model, epithelium, left-right asymmetry},
+}
+
 @preamble{ "\ifdefined\DeclarePrefChars\DeclarePrefChars{'’-}\else\fi " }

tests/collisions/test_sheet_collision.py

@@ -0,0 +1,54 @@
+from pathlib import Path
+
+from tyssue import Sheet, SheetGeometry, collisions
+from tyssue.collisions import solvers
+from tyssue.io import hdf5
+from tyssue.stores import stores_dir
+
+
+def test_detection():
+    sheet = Sheet("crossed", hdf5.load_datasets(Path(stores_dir) / "sheet6x5.hf5"))
+    sheet.vert_df.z = 5 * sheet.vert_df.x ** 2
+    # sheet.vert_df[sheet.coords] += np.random.normal(scale=0.001, size=(sheet.Nv, 3))
+    SheetGeometry.update_all(sheet)
+
+    sheet.vert_df.x -= 35 * (sheet.vert_df.x / 2) ** 3
+    SheetGeometry.update_all(sheet)
+    colliding_edges = set(collisions.self_intersections(sheet).flatten())
+
+    expected = {0, 1, 5, 6, 9, 32, 34, 35, 83, 84, 152, 153}
+    assert colliding_edges == expected
+
+
+# def test_solving():
+#
+#     sheet = Sheet("crossed", hdf5.load_datasets(Path(stores_dir) / "sheet6x5.hf5"))
+#     sheet.vert_df.z = 5 * sheet.vert_df.x**2
+#     SheetGeometry.update_all(sheet)
+#     positions_buffer = sheet.vert_df[sheet.coords].copy()
+#
+#     sheet.vert_df.x -= 35 * (sheet.vert_df.x / 2) ** 3
+#     SheetGeometry.update_all(sheet)
+#     colliding_edges = collisions.self_intersections(sheet)
+#     boxes = solvers.CollidingBoxes(sheet, positions_buffer, colliding_edges)
+#     boxes.solve_collisions(shyness=0.01)
+#     assert collisions.self_intersections(sheet).size == 0
+#     assert sheet.vert_df.loc[[22, 12], "x"].diff().loc[12] == 0.01
+
+
+# def test_already():
+#     # GH111
+#     sheet = Sheet("crossed", hdf5.load_datasets(Path(stores_dir) / "sheet6x5.hf5"))
+#     sheet.vert_df.z = 5 * sheet.vert_df.x**2
+#     SheetGeometry.update_all(sheet)
+
+#     sheet.vert_df.x -= 35 * (sheet.vert_df.x / 2) ** 3
+#     SheetGeometry.update_all(sheet)
+#     positions_buffer = sheet.vert_df[sheet.coords].copy()
+#     sheet.vert_df.x -= 0.1 * (sheet.vert_df.x / 2) ** 3
+#     SheetGeometry.update_all(sheet)
+#     colliding_edges = collisions.self_intersections(sheet)
+#     boxes = solvers.CollidingBoxes(sheet, positions_buffer, colliding_edges)
+#     boxes.solve_collisions(shyness=0.01)
+#     colliding_edges = collisions.self_intersections(sheet)
+#     assert len(colliding_edges) == 0

tests/core/test_lateralsheet.py

@@ -0,0 +1,21 @@
+# from numpy.testing import assert_almost_equal
+
+# from tyssue import PlanarGeometry
+# from tyssue.generation.shapes import (
+#     generate_lateral_tissue
+# )
+
+# def test_lateralsheet():
+
+#     sheet = generate_lateral_tissue(15, 15, 2)
+#     PlanarGeometry.update_all(sheet)
+#     apical_length = sheet.edge_df.loc[sheet.apical_edges, "length"]
+#     basal_length = sheet.edge_df.loc[sheet.basal_edges, "length"]
+#     lateral_length = sheet.edge_df.loc[sheet.lateral_edges, "length"]
+
+#     assert sheet.Nf == 15
+#     assert sheet.Ne == 60
+#     assert sheet.Nv == 32
+#     assert_almost_equal(apical_length.mean(), 1)
+#     assert_almost_equal(basal_length.mean(), 1)
+#     assert_almost_equal(lateral_length.mean(), 2)

tests/core/test_objects.py

@@ -1012,12 +1012,12 @@ def test_ordered_edges():
 
     res_edges_2d = _ordered_edges(eptm.edge_df.loc[eptm.edge_df["face"] == 0])
     expected_edges_2d = [
-        [0, 1, 0],
-        [1, 2, 0],
-        [2, 3, 0],
-        [3, 4, 0],
-        [4, 5, 0],
-        [5, 0, 0],
+        [0, 1, 0, 0],
+        [1, 2, 0, 1],
+        [2, 3, 0, 2],
+        [3, 4, 0, 3],
+        [4, 5, 0, 4],
+        [5, 0, 0, 5],
     ]
     expected_vert_idxs = [idxs[0] for idxs in expected_edges_2d]
     assert res_edges_2d == expected_edges_2d