Update documentation #146
Update documentation #146
Conversation
…ions module to avoid api braking
- Updated the main index.rst to provide a clearer overview of adam's capabilities, including backend options and core features. - Revised installation instructions in installation.rst to reflect Python version requirements and backend installation methods. - Improved JAX module documentation to clarify batching support and JIT compilation benefits. - Removed the separate PyTorch batched module and integrated its content into the main PyTorch documentation for simplicity. - Expanded CasADi quickstart guide with detailed usage examples, including symbolic computation and optimization problem setup. - Added a new quickstart guide for the NumPy backend, highlighting its use for model validation and debugging. - Enhanced the PyTorch quickstart with GPU support instructions and integration with neural networks. - Removed outdated references to batched PyTorch computations, consolidating information for better clarity.
There was a problem hiding this comment.
Pull request overview
This pull request significantly improves the adam robotics library documentation with a focus on clarity, accessibility, and comprehensive guidance for users. The main changes consolidate PyTorch batched operations into a unified API and add extensive documentation covering backend selection, core concepts, and MuJoCo integration.
Key Changes
- Unified PyTorch API: Consolidated
KinDynComputationsBatchintoKinDynComputationswith backward compatibility alias - Comprehensive Documentation: Added new guides for backend selection, core concepts, MuJoCo integration, and troubleshooting
- Expanded Examples: Each backend (NumPy, JAX, CasADi, PyTorch) now has dedicated quickstart documentation with practical examples
Reviewed changes
Copilot reviewed 20 out of 20 changed files in this pull request and generated 12 comments.
Show a summary per file
| File | Description |
|---|---|
src/adam/pytorch/computations.py |
Fixed type annotation for gravity parameter from np.array to torch.Tensor |
src/adam/pytorch/computation_batch.py |
Removed entire file (316 lines) - functionality merged into main computations module |
src/adam/pytorch/__init__.py |
Added backward compatibility alias KinDynComputationsBatch = KinDynComputations |
README.md |
Complete rewrite with clearer structure, better examples, and improved installation instructions |
docs/installation.rst |
Streamlined installation guide with backend-specific instructions |
docs/index.rst |
Restructured landing page with feature highlights and updated navigation |
docs/quickstart/numpy.rst |
New guide for NumPy backend usage |
docs/quickstart/jax.rst |
Expanded with JIT compilation, autodiff, and native batching examples |
docs/quickstart/casadi.rst |
Enhanced with symbolic computation, optimization, and inverse kinematics examples |
docs/quickstart/pytorch.rst |
Comprehensive guide including GPU support, autodiff, and batch processing |
docs/quickstart/pytorch_batched.rst |
Removed - content consolidated into pytorch.rst |
docs/modules/pytorch_batched.rst |
Removed - no longer needed with unified API |
docs/guides/backend_selection.rst |
New guide comparing all backends with use case recommendations |
docs/guides/concepts.rst |
New guide explaining floating-base representation, velocity representations, and dynamics algorithms |
docs/guides/mujoco.rst |
New comprehensive guide for MuJoCo model integration |
docs/guides/troubleshooting.rst |
New FAQ and common issues guide for all backends |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
… KinDynComputations API
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 21 out of 21 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
The tests are failing due to the recent release of Numpy 2.4. |
GiulioRomualdi
left a comment
GiulioRomualdi
left a comment
There was a problem hiding this comment.
Super minor comment
| **Best for:** Quick prototyping, validation, simplicity | ||
|
|
||
| - Direct numerical computation | ||
| - No compilation or setup overhead | ||
| - Easiest to debug and understand | ||
| - Good for initial model verification | ||
|
|
||
| **When to use:** | ||
|
|
||
| - Validating robot models | ||
| - Quick experiments | ||
| - Educational purposes |
There was a problem hiding this comment.
Do you think this is really required? 🤔
There was a problem hiding this comment.
Yeah maybe this is just fancy. We could remove this piece and keep the doc more minimal.
There was a problem hiding this comment.
Yeah maybe this is just fancy. We could remove this piece and keep the doc more minimal.
| # Create symbolic variables | ||
| w_H_b_sym = cs.SX.sym('H', 4, 4) | ||
| joints_sym = cs.SX.sym('q', len(joints_name_list)) | ||
There was a problem hiding this comment.
I noticed there are a lot of trailing whitespaces. I suggested to remove them :)
| **Automatic Differentiation for rigid-body-dynamics Algorithms** | ||
|
|
||
| **adam** implements a collection of algorithms for calculating rigid-body dynamics for **floating-base** robots, in _mixed_ and _body fixed representations_ (see [Traversaro's A Unified View of the Equations of Motion used for Control Design of Humanoid Robots](https://www.researchgate.net/publication/312200239_A_Unified_View_of_the_Equations_of_Motion_used_for_Control_Design_of_Humanoid_Robots)) using: | ||
| **adam** computes rigid-body dynamics for floating-base robots. Built on Featherstone's algorithms and available across multiple backends for flexibility: |
There was a problem hiding this comment.
you might add the reference to the book
Warning
The documentation is heavily produced with the help of LLM. I have reviewed and corrected the unclear and incorrect statements.
Documentation preview: https://adam-docs--146.org.readthedocs.build/en/146/
This pull request significantly improves the user experience and documentation for the
adamrobotics library. It modernizes and clarifies theREADME.md, adds comprehensive guides to the documentation, and explains core concepts and backend selection to help users get started and choose the right tools for their needs.Major documentation and usability improvements:
README.md Enhancements:
README.mdhas been rewritten for clarity and accessibility. Installation instructions are streamlined for both pip and conda, backend capabilities are clearly presented, and quick-start code examples are provided for all supported backends. The inverse kinematics and features sections are improved, and new sections on documentation, testing, contributing, license, and acknowledgments are added. [1] [2] [3] [4] [5] [6] [7] [8]New Documentation Guides:
docs/guides/backend_selection.rst, which explains the strengths, best use cases, and example code for each backend (NumPy, JAX, CasADi, PyTorch), helping users choose the optimal backend for their application.docs/guides/concepts.rst, providing detailed explanations of floating-base robot modeling, velocity representations, key matrices (mass matrix, Jacobian, centroidal momentum), and the underlying dynamics algorithms (ABA, RNEA, CRBA). This guide also describes how to handle external wrenches and set velocity representations.