diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..ab5cf4b --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,64 @@ +name: Deploy Documentation + +on: + push: + branches: + - main + pull_request: + branches: + - main + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -e ".[docs,examples]" + + - name: Build documentation + run: | + mkdocs build --clean + + - name: Setup Pages + if: github.ref == 'refs/heads/main' + uses: actions/configure-pages@v4 + + - name: Upload artifact + if: github.ref == 'refs/heads/main' + uses: actions/upload-pages-artifact@v3 + with: + path: ./site + + deploy: + if: github.ref == 'refs/heads/main' + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index aee7883..6473035 100644 --- a/.gitignore +++ b/.gitignore @@ -136,4 +136,7 @@ dmypy.json # DS_STORE .DS_Store *.mp4 -*.gif \ No newline at end of file +*.gif + +# Documentation build +site/ \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..a8c2003 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,5 @@ +{ + "python-envs.defaultEnvManager": "ms-python.python:conda", + "python-envs.defaultPackageManager": "ms-python.python:conda", + "python-envs.pythonProjects": [] +} \ No newline at end of file diff --git a/Makefile b/Makefile index 0da2b86..7cfb119 100644 --- a/Makefile +++ b/Makefile @@ -54,6 +54,23 @@ pytestcache-remove: build-remove: rm -rf build/ +#* Documentation +.PHONY: docs-serve +docs-serve: + conda run --live-stream --name jsrm mkdocs serve + +.PHONY: docs-build +docs-build: + conda run --live-stream --name jsrm mkdocs build --clean + +.PHONY: docs-build-strict +docs-build-strict: + conda run --live-stream --name jsrm mkdocs build --clean --strict + +.PHONY: docs-deploy +docs-deploy: + conda run --live-stream --name jsrm mkdocs gh-deploy --force + .PHONY: cleanup cleanup: pycache-remove dsstore-remove ipynbcheckpoints-remove pytestcache-remove diff --git a/README.md b/README.md index ae9a21b..c19cb99 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,12 @@ # JAX Soft Robot Modelling +[![Test](https://github.com/tud-phi/jax-soft-robot-modeling/actions/workflows/test.yml/badge.svg)](https://github.com/tud-phi/jax-soft-robot-modeling/actions/workflows/test.yml) +[![Documentation](https://github.com/tud-phi/jax-soft-robot-modeling/actions/workflows/docs.yml/badge.svg)](https://github.com/tud-phi/jax-soft-robot-modeling/actions/workflows/docs.yml) +[![PyPI version](https://badge.fury.io/py/jsrm.svg)](https://badge.fury.io/py/jsrm) +[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) +[![License](https://img.shields.io/github/license/tud-phi/jax-soft-robot-modeling.svg)](https://github.com/tud-phi/jax-soft-robot-modeling/blob/main/LICENSE.txt) +[![Docs](https://img.shields.io/badge/docs-live-brightgreen.svg)](https://tud-phi.github.io/jax-soft-robot-modelling) + This repository contains symbolic derivations of the kinematics and dynamics of various soft robots using Sympy. The symbolic expressions are then implemented in JAX and can be used for fast, parallelizable, and differentiable simulations. So far, we have focused on planar settings and implemented the following soft robots: @@ -68,6 +75,61 @@ Finally, we can simulate the pendulum python examples/simulate_pendulum.py ``` +## Documentation + +The full documentation is available at: https://tud-phi.github.io/jax-soft-robot-modelling + +### Building Documentation Locally + +To build and serve the documentation locally: + +```bash +# Install documentation dependencies +pip install -e ".[docs]" + +# Serve documentation with live reload (if mkdocs is in PATH) +mkdocs serve + +# OR using conda environment +conda run --live-stream --name jsrm mkdocs serve +``` + +The documentation will be available at `http://127.0.0.1:8000`. + +### Building Documentation for Production + +```bash +# Build static documentation (if mkdocs is in PATH) +mkdocs build + +# OR using conda environment +conda run --live-stream --name jsrm mkdocs build + +# Build with strict mode (for CI/development) +mkdocs build --strict +# OR: conda run --live-stream --name jsrm mkdocs build --strict + +# Deploy to GitHub Pages (maintainers only) +mkdocs gh-deploy +# OR: conda run --live-stream --name jsrm mkdocs gh-deploy +``` + +You can also use the Makefile targets: + +```bash +# Serve locally +make docs-serve + +# Build documentation +make docs-build + +# Build with strict mode checking +make docs-build-strict + +# Deploy to GitHub Pages +make docs-deploy +``` + ## See also You might also be interested in the following repositories: diff --git a/docs/404.md b/docs/404.md new file mode 100644 index 0000000..f6897da --- /dev/null +++ b/docs/404.md @@ -0,0 +1,71 @@ +--- +hide: + - navigation + - toc +--- + +# ๐Ÿค– 404 - Page Not Found + +
+ Oops! The page you're looking for doesn't exist. But don't worry, we can help you get back on track with your soft robotics journey! +
+ +--- + +## ๐Ÿงญ Navigation Help + +
+
+

๐Ÿ  [Home](index.md)

+

Go back to the main page and start fresh

+
+ +
+

๐Ÿš€ [Quick Start](user-guide/quick-start.md)

+

Jump into hands-on tutorials and examples

+
+ +
+

๐Ÿ“š [API Reference](api/systems.md)

+

Browse the complete API documentation

+
+ +
+

๐Ÿ“– [Examples](user-guide/examples.md)

+

Explore comprehensive examples and use cases

+
+
+ +--- + +## ๐Ÿ” Popular Resources + +!!! tip "Most Visited Pages" + + - **[Installation Guide](installation.md)** - Get JSRM up and running + - **[Planar PCS Systems](api/planar-pcs.md)** - Continuum soft robot documentation + - **[Contributing Guidelines](development/contributing.md)** - Join our community + - **[System Factory Pattern](user-guide/quick-start.md#core-concepts)** - Learn the basics + +--- + +## ๐Ÿ†˜ Still Lost? + +!!! question "Need help finding something specific?" + + === "๐Ÿ” Search" + Use the search box at the top of the page to find what you're looking for. + + === "๐Ÿ“ง Contact" + Reach out to us at [m.stolzle@tudelft.nl](mailto:m.stolzle@tudelft.nl) + + === "๐Ÿ› Report Issue" + If you think this is a broken link, please [report it on GitHub](https://github.com/tud-phi/jax-soft-robot-modelling/issues/new) + +--- + +
+

+ ๐Ÿค– Happy Coding with JSRM! +

