Merge pull request #251 from GazzolaLab/update-0.3.1

Update 0.3.1

.github/workflows/main.yml

@@ -20,15 +20,15 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.8", "3.9", "3.10"]
         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
             path: ~/.cache/pip
           - os: macos-latest
             path: ~/Library/Caches/pip
-#          - os: windows-latest
-#            path: ~\AppData\Local\pip\Cache
+          #- os: windows-latest
+          #  path: ~\AppData\Local\pip\Cache
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
@@ -102,6 +102,6 @@ jobs:
         run: |
           make test_coverage_xml
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v2
+        uses: codecov/codecov-action@v3
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

.readthedocs.yaml

@@ -6,13 +6,11 @@ build:
   os: ubuntu-20.04
   tools: {python: "3.10"}
   jobs:
-    pre_create_environment:
-      - asdf plugin add poetry
-      - asdf install poetry latest
-      - asdf global poetry latest
-      - poetry config virtualenvs.create false  # Key
+    post_create_environment:
+      - pip install poetry
+      - poetry config virtualenvs.create false
     post_install:
-      - poetry install -E docs
+      - poetry install --all-extras
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

CONTRIBUTING.md

@@ -60,8 +60,15 @@ make install
 make pre-commit-install
 ```
 
+If you are planning to contribute to the examples,
+extra dependencies can be installed using `poetry install -E examples`.
+
+If you are planning to contribute on the functionality for simulating magnetic Cosserat rods,
+implementation details can be found [here](https://github.com/armantekinalp/MagnetoPyElastica).
+
 If you are planning to contribute on documentation, extra dependencies can be installed
-using `poetry install -E docs`. The detail instruction is included
+using `poetry install -E docs`.
+The detail instruction is included
 [here](https://github.com/GazzolaLab/PyElastica/blob/master/docs/README.md).
 
 4. Now your working environment is set!

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019-2022 GazzolaLab
+Copyright (c) 2019-2023 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

Makefile

@@ -1,6 +1,7 @@
 #* Variables
 PYTHON := python3
 PYTHONPATH := `pwd`
+AUTOFLAKE8_ARGS := -r --exclude '__init__.py' --keep-pass-after-docstring
 #* Poetry
 .PHONY: poetry-download
 poetry-download:
@@ -46,6 +47,17 @@ flake8:
 	poetry run flake8 --version
 	poetry run flake8 elastica tests
 
+.PHONY: autoflake8-check
+autoflake8-check:
+	poetry run autoflake8 --version
+	poetry run autoflake8 $(AUTOFLAKE8_ARGS) elastica tests examples
+	poetry run autoflake8 --check $(AUTOFLAKE8_ARGS) elastica tests examples
+
+.PHONY: autoflake8-format
+autoflake8-format:
+	poetry run autoflake8 --version
+	poetry run autoflake8 --in-place $(AUTOFLAKE8_ARGS) elastica tests examples
+
 .PHONY: format-codestyle
 format-codestyle: black flake8
 
@@ -62,7 +74,7 @@ test_coverage_xml:
 	NUMBA_DISABLE_JIT=1 poetry run pytest --cov=elastica --cov-report=xml
 
 .PHONY: check-codestyle
-check-codestyle: black-check flake8
+check-codestyle: black-check flake8 autoflake8-check
 
 .PHONY: formatting
 formatting: format-codestyle

README.md

@@ -3,24 +3,39 @@
 
 [![Build_status][badge-travis]][link-travis] [![CI][badge-CI]][link-CI] [![Documentation Status][badge-docs-status]][link-docs-status] [![codecov][badge-codecov]][link-codecov] [![Downloads][badge-pepy-download-count]][link-pepy-download-count] [![DOI][badge-doi]][link-doi] [![Binder][badge-binder]][link-binder] [![Gitter][badge-gitter]][link-gitter]
  </div>
- 
+
 PyElastica is the python implementation of **Elastica**: an *open-source* project for simulating assemblies of slender, one-dimensional structures using Cosserat Rod theory.
 
 [![gallery][link-readme-gallary]][link-project-website]
 
 Visit [cosseratrods.org][link-project-website] for more information and learn about Elastica and Cosserat rod theory.
 
-## How to Start 
+## How to Start
 [![PyPI version][badge-pypi]][link-pypi] [![Documentation Status][badge-docs-status]][link-docs-status]
 
-PyElastica is compatible with Python 3.7 - 3.10.
+PyElastica is compatible with Python 3.8 - 3.10.
 
 ~~~bash
-$ pip install pyelastica 
+$ pip install pyelastica
 ~~~
 
+With this you get a minimal version with very little dependencies.
+
+All options:
+- `magnetism`: use this if you want to simulate magnetic Cosserat rods
+interacting with external magnetic environments (details can be found [here](https://github.com/armantekinalp/MagnetoPyElastica)) .
+- `examples`: installs dependencies to run example cases,
+found under the folder `examples`.
+- `docs`: packages to build documentation
+
+Options can be combined e.g.
+```bash
+pip install "pyelastica[magnetism,examples,docs]"
+```
+
 Documentation of PyElastica is available [here][link-docs-website].
 
+Example cases for simulating magnetic Cosserat rods can be found [here](https://github.com/armantekinalp/MagnetoPyElastica).
 ## Citation
 
 We ask that any publications which use Elastica cite as following:
@@ -36,7 +51,7 @@ We ask that any publications which use Elastica cite as following:
                   Zhi Dou and
                   Chia-Hsien (Cathy) Shih and
                   Mattia Gazzola},
-  title        = {{PyElastica: Open-source software for the 
+  title        = {{PyElastica: Open-source software for the
                    simulation of assemblies of slender, one-
                    dimensional structures using Cosserat Rod theory}},
   month        = feb,
@@ -50,19 +65,22 @@ We ask that any publications which use Elastica cite as following:
 
 <details>
   <summary><h4>References</h4></summary>
- 
+
 - Gazzola, Dudte, McCormick, Mahadevan, <strong>Forward and inverse problems in the mechanics of soft filaments</strong>, Royal Society Open Science, 2018. doi: [10.1098/rsos.171628](https://doi.org/10.1098/rsos.171628)
 - Zhang, Chan, Parthasarathy, Gazzola, <strong>Modeling and simulation of complex dynamic musculoskeletal architectures</strong>, Nature Communications, 2019. doi: [10.1038/s41467-019-12759-5](https://doi.org/10.1038/s41467-019-12759-5)
 
 </details>
 
 ## List of publications and submissions
-
-- [Control-oriented modeling of bend propagation in an octopus arm](https://arxiv.org/abs/2110.07211) (UIUC, 2021)
+- [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)
+- [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)
 - [A physics-informed, vision-based method to reconstruct all deformation modes in slender bodies](https://arxiv.org/abs/2109.08372) (UIUC, 2021) (IEEE ICRA 2022) [code](https://github.com/GazzolaLab/BR2-vision-based-smoothing)
-- [Optimal control of a soft CyberOctopus arm](https://ieeexplore.ieee.org/document/9483284) (UIUC, 2021) (ACC 2021)
+- [Optimal control of a soft CyberOctopus arm](https://ieeexplore.ieee.org/document/9483284) (UIUC, 2021) (IEEE ACC 2021)
 - [Elastica: A compliant mechanics environment for soft robotic control](https://ieeexplore.ieee.org/document/9369003) (UIUC, 2021) (IEEE RA-L 2021)
-- [Controlling a CyberOctopus soft arm with muscle-like actuation](https://arxiv.org/abs/2010.03368) (UIUC, 2020)
+- [Controlling a CyberOctopus soft arm with muscle-like actuation](https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=9683318) (UIUC, 2020) (IEEE CDC 2021)
 - [Energy shaping control of a CyberOctopus soft arm](https://ieeexplore.ieee.org/document/9304408) (UIUC, 2020) (IEEE CDC 2020)
 
 ## Tutorials
@@ -83,8 +101,10 @@ _Names arranged alphabetically_
 - Arman Tekinalp
 - Chia-Hsien Shih (Cathy)
 - Fan Kiat Chan
+- Ilia Nasiriziba
 - Noel Naughton
 - [Seung Hyun Kim](https://github.com/skim0119)
+- Songyuan Cui
 - Tejaswin Parthasarathy (Teja)
 - [Yashraj Bhosale](https://github.com/bhosale2)
 

docs/conf.py

@@ -22,7 +22,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'PyElastica'
-copyright = '2022, Gazzola Lab'
+copyright = '2023, Gazzola Lab'
 author = 'Gazzola Lab'
 
 # The full version, including alpha/beta/rc tags

docs/guide/workflow.md

@@ -63,7 +63,6 @@ rod1 = CosseratRod.straight_rod(
     base_length=0.5,                              # original length of rod (m)
     base_radius=10e-2,                            # original radius of rod (m)
     density=1e3,                                  # density of rod (kg/m^3)
-    nu=1e-3,                                      # Energy dissipation of rod, internal damping constant, deprecated in v0.3.0
     youngs_modulus=1e7,                           # Elastic Modulus (Pa)
     shear_modulus=1e7/(2* (1+0.5)),               # Shear Modulus (Pa)
 )
@@ -75,7 +74,6 @@ rod2 = CosseratRod.straight_rod(
     base_length=0.5,                              # original length of rod (m)
     base_radius=10e-2,                            # original radius of rod (m)
     density=1e3,                                  # density of rod (kg/m^3)
-    nu=0.0,                                       # Energy dissipation of rod,  internal damping constant, deprecated in v0.3.0
     youngs_modulus=1e7,                           # Elastic Modulus (Pa)
     shear_modulus=1e7/(2* (1+0.5)),               # Shear Modulus (Pa)
 )

docs/index.rst

@@ -36,6 +36,7 @@ If you are interested to contribute, please read `contribution-guide`_ first.
 
    overview/welcome_page
    overview/installation
+   overview/FAQs
 
 .. toctree::
    :maxdepth: 1
@@ -50,7 +51,7 @@ If you are interested to contribute, please read `contribution-guide`_ first.
 .. toctree::
    :maxdepth: 2
    :caption: API Documentation
-   
+
    api/rods
    api/rigidbody
    api/constraints

docs/intro_page.rst.inc

@@ -6,28 +6,43 @@ More information about Elastica is available at the `project website`_
 PyElastica
 ~~~~~~~~~~
 .. image:: https://travis-ci.com/GazzolaLab/PyElastica.svg?branch=master
-	:target: https://travis-ci.com/gazzolalab 
+	:target: https://travis-ci.com/gazzolalab
 	:alt: Build_status
 
 .. image:: https://codecov.io/gh/gazzolalab/PyElastica/branch/master/graph/badge.svg
 	:target: https://codecov.io/gh/gazzolalab/PyElastica
 	:alt: codecov
-	
+
 .. image:: https://readthedocs.org/projects/pyelastica/badge/?version=latest
 	:target: https://pyelastica.readthedocs.io/en/latest/?badge=latest
 	:alt: Documentation Status
 
-PyElastica is the python implementation of Elastica. The easiest way to install PyElastica is with PIP: 
+PyElastica is the python implementation of Elastica. The easiest way to install PyElastica is with PIP:
+
+.. code-block:: bash
+
+   $ pip install pyelastica
+
+You can also download the source code for PyElastica directly from `GitHub <https://github.com/GazzolaLab/PyElastica>`__.
+
+All options:
+
+- ``magnetism``: use this if you want to simulate magnetic Cosserat rods
+  interacting with external magnetic environments (details can be found `here <https://github.com/armantekinalp/MagnetoPyElastica>`__).
+- ``examples``: installs dependencies to run example cases,
+  found under the folder `examples <https://github.com/GazzolaLab/PyElastica/tree/master/examples>`__.
+- ``docs``: packages to build documentation
+
+Options can be combined, e.g.
 
