docs: add duck-typing structure into documentation

docs/advanced/PackageDesign.md

@@ -1,8 +1,114 @@
-# Code Design: Mixin and Composition
+# Code Design
+
+## Mixin and Composition
 
 Elastica package follows Mixin and composition design patterns that may be unfamiliar to users. Here is a collection of references that introduce the package design.
 
-## References
+### References
 
 - [stackoverflow discussion on Mixin](https://stackoverflow.com/questions/533631/what-is-a-mixin-and-why-are-they-useful)
 - [example of Mixin: python collections](https://docs.python.org/dev/library/collections.abc.html)
+
+## Duck Typing
+
+Elastica package uses duck typing to allow users to define their own classes and functions. Here is a `typing.Protocol` structure that is used in the package.
+
+### Systems
+
+``` {mermaid}
+    flowchart LR
+      direction RL
+      subgraph Systems Protocol
+        direction RL
+        SLBD(SlenderBodyGeometryProtool)
+        SymST["SymplecticSystem:\n• KinematicStates/Rates\n• DynamicStates/Rates"]
+        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
+        SystemType --> SymST
+        SLBD --> ExpST
+        SystemType --> ExpST
+      end
+      subgraph Timestepper Protocol
+        direction TB
+        StP["StepperProtocol\n• step(SystemCollection, time, dt)"]
+        style StP text-align:left
+        SymplecticStepperProtocol["SymplecticStepperProtocol\n• PositionVerlet"]
+        style SymplecticStepperProtocol text-align:left
+        ExpplicitStepperProtocol["ExpplicitStepperProtocol\n(Unused)"]
+      end
+
+      subgraph SystemCollection
+
+      end
+      SymST --> SystemCollection --> SymplecticStepperProtocol
+      ExpST --> SystemCollection --> ExpplicitStepperProtocol
+      StaticSystemType --> SystemCollection
+
+```
+
+### System Collection (Build memory block)
+
+``` {mermaid}
+    flowchart LR
+      Sys((Systems))
+      St((Stepper))
+      subgraph SystemCollectionType
+        direction LR
+        StSys["StaticSystem:\n• Surface\n• Mesh"]
+        style StSys text-align:left
+        DynSys["DynamicSystem:\n• Rod\n  • CosseratRod\n• RigidBody\n  • Sphere\n  • Cylinder"]
+        style DynSys text-align:left
+
+        BlDynSys["BlockSystemType:\n• BlockCosseratRod\n• BlockRigidBody"]
+        style BlDynSys text-align:left
+
+        F{{"Feature Group (OperatorGroup):\n• Synchronize\n• Constrain values\n• Constrain rates\n• Callback"}}
+        style F text-align:left
+      end
+      Sys --> StSys --> F
+      Sys --> DynSys -->|Finalize| BlDynSys --> St
+      DynSys --> F <--> St
+
+```
+
+### System Collection (Features)
+
+``` {mermaid}
+    flowchart LR
+      Sys((Systems))
+      St((Stepper))
+      subgraph SystemCollectionType
+        direction LR
+        StSys["StaticSystem:\n• Surface\n• Mesh"]
+        style StSys text-align:left
+        DynSys["DynamicSystem:\n• Rod\n&nbsp;&nbsp;• CosseratRod\n• RigidBody\n&nbsp;&nbsp;• Sphere\n&nbsp;&nbsp;• Cylinder"]
+        style DynSys text-align:left
+
+        subgraph Feature
+        direction LR
+        Forcing -->|add_forcing_to| Synchronize
+        Constraints -->|constrain| ConstrainValues
+        Constraints -->|constrain| ConstrainRates
+        Contact -->|detect_contact_between| Synchronize
+        Connection -->|connect| Synchronize
+        Damping -->|dampen| ConstrainRates
+        Callback -->|collect_diagnosis| CallbackGroup
+        end
+      end
+      Sys --> StSys --> Feature
+      Sys --> DynSys
+      DynSys --> Feature <--> St
+
+```

docs/conf.py

@@ -41,6 +41,7 @@
     #'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
     'sphinx.ext.mathjax',
+    "sphinxcontrib.mermaid",
     'numpydoc',
     'myst_parser',
 ]
@@ -98,3 +99,6 @@
 
 # -- Options for numpydoc ---------------------------------------------------
 numpydoc_show_class_members = False
+
+# -- Mermaid configuration ---------------------------------------------------
+mermaid_params = ['--theme', 'neutral']

elastica/modules/operator_group.py

@@ -11,16 +11,31 @@
 class OperatorGroupFIFO(Iterable, Generic[T, F]):
     """
     A class to store the features and their corresponding operators in a FIFO manner.
+    Feature can be any user-defined object to label the operators, and operators are
+    callable functions.
+
+    This data structure is used to organize elastica operators, such as forcing,
+    constraints, boundary condition, etc.
 
     Examples
     --------
+    >>> class FeatureObj:
+    ...     ADD: Callable
+    ...     SUBTRACT: Callable
+    ...     MULTIPLY: Callable
+
+    >>> obj_1 = FeatureObj()
+    >>> obj_2 = FeatureObj()
+    >>>
     >>> operator_group = OperatorGroupFIFO()
     >>> operator_group.append_id(obj_1)
     >>> operator_group.append_id(obj_2)
-    >>> operator_group.add_operators(obj_1, [ADD, SUBTRACT])
-    >>> operator_group.add_operators(obj_2, [SUBTRACT, MULTIPLY])
-    >>> list(operator_group)
-    [ADD, SUBTRACT, SUBTRACT, MULTIPLY]
+    >>> operator_group.add_operators(obj_1, [obj_1.ADD, obj_1.SUBTRACT])
+    >>> operator_group.add_operators(obj_2, [obj_2.SUBTRACT, obj_2.MULTIPLY])
+    >>> list(iter(operator_group))
+    [obj_1.ADD, obj_1.SUBTRACT, obj_2.SUBTRACT, obj_2.MULTIPLY]
+    >>> for operator in operator_group:  # call operator in the group
+    ...     operator()
 
     Attributes
     ----------

pyproject.toml

@@ -48,6 +48,7 @@ Sphinx = {version = "^6.1", optional = true}
 sphinx-book-theme = {version = "^1.0", optional = true}
 readthedocs-sphinx-search = {version = ">=0.1.1,<0.4.0", optional = true}
 sphinx-autodoc-typehints = {version = "^1.21", optional = true}
+sphinxcontrib-mermaid = {version = "^0.9.2", optional = true}
 myst-parser = {version = "^1.0", optional = true}
 numpydoc = {version = "^1.3.1", optional = true}
 docutils = {version = "^0.18", optional = true}
@@ -73,6 +74,7 @@ docs = [
   "sphinx-book-theme",
   "readthedocs-sphinx-search",
   "sphinx-autodoc-typehints",
+  "sphinxcontrib-mermaid",
   "myst-parser",
   "numpydoc",
   "docutils",