+
diff --git a/docs/api/integration.md b/docs/api/integration.md new file mode 100644 index 0000000..e508a96 --- /dev/null +++ b/docs/api/integration.md @@ -0,0 +1,18 @@ +# Integration Utilities + +Numerical integration methods and utilities for solving differential equations. + +## Overview + +This module provides various integration schemes including Gauss-Legendre quadrature and other numerical methods used in the robot dynamics computations. + +## API Reference + +::: jsrm.integration + options: + show_root_heading: true + show_source: false + heading_level: 3 + group_by_category: true + docstring_section_style: table + members_order: source diff --git a/docs/api/math-utils.md b/docs/api/math-utils.md new file mode 100644 index 0000000..8a86890 --- /dev/null +++ b/docs/api/math-utils.md @@ -0,0 +1,18 @@ +# Math Utilities + +Mathematical utility functions used throughout JSRM for various computations. + +## Overview + +This module provides core mathematical operations including linear algebra utilities, matrix operations, and specialized functions for robotics computations. + +## API Reference + +::: jsrm.math_utils + options: + show_root_heading: true + show_source: false + heading_level: 3 + group_by_category: true + docstring_section_style: table + members_order: source diff --git a/docs/api/parameters.md b/docs/api/parameters.md new file mode 100644 index 0000000..e21832b --- /dev/null +++ b/docs/api/parameters.md @@ -0,0 +1,18 @@ +# Parameters + +Parameter handling and configuration utilities for robot systems. + +## Overview + +This module provides functions for handling robot parameters, including validation, conversion, and default parameter sets for various robot types. + +## API Reference + +::: jsrm.parameters + options: + show_root_heading: true + show_source: false + heading_level: 3 + group_by_category: true + docstring_section_style: table + members_order: source diff --git a/docs/api/pcs.md b/docs/api/pcs.md new file mode 100644 index 0000000..08d678b --- /dev/null +++ b/docs/api/pcs.md @@ -0,0 +1,24 @@ +# PCS Systems (General) + +The general Piecewise Constant Strain (PCS) implementation provides the core modeling framework for continuum soft robots, based on the discrete Cosserat approach proposed by Renda et al. (2018). + +## Overview + +This module contains the fundamental PCS implementation that serves as the foundation for more specialized PCS variants. It provides the core mathematical framework for modeling continuum robots using piecewise constant strain assumptions, following the discrete Cosserat approach for multisection soft manipulator dynamics. + +## API Reference + +::: jsrm.systems.pcs + options: + show_root_heading: true + show_source: false + heading_level: 3 + group_by_category: true + docstring_section_style: table + members_order: source + +## References + +The PCS (Piecewise Constant Strain) model was originally proposed in: + +Renda, F., Boyer, F., Dias, J., & Seneviratne, L. (2018). Discrete cosserat approach for multisection soft manipulator dynamics. *IEEE Transactions on Robotics*, 34(6), 1518-1533. diff --git a/docs/api/pendulum.md b/docs/api/pendulum.md new file mode 100644 index 0000000..168b5b4 --- /dev/null +++ b/docs/api/pendulum.md @@ -0,0 +1,18 @@ +# Pendulum Systems + +The pendulum module provides implementations for N-link pendulum systems, which are useful for benchmarking and comparison with soft robot systems. + +## Overview + +The pendulum system implements classical rigid-body dynamics for articulated robots with revolute joints. This serves as a baseline for comparing with continuum soft robot models. + +## API Reference + +::: jsrm.systems.pendulum + options: + show_root_heading: true + show_source: false + heading_level: 3 + group_by_category: true + docstring_section_style: table + members_order: source diff --git a/docs/api/planar-hsa.md b/docs/api/planar-hsa.md new file mode 100644 index 0000000..181ed5b --- /dev/null +++ b/docs/api/planar-hsa.md @@ -0,0 +1,18 @@ +# Planar HSA Systems + +The Planar Handed Shearing Auxetics (HSA) systems provide implementations for soft robots with auxetic properties in planar settings. + +## Overview + +HSA robots exhibit unique mechanical properties due to their auxetic structure, which allows for interesting deformation patterns and control strategies. This module implements the kinematic and dynamic models for planar HSA robots. + +## API Reference + +::: jsrm.systems.planar_hsa + options: + show_root_heading: true + show_source: false + heading_level: 3 + group_by_category: true + docstring_section_style: table + members_order: source diff --git a/docs/api/planar-pcs-sym.md b/docs/api/planar-pcs-sym.md new file mode 100644 index 0000000..239fb7a --- /dev/null +++ b/docs/api/planar-pcs-sym.md @@ -0,0 +1,24 @@ +# Planar PCS Symbolic Systems + +The symbolic implementation of Planar PCS systems provides pre-computed symbolic expressions for kinematics and dynamics, offering improved computational performance. This implementation is based on the discrete Cosserat approach by Renda et al. (2018). + +## Overview + +This module contains symbolic derivations of the PCS model equations, based on the discrete Cosserat approach for multisection soft manipulator dynamics (Renda et al., 2018), which are pre-computed using SymPy and then implemented in JAX for fast execution. This approach eliminates the need for numerical differentiation during runtime. + +## API Reference + +::: jsrm.systems.planar_pcs_sym + options: + show_root_heading: true + show_source: false + heading_level: 3 + group_by_category: true + docstring_section_style: table + members_order: source + +## References + +The PCS (Piecewise Constant Strain) model was originally proposed in: + +Renda, F., Boyer, F., Dias, J., & Seneviratne, L. (2018). Discrete cosserat approach for multisection soft manipulator dynamics. *IEEE Transactions on Robotics*, 34(6), 1518-1533. diff --git a/docs/api/planar-pcs.md b/docs/api/planar-pcs.md new file mode 100644 index 0000000..81ea390 --- /dev/null +++ b/docs/api/planar-pcs.md @@ -0,0 +1,24 @@ +# Planar PCS Systems + +The planar Piecewise Constant Strain (PCS) systems provide implementations for 2D soft continuum robots using the Cosserat rod theory with piecewise constant strain assumptions, based on the discrete Cosserat approach by Renda et al. (2018). + +## Overview + +The PCS model divides the continuum robot into segments, each with constant strain properties. This approach, originally proposed by Renda et al. (2018), provides a good balance between computational efficiency and modeling accuracy for soft continuum robots. + +## Main Implementation + +::: jsrm.systems.planar_pcs + options: + show_root_heading: true + show_source: false + heading_level: 3 + group_by_category: true + docstring_section_style: table + members_order: source + +## References + +The PCS (Piecewise Constant Strain) model was originally proposed in: + +Renda, F., Boyer, F., Dias, J., & Seneviratne, L. (2018). Discrete cosserat approach for multisection soft manipulator dynamics. *IEEE Transactions on Robotics*, 34(6), 1518-1533. diff --git a/docs/api/pneumatic-planar-pcs.md b/docs/api/pneumatic-planar-pcs.md new file mode 100644 index 0000000..73e5fc0 --- /dev/null +++ b/docs/api/pneumatic-planar-pcs.md @@ -0,0 +1,24 @@ +# Pneumatically Actuated Planar PCS + +Pneumatically actuated Planar PCS systems with pressure-based actuation mechanisms, extending the discrete Cosserat approach by Renda et al. (2018). + +## Overview + +This module extends the planar PCS model (based on the discrete Cosserat approach by Renda et al., 2018) to include pneumatic actuation, where the robot is actuated by controlling internal pressure in chambers or bellows. This actuation method is common in soft pneumatic robots. + +## API Reference + +::: jsrm.systems.pneumatically_actuated_planar_pcs + options: + show_root_heading: true + show_source: false + heading_level: 3 + group_by_category: true + docstring_section_style: table + members_order: source + +## References + +The PCS (Piecewise Constant Strain) model was originally proposed in: + +Renda, F., Boyer, F., Dias, J., & Seneviratne, L. (2018). Discrete cosserat approach for multisection soft manipulator dynamics. *IEEE Transactions on Robotics*, 34(6), 1518-1533. diff --git a/docs/api/rendering.md b/docs/api/rendering.md new file mode 100644 index 0000000..25577a7 --- /dev/null +++ b/docs/api/rendering.md @@ -0,0 +1,18 @@ +# Rendering + +Visualization and rendering utilities for robot systems. + +## Overview + +This module provides tools for visualizing robot configurations, trajectories, and animations. Includes both 2D and OpenCV-based rendering capabilities. + +## API Reference + +::: jsrm.rendering + options: + show_root_heading: true + show_source: false + heading_level: 3 + group_by_category: true + docstring_section_style: table + members_order: source diff --git a/docs/api/symbolic-derivation.md b/docs/api/symbolic-derivation.md new file mode 100644 index 0000000..bff079c --- /dev/null +++ b/docs/api/symbolic-derivation.md @@ -0,0 +1,18 @@ +# Symbolic Derivation + +Symbolic mathematics and derivation utilities using SymPy. + +## Overview + +This module contains functions for symbolic derivation of robot kinematics and dynamics equations. These tools are used to generate the symbolic expressions that are then implemented in JAX for fast computation. + +## API Reference + +::: jsrm.symbolic_derivation + options: + show_root_heading: true + show_source: false + heading_level: 3 + group_by_category: true + docstring_section_style: table + members_order: source diff --git a/docs/api/systems.md b/docs/api/systems.md new file mode 100644 index 0000000..7907310 --- /dev/null +++ b/docs/api/systems.md @@ -0,0 +1,88 @@ +# Systems API + +This module contains the main system implementations for different robot types in JSRM. + +## Overview + +JSRM provides implementations for various robot systems, from classical rigid-body pendulums to advanced soft continuum robots. Each system includes: + +- **Forward Kinematics**: Computing end-effector positions and orientations +- **Jacobians**: Computing velocity relationships and sensitivities +- **Dynamics**: Mass matrices, Coriolis forces, and gravitational effects +- **Factory Functions**: Convenient initialization and configuration + +## Available Systems + +### [Pendulum Systems](pendulum.md) +Classical N-link pendulum implementations for benchmarking and comparison. + +- Rigid-body dynamics +- Revolute joints +- Configurable number of links +- Useful as baseline for soft robot comparisons + +### PCS (Piecewise Constant Strain) Systems +Multiple implementations of continuum soft robots using piecewise constant strain modeling. + +#### [General PCS](pcs.md) +Core PCS implementation providing the fundamental framework. + +- Base PCS mathematical framework +- Foundation for specialized variants +- General continuum robot modeling + +#### [Planar PCS](planar-pcs.md) +Planar PCS continuum soft robots in 2D. + +- Cosserat rod theory based +- Piecewise constant strain assumptions +- Numerical implementation with Gauss-Legendre integration +- Suitable for real-time applications + +#### [Planar PCS Symbolic](planar-pcs-sym.md) +Symbolic implementation of planar PCS systems for improved performance. + +- Pre-computed symbolic expressions +- SymPy-derived equations implemented in JAX +- Faster execution through elimination of runtime differentiation +- Identical physics to numerical PCS implementation + +#### [Pneumatic Planar PCS](pneumatic-planar-pcs.md) +Pneumatically actuated planar PCS robots. + +- Pressure-based actuation +- Pneumatic chamber modeling +- Soft pneumatic robot applications +- Real-time pressure control + +#### [Tendon Planar PCS](tendon-planar-pcs.md) +Tendon actuated planar PCS robots. + +- Cable-driven actuation +- Tendon tension control +- Precise manipulation capabilities +- Cable-driven continuum robots + +### [Planar HSA Systems](planar-hsa.md) +Handed Shearing Auxetics (HSA) soft robots with unique mechanical properties. + +- Auxetic material properties +- Specialized deformation patterns +- Advanced control capabilities +- Research-oriented implementation + +## System Factory Pattern + +All systems follow a consistent factory pattern for initialization: + +```python +from jsrm.systems import system_module + +# Initialize system with parameters +ode_fn, forward_kinematics, jacobian_fn, auxiliary_fns = system_module.factory( + system_parameters, + configuration_options +) +``` + +This pattern ensures consistent interfaces across all robot types while allowing for system-specific customizations. diff --git a/docs/api/tendon-planar-pcs.md b/docs/api/tendon-planar-pcs.md new file mode 100644 index 0000000..cf18c05 --- /dev/null +++ b/docs/api/tendon-planar-pcs.md @@ -0,0 +1,24 @@ +# Tendon Actuated Planar PCS + +Tendon actuated Planar PCS systems with cable-driven actuation mechanisms, extending the discrete Cosserat approach by Renda et al. (2018). + +## Overview + +This module extends the planar PCS model (based on the discrete Cosserat approach by Renda et al., 2018) to include tendon actuation, where the robot is actuated by controlling the tension in cables or tendons. This actuation method provides precise control and is commonly used in cable-driven continuum robots. + +## API Reference + +::: jsrm.systems.tendon_actuated_planar_pcs + options: + show_root_heading: true + show_source: false + heading_level: 3 + group_by_category: true + docstring_section_style: table + members_order: source + +## References + +The PCS (Piecewise Constant Strain) model was originally proposed in: + +Renda, F., Boyer, F., Dias, J., & Seneviratne, L. (2018). Discrete cosserat approach for multisection soft manipulator dynamics. *IEEE Transactions on Robotics*, 34(6), 1518-1533. diff --git a/docs/api/utils.md b/docs/api/utils.md new file mode 100644 index 0000000..ef8647d --- /dev/null +++ b/docs/api/utils.md @@ -0,0 +1,58 @@ +# Utils API + +This module contains utility functions and helper modules used throughout JSRM. + +## Overview + +JSRM provides various utility modules that support the core robot system implementations. These utilities handle mathematical operations, numerical integration, parameter management, visualization, and symbolic computations. + +## Available Utilities + +### [Math Utils](math-utils.md) +Core mathematical operations and linear algebra utilities. + +- Matrix operations and manipulations +- Specialized robotics mathematics +- Linear algebra helper functions +- Numerical computation utilities + +### [Integration](integration.md) +Numerical integration methods for differential equations. + +- Gauss-Legendre quadrature +- Integration schemes for robot dynamics +- Numerical differentiation utilities +- Solver interfaces + +### [Parameters](parameters.md) +Parameter handling and configuration management. + +- Robot parameter validation +- Default parameter sets +- Configuration utilities +- Parameter conversion functions + +### [Rendering](rendering.md) +Visualization and animation tools for robot systems. + +- 2D robot visualization +- OpenCV-based rendering +- Animation generation +- Trajectory plotting + +### [Symbolic Derivation](symbolic-derivation.md) +SymPy-based symbolic mathematics for robot modeling. + +- Symbolic kinematics derivation +- Dynamic equation generation +- Expression optimization +- JAX code generation from symbolic expressions + +## Common Patterns + +All utility modules are designed to integrate seamlessly with the main robot systems, providing: + +- **JAX Compatibility**: All functions work with JAX arrays and transformations +- **Vectorization**: Support for batch operations where applicable +- **Type Safety**: Comprehensive type hints for all functions +- **Documentation**: Detailed docstrings with examples diff --git a/docs/authors.md b/docs/authors.md new file mode 100644 index 0000000..2aaafe5 --- /dev/null +++ b/docs/authors.md @@ -0,0 +1,91 @@ +# Authors & Maintainers + +This project is developed and maintained by researchers from the Physical Intelligence (PhI) Lab at TU Delft. + +## Authors + +### Maximilian Stรถlzle + +Postdoctoral Researcher +Physical Intelligence (PhI) Lab, TU Delft + +**Contact:** | + +**Links:** + +- [:fontawesome-brands-github: GitHub](https://github.com/mstoelzle) +- [:fontawesome-brands-linkedin: LinkedIn](https://linkedin.com/in/maximilian-stoelzle) +- [:fontawesome-solid-graduation-cap: Google Scholar](https://scholar.google.com/citations?user=yHmOzBsAAAAJ&hl=de) + +Maximilian is the primary developer and maintainer of the JAX Soft Robot Modelling library. His research focuses on modeling, control, and learning for continuum and soft robotic systems. + +--- + +### Solange Gribonval + +MSc Student & Research Intern +ร‰cole Polytechnique, Paris + +**Contact:** + +**Links:** + +- [:fontawesome-brands-github: GitHub](https://github.com/solangegbv) +- [:fontawesome-brands-linkedin: LinkedIn](https://www.linkedin.com/in/solange-gribonval-b70a5a292/) + +Solange contributes to the theoretical foundations and implementation of the library, with expertise in continuum mechanics and soft robot modeling. + +--- + +### Daniel Feliu Talegon + +Postdoctoral Researcher +Physical Intelligence (PhI) Lab, TU Delft + +**Links:** + +- [:fontawesome-brands-github: GitHub](https://github.com/DanielFeliuT91) +- [:fontawesome-brands-linkedin: LinkedIn](https://www.linkedin.com/in/daniel-feliu-talegon-3492a2161/) +- [:fontawesome-solid-graduation-cap: Google Scholar](https://scholar.google.com/citations?user=gCtANb8AAAAJ&hl=de&oi=ao) + +Daniel is a Postdoctoral Researcher at the PhI Lab contributing to the development and research of soft robotics systems. + +--- + +### Cosimo Della Santina + +Principal Investigator +Physical Intelligence (PhI) Lab, TU Delft + +**Links:** + +- [:fontawesome-solid-globe: Website](https://cosimodellasantina.eu) +- [:fontawesome-brands-linkedin: LinkedIn](https://www.linkedin.com/in/cosimodellasantina/) +- [:fontawesome-solid-graduation-cap: Google Scholar](https://scholar.google.com/citations?user=7RAU5jYAAAAJ&hl=en) + +Cosimo is the Principal Investigator of the Physical Intelligence Lab and leads the research direction of the project. + +## Maintainers + +The project is actively maintained by: + +- **Maximilian Stรถlzle** - Primary maintainer and lead developer + +## Contributing + +We welcome contributions from the community! If you're interested in contributing to this project, please check out our [Contributing Guide](development/contributing.md). + +## Acknowledgments + +This work is supported by the Physical Intelligence (PhI) Lab at TU Delft and benefits from collaborations with researchers worldwide working on soft robotics and continuum mechanics. + +### Theoretical Foundations + +We gratefully acknowledge the foundational contributions of Prof. Federico Renda, Prof. Frederic Boyer, and Dr. Anup Teejo Mathew, along with all other researchers who developed the soft robot strain models (including PCS - Piecewise Constant Strain, GVS - Geometric Variable-Strain, and other approaches) that are implemented in this library. Their pioneering work in continuum mechanics for soft robotics and the development of modeling frameworks has made this JAX implementation possible. + +### Inspiration + +This package was inspired by **SoRoSim**, a MATLAB toolbox for hybrid rigid-soft robots. We acknowledge the pioneering work of the SoRoSim team in making soft robot modeling accessible to the research community. + +**Reference:** +Mathew, A. T., Hmida, I. B., Armanini, C., Boyer, F., & Renda, F. (2022). Sorosim: A matlab toolbox for hybrid rigidโ€“soft robots based on the geometric variable-strain approach. *IEEE Robotics & Automation Magazine*, 30(3), 106-122. diff --git a/docs/development/changelog.md b/docs/development/changelog.md new file mode 100644 index 0000000..9989e08 --- /dev/null +++ b/docs/development/changelog.md @@ -0,0 +1,47 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added +- MkDocs documentation infrastructure +- Material theme for documentation +- API reference generation +- Comprehensive user guides + +### Changed +- Updated project structure for better organization + +### Fixed +- Various bug fixes and improvements + +## [0.1.0] - 2023-XX-XX + +### Added +- Initial release of JAX Soft Robot Modelling +- N-link pendulum implementation +- Planar Piecewise Constant Strain (PCS) continuum robot +- Planar Handed Shearing Auxetics (HSA) robot +- Symbolic derivation capabilities with SymPy +- JAX-based numerical implementations +- Comprehensive example suite +- Testing framework with pytest +- CI/CD pipeline with GitHub Actions + +### Features +- Fast, parallelizable, and differentiable simulations +- Multiple integration methods (explicit, autodiff, symbolic) +- Parameter sensitivity analysis +- Visualization and animation tools +- Extensible architecture for new robot types + +--- + +## Version History + +- **v0.1.0**: Initial release with core functionality +- **Future**: Planned additions include 3D robot models, additional soft robot types, and enhanced visualization tools diff --git a/docs/development/contributing.md b/docs/development/contributing.md new file mode 100644 index 0000000..2995dac --- /dev/null +++ b/docs/development/contributing.md @@ -0,0 +1,272 @@ +# Contributing + +Thank you for your interest in contributing to JAX Soft Robot Modelling! This guide will help you get started. + +## Development Setup + +### 1. Fork and Clone + +```bash +git clone https://github.com/YOUR_USERNAME/jax-soft-robot-modelling.git +cd jax-soft-robot-modelling +``` + +### 2. Install Development Dependencies + +```bash +pip install -e ".[dev,docs,examples]" +``` + +### 3. Set Up Pre-commit Hooks + +```bash +pre-commit install +``` + +### 4. Environment Variables + +```bash +source 01-configure-env-vars.sh +``` + +## Development Workflow + +### 1. Create a Branch + +```bash +git checkout -b feature/your-feature-name +``` + +### 2. Make Changes + +Follow our coding standards: +- Use type hints +- Write docstrings in Google format +- Follow PEP 8 style guidelines +- Add tests for new functionality + +### 3. Run Tests + +```bash +# Run all tests +pytest + +# Run specific test file +pytest tests/test_planar_pcs_num.py + +# Run with coverage +pytest --cov=jsrm +``` + +### 4. Format Code + +```bash +# Auto-format with ruff +ruff format . + +# Check for issues +ruff check . +``` + +### 5. Build Documentation + +```bash +# Serve documentation locally +mkdocs serve + +# Build documentation +mkdocs build +``` + +### 6. Commit Changes + +```bash +git add . +git commit -m "feat: add new robot system" +``` + +Use conventional commit messages: +- `feat:` for new features +- `fix:` for bug fixes +- `docs:` for documentation changes +- `test:` for test additions +- `refactor:` for code refactoring + +## Adding New Robot Systems + +### 1. System Structure + +Create a new module in `src/jsrm/systems/`: + +``` +src/jsrm/systems/your_robot/ +โ”œโ”€โ”€ __init__.py +โ”œโ”€โ”€ symbolic_derivation.py +โ”œโ”€โ”€ numerical_implementation.py +โ””โ”€โ”€ factory.py +``` + +### 2. Factory Pattern + +Follow the established factory pattern: + +```python +def factory(parameters): + """ + Factory function for your robot system. + + Args: + parameters: System-specific parameters + + Returns: + tuple: (ode_fn, forward_kinematics, jacobian_fn, additional_fns) + """ + pass +``` + +### 3. Testing + +Add comprehensive tests in `tests/`: + +```python +def test_your_robot_forward_kinematics(): + """Test forward kinematics computation.""" + pass + +def test_your_robot_dynamics(): + """Test dynamic simulation.""" + pass +``` + +### 4. Documentation + +Add examples and documentation: +- Example script in `examples/` +- Documentation in `docs/` +- Docstrings for all functions + +## Code Style + +### Python Style + +- Follow PEP 8 +- Use type hints for all function signatures +- Maximum line length: 88 characters +- Use descriptive variable names + +### Docstring Format + +Use Google-style docstrings: + +```python +def forward_kinematics(params: Dict, q: Array) -> Array: + """ + Compute forward kinematics for the robot. + + Args: + params: Dictionary of robot parameters including: + - l: Segment lengths + - r: Segment radii + - E: Young's moduli + q: Configuration vector of shape (n_dof,) + + Returns: + End-effector position of shape (2,) for planar robots + + Raises: + ValueError: If configuration vector has wrong dimensions + + Example: + >>> params = {"l": jnp.array([0.1]), "r": jnp.array([0.01])} + >>> q = jnp.array([0.0, 0.0, -1.0]) + >>> pos = forward_kinematics(params, q) + """ +``` + +### JAX Best Practices + +- Use `jax.numpy` instead of `numpy` +- Make functions JAX-transformable (pure, no side effects) +- Use `jit` for performance-critical functions +- Avoid Python loops in favor of JAX operations + +## Testing Guidelines + +### Test Structure + +```python +import pytest +import jax.numpy as jnp +from jsrm.systems import your_system + +class TestYourSystem: + def setup_method(self): + """Set up test fixtures.""" + self.params = { + # Test parameters + } + + def test_forward_kinematics(self): + """Test forward kinematics.""" + # Test implementation + pass + + def test_jacobian_computation(self): + """Test Jacobian computation.""" + # Test implementation + pass +``` + +### Test Coverage + +Aim for high test coverage: +- Unit tests for individual functions +- Integration tests for complete workflows +- Property-based tests for mathematical relationships +- Regression tests for bug fixes + +## Documentation Guidelines + +### API Documentation + +- Document all public functions and classes +- Include examples in docstrings +- Use type hints consistently +- Explain mathematical concepts clearly + +### User Documentation + +- Write clear, step-by-step tutorials +- Include complete, runnable examples +- Explain the mathematical background +- Provide troubleshooting guides + +## Submitting Changes + +### 1. Push Changes + +```bash +git push origin feature/your-feature-name +``` + +### 2. Create Pull Request + +- Provide a clear description of changes +- Reference related issues +- Include screenshots for UI changes +- Ensure all tests pass + +### 3. Code Review + +- Address reviewer feedback +- Update tests and documentation as needed +- Maintain a clean commit history + +## Getting Help + +- Open an issue for bugs or feature requests +- Join discussions in pull requests +- Check existing documentation and examples +- Ask questions in the community + +Thank you for contributing to JSRM! diff --git a/docs/gen_ref_pages.py b/docs/gen_ref_pages.py new file mode 100644 index 0000000..4c83f8f --- /dev/null +++ b/docs/gen_ref_pages.py @@ -0,0 +1,36 @@ +"""Generate the code reference pages and navigation.""" + +from pathlib import Path +import mkdocs_gen_files + +nav = mkdocs_gen_files.Nav() + +src = Path(__file__).parent.parent / "src" +for path in sorted(src.rglob("*.py")): + module_path = path.relative_to(src).with_suffix("") + doc_path = path.relative_to(src).with_suffix(".md") + full_doc_path = Path("api", doc_path) + + parts = tuple(module_path.parts) + + if parts[-1] == "__init__": + parts = parts[:-1] + doc_path = doc_path.with_name("index.md") + full_doc_path = full_doc_path.with_name("index.md") + elif parts[-1] == "__main__": + continue + + # Skip empty parts to avoid navigation errors + if not parts: + continue + + nav[parts] = doc_path.as_posix() + + with mkdocs_gen_files.open(full_doc_path, "w") as fd: + ident = ".".join(parts) + fd.write(f"# {ident}\n\n::: {ident}") + + mkdocs_gen_files.set_edit_path(full_doc_path, path) + +with mkdocs_gen_files.open("api/SUMMARY.md", "w") as nav_file: + nav_file.writelines(nav.build_literate_nav()) diff --git a/docs/includes/mkdocs.md b/docs/includes/mkdocs.md new file mode 100644 index 0000000..b4d88a5 --- /dev/null +++ b/docs/includes/mkdocs.md @@ -0,0 +1,12 @@ +*[JAX]: Just After eXecution - A library for high-performance machine learning research +*[PCS]: Piecewise Constant Strain +*[HSA]: Handed Shearing Auxetics +*[SE(2)]: Special Euclidean group in 2D +*[SE(3)]: Special Euclidean group in 3D +*[DOF]: Degrees of Freedom +*[JIT]: Just-In-Time compilation +*[API]: Application Programming Interface +*[GPU]: Graphics Processing Unit +*[TPU]: Tensor Processing Unit +*[CPU]: Central Processing Unit +*[JSRM]: JAX Soft Robot Modelling diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..668ead2 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,179 @@ +# ๐Ÿค– JAX Soft Robot Modelling + +
+ Welcome to JAX Soft Robot Modelling (JSRM)! A cutting-edge library for fast, parallelizable, and differentiable simulations of soft robots using JAX and symbolic mathematics. +
+ +--- + +## ๐ŸŽฏ Overview + +This repository contains symbolic derivations of the kinematics and dynamics of various soft robots using **SymPy**. +The symbolic expressions are then implemented in **JAX** and can be used for fast, parallelizable, and differentiable simulations. + +
+
+