-.. code:: console
+.. code-block:: bash
 
-    $ pip install pyelastica
+    $ pip install "pyelastica[magnetism,examples,docs]"
 
-Or download the source code from the `GitHub repo`_ 
 
 Elastica++
 ==========
-Elastica++ is a C++ implementation of Elastica. The expected release date for the beta version is 2022 Q2.
+Elastica++ is a C++ implementation of Elastica. The expected release date for the beta version is 2023 Q4.
 
 .. _project website: https://cosseratrods.org
 .. _GitHub repo: https://github.com/GazzolaLab/PyElastica

docs/overview/FAQs.md

@@ -1,12 +1,7 @@
+# FAQs
+
 If you have a question not answered here, leave an issue on our [github-issue](https://github.com/GazzolaLab/PyElastica/issues).
 
-### Q. Is there support available for Elastica?
+## Q. Is there support available for Elastica?
 
 If you open an issue on [GitHub](https://github.com/GazzolaLab/PyElastica), we will look and respond within 24-48 hours.
-
-<!--
-### Q2. Do PyElastica and Elastica++ have the same features?
-Almost. Due to development cycles, they may not always be equally up to date. If there is a feature in one that you would like to see in the other, let us know on [GitHub](https://github.com/GazzolaLab/PyElastica). 
--->
-
-[link-citation]: https://github.com/GazzolaLab/PyElastica#citation

docs/overview/installation.md

@@ -2,18 +2,30 @@
 
 ## Instruction
 
-PyElastica requires Python 3.5 - 3.8, 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.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).
 
 :::{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.
 :::
 
 The easiest way to install PyElastica is with `pip`:
 
-```sh
+```bash
 $ pip install pyelastica
 ```
-You can also download the source code for PyElastica directly from [GitHub](https://github.com/GazzolaLab/PyElastica). 
+You can also download the source code for PyElastica directly from [GitHub](https://github.com/GazzolaLab/PyElastica).
+
+All options:
+- `magnetism`: use this if you want to simulate magnetic Cosserat rods
+interacting with external magnetic environments (details can be found [here](https://github.com/armantekinalp/MagnetoPyElastica)) .
+- `examples`: installs dependencies to run example cases,
+found under the folder [`examples`](https://github.com/GazzolaLab/PyElastica/tree/master/examples).
+- `docs`: packages to build documentation
+
+Options can be combined e.g.
+```bash
+$ pip install "pyelastica[magnetism,examples,docs]"
+```
 
 ## Dependencies
 
@@ -26,4 +38,4 @@ The core of PyElastica is developed using:
 - matplotlib (visualization)
 
 Above packages will be installed along with PyElastica if you used `pip` to install.
-If you have directly downloaded the source code, you must install these packages separately. 
+If you have directly downloaded the source code, you must install these packages separately.