Update v1

.github/dependabot.yml

@@ -10,5 +10,5 @@ updates:
     schedule:
       interval: "daily"
     open-pull-requests-limit: 99
-    target-branch: "update-v1"
+    target-branch: "master"
     versioning-strategy: lockfile-only

.github/workflows/main.yml

@@ -3,14 +3,6 @@ name: CI
 
 # Controls when the action will run.
 on: [push, pull_request]
-# Older settings:
-# Triggers the workflow on push request events for the master branch,
-# and pull request events for all branches.
-#on:
-#  push:
-#    branches: [ master ]
-#  pull_request:
-#    branches: [ '**' ]
 
 # A workflow run is made up of one or more jobs that can run sequentially or in parallel
 jobs:
@@ -62,7 +54,7 @@ jobs:
       # Install dependencies
       - name: Install dependencies
         run: |
-          make install-dev-deps
+          make install-dev-deps PYTHON_VERSION=${{ matrix.python-version }}
           uv cache prune --ci
           source .venv/bin/activate
       # Runs a single command using the runners shell
@@ -102,7 +94,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Set up cache
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: ${{ matrix.path }}
           key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}-${{ hashFiles('uv.lock') }}
@@ -111,14 +103,14 @@ jobs:
             ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}
       - name: Install dependencies
         run: |
-          make install-dev-deps
+          make install-dev-deps PYTHON_VERSION=${{ matrix.python-version }}
           uv cache prune --ci
           source .venv/bin/activate
       - name: Test PyElastica using pytest
         if: startsWith(runner.os, 'macOS')
         run: |
           make test_coverage_xml
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v5
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

.gitignore

@@ -7,6 +7,10 @@ __pycache__/
 *.so
 
 *.swp
+.vscode
+docs/_gallery
+docs/gen_modules
+docs/sg_execution_times.rst
 
 # Distribution / packaging
 .Python

.pre-commit-config.yaml

@@ -1,11 +1,11 @@
 default_language_version:
   python: python3
 
-default_stages: [commit, push]
+default_stages: [pre-commit, pre-push]
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v2.5.0
+    rev: v6.0.0
     hooks:
       - id: trailing-whitespace
       - id: check-json

.readthedocs.yaml

@@ -4,6 +4,8 @@ version: 2
 # Set the version of Python and other tools you might need
 build:
   os: ubuntu-24.04
+  apt_packages:
+    - ffmpeg
   tools: { python: "3.10" }
   jobs:
     create_environment:
@@ -14,6 +16,7 @@ build:
     install:
       - "true"
 
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   builder: html

CONTRIBUTING.md

@@ -121,7 +121,7 @@ Please don't hesitate improving [documentation](https://github.com/GazzolaLab/Py
 
 We also have many related projects in separate repositories that utilize the PyElastica as a core library.
 Since the package is often used for research purpose, many on-going projects are typically not published.
-If you are interested in hearing more, please contact one of our the maintainer.
+If you are interested in hearing more, please contact the maintainer.
 
 ### Pull requests
 

Makefile

@@ -2,15 +2,24 @@
 PYTHON := python3
 PYTHONPATH := `pwd`
 AUTOFLAKE_ARGS := -r
+PYTHON_VERSION :=
 
 #* Installation
 .PHONY: install
 install:
+ifdef PYTHON_VERSION
+	uv sync --python $(PYTHON_VERSION)
+else
 	uv sync
+endif
 
 .PHONY: install-dev-deps
 install-dev-deps:
+ifdef PYTHON_VERSION
+	uv sync --all-groups --all-extras --python $(PYTHON_VERSION)
+else
 	uv sync --all-groups --all-extras
+endif
 
 
 .PHONY: build
@@ -35,7 +44,7 @@ black-check:
 .PHONY: flake8
 flake8:
 	uv run flake8 --version
-	uv run flake8 elastica tests
+	uv run flake8 elastica
 
 .PHONY: autoflake-check
 autoflake-check:
@@ -103,8 +112,12 @@ pytestcache-remove:
 build-remove:
 	rm -rf build/ dist/
 
+.PHONY: doc-remove
+doc-remove:
+	rm -rf docs/_build docs/gen_modules/ docs/sg_execution_times.rst docs/_gallery/
+
 .PHONY: cleanup
-cleanup: pycache-remove dsstore-remove ipynbcheckpoints-remove pytestcache-remove mypycache-remove build-remove
+cleanup: pycache-remove dsstore-remove ipynbcheckpoints-remove pytestcache-remove mypycache-remove build-remove doc-remove
 
 all: format-codestyle cleanup test
 

README.md

@@ -1,12 +1,12 @@
 <div align='center'>
 <h1> PyElastica </h1>
 
