From e54536c43bce3bb5a2643803b175b0e2877f81cd Mon Sep 17 00:00:00 2001 From: Seung Hyun Kim Date: Mon, 24 Jun 2024 09:36:57 -0500 Subject: [PATCH] docs: add duck-typing structure into documentation --- docs/advanced/PackageDesign.md | 110 ++++++++++++++++++++++++++++++++- docs/conf.py | 4 ++ poetry.lock | 30 ++++----- pyproject.toml | 2 + 4 files changed, 129 insertions(+), 17 deletions(-) diff --git a/docs/advanced/PackageDesign.md b/docs/advanced/PackageDesign.md index 857a3c04..1ef46121 100644 --- a/docs/advanced/PackageDesign.md +++ b/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  • CosseratRod\n• RigidBody\n  • Sphere\n  • 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 + +``` diff --git a/docs/conf.py b/docs/conf.py index 6d204796..f2ca1f39 100644 --- a/docs/conf.py +++ b/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'] diff --git a/poetry.lock b/poetry.lock index ee1ffa8b..196c8dd3 100644 --- a/poetry.lock +++ b/poetry.lock @@ -627,7 +627,7 @@ files = [ name = "jinja2" version = "3.1.4" description = "A very fast and expressive template engine." -optional = false +optional = true python-versions = ">=3.7" files = [ {file = "jinja2-3.1.4-py3-none-any.whl", hash = "sha256:bc5dd2abb727a5319567b7a813e6a2e7318c39f4f487cfe6c89c6f9c7d25197d"}, @@ -814,7 +814,7 @@ testing = ["coverage", "pytest", "pytest-cov", "pytest-regressions"] name = "markupsafe" version = "2.1.5" description = "Safely add untrusted strings to HTML/XML markup." -optional = false +optional = true python-versions = ">=3.7" files = [ {file = "MarkupSafe-2.1.5-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:a17a92de5231666cfbe003f0e4b9b3a7ae3afb1ec2845aadc2bacc93ff85febc"}, @@ -1557,7 +1557,6 @@ files = [ {file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:69b023b2b4daa7548bcfbd4aa3da05b3a74b772db9e23b982788168117739938"}, {file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:81e0b275a9ecc9c0c0c07b4b90ba548307583c125f54d5b6946cfee6360c733d"}, {file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ba336e390cd8e4d1739f42dfe9bb83a3cc2e80f567d8805e11b46f4a943f5515"}, - {file = "PyYAML-6.0.1-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:326c013efe8048858a6d312ddd31d56e468118ad4cdeda36c719bf5bb6192290"}, {file = "PyYAML-6.0.1-cp310-cp310-win32.whl", hash = "sha256:bd4af7373a854424dabd882decdc5579653d7868b8fb26dc7d0e99f823aa5924"}, {file = "PyYAML-6.0.1-cp310-cp310-win_amd64.whl", hash = "sha256:fd1592b3fdf65fff2ad0004b5e363300ef59ced41c2e6b3a99d4089fa8c5435d"}, {file = "PyYAML-6.0.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:6965a7bc3cf88e5a1c3bd2e0b5c22f8d677dc88a455344035f03399034eb3007"}, @@ -1565,16 +1564,8 @@ files = [ {file = "PyYAML-6.0.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:42f8152b8dbc4fe7d96729ec2b99c7097d656dc1213a3229ca5383f973a5ed6d"}, {file = "PyYAML-6.0.1-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:062582fca9fabdd2c8b54a3ef1c978d786e0f6b3a1510e0ac93ef59e0ddae2bc"}, {file = "PyYAML-6.0.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:d2b04aac4d386b172d5b9692e2d2da8de7bfb6c387fa4f801fbf6fb2e6ba4673"}, - {file = "PyYAML-6.0.1-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:e7d73685e87afe9f3b36c799222440d6cf362062f78be1013661b00c5c6f678b"}, {file = "PyYAML-6.0.1-cp311-cp311-win32.whl", hash = "sha256:1635fd110e8d85d55237ab316b5b011de701ea0f29d07611174a1b42f1444741"}, {file = "PyYAML-6.0.1-cp311-cp311-win_amd64.whl", hash = "sha256:bf07ee2fef7014951eeb99f56f39c9bb4af143d8aa3c21b1677805985307da34"}, - {file = "PyYAML-6.0.1-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:855fb52b0dc35af121542a76b9a84f8d1cd886ea97c84703eaa6d88e37a2ad28"}, - {file = "PyYAML-6.0.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:40df9b996c2b73138957fe23a16a4f0ba614f4c0efce1e9406a184b6d07fa3a9"}, - {file = "PyYAML-6.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a08c6f0fe150303c1c6b71ebcd7213c2858041a7e01975da3a99aed1e7a378ef"}, - {file = "PyYAML-6.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6c22bec3fbe2524cde73d7ada88f6566758a8f7227bfbf93a408a9d86bcc12a0"}, - {file = "PyYAML-6.0.1-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:8d4e9c88387b0f5c7d5f281e55304de64cf7f9c0021a3525bd3b1c542da3b0e4"}, - {file = "PyYAML-6.0.1-cp312-cp312-win32.whl", hash = "sha256:d483d2cdf104e7c9fa60c544d92981f12ad66a457afae824d146093b8c294c54"}, - {file = "PyYAML-6.0.1-cp312-cp312-win_amd64.whl", hash = "sha256:0d3304d8c0adc42be59c5f8a4d9e3d7379e6955ad754aa9d6ab7a398b59dd1df"}, {file = "PyYAML-6.0.1-cp36-cp36m-macosx_10_9_x86_64.whl", hash = "sha256:50550eb667afee136e9a77d6dc71ae76a44df8b3e51e41b77f6de2932bfe0f47"}, {file = "PyYAML-6.0.1-cp36-cp36m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:1fe35611261b29bd1de0070f0b2f47cb6ff71fa6595c077e42bd0c419fa27b98"}, {file = "PyYAML-6.0.1-cp36-cp36m-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:704219a11b772aea0d8ecd7058d0082713c3562b4e271b849ad7dc4a5c90c13c"}, @@ -1591,7 +1582,6 @@ files = [ {file = "PyYAML-6.0.1-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a0cd17c15d3bb3fa06978b4e8958dcdc6e0174ccea823003a106c7d4d7899ac5"}, {file = "PyYAML-6.0.1-cp38-cp38-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:28c119d996beec18c05208a8bd78cbe4007878c6dd15091efb73a30e90539696"}, {file = "PyYAML-6.0.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7e07cbde391ba96ab58e532ff4803f79c4129397514e1413a7dc761ccd755735"}, - {file = "PyYAML-6.0.1-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:49a183be227561de579b4a36efbb21b3eab9651dd81b1858589f796549873dd6"}, {file = "PyYAML-6.0.1-cp38-cp38-win32.whl", hash = "sha256:184c5108a2aca3c5b3d3bf9395d50893a7ab82a38004c8f61c258d4428e80206"}, {file = "PyYAML-6.0.1-cp38-cp38-win_amd64.whl", hash = "sha256:1e2722cc9fbb45d9b87631ac70924c11d3a401b2d7f410cc0e3bbf249f2dca62"}, {file = "PyYAML-6.0.1-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:9eb6caa9a297fc2c2fb8862bc5370d0303ddba53ba97e71f08023b6cd73d16a8"}, @@ -1599,7 +1589,6 @@ files = [ {file = "PyYAML-6.0.1-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5773183b6446b2c99bb77e77595dd486303b4faab2b086e7b17bc6bef28865f6"}, {file = "PyYAML-6.0.1-cp39-cp39-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:b786eecbdf8499b9ca1d697215862083bd6d2a99965554781d0d8d1ad31e13a0"}, {file = "PyYAML-6.0.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:bc1bf2925a1ecd43da378f4db9e4f799775d6367bdb94671027b73b393a7c42c"}, - {file = "PyYAML-6.0.1-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:04ac92ad1925b2cff1db0cfebffb6ffc43457495c9b3c39d3fcae417d7125dc5"}, {file = "PyYAML-6.0.1-cp39-cp39-win32.whl", hash = "sha256:faca3bdcf85b2fc05d06ff3fbc1f83e1391b3e724afa3feba7d13eeab355484c"}, {file = "PyYAML-6.0.1-cp39-cp39-win_amd64.whl", hash = "sha256:510c9deebc5c0225e8c96813043e62b680ba2f9c50a08d3724c7f28a747d1486"}, {file = "PyYAML-6.0.1.tar.gz", hash = "sha256:bfdf460b1736c775f2ba9f6a92bca30bc2095067b8a9d77876d1fad6cc3b4a43"}, @@ -1877,6 +1866,17 @@ files = [ [package.extras] test = ["flake8", "mypy", "pytest"] +[[package]] +name = "sphinxcontrib-mermaid" +version = "0.9.2" +description = "Mermaid diagrams in yours Sphinx powered docs" +optional = true +python-versions = ">=3.7" +files = [ + {file = "sphinxcontrib-mermaid-0.9.2.tar.gz", hash = "sha256:252ef13dd23164b28f16d8b0205cf184b9d8e2b714a302274d9f59eb708e77af"}, + {file = "sphinxcontrib_mermaid-0.9.2-py3-none-any.whl", hash = "sha256:6795a72037ca55e65663d2a2c1a043d636dc3d30d418e56dd6087d1459d98a5d"}, +] + [[package]] name = "sphinxcontrib-qthelp" version = "1.0.7" @@ -2044,10 +2044,10 @@ numpy = ["numpy (>=1.9)"] web = ["wslink (>=1.0.4)"] [extras] -docs = ["Sphinx", "docutils", "myst-parser", "numpydoc", "readthedocs-sphinx-search", "sphinx-autodoc-typehints", "sphinx-book-theme"] +docs = ["Sphinx", "docutils", "myst-parser", "numpydoc", "readthedocs-sphinx-search", "sphinx-autodoc-typehints", "sphinx-book-theme", "sphinxcontrib-mermaid"] examples = ["cma"] [metadata] lock-version = "2.0" python-versions = ">=3.10,<3.12" -content-hash = "07105447f85d22c61c0766e22959a4f3428f9cfa20e7499aae4017fa993fdca3" +content-hash = "c9747151a346aa7c37c83f66c82b8283aa4ed796788d545d65378b7e8a117260" diff --git a/pyproject.toml b/pyproject.toml index 9851cafc..bbd4e9ce 100644 --- a/pyproject.toml +++ b/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",