โšก JAX-Powered

+

Leverage JAX for lightning-fast computations with automatic differentiation and JIT compilation

+
+ +
+

๐Ÿงฎ Symbolic Foundation

+

Mathematically rigorous models derived from first principles using symbolic computation

+
+ +
+

๐Ÿ”ง Modular Design

+

Extensible architecture that makes it easy to add new robot types and configurations

+
+ +
+

๐Ÿ“Š Differentiable

+

Full gradient support for optimization, control, and machine learning applications

+
+ +
+

๐Ÿš€ High Performance

+

Parallelizable computations that scale efficiently across multiple devices

+
+ +
+

๐Ÿ”ฌ Research-Ready

+

Validated implementations used in peer-reviewed robotics research

+
+
+ +--- + +## ๐Ÿค– Supported Robot Types + +We focus on planar settings and have implemented the following soft robot architectures: + +!!! note "๐Ÿฆพ **N-link Pendulum**" + Classical articulated robot perfect for benchmarking and comparison studies + +!!! tip "๐ŸŒŠ **Planar Piecewise Constant Strain (PCS)**" + Advanced continuum soft robot with constant strain segments for precise modeling + +!!! info "๐Ÿ”— **Planar Handed Shearing Auxetics (HSA)**" + Novel soft robot with auxetic properties for unique deformation characteristics + +--- + +## โœจ Key Features + +=== "๐Ÿš€ Performance" + + - **JAX Backend**: Ultra-fast computations with automatic vectorization + - **JIT Compilation**: Optimized machine code generation for maximum speed + - **GPU/TPU Support**: Seamless acceleration on modern hardware + - **Parallel Processing**: Scale across multiple devices effortlessly + +=== "๐Ÿง  Intelligence" + + - **Automatic Differentiation**: Full gradient support for all operations + - **Symbolic Derivation**: Mathematically rigorous kinematic and dynamic models + - **Optimization Ready**: Perfect for control and learning applications + - **Numerical Stability**: Robust implementations that handle edge cases + +=== "๐Ÿ”ง Usability" + + - **Clean API**: Intuitive interfaces that are easy to learn and use + - **Comprehensive Documentation**: Detailed guides, examples, and API reference + - **Extensible Design**: Add new robot types and configurations with ease + - **Research Proven**: Validated in real-world robotics applications + +--- + +## ๐Ÿš€ Quick Start + +Get up and running in minutes: + +=== "Installation" + + ```bash + pip install jsrm + ``` + +=== "Basic Usage" + + ```python + import jax.numpy as jnp + from jsrm.systems import PlanarPCS + + # Create a planar PCS robot + robot = PlanarPCS(num_segments=3, params=params) + + # Compute forward kinematics + q = jnp.array([0.1, 0.2, 0.3]) # Configuration + chi = robot.forward_kinematics(q, s=1.0) # End-effector pose + ``` + +=== "Advanced Features" + + ```python + # Compute Jacobians for control + J = robot.jacobian(q, s=1.0) + + # Dynamic simulation + B, C, G, K, D, A = robot.dynamical_matrices(q, qd) + + # Differentiable operations + loss_fn = lambda q: jnp.sum(robot.forward_kinematics(q, s=1.0)**2) + grad_fn = jax.grad(loss_fn) + ``` + +--- + +## ๐Ÿ“š Quick Links + +
+
+