-[![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]
+[![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] [![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]
+[![gallery][link-readme-gallery]][link-project-website]
 
 Visit [www.cosseratrods.org][link-project-website] for more information and learn about Elastica and Cosserat rod theory.
 
@@ -84,13 +84,6 @@ We ask that any publications which use Elastica cite as following:
 - [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
-[![Binder][badge-binder-tutorial]][link-binder]
-
-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)).
-
 ## Contribution
 
 If you would like to participate, please read our [contribution guideline](CONTRIBUTING.md). Private development branches are moved to [elastica-python](https://github.com/GazzolaLab/elastica-python) repository; access is limited to the core developers, collaborators, and maintainers.
@@ -113,7 +106,7 @@ _Names arranged alphabetically_
 
 [//]: # (Collection of URLs.)
 
-[link-readme-gallary]: https://github.com/skim0119/PyElastica/blob/assets_logo/assets/alpha_gallery.gif
+[link-readme-gallery]: https://github.com/skim0119/PyElastica/blob/assets_logo/assets/alpha_gallery.gif
 
 [link-project-website]: https://cosseratrods.org
 [link-lab-website]: http://mattia-lab.com/
@@ -122,7 +115,6 @@ _Names arranged alphabetically_
 [badge-pypi]: https://badge.fury.io/py/pyelastica.svg
 [badge-CI]: https://github.com/GazzolaLab/PyElastica/workflows/CI/badge.svg
 [badge-docs-status]: https://readthedocs.org/projects/pyelastica/badge/?version=latest
-[badge-binder]: https://mybinder.org/badge_logo.svg
 [badge-pepy-download-count]: https://pepy.tech/badge/pyelastica
 [badge-codecov]: https://codecov.io/gh/GazzolaLab/PyElastica/branch/master/graph/badge.svg
 [badge-gitter]: https://badges.gitter.im/PyElastica/community.svg
@@ -133,7 +125,5 @@ _Names arranged alphabetically_
 [link-pepy-download-count]: https://pepy.tech/project/pyelastica
 [link-codecov]: https://codecov.io/gh/GazzolaLab/PyElastica
 
-[badge-binder-tutorial]: https://img.shields.io/badge/Launch-PyElastica%20Tutorials-579ACA.svg?logo=data:image/png;base64,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
-[link-binder]: https://mybinder.org/v2/gh/GazzolaLab/PyElastica/master?filepath=examples%2FBinder%2F0_PyElastica_Tutorials_Overview.ipynb
 [link-gitter]: https://gitter.im/PyElastica/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
 [link-doi]: https://zenodo.org/badge/latestdoi/254172891

docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -v -T
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build

docs/README.md

@@ -8,8 +8,8 @@ In addition, we utilize the following extensions to enhance the documentation :c
 
 ## Build documentation
 
-The `sphinx` is already initialized in `docs` directory. 
-In order to build the documentation, you will need additional 
+The `sphinx` is already initialized in `docs` directory.
+In order to build the documentation, you will need additional
 packages listed in extra dependencies.
 
 ```bash
@@ -27,7 +27,7 @@ Use `make help` for other options.
 
 # Contribution
 
-The documentation-related commits will be collected in the branch `doc_**` separate from `master` branch, and merged into `master` collectively. Ideally, the updates in the documentation branch will seek upcoming version update (i.e. `update-**` branch) and merged shortly after the version release. If an update is critical and urgent, create PR directly to `master` branch.
+Documentation-related commits should be pushed to the appropriate `update-**` branch. These changes will be incorporated into the `master` branch upon the corresponding release. For urgent or critical documentation updates, you may create a pull request directly to `master`.
 
 ## User Guide
 
@@ -39,7 +39,7 @@ These files will be managed in `docs` directory.
 ## API documentation
 
 The docstring for function or modules are automatically parsed using `sphinx`+`numpydoc`.
-Any inline function description, such as 
+Any inline function description, such as
 
 ```py
 """ This is the form of a docstring.
@@ -62,4 +62,4 @@ will be parsed and displayed in API documentation. See `numpydoc` for more detai
 
 `ReadtheDocs` runs `sphinx` internally and maintain the documentation website. We will always activate the `stable` and `latest` version, and few past-documentations will also be available for the support.
 
-@nmnaughton and @skim449 has access to the `ReadtheDocs` account.
+@nmnaughton and [@skim0119](https://github.com/skim0119) has access to the `ReadtheDocs` account.

docs/advanced/PackageDesign.md

@@ -20,43 +20,35 @@ Elastica package uses [structural subtyping](https://peps.python.org/pep-0544/)
       direction RL
       subgraph Systems Protocol
         direction RL
-        SLBD(SlenderBodyGeometryProtool)
-        SymST["SymplecticSystem:\n• KinematicStates/Rates\n• DynamicStates/Rates"]
+        SymST["SymplecticSystemProtocol<br/>(Mixin for timestepper)<br/>• update_kinematics<br/>• update_dynamics"]
         style SymST text-align:left
-        ExpST["ExplicitSystem:\n• States (Unused)"]
-        style ExpST text-align:left
-        P((position\nvelocity\nacceleration\n..)) --> SLBD
-        subgraph StaticSystemType
-            Surface
-            Mesh
-        end
-        subgraph SystemType
-            direction TB
-            Rod
-            RigidBody
-        end
-        SLBD --> SymST
+        StaticSystemType["Static System Type"<br/>• Plane]
+        SystemType["(Dynamic) System Type<br/>• CosseratRod (Rod)<br/>• Sphere (RigidBody)<br/>• Cylinder (RigidBody)"]
+
         SystemType --> SymST
-        SLBD --> ExpST
-        SystemType --> ExpST
       end
+
+      subgraph System Collection
+        SysColl["SystemCollectionProtocol"]
+      end
+
       subgraph Timestepper Protocol
-        direction TB
-        StP["StepperProtocol\n• step(SystemCollection, time, dt)"]
-        style StP text-align:left
-        SymplecticStepperProtocol["SymplecticStepperProtocol\n• PositionVerlet"]
+        direction LR
+        SymplecticStepperProtocol["SymplecticStepperProtocol<br/>• PositionVerlet"]
         style SymplecticStepperProtocol text-align:left
-        ExpplicitStepperProtocol["ExpplicitStepperProtocol\n(Unused)"]
       end
 
-      subgraph SystemCollection
+      SymST --> SysColl -->|Symplectic systems only| SymplecticStepperProtocol
+      StaticSystemType --> SysColl
+```
 
-      end
-      SymST --> SystemCollection --> SymplecticStepperProtocol
-      ExpST --> SystemCollection --> ExpplicitStepperProtocol
-      StaticSystemType --> SystemCollection
+#### Key takeaways:
+
+- Any object that conforms to `StaticSystemProtocol` can be added to the system collection.
+    - If you want to add custom type to the system, you can use `append_allowed_types` to add it to the system collection. To add associated block support, you can use `enable_block_supports`.
+- Among the systems added to the system collection, only objects that conform to `SymplecticSystemProtocol` will be integrated by the symplectic timestepper. This protocol requires `update_kinematics(time, prefac)` and `update_dynamics(time, prefac)` methods to be implemented.
+- If block support is available for a system, they will be collected together during the `finalize` step, and passed to the timestepper.
 
-```
 
 ### System Collection (Build memory block)
 
@@ -66,15 +58,15 @@ Elastica package uses [structural subtyping](https://peps.python.org/pep-0544/)
       St((Stepper))
       subgraph SystemCollectionType
         direction LR
-        StSys["StaticSystem:\n• Surface\n• Mesh"]
+        StSys["StaticSystem:<br/>• Plane"]
         style StSys text-align:left
-        DynSys["DynamicSystem:\n• Rod\n&nbsp;&nbsp;• CosseratRod\n• RigidBody\n&nbsp;&nbsp;• Sphere\n&nbsp;&nbsp;• Cylinder"]
+        DynSys["DynamicSystem:<br/>• CosseratRod<br/>• Sphere<br/>• Cylinder"]
         style DynSys text-align:left
 
-        BlDynSys["BlockSystemType:\n• BlockCosseratRod\n• BlockRigidBody"]
+        BlDynSys["BlockSystem:<br/>• MemoryBlockCosseratRod<br/>• MemoryBlockRigidBody"]
         style BlDynSys text-align:left
 
-        F{{"Feature Group (OperatorGroup):\n• Synchronize\n• Constrain values\n• Constrain rates\n• Callback"}}
+        F{{"Feature Group (OperatorGroup):<br/>• Synchronize<br/>• Constrain values<br/>• Constrain rates<br/>• Callback"}}
         style F text-align:left
       end
       Sys --> StSys --> F
@@ -91,9 +83,9 @@ Elastica package uses [structural subtyping](https://peps.python.org/pep-0544/)
       St((Stepper))
       subgraph SystemCollectionType
         direction LR
-        StSys["StaticSystem:\n• Surface\n• Mesh"]
+        StSys["StaticSystem:<br/>• Plane"]
         style StSys text-align:left
-        DynSys["DynamicSystem:\n• Rod\n&nbsp;&nbsp;• CosseratRod\n• RigidBody\n&nbsp;&nbsp;• Sphere\n&nbsp;&nbsp;• Cylinder"]
+        DynSys["DynamicSystem:<br/>• Rod<br/>&nbsp;&nbsp;• CosseratRod<br/>• RigidBody<br/>&nbsp;&nbsp;• Sphere<br/>&nbsp;&nbsp;• Cylinder"]
         style DynSys text-align:left
 
         subgraph Feature
@@ -104,7 +96,7 @@ Elastica package uses [structural subtyping](https://peps.python.org/pep-0544/)
         Contact -->|detect_contact_between| Synchronize
         Connection -->|connect| Synchronize
         Damping -->|dampen| ConstrainRates
-        Callback -->|collect_diagnosis| CallbackGroup
+        Callback -->|collect_diagnostics| CallbackGroup
         end
       end
       Sys --> StSys --> Feature