Merge pull request #345 from GazzolaLab/update-0.3.2

Update 0.3.2
GazzolaLab · Mar 26, 2024 · b8c8807 · b8c8807
2 parents 7095d9e + d3fb41f
commit b8c8807
Show file tree

Hide file tree

Showing 85 changed files with 10,452 additions and 2,665 deletions.
diff --git a/.coveragerc b/.coveragerc
@@ -8,6 +8,8 @@ exclude_lines =
     def __repr__
     from
     import
+    raise AssertionError
+    raise NotImplementedError
 show_missing = true
 
 [run]

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -20,7 +20,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10"]
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
         os: [ubuntu-latest, macos-latest] #, windows-latest] # Run macos tests if really required, since they charge 10 times more for macos
         include:
           - os: ubuntu-latest

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -61,7 +61,7 @@ make pre-commit-install
 ```
 
 If you are planning to contribute to the examples,
-extra dependencies can be installed using `poetry install -E examples`.
+extra dependencies can be installed using `make install_examples_dependencies`.
 
 If you are planning to contribute on documentation, extra dependencies can be installed
 using `poetry install -E docs`.

diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019-2023 GazzolaLab
+Copyright (c) 2019-2024 GazzolaLab
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -8,12 +8,12 @@ PyElastica is the python implementation of **Elastica**: an *open-source* projec
 
 [![gallery][link-readme-gallary]][link-project-website]
 
-Visit [cosseratrods.org][link-project-website] for more information and learn about Elastica and Cosserat rod theory.
+Visit [www.cosseratrods.org][link-project-website] for more information and learn about Elastica and Cosserat rod theory.
 
 ## How to Start
 [![PyPI version][badge-pypi]][link-pypi] [![Documentation Status][badge-docs-status]][link-docs-status]
 
-PyElastica is compatible with Python 3.8 - 3.10.
+PyElastica is compatible with Python 3.8 - 3.11.
 
 ~~~bash
 $ pip install pyelastica
@@ -31,6 +31,11 @@ Options can be combined e.g.
 $ pip install "pyelastica[examples,docs]"
 ```
 
+For plotting videos, ffmpeg has to be installed:
+```bash
+$ conda install -c conda-forge ffmpeg
+```
+
 Documentation of PyElastica is available [here][link-docs-website].
 
 If you want to simulate magnetic Cosserat rods interacting with external magnetic environments you can install the derived package using
@@ -77,8 +82,11 @@ We ask that any publications which use Elastica cite as following:
 </details>
 
 ## List of publications and submissions