๐Ÿ“ฆ [Installation Guide](installation.md)

+

Get JSRM installed and configured on your system

+
+ +
+

๐Ÿš€ [Quick Start](user-guide/quick-start.md)

+

Jump right in with hands-on tutorials and examples

+
+ +
+

๐Ÿ“– [Examples](user-guide/examples.md)

+

Explore comprehensive examples and use cases

+
+ +
+

๐Ÿ“‹ [API Reference](api/systems.md)

+

Complete documentation of all classes and functions

+
+
+ +--- + +## ๐Ÿ“„ Citation + +This simulator is part of the publication **"An Experimental Study of Model-based Control for Planar Handed Shearing Auxetics Robots"** presented at the *18th International Symposium on Experimental Robotics*. + +!!! quote "If you use our software in your research, please cite:" + + ```bibtex + @inproceedings{stolzle2023experimental, + title={An experimental study of model-based control for planar handed shearing auxetics robots}, + author={St{\"o}lzle, Maximilian and Rus, Daniela and Della Santina, Cosimo}, + booktitle={International Symposium on Experimental Robotics}, + pages={153--167}, + year={2023}, + organization={Springer} + } + ``` + +--- + +## ๐Ÿค Contributing + +We welcome contributions! Please see our [Contributing Guide](development/contributing.md) for details on how to get started. + +## License + +This project is licensed under the MIT License - see the [LICENSE.txt](https://github.com/tud-phi/jax-soft-robot-modelling/blob/main/LICENSE.txt) file for details. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..faae898 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,229 @@ +# ๐Ÿ“ฆ Installation + +
+ Get started with JSRM in minutes! Choose from multiple installation methods to get JAX Soft Robot Modelling running on your system. +
+ +--- + +## ๐Ÿ”ง Requirements + +!!! note "System Requirements" + - **Python** >= 3.10 + - **JAX** >= 0.4.0 + - **NumPy** >= 1.21.0 + +--- + +## ๐Ÿš€ Quick Install + +=== "๐Ÿ PyPI (Recommended)" + + The easiest way to install JSRM is from PyPI: + + ```bash + pip install jsrm + ``` + + !!! success "Ready to go!" + This installs the core JSRM package with all essential dependencies. + +=== "๐Ÿ”จ From Source" + + For development or to get the latest features: + + ```bash + git clone https://github.com/tud-phi/jax-soft-robot-modelling.git + cd jax-soft-robot-modelling + pip install -e . + ``` + + !!! tip "Development Mode" + The `-e` flag installs in "editable" mode, so changes to the source code are immediately available. + +=== "๐Ÿ‹ Docker" + + Use our pre-built Docker container: + + ```bash + docker pull ghcr.io/tud-phi/jax-soft-robot-modelling:latest + docker run -it --rm ghcr.io/tud-phi/jax-soft-robot-modelling:latest + ``` + +--- + +## ๐ŸŽฏ Installation Options + +### ๐Ÿ“š Examples Dependencies + +To run all examples and tutorials: + +```bash +pip install jsrm[examples] +``` + +**Includes:** + +- `diffrax` - Advanced differential equation solving +- `jaxopt` - High-performance optimization algorithms +- `matplotlib` - Publication-ready plotting and visualization +- `opencv-python` - Computer vision and image processing +- `scipy` - Scientific computing utilities + +### ๐Ÿ› ๏ธ Development Dependencies + +For contributing to JSRM: + +```bash +pip install jsrm[dev] +``` + +**Includes:** + +- `pytest` - Testing framework +- `black` - Code formatting +- `flake8` - Code linting +- `mypy` - Type checking +- `pre-commit` - Git hooks + +### ๐Ÿ“– Documentation Dependencies + +To build documentation locally: + +```bash +pip install jsrm[docs] +``` + +**Includes:** + +- `mkdocs-material` - Modern documentation theme +- `mkdocstrings` - API documentation generation +- `mkdocs-jupyter` - Jupyter notebook integration + +### ๐ŸŽ‰ Complete Installation + +Get everything at once: + +```bash +pip install jsrm[all] +``` + +--- + +## โš™๏ธ Environment Setup + +!!! warning "Important Step" + After installation, always source the environment variables when opening a new terminal: + + ```bash + source 01-configure-env-vars.sh + ``` + + This ensures JSRM can find all necessary configuration files and paths. + +--- + +## โœ… Verification + +Test your installation with this quick verification script: + +=== "๐Ÿงช Basic Test" + + ```python + import jax.numpy as jnp + from jsrm.systems import planar_pcs_num + + # Create a simple 1-segment PCS robot + num_segments = 1 + strain_selector = jnp.ones((3 * num_segments,), dtype=bool) + + # Initialize the system + _, forward_kinematics, _, _ = planar_pcs_num.factory( + num_segments, + strain_selector + ) + + print("๐ŸŽ‰ JSRM installation successful!") + ``` + +=== "๐Ÿš€ Advanced Test" + + ```python + import jax + import jax.numpy as jnp + from jsrm.systems.planar_pcs import PlanarPCS + from jsrm.parameters import Params + + # Test JAX compilation and differentiation + @jax.jit + def test_function(q): + robot = PlanarPCS(num_segments=2, params=Params.default()) + return robot.forward_kinematics(q, s=1.0) + + # Test with sample configuration + q = jnp.array([0.1, 0.0, 0.0, 0.1, 0.0, 0.0]) + result = test_function(q) + + # Test differentiation + grad_fn = jax.grad(lambda q: jnp.sum(test_function(q)**2)) + gradient = grad_fn(q) + + print(f"โœ… Forward kinematics: {result}") + print(f"โœ… Gradient computation: {gradient}") + print("๐ŸŽ‰ Advanced features working perfectly!") + ``` + +--- + +## ๐Ÿ”ง Troubleshooting + +!!! question "Common Issues" + + === "๐Ÿ Python Version" + + **Problem:** `ImportError` or compatibility issues + + **Solution:** Ensure you're using Python 3.10 or later: + ```bash + python --version # Should be >= 3.10 + ``` + + === "๐Ÿ“ฆ JAX Installation" + + **Problem:** JAX import errors or GPU issues + + **Solution:** Install JAX with proper hardware support: + ```bash + # For CPU only + pip install jax[cpu] + + # For NVIDIA GPU + pip install jax[cuda12_pip] + + # For Apple Silicon + pip install jax[metal] + ``` + + === "๐Ÿ”ง Environment Variables" + + **Problem:** Module not found errors + + **Solution:** Ensure environment is properly configured: + ```bash + # Check if variables are set + echo $PYTHONPATH + + # Re-source the configuration + source 01-configure-env-vars.sh + ``` + +--- + +## ๐Ÿ†˜ Getting Help + +!!! info "Need assistance?" + + - ๐Ÿ“š **Documentation**: Check our [API Reference](api/systems.md) + - ๐Ÿ’ฌ **Discussions**: Join our [GitHub Discussions](https://github.com/tud-phi/jax-soft-robot-modelling/discussions) + - ๐Ÿ› **Issues**: Report bugs on [GitHub Issues](https://github.com/tud-phi/jax-soft-robot-modelling/issues) + - ๐Ÿ“ง **Email**: Contact us at `m.stolzle@tudelft.nl` diff --git a/docs/javascripts/mathjax.js b/docs/javascripts/mathjax.js new file mode 100644 index 0000000..80e81ba --- /dev/null +++ b/docs/javascripts/mathjax.js @@ -0,0 +1,12 @@ +window.MathJax = { + tex: { + inlineMath: [["\\(", "\\)"]], + displayMath: [["\\[", "\\]"]], + processEscapes: true, + processEnvironments: true + }, + options: { + ignoreHtmlClass: ".*|", + processHtmlClass: "arithmatex" + } +}; diff --git a/docs/overrides/main.html b/docs/overrides/main.html new file mode 100644 index 0000000..94d9808 --- /dev/null +++ b/docs/overrides/main.html @@ -0,0 +1 @@ +{% extends "base.html" %} diff --git a/docs/overrides/partials/footer.html b/docs/overrides/partials/footer.html new file mode 100644 index 0000000..52e84b0 --- /dev/null +++ b/docs/overrides/partials/footer.html @@ -0,0 +1,73 @@ +{% import "partials/language.html" as lang with context %} + + diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..330b517 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,499 @@ +/* Custom styling for JAX Soft Robot Modelling documentation */ + +:root { + /* Custom color palette */ + --md-primary-fg-color: #3f51b5; + --md-primary-fg-color--light: #7986cb; + --md-primary-fg-color--dark: #303f9f; + --md-accent-fg-color: #009688; + --md-accent-fg-color--transparent: #0096881a; + + /* Custom gradients */ + --gradient-primary: linear-gradient(135deg, #667eea 0%, #764ba2 100%); + --gradient-accent: linear-gradient(135deg, #f093fb 0%, #f5576c 100%); + --gradient-success: linear-gradient(135deg, #4facfe 0%, #00f2fe 100%); + + /* Shadows */ + --shadow-light: 0 2px 8px rgba(0, 0, 0, 0.1); + --shadow-medium: 0 4px 16px rgba(0, 0, 0, 0.15); + --shadow-heavy: 0 8px 32px rgba(0, 0, 0, 0.2); +} + +/* Hero section styling */ +.md-content__inner > h1:first-child { + background: var(--gradient-primary); + -webkit-background-clip: text; + -webkit-text-fill-color: transparent; + background-clip: text; + font-size: 3.2rem; + font-weight: 700; + text-align: center; + margin-bottom: 2rem; + line-height: 1.2; +} + +/* Enhanced cards and admonitions */ +.md-typeset .admonition, +.md-typeset details { + border-radius: 12px; + box-shadow: var(--shadow-light); + border: none; + overflow: hidden; + transition: all 0.3s ease; +} + +.md-typeset .admonition:hover, +.md-typeset details:hover { + box-shadow: var(--shadow-medium); + transform: translateY(-2px); +} + +/* Special styling for different admonition types */ +.md-typeset .admonition.note { + background: linear-gradient(135deg, #e3f2fd 0%, #f3e5f5 100%); +} + +.md-typeset .admonition.tip { + background: linear-gradient(135deg, #e8f5e8 0%, #f1f8e9 100%); +} + +.md-typeset .admonition.warning { + background: linear-gradient(135deg, #fff8e1 0%, #fff3e0 100%); +} + +.md-typeset .admonition.danger { + background: linear-gradient(135deg, #ffebee 0%, #fce4ec 100%); +} + +/* Code blocks enhancement */ +.md-typeset .highlight { + border-radius: 12px; + overflow: hidden; + box-shadow: var(--shadow-light); + margin: 1.5rem 0; +} + +.md-typeset pre { + border-radius: 12px; +} + +.md-typeset code { + background: rgba(var(--md-accent-fg-color--rgb), 0.1); + border-radius: 6px; + padding: 0.2rem 0.4rem; + font-weight: 500; +} + +/* Navigation enhancements */ +.md-tabs__item { + transition: all 0.3s ease; +} + +.md-tabs__item:hover { + background: rgba(var(--md-accent-fg-color--rgb), 0.1); + border-radius: 8px; +} + +/* Search box styling */ +.md-search__form { + border-radius: 25px; + box-shadow: var(--shadow-light); + transition: all 0.3s ease; +} + +.md-search__form:hover { + box-shadow: var(--shadow-medium); +} + +/* Button enhancements */ +.md-button { + border-radius: 25px; + background: var(--gradient-primary); + border: none; + padding: 0.8rem 2rem; + font-weight: 600; + box-shadow: var(--shadow-light); + transition: all 0.3s ease; +} + +.md-button:hover { + box-shadow: var(--shadow-medium); + transform: translateY(-2px); +} + +.md-button--primary { + background: var(--gradient-accent); +} + +/* Table styling */ +.md-typeset table:not([class]) { + border-radius: 12px; + overflow: hidden; + box-shadow: var(--shadow-light); + border: none; +} + +.md-typeset table:not([class]) th { + background: var(--gradient-primary); + color: white; + font-weight: 600; +} + +.md-typeset table:not([class]) tr:nth-child(even) { + background: rgba(var(--md-primary-fg-color--rgb), 0.05); +} + +/* Feature cards */ +.feature-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); + gap: 2rem; + margin: 2rem 0; +} + +.feature-card { + background: white; + border-radius: 16px; + padding: 2rem; + box-shadow: var(--shadow-light); + transition: all 0.3s ease; + border: 1px solid rgba(var(--md-primary-fg-color--rgb), 0.1); +} + +.feature-card:hover { + box-shadow: var(--shadow-medium); + transform: translateY(-4px); +} + +.feature-card h3 { + color: var(--md-primary-fg-color); + margin-bottom: 1rem; + display: flex; + align-items: center; + gap: 0.5rem; +} + +.feature-card .icon { + font-size: 1.5rem; + color: var(--md-accent-fg-color); +} + +/* API documentation enhancements */ +.doc-summary { + background: linear-gradient(135deg, #f8f9fa 0%, #e9ecef 100%); + border-radius: 8px; + padding: 1rem; + margin: 1rem 0; + border-left: 4px solid var(--md-accent-fg-color); +} + +/* Enhanced method signatures - hierarchical styling with blue/purple background */ +/* Class headers (h4) - larger and more prominent */ +h2[id^="jsrm"], h3[id^="jsrm"], h4[id^="jsrm"] { + background: linear-gradient(135deg, #4f46e5 0%, #7c3aed 100%); + color: white !important; + padding: 1.2rem 1.5rem; + margin: 2rem 0 1.2rem 0; + border-radius: 8px; + font-size: 1.5rem !important; + font-weight: 700 !important; + box-shadow: 0 4px 16px rgba(79, 70, 229, 0.25); + border: none !important; + position: relative; +} + +/* Method headers (h5) - smaller than class headers */ +h5[id^="jsrm"] { + background: linear-gradient(135deg, #4f46e5 0%, #7c3aed 100%); + color: white !important; + padding: 0.8rem 1rem; + margin: 1.5rem 0 0.8rem 0; + border-radius: 6px; + font-size: 1.2rem !important; + font-weight: 600 !important; + box-shadow: 0 3px 12px rgba(79, 70, 229, 0.2); + border: none !important; + position: relative; +} + +/* Target mkdocstrings method headings specifically */ +.doc.doc-heading { + background: linear-gradient(135deg, #4f46e5 0%, #7c3aed 100%) !important; + color: white !important; + padding: 0.8rem 1rem !important; + margin: 1.5rem 0 0.8rem 0 !important; + border-radius: 6px !important; + font-size: 1.2rem !important; + font-weight: 600 !important; + box-shadow: 0 3px 12px rgba(79, 70, 229, 0.2) !important; + border: none !important; + position: relative; +} + +/* Method name styling within the heading */ +.doc-object-name.doc-function-name { + color: white !important; + font-size: 1.2rem !important; + font-weight: 600 !important; +} + +/* Code symbols in method headings */ +.doc-heading .doc-symbol { + color: white !important; + background: rgba(255, 255, 255, 0.15) !important; + padding: 0.2rem 0.4rem !important; + border-radius: 4px !important; +} + +/* Icons for class headers (larger) */ +h2[id^="jsrm"]:before, h3[id^="jsrm"]:before, h4[id^="jsrm"]:before { + content: "๐Ÿ—๏ธ"; + position: absolute; + right: 1.2rem; + top: 50%; + transform: translateY(-50%); + font-size: 1.2rem; + opacity: 0.8; +} + +/* Icons for method headers (smaller) */ +h5[id^="jsrm"]:before { + content: "๐Ÿ”ง"; + position: absolute; + right: 1rem; + top: 50%; + transform: translateY(-50%); + font-size: 1rem; + opacity: 0.8; +} + +/* Code styling for class headers */ +h2[id^="jsrm"] code, h3[id^="jsrm"] code, h4[id^="jsrm"] code { + background: rgba(255, 255, 255, 0.15) !important; + color: white !important; + padding: 0.4rem 0.8rem; + border-radius: 5px; + font-size: 1.3rem !important; + font-weight: 700 !important; +} + +/* Code styling for method headers */ +h5[id^="jsrm"] code { + background: rgba(255, 255, 255, 0.15) !important; + color: white !important; + padding: 0.3rem 0.6rem; + border-radius: 4px; + font-size: 1.1rem !important; + font-weight: 600 !important; +} + +h2[id^="jsrm"] a, h3[id^="jsrm"] a, h4[id^="jsrm"] a { + color: white !important; + text-decoration: none !important; +} + +/* Class and function headings - slightly smaller */ +h2[id*="class"], h2[id*="function"], h2[id*="method"] { + background: linear-gradient(135deg, #059669 0%, #0d9488 100%); + color: white !important; + padding: 0.75rem 1rem; + margin: 1.5rem 0 0.75rem 0; + border-radius: 8px; + font-size: 1.1rem !important; + font-weight: 600 !important; + box-shadow: 0 2px 8px rgba(5, 150, 105, 0.15); +} + +h2[id*="class"]:before { + content: "๐Ÿ—๏ธ"; + position: absolute; + right: 0.75rem; + top: 50%; + transform: translateY(-50%); + font-size: 0.9rem; +} + +h2[id*="function"]:before, h2[id*="method"]:before { + content: "โš™๏ธ"; + position: absolute; + right: 0.75rem; + top: 50%; + transform: translateY(-50%); + font-size: 0.9rem; +} + +/* Property headings */ +h3[id*="property"], h4[id*="property"] { + background: linear-gradient(135deg, #dc2626 0%, #ea580c 100%); + color: white !important; +} + +h3[id*="property"]:before, h4[id*="property"]:before { + content: "๐Ÿ“‹"; +} + +/* Parameter and Return tables - reduced size and padding */ +.md-typeset table:not([class]) { + border-radius: 6px; + overflow: hidden; + box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08); + border: 1px solid rgba(var(--md-default-fg-color--rgb), 0.1); + margin: 0.5rem 0; + font-size: 0.78rem; +} + +.md-typeset table:not([class]) th { + background: linear-gradient(135deg, #6b7280 0%, #9ca3af 100%); + color: white; + font-weight: 600; + font-size: 0.72rem; + padding: 0.35rem 0.5rem; + text-transform: uppercase; + letter-spacing: 0.4px; +} + +.md-typeset table:not([class]) td { + padding: 0.3rem 0.5rem; + vertical-align: top; + font-size: 0.78rem; + line-height: 1.3; +} + +.md-typeset table:not([class]) tr:nth-child(even) { + background: rgba(var(--md-primary-fg-color--rgb), 0.02); +} + +/* Code in table cells - smaller and more subtle */ +.md-typeset table:not([class]) td code { + background: rgba(var(--md-accent-fg-color--rgb), 0.08); + color: var(--md-accent-fg-color); + font-weight: 500; + padding: 0.1rem 0.25rem; + border-radius: 3px; + font-size: 0.72rem; +} + +/* Docstring sections - consistent with sidebar */ +.md-typeset h4 { + color: var(--md-primary-fg-color); + font-weight: 600; + margin: 1rem 0 0.5rem 0; + font-size: 1rem; +} + +/* Method separator - more subtle */ +hr { + border: none; + height: 1px; + background: linear-gradient(90deg, transparent, var(--md-default-fg-color--light), transparent); + margin: 2rem 0; + opacity: 0.3; +} + +/* Footer enhancements */ +.md-footer { + background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important; + border-top: 1px solid rgba(255, 255, 255, 0.1); +} + +.md-footer-meta { + background: rgba(0, 0, 0, 0.1) !important; +} + +.md-footer__inner { + max-width: 1200px; + margin: 0 auto; +} + +.md-footer-meta__inner { + max-width: 1200px; + margin: 0 auto; +} + +/* Fix oversized social media icons */ +.md-footer__social-link { + width: 32px !important; + height: 32px !important; + display: inline-flex !important; + align-items: center !important; + justify-content: center !important; +} + +.md-footer__social-link svg { + width: 20px !important; + height: 20px !important; + max-width: 20px !important; + max-height: 20px !important; +} + +.md-footer__social { + display: flex !important; + gap: 0.5rem !important; + align-items: center !important; +} + +/* Responsive adjustments */ +@media screen and (max-width: 768px) { + .md-content__inner > h1:first-child { + font-size: 2.5rem; + } + + .feature-grid { + grid-template-columns: 1fr; + gap: 1rem; + } + + .feature-card { + padding: 1.5rem; + } +} + +/* Dark mode adjustments */ +[data-md-color-scheme="slate"] { + --gradient-primary: linear-gradient(135deg, #4a5568 0%, #2d3748 100%); + --gradient-accent: linear-gradient(135deg, #805ad5 0%, #553c9a 100%); +} + +[data-md-color-scheme="slate"] .feature-card { + background: var(--md-default-bg-color); + border-color: rgba(255, 255, 255, 0.1); +} + +[data-md-color-scheme="slate"] .doc-summary { + background: rgba(255, 255, 255, 0.05); +} + +/* Animation for page load */ +@keyframes fadeInUp { + from { + opacity: 0; + transform: translateY(20px); + } + to { + opacity: 1; + transform: translateY(0); + } +} + +.md-content__inner { + animation: fadeInUp 0.6s ease-out; +} + +/* Custom scrollbar */ +::-webkit-scrollbar { + width: 8px; +} + +::-webkit-scrollbar-track { + background: rgba(var(--md-primary-fg-color--rgb), 0.1); + border-radius: 4px; +} + +::-webkit-scrollbar-thumb { + background: var(--gradient-primary); + border-radius: 4px; +} + +::-webkit-scrollbar-thumb:hover { + background: var(--gradient-accent); +} diff --git a/docs/user-guide/examples.md b/docs/user-guide/examples.md new file mode 100644 index 0000000..4a40c55 --- /dev/null +++ b/docs/user-guide/examples.md @@ -0,0 +1,199 @@ +# Examples + +This page provides an overview of the example scripts included with JSRM. + +## Available Examples + +### Pendulum Examples + +#### Single Pendulum +```bash +python examples/simulate_pendulum.py +``` + +Demonstrates: +- Basic pendulum dynamics +- Numerical integration with JAX +- Visualization of results + +#### Double Pendulum +```python +# Modify examples/simulate_pendulum.py +num_links = 2 # Change this line +``` + +### Soft Robot Examples + +#### Planar PCS Robot +```bash +python examples/simulate_planar_pcs.py +``` + +Features: +- Piecewise Constant Strain kinematics +- Continuum robot dynamics +- Parameter sensitivity analysis + +#### HSA Robot +```bash +python examples/simulate_planar_hsa.py +``` + +Demonstrates: +- Handed Shearing Auxetics mechanics +- Motor-to-end-effector Jacobians +- Control applications + +### Analysis Examples + +#### Symbolic Derivation +```bash +python examples/derive_planar_pcs.py +``` + +Shows how to: +- Generate symbolic expressions +- Export for numerical use +- Validate against numerical methods + +#### Benchmarking +```bash +python examples/benchmark_planar_pcs.py +``` + +Compares: +- Different integration methods +- Symbolic vs numerical approaches +- Performance characteristics + +## Running Examples + +### Prerequisites + +Install example dependencies: +```bash +pip install -e ".[examples]" +``` + +### Environment Setup + +Always source environment variables first: +```bash +source 01-configure-env-vars.sh +``` + +### Basic Workflow + +1. **Derive symbolic expressions** (if needed): + ```bash + python examples/derive_[robot_type].py + ``` + +2. **Run simulation**: + ```bash + python examples/simulate_[robot_type].py + ``` + +3. **Analyze results** in generated plots and videos + +## Customizing Examples + +### Parameter Modification + +Most examples allow easy parameter modification: + +```python +# In any example file +params = { + "l": 0.2, # Change length + "r": 0.01, # Change radius + "E": 1e6, # Change Young's modulus + # ... other parameters +} +``` + +### Output Customization + +Control visualization and output: + +```python +# Enable/disable video recording +create_video = True + +# Adjust simulation time +t_span = (0.0, 10.0) # 10 seconds + +# Change integration parameters +dt = 0.001 # Smaller timestep for higher accuracy +``` + +## Advanced Examples + +### GUI Testing Tools + +Interactive parameter exploration: +```bash +python tests/gui_test_fwd_kine_eps_planar_pcs.py +``` + +Features: +- Real-time parameter adjustment +- Multiple Jacobian method comparison +- Strain visualization + +### Segment Fusion Analysis +```bash +python examples/analyze_segment_fusion.py +``` + +Investigates: +- Multi-segment behavior +- Coupling effects +- Performance optimization + +## Troubleshooting + +### Common Issues + +1. **Import errors**: Ensure JSRM is installed with `pip install -e .` +2. **Missing dependencies**: Install examples group with `pip install -e ".[examples]"` +3. **Environment variables**: Always run `source 01-configure-env-vars.sh` + +### Performance Tips + +- Use smaller `dt` for accuracy vs speed tradeoffs +- Enable JAX JIT compilation for repeated runs +- Consider using GPU acceleration for large-scale studies + +## Creating New Examples + +To create a new example: + +1. **Choose a base example** similar to your use case +2. **Copy and modify** parameters and logic +3. **Test thoroughly** with different configurations +4. **Add documentation** explaining the new features + +Example template: +```python +#!/usr/bin/env python3 +""" +New Example: Description of what this example demonstrates +""" + +import jax.numpy as jnp +from jsrm.systems import your_system + +# Parameters +params = { + # Your parameters here +} + +# Main simulation logic +def main(): + # Your code here + pass + +if __name__ == "__main__": + main() +``` diff --git a/docs/user-guide/quick-start.md b/docs/user-guide/quick-start.md new file mode 100644 index 0000000..557221b --- /dev/null +++ b/docs/user-guide/quick-start.md @@ -0,0 +1,337 @@ +# ๐Ÿš€ Quick Start + +
+ Get up and running with JSRM in minutes! This hands-on guide walks you through your first soft robot simulation with step-by-step examples. +
+ +--- + +## ๐ŸŽฏ Your First Simulation + +Let's dive right in with a classic example - simulating a double pendulum to understand the basics: + +=== "๐Ÿ”ง Setup" + + ```python + import jax.numpy as jnp + import matplotlib.pyplot as plt + from jsrm.systems import pendulum + import diffrax + + # Define parameters for a double pendulum + num_links = 2 + params = { + "l": jnp.array([0.5, 0.3]), # Link lengths [m] + "lc": jnp.array([0.25, 0.15]), # Center of mass positions [m] + "m": jnp.array([1.0, 0.5]), # Masses [kg] + "I": jnp.array([0.1, 0.05]), # Moments of inertia [kgโ‹…mยฒ] + "g": 9.81, # Gravity [m/sยฒ] + } + ``` + +=== "๐Ÿ—๏ธ Initialize" + + ```python + # Create the system using the factory pattern + ode_fn, forward_kinematics, jacobian_end_effector, _ = pendulum.factory(num_links) + + # Set initial conditions + q0 = jnp.array([jnp.pi/4, jnp.pi/6]) # Initial angles [rad] + q_dot0 = jnp.array([0.0, 0.0]) # Initial velocities [rad/s] + state0 = jnp.concatenate([q0, q_dot0]) + ``` + +=== "โšก Simulate" + + ```python + # Configure simulation + t_span = (0.0, 5.0) # 5 seconds + dt = 0.01 # 10ms timestep + saveat = diffrax.SaveAt(ts=jnp.arange(0, 5.0, dt)) + + # Solve the differential equation + solution = diffrax.diffeqsolve( + diffrax.ODETerm(lambda t, state, args: ode_fn(params, state)), + diffrax.Dopri5(), # 5th-order Runge-Kutta + t0=t_span[0], + t1=t_span[1], + dt0=dt, + y0=state0, + saveat=saveat, + ) + ``` + +=== "๐Ÿ“Š Analyze" + + ```python + # Extract results + t = solution.ts + states = solution.ys + q = states[:, :num_links] + q_dot = states[:, num_links:] + + # Compute end-effector trajectory + end_effector_positions = jnp.array([ + forward_kinematics(params, q_i)[-2:] for q_i in q # Get [x, y] position + ]) + + # Create visualization + fig, (ax1, ax2, ax3) = plt.subplots(3, 1, figsize=(12, 10)) + + # Joint angles over time + ax1.plot(t, q[:, 0], label='Joint 1', linewidth=2, color='#1f77b4') + ax1.plot(t, q[:, 1], label='Joint 2', linewidth=2, color='#ff7f0e') + ax1.set_ylabel('Joint Angles [rad]') + ax1.set_title('๐Ÿ”„ Joint Angles vs Time') + ax1.legend() + ax1.grid(True, alpha=0.3) + + # Joint velocities over time + ax2.plot(t, q_dot[:, 0], label='Joint 1', linewidth=2, color='#1f77b4') + ax2.plot(t, q_dot[:, 1], label='Joint 2', linewidth=2, color='#ff7f0e') + ax2.set_ylabel('Joint Velocities [rad/s]') + ax2.set_title('๐Ÿ’จ Joint Velocities vs Time') + ax2.legend() + ax2.grid(True, alpha=0.3) + + # End-effector trajectory + ax3.plot(end_effector_positions[:, 0], end_effector_positions[:, 1], + linewidth=3, color='#2ca02c', alpha=0.8) + ax3.scatter(end_effector_positions[0, 0], end_effector_positions[0, 1], + s=100, color='green', marker='o', label='Start', zorder=5) + ax3.scatter(end_effector_positions[-1, 0], end_effector_positions[-1, 1], + s=100, color='red', marker='s', label='End', zorder=5) + ax3.set_xlabel('X Position [m]') + ax3.set_ylabel('Y Position [m]') + ax3.set_title('๐ŸŽฏ End-Effector Trajectory') + ax3.legend() + ax3.grid(True, alpha=0.3) + ax3.axis('equal') + + plt.tight_layout() + plt.show() + ``` + +!!! success "๐ŸŽ‰ Congratulations!" + You've just simulated your first robot with JSRM! The pendulum exhibits chaotic motion due to its nonlinear dynamics. + +--- + +## ๐Ÿง  Core Concepts + +### ๐Ÿญ Factory Pattern + +JSRM uses an elegant factory pattern to create system functions: + +```python title="System Creation" +ode_fn, forward_kinematics, jacobian_fn, _ = system.factory(parameters) +``` + +**Returns:** + +- `ode_fn` โ†’ Differential equations for numerical integration +- `forward_kinematics` โ†’ Position and orientation computation +- `jacobian_fn` โ†’ Velocity relationships and sensitivities +- `_` โ†’ Additional system-specific functions + +!!! tip "Why Factory Pattern?" + This approach allows JAX to optimize the entire computation graph at compile time, resulting in much faster execution. + +### ๐Ÿ“‹ Parameter Dictionary + +Each robot system expects a structured parameter dictionary: + +```python title="Parameter Structure" +params = { + "l": link_lengths, # Physical dimensions + "m": masses, # Inertial properties + "I": inertias, # Rotational inertia + "g": gravity, # Environmental forces + # ... system-specific parameters +} +``` + +!!! note "Units Matter" + Always use consistent SI units (meters, kilograms, seconds) for reliable results. + +### ๐Ÿ”„ State Representation + +Robot states follow a consistent `[positions, velocities]` format: + +```python title="State Vector" +# For an n-DOF system: +positions = q # Shape: (n,) +velocities = q_dot # Shape: (n,) +state = jnp.concatenate([q, q_dot]) # Shape: (2n,) +``` + +--- + +## ๐Ÿค– Soft Robot Example + +Ready for something more advanced? Let's simulate a soft continuum robot: + +=== "๐ŸŒŠ Continuum Robot" + + ```python + from jsrm.systems.planar_pcs import PlanarPCS + from jsrm.parameters import Params + + # Create a 3-segment soft robot + num_segments = 3 + params = Params.default_planar_pcs(num_segments) + + # Initialize the PCS robot + robot = PlanarPCS( + num_segments=num_segments, + params=params, + ) + + # Define configuration (strains) + q = jnp.array([0.1, 0.0, 0.0, # Segment 1: [curvature, shear_x, shear_y] + 0.2, 0.0, 0.0, # Segment 2 + 0.3, 0.0, 0.0]) # Segment 3 + + # Compute forward kinematics along the robot + s_values = jnp.linspace(0, robot.L.sum(), 100) + backbone_shape = jnp.array([ + robot.forward_kinematics(q, s) for s in s_values + ]) + + # Extract positions for plotting + x_positions = backbone_shape[:, 1] # X coordinates + y_positions = backbone_shape[:, 2] # Y coordinates + + # Visualize the robot shape + plt.figure(figsize=(10, 6)) + plt.plot(x_positions, y_positions, 'b-', linewidth=4, label='Robot Backbone') + plt.scatter(x_positions[0], y_positions[0], s=150, color='green', + marker='o', label='Base', zorder=5) + plt.scatter(x_positions[-1], y_positions[-1], s=150, color='red', + marker='s', label='Tip', zorder=5) + plt.xlabel('X Position [m]') + plt.ylabel('Y Position [m]') + plt.title('๐ŸŒŠ Soft Continuum Robot Shape') + plt.legend() + plt.grid(True, alpha=0.3) + plt.axis('equal') + plt.show() + ``` + +=== "๐Ÿ“ Jacobian Analysis" + + ```python + # Compute Jacobian at the end-effector + s_tip = robot.L.sum() # End of the robot + J = robot.jacobian(q, s_tip) + + print(f"๐Ÿ” Jacobian shape: {J.shape}") + print(f"๐Ÿ“ Jacobian matrix:\n{J}") + + # Analyze manipulability + manipulability = jnp.sqrt(jnp.linalg.det(J @ J.T)) + print(f"๐Ÿ’ช Manipulability index: {manipulability:.4f}") + + # Compute workspace boundary + theta_range = jnp.linspace(0, 2*jnp.pi, 100) + workspace_boundary = [] + + for theta in theta_range: + # Unit direction in task space + direction = jnp.array([jnp.cos(theta), jnp.sin(theta), 0.0]) + + # Compute maximum reach in this direction + # (This is a simplified analysis - real workspace computation is more complex) + max_reach = jnp.linalg.norm(J @ direction) + workspace_boundary.append(max_reach * direction[:2]) + + workspace_boundary = jnp.array(workspace_boundary) + + # Plot workspace + plt.figure(figsize=(8, 8)) + plt.plot(workspace_boundary[:, 0], workspace_boundary[:, 1], + 'r--', linewidth=2, label='Approximate Workspace') + plt.scatter(x_positions[-1], y_positions[-1], s=150, color='blue', + marker='o', label='Current Tip Position') + plt.xlabel('X Position [m]') + plt.ylabel('Y Position [m]') + plt.title('๐ŸŽฏ Robot Workspace Analysis') + plt.legend() + plt.grid(True, alpha=0.3) + plt.axis('equal') + plt.show() + ``` + +--- + +## ๐ŸŽฏ Next Steps + +
+
+