+- [Soft, slender and active structures in fluids: embedding Cosserat rods in vortex methods](https://doi.org/10.48550/arXiv.2401.09506) (UIUC 2024)
+- [Neural models and algorithms for sensorimotor control of an octopus arm](https://doi.org/10.48550/arXiv.2402.01074)(UIUC 2024)
+- [On the mechanical origins of waving, coiling and skewing in Arabidopsis thaliana roots](https://www.pnas.org/doi/10.1073/pnas.2312761121) (Tel Aviv University, UIUC 2024) (PNAS)
 - [Topology, dynamics, and control of an octopus-analog muscular hydrostat](https://arxiv.org/abs/2304.08413) (UIUC, 2023)
-- [Hierarchical control and learning of a foraging CyberOctopus](https://arxiv.org/abs/2302.05811) (UIUC, 2023)
+- [Hierarchical control and learning of a foraging CyberOctopus](https://onlinelibrary.wiley.com/doi/full/10.1002/aisy.202300088) (UIUC, 2023) (Advanced Intelligent Systems)
 - [Energy-shaping control of a muscular octopus arm moving in three dimensions](https://royalsocietypublishing.org/doi/full/10.1098/rspa.2022.0593) (UIUC, 2023) (Proceedings of the Royal Society A 2023)
 - [A sensory feedback control law for octopus arm movements](https://ieeexplore.ieee.org/abstract/document/9993021/) (UIUC, 2022) (IEEE CDC 2022)
 - [Control-oriented modeling of bend propagation in an octopus arm](https://ieeexplore.ieee.org/abstract/document/9867689/) (UIUC, 2021) (IEEE ACC 2022)
@@ -93,16 +101,17 @@ We ask that any publications which use Elastica cite as following:
 
 We have created several Jupyter notebooks and Python scripts to help users get started with PyElastica. The Jupyter notebooks are available on Binder, allowing you to try out some of the tutorials without having to install PyElastica.
 
-We have also included an example script for visualizing PyElastica simulations using POVray. This script is located in the examples folder ([`examples/visualization`](examples/visualization)).
+We have also included an example script for visualizing PyElastica simulations using POVray. This script is located in the examples folder ([`examples/Visualization`](examples/Visualization)).
 
 ## Contribution
 
 If you would like to participate, please read our [contribution guideline](CONTRIBUTING.md)
 
-PyElastica is developed by the [Gazzola Lab][link-lab-website] at the University of Illinois at Urbana-Champaign.
+PyElastica is developed by the [Gazzola Lab][link-lab-website] at the University of Illinois Urbana-Champaign.
 
 ## Senior Developers ✨
 _Names arranged alphabetically_
+- Ali Albazroun
 - Arman Tekinalp
 - Chia-Hsien Shih (Cathy)
 - Fan Kiat Chan

diff --git a/docs/api/connections.rst b/docs/api/connections.rst
@@ -1,4 +1,4 @@
-Connections / Contact / Joints
+Connections / Joints
 ==============================
 
 .. _connections:
@@ -8,44 +8,34 @@ Connections / Contact / Joints
 Description
 -----------
 
-.. rubric:: Available Connection/Contact/Joints
+.. rubric:: Available Connections/Joints
 
 .. autosummary::
    :nosignatures:
 
    FreeJoint
-   ExternalContact
    FixedJoint
    HingeJoint
-   SelfContact
 
 Compatibility
 ~~~~~~~~~~~~~
 
-=============================== ==== =========== 
-Connection / Contact / Joints   Rod  Rigid Body
-=============================== ==== =========== 
+=============================== ==== ===========
+Connection / Joints   		Rod  Rigid Body
+=============================== ==== ===========
 FreeJoint                       ✅   ❌
-ExternalContact                 ✅   ❌
 FixedJoint                      ✅   ❌
 HingeJoint                      ✅   ❌
-SelfContact                     ✅   ❌
-=============================== ==== =========== 
+=============================== ==== ===========
 
-Built-in Connection / Contact / Joint
+Built-in Connection / Joint
 -------------------------------------
 
 .. autoclass:: FreeJoint
-   :special-members: __init__
-
-.. autoclass:: ExternalContact
-   :special-members: __init__
+   :special-members: __init__,apply_forces,apply_torques
 
 .. autoclass:: FixedJoint
-   :special-members: __init__
+   :special-members: __init__,apply_forces,apply_torques
 
 .. autoclass:: HingeJoint
-   :special-members: __init__
-
-.. autoclass:: SelfContact
-   :special-members: __init__
+   :special-members: __init__,apply_forces,apply_torques
diff --git a/docs/api/contact.rst b/docs/api/contact.rst
@@ -0,0 +1,51 @@
+Contact
+==============================
+
+.. _contact:
+
+.. automodule:: elastica.contact_forces
+
+Description
+-----------
+
+.. rubric:: Available Contact Classes
+
+.. autosummary::
+   :nosignatures:
+
+   NoContact
+   RodRodContact
+   RodCylinderContact
+   RodSelfContact
+   RodSphereContact
+   RodPlaneContact
+   RodPlaneContactWithAnisotropicFriction
+   CylinderPlaneContact
+
+
+Built-in Contact Classes
+-------------------------------------
+
+.. autoclass:: NoContact
+   :special-members: __init__,apply_contact
+
+.. autoclass:: RodRodContact
+   :special-members: __init__,apply_contact
+
+.. autoclass:: RodCylinderContact
+   :special-members: __init__,apply_contact
+
+.. autoclass:: RodSelfContact
+   :special-members: __init__,apply_contact
+
+.. autoclass:: RodSphereContact
+   :special-members: __init__,apply_contact
+
+.. autoclass:: RodPlaneContact
+   :special-members: __init__,apply_contact
+
+.. autoclass:: RodPlaneContactWithAnisotropicFriction
+   :special-members: __init__,apply_contact
+
+.. autoclass:: CylinderPlaneContact
+   :special-members: __init__,apply_contact
diff --git a/docs/api/external_forces.rst b/docs/api/external_forces.rst
@@ -63,25 +63,25 @@ Built-in External Forces
    :noindex:
 
 .. autoclass:: NoForces
-   :special-members: __init__
+   :special-members: __init__,apply_forces,apply_torques
 
 .. autoclass:: EndpointForces
-   :special-members: __init__
+   :special-members: __init__,apply_forces,apply_torques
 
 .. autoclass:: GravityForces
-   :special-members: __init__
+   :special-members: __init__,apply_forces,apply_torques
 
 .. autoclass:: UniformForces
-   :special-members: __init__
+   :special-members: __init__,apply_forces,apply_torques
 
 .. autoclass:: UniformTorques
-   :special-members: __init__
+   :special-members: __init__,apply_forces,apply_torques
 
 .. autoclass:: MuscleTorques
-   :special-members: __init__
+   :special-members: __init__,apply_forces,apply_torques
 
 .. autoclass:: EndpointForcesSinusoidal
-   :special-members: __init__
+   :special-members: __init__,apply_forces,apply_torques
 
 Built-in Environment Interactions
 ---------------------------------

diff --git a/docs/api/surface.rst b/docs/api/surface.rst
@@ -0,0 +1,16 @@
+Surface
+==========
+
++----------+----+
+| type     |    |
++==========+====+
+| plane    |    |
++----------+----+
+
+.. automodule:: elastica.surface.surface_base
+   :members:
+   :exclude-members: __weakref__
+
+.. automodule:: elastica.surface.plane
+   :members:
+   :exclude-members: __weakref__
diff --git a/docs/conf.py b/docs/conf.py
@@ -22,7 +22,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'PyElastica'
-copyright = '2023, Gazzola Lab'
+copyright = '2024, Gazzola Lab'
 author = 'Gazzola Lab'
 
 # The full version, including alpha/beta/rc tags

diff --git a/docs/index.rst b/docs/index.rst
@@ -54,9 +54,11 @@ If you are interested to contribute, please read `contribution-guide`_ first.
 
    api/rods
    api/rigidbody
+   api/surface
    api/constraints
    api/external_forces
    api/connections
+   api/contact
    api/callback
    api/time_steppers
    api/damping

diff --git a/docs/intro_page.rst.inc b/docs/intro_page.rst.inc
@@ -48,7 +48,7 @@ Details can be found `here <https://github.com/armantekinalp/MagnetoPyElastica>`
 
 Elastica++
 ==========
-Elastica++ is a C++ implementation of Elastica. The expected release date for the beta version is 2023 Q4.
+Elastica++ is a C++ implementation of Elastica. The expected release date for the beta version is 2024 Q4.
 
 .. _project website: https://cosseratrods.org
 .. _GitHub repo: https://github.com/GazzolaLab/PyElastica
diff --git a/docs/overview/installation.md b/docs/overview/installation.md
@@ -2,7 +2,7 @@
 
 ## Instruction
 
-PyElastica requires Python 3.8 - 3.10, which needs to be installed prior to using PyElastica. For information on installing Python, see [here](https://realpython.com/installing-python/). If you are interested in using a package manager like Conda, see [here](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html).
+PyElastica requires Python 3.8 - 3.11, which needs to be installed prior to using PyElastica. For information on installing Python, see [here](https://realpython.com/installing-python/). If you are interested in using a package manager like Conda, see [here](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html).
 
 :::{note}
 Python version above 3.8 is tested only in Ubuntu and Mac OS. For Windows 10, some of the dependencies were not yet compatible.

diff --git a/elastica/__init__.py b/elastica/__init__.py
@@ -1,10 +1,17 @@
 from collections import defaultdict
-from elastica.rod.knot_theory import KnotTheory, KnotTheoryCompatibleProtocol
+from elastica.rod.knot_theory import (
+    KnotTheory,
+    KnotTheoryCompatibleProtocol,
+    compute_link,
+    compute_twist,
+    compute_writhe,
+)
 from elastica.rod.rod_base import RodBase
 from elastica.rod.cosserat_rod import CosseratRod
 from elastica.rigidbody.rigid_body import RigidBodyBase
 from elastica.rigidbody.cylinder import Cylinder
 from elastica.rigidbody.sphere import Sphere
+from elastica.surface.plane import Plane
 from elastica.boundary_conditions import (
     ConstraintBase,
     FreeBC,
@@ -36,6 +43,16 @@
     HingeJoint,
     SelfContact,
 )
+from elastica.contact_forces import (
+    NoContact,
+    RodRodContact,
+    RodCylinderContact,
+    RodSelfContact,
+    RodSphereContact,
+    RodPlaneContact,
+    RodPlaneContactWithAnisotropicFriction,
+    CylinderPlaneContact,
+)
 from elastica.callback_functions import CallBackBaseClass, ExportCallBack, MyCallBack
 from elastica.dissipation import (
     DamperBase,
@@ -48,6 +65,8 @@
 from elastica.modules.constraints import Constraints
 from elastica.modules.forcing import Forcing
 from elastica.modules.damping import Damping
+from elastica.modules.contact import Contact
+
 from elastica.transformations import inv_skew_symmetrize
 from elastica.transformations import rotate
 from elastica._calculus import (
@@ -60,7 +79,7 @@
 )
 from elastica._linalg import levi_civita_tensor
 from elastica.utils import isqrt
-from elastica.typing import RodType, SystemType
+from elastica.typing import RodType, SystemType, AllowedContactType
 from elastica.timestepper import (
     integrate,
     PositionVerlet,