๐Ÿ“š [Explore Examples](examples.md)

+

Dive deeper with comprehensive examples and tutorials

+
+ +
+

๐Ÿ“– [API Reference](../api/systems.md)

+

Complete documentation of all classes and functions

+
+ +
+

๐Ÿค [Contributing](../development/contributing.md)

+

Learn how to contribute to the JSRM project

+
+ +
+

๐Ÿ”ฌ Advanced Topics

+

Control theory, optimization, and machine learning applications

+
+
+ +--- + +## ๐Ÿ’ก Pro Tips + +!!! tip "Performance Optimization" + + === "๐Ÿš€ JIT Compilation" + ```python + import jax + + # Compile functions for faster execution + fast_kinematics = jax.jit(robot.forward_kinematics) + fast_jacobian = jax.jit(robot.jacobian) + ``` + + === "๐Ÿ“Š Vectorization" + ```python + # Process multiple configurations at once + q_batch = jnp.array([[0.1, 0.0, 0.0], + [0.2, 0.0, 0.0], + [0.3, 0.0, 0.0]]) + + # Vectorized computation + batch_kinematics = jax.vmap( + lambda q: robot.forward_kinematics(q, s_tip) + )(q_batch) + ``` + + === "๐ŸŽฏ Gradient Computation" + ```python + # Automatic differentiation for optimization + def objective(q): + pos = robot.forward_kinematics(q, s_tip) + target = jnp.array([1.0, 0.5, 0.0]) # Target pose + return jnp.sum((pos - target)**2) + + # Compute gradients + grad_fn = jax.grad(objective) + gradient = grad_fn(q) + ``` + +!!! warning "Common Pitfalls" + + - **Singular Configurations**: Check manipulability before inverse operations + - **Physical Limits**: Ensure parameters respect material constraints + - **Numerical Precision**: Use appropriate tolerances for convergence + - **Memory Usage**: Be mindful of array sizes in batch operations diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..8e82f9d --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,211 @@ +site_name: ๐Ÿค– JAX Soft Robot Modelling +site_description: High-performance kinematic and dynamic models of continuum and articulated soft robots using JAX +site_author: Maximilian Stรถlzle, Solange Gribonval +site_url: https://tud-phi.github.io/jax-soft-robot-modelling + +repo_name: tud-phi/jax-soft-robot-modelling +repo_url: https://github.com/tud-phi/jax-soft-robot-modelling +edit_uri: edit/main/docs/ + +copyright: Copyright © 2020-2025 Physical Intelligence (PhI) Lab @ TU Delft + +theme: + name: material + custom_dir: docs/overrides + palette: + # Palette toggle for light mode + - scheme: default + primary: indigo + accent: teal + toggle: + icon: material/brightness-7 + name: Switch to dark mode + # Palette toggle for dark mode + - scheme: slate + primary: indigo + accent: teal + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - announce.dismiss + - content.action.edit + - content.action.view + - content.code.annotate + - content.code.copy + - content.code.select + - content.footnote.tooltips + - content.tabs.link + - content.tooltips + - header.autohide + - navigation.expand + - navigation.footer + - navigation.indexes + - navigation.instant + - navigation.instant.prefetch + - navigation.instant.progress + - navigation.prune + - navigation.sections + - navigation.tabs + - navigation.tabs.sticky + - navigation.top + - navigation.tracking + - search.highlight + - search.share + - search.suggest + - toc.follow + - toc.integrate + icon: + repo: fontawesome/brands/github + edit: material/pencil + view: material/eye + tag: + default: material/tag + robot: material/robot + math: material/function-variant + api: material/api + +nav: + - Home: index.md + - Installation: installation.md + - User Guide: + - Quick Start: user-guide/quick-start.md + - Examples: user-guide/examples.md + - API Reference: + - Overview: api/systems.md + - Systems: + - Pendulum: api/pendulum.md + - PCS Systems: + - General PCS: api/pcs.md + - Planar PCS: api/planar-pcs.md + - Planar PCS Symbolic: api/planar-pcs-sym.md + - Pneumatic Planar PCS: api/pneumatic-planar-pcs.md + - Tendon Planar PCS: api/tendon-planar-pcs.md + - Planar HSA: api/planar-hsa.md + - Utilities: + - Overview: api/utils.md + - Math Utils: api/math-utils.md + - Integration: api/integration.md + - Parameters: api/parameters.md + - Rendering: api/rendering.md + - Symbolic Derivation: api/symbolic-derivation.md + - Authors & Maintainers: authors.md + - Development: + - Contributing: development/contributing.md + - Changelog: development/changelog.md + +plugins: + - search + - mkdocstrings: + handlers: + python: + options: + docstring_style: google + show_source: false + show_root_heading: true + show_root_toc_entry: false + merge_init_into_class: true + show_signature_annotations: true + show_symbol_type_heading: true + show_symbol_type_toc: true + group_by_category: true + heading_level: 2 + members_order: source + docstring_section_style: table + line_length: 80 + show_if_no_docstring: false + separate_signature: true + show_signature: true + signature_crossrefs: true + show_bases: true + show_inheritance_diagram: false + paths: [src] + # Temporarily disable auto-generated API pages + # - gen-files: + # scripts: + # - docs/gen_ref_pages.py + # - literate-nav: + # nav_file: SUMMARY.md + - section-index + +markdown_extensions: + - abbr + - admonition + - attr_list + - def_list + - footnotes + - md_in_html + - toc: + permalink: true + title: On this page + - pymdownx.arithmatex: + generic: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.details + - pymdownx.emoji: + emoji_generator: !!python/name:material.extensions.emoji.to_svg + emoji_index: !!python/name:material.extensions.emoji.twemoji + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + use_pygments: true + - pymdownx.inlinehilite + - pymdownx.keys + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.snippets: + auto_append: + - includes/mkdocs.md + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde + +extra_javascript: + - javascripts/mathjax.js + - https://polyfill.io/v3/polyfill.min.js?features=es6 + - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js + +extra_css: + - stylesheets/extra.css + +extra: + version: + provider: mike + social: + - icon: fontawesome/brands/github + link: https://github.com/tud-phi/jax-soft-robot-modelling + name: View on GitHub + - icon: fontawesome/brands/python + link: https://pypi.org/project/jsrm/ + name: View on PyPI + - icon: fontawesome/solid/paper-plane + link: mailto:m.stolzle@tudelft.nl + name: Contact us + generator: false + analytics: + feedback: + title: Was this page helpful? + ratings: + - icon: material/emoticon-happy-outline + name: This page was helpful + data: 1 + note: >- + Thanks for your feedback! + - icon: material/emoticon-sad-outline + name: This page could be improved + data: 0 + note: >- + Thanks for your feedback! Help us improve this page by + telling us what you need. + +watch: + - src/jsrm diff --git a/pyproject.toml b/pyproject.toml index c8b08b7..6b33b12 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -148,6 +148,15 @@ test = [ "pytest-html", "tox", ] +docs = [ + "mkdocs", + "mkdocs-material", + "mkdocstrings[python]", + "mkdocs-gen-files", + "mkdocs-literate-nav", + "mkdocs-section-index", + "mkdocs-autorefs", +] # List URLs that are relevant to your project # @@ -160,9 +169,9 @@ test = [ # maintainers, and where to support the project financially. The key is # what's used to render the link text on PyPI. [project.urls] # Optional -"Homepage" = "https://github.com/tud-cor-sr/jax-soft-robot-modelling" -"Bug Reports" = "https://github.com/tud-cor-sr/jax-soft-robot-modelling/issues" -"Source" = "https://github.com/tud-cor-sr/jax-soft-robot-modelling" +"Homepage" = "https://github.com/tud-phi/jax-soft-robot-modelling" +"Bug Reports" = "https://github.com/tud-phi/jax-soft-robot-modelling/issues" +"Source" = "https://github.com/tud-phi/jax-soft-robot-modelling" # The following would provide a command line executable called `sample` # which executes the function `main` from this package when invoked. diff --git a/src/jsrm/math_utils.py b/src/jsrm/math_utils.py index e5323c6..5c34282 100644 --- a/src/jsrm/math_utils.py +++ b/src/jsrm/math_utils.py @@ -62,14 +62,14 @@ def compute_weighted_sums(M: Array, vecm: Array, idx: int) -> Array: Args: M (Array): array of shape (N, m, m) - Describes the matrix to be multiplied with vecm + Describes the matrix to be multiplied with vecm vecm (Array): array-like of shape (N, m) - Describes the vector to be multiplied with M + Describes the vector to be multiplied with M idx (int): index of the last row to be summed over Returns: Array: array of shape (N, m) - The result of the weighted sums. For each i, the result is the sum of the products of M[i, j] and vecm[j] for j from 0 to idx. + The result of the weighted sums. For each i, the result is the sum of the products of M[i, j] and vecm[j] for j from 0 to idx. """ N = M.shape[0] # Matrix product for each j: (N, m, m) @ (N, m, 1) -> (N, m) diff --git a/src/jsrm/systems/pcs.py b/src/jsrm/systems/pcs.py index 8f96cdf..853323d 100644 --- a/src/jsrm/systems/pcs.py +++ b/src/jsrm/systems/pcs.py @@ -1152,9 +1152,6 @@ def damping_matrix( """ Compute the damping matrix of the robot. - Args: - None - Returns: D (Array): Damping matrix of shape (num_active_strains, num_active_strains). """ diff --git a/src/jsrm/systems/planar_pcs.py b/src/jsrm/systems/planar_pcs.py index fe45390..bed9834 100644 --- a/src/jsrm/systems/planar_pcs.py +++ b/src/jsrm/systems/planar_pcs.py @@ -1143,9 +1143,6 @@ def damping_matrix( """ Compute the damping matrix of the robot. - Args: - None - Returns: D (Array): Damping matrix of shape (num_active_strains, num_active_strains). """