From cf1c30f63b19449edebb731e2f4896aefa4fd6fb Mon Sep 17 00:00:00 2001 From: giulero Date: Fri, 28 Jun 2024 17:44:47 +0200 Subject: [PATCH 01/26] Structure for rtd docs --- docs/Makefile | 20 ++++++++++++ docs/make.bat | 35 +++++++++++++++++++++ docs/requirements.txt | 14 +++++++++ docs/source/conf.py | 72 +++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 141 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/requirements.txt create mode 100644 docs/source/conf.py diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..747ffb7b --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..79409d4e --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,14 @@ +sphinx +sphinx-rtd-theme +sphinx-book-theme +sphinx-autodoc-typehints +sphinx-book-theme +sphinx-copybutton +sphinx-design +sphinx_fontawesome +sphinx-jinja2-compat +sphinx-multiversion +sphinx_rtd_theme +sphinx-toolbox +furo +myst-parser diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..8c8a0d49 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,72 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +import os +import sys + +sys.path.insert(0, os.path.abspath("../..")) +import subprocess + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "adam" +copyright = "2021, Artificial and Mechanical Intelligence Lab" +author = "Artificial and Mechanical Intelligence Lab" +# get release from git tag + +release = ( + subprocess.check_output(["git", "describe", "--tags", "--always"]).decode().strip() +) + + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.duration", + "sphinx.ext.doctest", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + # "sphinx.ext.inheritance_diagram", + "sphinx.ext.napoleon", + "sphinx.ext.viewcode", + # "sphinx.ext.autosectionlabel", + "sphinx_copybutton", + "myst_parser", + "sphinx.ext.napoleon", +] + +source_suffix = { + ".rst": "restructuredtext", + ".txt": "markdown", + ".md": "markdown", +} + +autosummary_generate = True +autodoc_member_order = "bysource" + +templates_path = ["_templates"] +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "sphinx_book_theme" +# html_theme = "sphinx_rtd_theme" + +# html_theme = "furo" +# html_logo = "pirati.png" + +html_context = { + "display_github": True, + "github_user": "TOB-KNPOB", + "github_repo": "Jabref2Obsdian", + "github_version": "main", + "conf_py_path": "/docs/", +} + +html_static_path = ["_static"] From 27d3b151ea4c79b920359c5bea0319ae9bbbc9dd Mon Sep 17 00:00:00 2001 From: giulero Date: Fri, 28 Jun 2024 17:57:29 +0200 Subject: [PATCH 02/26] Add rsts --- .../_templates/custom-class-template.rst | 33 ++++++++ .../_templates/custom-module-template.rst | 75 +++++++++++++++++++ docs/source/index.rst | 51 +++++++++++++ docs/source/installation.rst | 34 +++++++++ docs/source/modules/adam.core.rst | 28 +++++++ docs/source/modules/adam.geometry.rst | 21 ++++++ .../modules/adam.model.std_factories.rst | 29 +++++++ .../source/modules/adam.parametric.casadi.rst | 13 ++++ docs/source/modules/adam.parametric.jax.rst | 13 ++++ ....parametric.model.parametric_factories.rst | 29 +++++++ docs/source/modules/adam.parametric.model.rst | 10 +++ docs/source/modules/adam.parametric.numpy.rst | 13 ++++ .../modules/adam.parametric.pytorch.rst | 13 ++++ docs/source/modules/adam.parametric.rst | 24 ++++++ docs/source/modules/casadi.rst | 14 ++++ docs/source/modules/index.rst | 22 ++++++ docs/source/modules/jax.rst | 30 ++++++++ docs/source/modules/model.conversions.rst | 10 +++ docs/source/modules/model.rst | 27 +++++++ docs/source/modules/numpy.rst | 13 ++++ docs/source/modules/pytorch.rst | 17 +++++ docs/source/modules/pytorch_batched.rst | 24 ++++++ docs/source/quickstart/casadi.rst | 47 ++++++++++++ docs/source/quickstart/index.rst | 14 ++++ docs/source/quickstart/jax.rst | 60 +++++++++++++++ docs/source/quickstart/pytorch.rst | 32 ++++++++ docs/source/quickstart/pytorch_batched.rst | 40 ++++++++++ 27 files changed, 736 insertions(+) create mode 100644 docs/source/_templates/custom-class-template.rst create mode 100644 docs/source/_templates/custom-module-template.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/installation.rst create mode 100644 docs/source/modules/adam.core.rst create mode 100644 docs/source/modules/adam.geometry.rst create mode 100644 docs/source/modules/adam.model.std_factories.rst create mode 100644 docs/source/modules/adam.parametric.casadi.rst create mode 100644 docs/source/modules/adam.parametric.jax.rst create mode 100644 docs/source/modules/adam.parametric.model.parametric_factories.rst create mode 100644 docs/source/modules/adam.parametric.model.rst create mode 100644 docs/source/modules/adam.parametric.numpy.rst create mode 100644 docs/source/modules/adam.parametric.pytorch.rst create mode 100644 docs/source/modules/adam.parametric.rst create mode 100644 docs/source/modules/casadi.rst create mode 100644 docs/source/modules/index.rst create mode 100644 docs/source/modules/jax.rst create mode 100644 docs/source/modules/model.conversions.rst create mode 100644 docs/source/modules/model.rst create mode 100644 docs/source/modules/numpy.rst create mode 100644 docs/source/modules/pytorch.rst create mode 100644 docs/source/modules/pytorch_batched.rst create mode 100644 docs/source/quickstart/casadi.rst create mode 100644 docs/source/quickstart/index.rst create mode 100644 docs/source/quickstart/jax.rst create mode 100644 docs/source/quickstart/pytorch.rst create mode 100644 docs/source/quickstart/pytorch_batched.rst diff --git a/docs/source/_templates/custom-class-template.rst b/docs/source/_templates/custom-class-template.rst new file mode 100644 index 00000000..d2718c5f --- /dev/null +++ b/docs/source/_templates/custom-class-template.rst @@ -0,0 +1,33 @@ +{{ fullname | escape | underline}} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :members: + :show-inheritance: + :private-members: + :undoc-members: + + {% block methods %} + .. automethod:: __init__ + + {% if methods %} + .. rubric:: {{ _('Methods') }} + + .. autosummary:: + {% for item in methods %} + ~{{ name }}.{{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Attributes') }} + + .. autosummary:: + {% for item in attributes %} + ~{{ name }}.{{ item }} + {%- endfor %} + {% endif %} + {% endblock %} \ No newline at end of file diff --git a/docs/source/_templates/custom-module-template.rst b/docs/source/_templates/custom-module-template.rst new file mode 100644 index 00000000..13238001 --- /dev/null +++ b/docs/source/_templates/custom-module-template.rst @@ -0,0 +1,75 @@ +{{ fullname | escape | underline}} + +.. automodule:: {{ fullname }} + + {% block attributes %} + {% if attributes %} + .. rubric:: Module Attributes + + .. autosummary:: + :toctree: + {% for item in attributes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block classes %} + {% if classes %} + .. rubric:: {{ _('Classes') }} + + .. autosummary:: + :toctree: + :template: custom-class-template.rst + {% for item in classes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block inheritance %} + {% if classes %} + + .. inheritance-diagram:: {{ fullname }} + :caption: Inheritance Relationship + :parts: -1 + {% endif %} + {% endblock %} + + {% block functions %} + {% if functions %} + .. rubric:: {{ _('Functions') }} + + .. autosummary:: + :toctree: + {% for item in functions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block exceptions %} + {% if exceptions %} + .. rubric:: {{ _('Exceptions') }} + + .. autosummary:: + :toctree: + {% for item in exceptions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + +{% block modules %} +{% if modules %} +.. rubric:: Modules + +.. autosummary:: + :toctree: + :template: custom-module-template.rst + :recursive: +{% for item in modules %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..e0a63d38 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,51 @@ +.. adam documentation master file, created by + sphinx-quickstart on Fri Jun 28 14:10:15 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + + +adam +---- + +**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 using: + +.. create rst list with links to the following libraries + +- `Jax `_ +- `CasADi `_ +- `PyTorch `_ +- `NumPy `_ + + +**adam** employs the automatic differentiation capabilities of these frameworks to compute, if needed, gradients, Jacobian, Hessians of rigid-body dynamics quantities. This approach enables the design of optimal control and reinforcement learning strategies in robotics. +Thanks to the `jax.vmap`-ing and `jax.jit`-ing capabilities, the algorithms can be run on batches of inputs, which are possibly converted to PyTorch using the `jax2torch` conversion functions. + + +**adam** is based on **Roy Featherstone's Rigid Body Dynamics Algorithms**. + +Examples +-------- + +Have a look at the examples `folder in the repository `_! + + +License +------- + +`BSD-3-Clause `_ + + +.. toctree:: + :maxdepth: 2 + :caption: Getting started: + + installation + quickstart/index + +.. toctree:: + :maxdepth: 2 + :caption: API: + + modules/index diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 00000000..bda615f7 --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,34 @@ +Installation +============ +This is the installation guide for the project. + + +Prerequisites +------------- + +adam requires python 3.7 or later. + + +🐍 Conda installation +------------------ + +We suggest to install adam using `conda `_: + +.. code-block:: bash + + conda install adam-robotics -c conda-forge + +📦 Pip installation +------------------ + +You can also install adam using `pip `_: + +.. code-block:: bash + + pip install adam-robotics + +If you want to install all the dependencies install ``adam-robotics[all]``. + +.. note:: + + If the GPU support for ``JAX`` is needed, follow the instructions in the `Jax documentation `_. diff --git a/docs/source/modules/adam.core.rst b/docs/source/modules/adam.core.rst new file mode 100644 index 00000000..6b2c7269 --- /dev/null +++ b/docs/source/modules/adam.core.rst @@ -0,0 +1,28 @@ +adam.core package +================= + +Submodules +---------- + +adam.core.constants module +-------------------------- + +.. automodule:: adam.core.constants + :members: + :undoc-members: + :show-inheritance: + +adam.core.rbd\_algorithms module +-------------------------------- + +.. automodule:: adam.core.rbd_algorithms + :members: + :show-inheritance: + +adam.core.spatial\_math module +------------------------------ + +.. automodule:: adam.core.spatial_math + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/modules/adam.geometry.rst b/docs/source/modules/adam.geometry.rst new file mode 100644 index 00000000..9c140d3b --- /dev/null +++ b/docs/source/modules/adam.geometry.rst @@ -0,0 +1,21 @@ +adam.geometry package +===================== + +Submodules +---------- + +adam.geometry.utils module +-------------------------- + +.. automodule:: adam.geometry.utils + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: adam.geometry + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/modules/adam.model.std_factories.rst b/docs/source/modules/adam.model.std_factories.rst new file mode 100644 index 00000000..c0f2b520 --- /dev/null +++ b/docs/source/modules/adam.model.std_factories.rst @@ -0,0 +1,29 @@ +adam.model.std\_factories package +================================= + +Submodules +---------- + +adam.model.std\_factories.std\_joint module +------------------------------------------- + +.. automodule:: adam.model.std_factories.std_joint + :members: + :undoc-members: + :show-inheritance: + +adam.model.std\_factories.std\_link module +------------------------------------------ + +.. automodule:: adam.model.std_factories.std_link + :members: + :undoc-members: + :show-inheritance: + +adam.model.std\_factories.std\_model module +------------------------------------------- + +.. automodule:: adam.model.std_factories.std_model + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/modules/adam.parametric.casadi.rst b/docs/source/modules/adam.parametric.casadi.rst new file mode 100644 index 00000000..153b30bf --- /dev/null +++ b/docs/source/modules/adam.parametric.casadi.rst @@ -0,0 +1,13 @@ +adam.parametric.casadi package +============================== + +Submodules +---------- + +adam.parametric.casadi.computations\_parametric module +------------------------------------------------------ + +.. automodule:: adam.parametric.casadi.computations_parametric + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/modules/adam.parametric.jax.rst b/docs/source/modules/adam.parametric.jax.rst new file mode 100644 index 00000000..f24c5ef1 --- /dev/null +++ b/docs/source/modules/adam.parametric.jax.rst @@ -0,0 +1,13 @@ +adam.parametric.jax package +=========================== + +Submodules +---------- + +adam.parametric.jax.computations\_parametric module +--------------------------------------------------- + +.. automodule:: adam.parametric.jax.computations_parametric + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/modules/adam.parametric.model.parametric_factories.rst b/docs/source/modules/adam.parametric.model.parametric_factories.rst new file mode 100644 index 00000000..f1643c97 --- /dev/null +++ b/docs/source/modules/adam.parametric.model.parametric_factories.rst @@ -0,0 +1,29 @@ +adam.parametric.model.parametric\_factories package +=================================================== + +Submodules +---------- + +adam.parametric.model.parametric\_factories.parametric\_joint module +-------------------------------------------------------------------- + +.. automodule:: adam.parametric.model.parametric_factories.parametric_joint + :members: + :undoc-members: + :show-inheritance: + +adam.parametric.model.parametric\_factories.parametric\_link module +------------------------------------------------------------------- + +.. automodule:: adam.parametric.model.parametric_factories.parametric_link + :members: + :undoc-members: + :show-inheritance: + +adam.parametric.model.parametric\_factories.parametric\_model module +-------------------------------------------------------------------- + +.. automodule:: adam.parametric.model.parametric_factories.parametric_model + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/modules/adam.parametric.model.rst b/docs/source/modules/adam.parametric.model.rst new file mode 100644 index 00000000..dcf6e3e0 --- /dev/null +++ b/docs/source/modules/adam.parametric.model.rst @@ -0,0 +1,10 @@ +adam.parametric.model package +============================= + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + adam.parametric.model.parametric_factories diff --git a/docs/source/modules/adam.parametric.numpy.rst b/docs/source/modules/adam.parametric.numpy.rst new file mode 100644 index 00000000..9e996a2c --- /dev/null +++ b/docs/source/modules/adam.parametric.numpy.rst @@ -0,0 +1,13 @@ +adam.parametric.numpy package +============================= + +Submodules +---------- + +adam.parametric.numpy.computations\_parametric module +----------------------------------------------------- + +.. automodule:: adam.parametric.numpy.computations_parametric + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/modules/adam.parametric.pytorch.rst b/docs/source/modules/adam.parametric.pytorch.rst new file mode 100644 index 00000000..de8d2aa1 --- /dev/null +++ b/docs/source/modules/adam.parametric.pytorch.rst @@ -0,0 +1,13 @@ +adam.parametric.pytorch package +=============================== + +Submodules +---------- + +adam.parametric.pytorch.computations\_parametric module +------------------------------------------------------- + +.. automodule:: adam.parametric.pytorch.computations_parametric + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/modules/adam.parametric.rst b/docs/source/modules/adam.parametric.rst new file mode 100644 index 00000000..43ece6f8 --- /dev/null +++ b/docs/source/modules/adam.parametric.rst @@ -0,0 +1,24 @@ +Parametric package +======================= + +This package provides an interface for parametric models. + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + adam.parametric.casadi + adam.parametric.jax + adam.parametric.model + adam.parametric.numpy + adam.parametric.pytorch + +Module contents +--------------- + +.. automodule:: adam.parametric + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/modules/casadi.rst b/docs/source/modules/casadi.rst new file mode 100644 index 00000000..ae90f779 --- /dev/null +++ b/docs/source/modules/casadi.rst @@ -0,0 +1,14 @@ +CasADi interface +=================== + +This module provides an interface to CasADi, a symbolic framework for automatic differentiation and optimization. + +---------------- + +.. currentmodule:: adam.casadi + + +.. automodule:: adam.casadi.computations + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/modules/index.rst b/docs/source/modules/index.rst new file mode 100644 index 00000000..7ba8ef62 --- /dev/null +++ b/docs/source/modules/index.rst @@ -0,0 +1,22 @@ +Modules +========== + +This section contains the documentation for the different modules of the library. + +.. _modules: + +.. Modules +.. ------- + +.. toctree:: + :maxdepth: 2 + + casadi + jax + pytorch + pytorch_batched + numpy + model + model.conversions + adam.parametric + adam.core diff --git a/docs/source/modules/jax.rst b/docs/source/modules/jax.rst new file mode 100644 index 00000000..2aeb700a --- /dev/null +++ b/docs/source/modules/jax.rst @@ -0,0 +1,30 @@ +Jax inteface +================ + +This module provides the Jax implementation of the Rigid Body Dynamics algorithms. + +.. tip:: + + We suggest to ``jax.jit`` the functions as it will make them run faster! + +.. tip:: + + The functions in this module can be also ``jax.vmap``-ed to run on batches of inputs. + +.. note:: + + The first time you run a ``jax.jit``-ed function, it will take a bit longer to execute as they are being compiled by Jax. + +.. note:: + + If the GPU support for ``JAX`` is needed, follow the instructions in the `Jax documentation `_. + + +---------------- + +.. currentmodule:: adam.jax + +.. automodule:: adam.jax.computations + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/modules/model.conversions.rst b/docs/source/modules/model.conversions.rst new file mode 100644 index 00000000..7e7f825e --- /dev/null +++ b/docs/source/modules/model.conversions.rst @@ -0,0 +1,10 @@ +Model conversions +============================== + +.. currentmodule:: adam.model.conversions + + +.. automodule:: adam.model.conversions.idyntree + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/modules/model.rst b/docs/source/modules/model.rst new file mode 100644 index 00000000..003a709a --- /dev/null +++ b/docs/source/modules/model.rst @@ -0,0 +1,27 @@ +Model package +================== + +The model package builds the graph of the robot model and stores the information about the robot's kinematics and dynamics. + +.. currentmodule:: adam.model + +.. automodule:: adam.model.model + :members: + :undoc-members: + :show-inheritance: + +adam.model.tree module +---------------------- + +.. automodule:: adam.model.tree + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: adam.model + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/modules/numpy.rst b/docs/source/modules/numpy.rst new file mode 100644 index 00000000..e4fe2de9 --- /dev/null +++ b/docs/source/modules/numpy.rst @@ -0,0 +1,13 @@ +NumPy +================== + +This module provides the NumPy implementation of the Rigid Body Dynamics algorithms. + +---------------- + +.. currentmodule:: adam.numpy + +.. automodule:: adam.numpy.computations + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/modules/pytorch.rst b/docs/source/modules/pytorch.rst new file mode 100644 index 00000000..4870c48f --- /dev/null +++ b/docs/source/modules/pytorch.rst @@ -0,0 +1,17 @@ +PyTorch interface +==================== + +This module provides the PyTorch implementation of the Rigid Body Dynamics algorithms. + +.. tip:: + + For the batched version of the algorithms, see :mod:`adam.pytorch.computation_batch`. + +---------------- + +.. currentmodule:: adam.pytorch + +.. automodule:: adam.pytorch.computations + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/modules/pytorch_batched.rst b/docs/source/modules/pytorch_batched.rst new file mode 100644 index 00000000..1e5001ea --- /dev/null +++ b/docs/source/modules/pytorch_batched.rst @@ -0,0 +1,24 @@ +PyTorch Batched interface +========================= + +This module implements the batched version of the Rigid Body Dynamics algorithms using PyTorch. +This module uses Jax under the hood, then the functions are ``jax.vmap``-ed and ``jax.jit``-ed to run on batches of inputs, which are ultimately converted to PyTorch using the ``jax2torch`` conversion functions. + +.. note:: + + The first time you run a function from this module, it will take a bit longer to execute as they are being compiled by Jax. + + +.. note:: + + If the GPU support for ``JAX`` is needed, follow the instructions in the `Jax documentation `_. + + +---------------- + +.. currentmodule:: adam.pytorch.computation_batch + +.. automodule:: adam.pytorch.computation_batch + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/quickstart/casadi.rst b/docs/source/quickstart/casadi.rst new file mode 100644 index 00000000..1f089a98 --- /dev/null +++ b/docs/source/quickstart/casadi.rst @@ -0,0 +1,47 @@ +CasADi usage +============ + +The following example shows how to call an instance of the ``adam.casadi.KinDynComputations`` class and use it to compute the mass matrix and forward dynamics of a floating-base robot. + +.. code-block:: python + + import adam + from adam.casadi import KinDynComputations + import icub_models + import numpy as np + + # if you want to icub-models https://github.com/robotology/icub-models to retrieve the urdf + model_path = icub_models.get_model_file("iCubGazeboV2_5") + # The joint list + joints_name_list = [ + 'torso_pitch', 'torso_roll', 'torso_yaw', 'l_shoulder_pitch', + 'l_shoulder_roll', 'l_shoulder_yaw', 'l_elbow', 'r_shoulder_pitch', + 'r_shoulder_roll', 'r_shoulder_yaw', 'r_elbow', 'l_hip_pitch', 'l_hip_roll', + 'l_hip_yaw', 'l_knee', 'l_ankle_pitch', 'l_ankle_roll', 'r_hip_pitch', + 'r_hip_roll', 'r_hip_yaw', 'r_knee', 'r_ankle_pitch', 'r_ankle_roll' + ] + + kinDyn = KinDynComputations(model_path, joints_name_list) + # choose the representation you want to use the body fixed representation + kinDyn.set_frame_velocity_representation(adam.Representations.BODY_FIXED_REPRESENTATION) + # or, if you want to use the mixed representation (that is the default) + kinDyn.set_frame_velocity_representation(adam.Representations.MIXED_REPRESENTATION) + w_H_b = np.eye(4) + joints = np.ones(len(joints_name_list)) + M = kinDyn.mass_matrix_fun() + print(M(w_H_b, joints)) + + # If you want to use the symbolic version + w_H_b = cs.SX.eye(4) + joints = cs.SX.sym('joints', len(joints_name_list)) + M = kinDyn.mass_matrix_fun() + print(M(w_H_b, joints)) + + # This is usable also with casadi.MX + w_H_b = cs.MX.eye(4) + joints = cs.MX.sym('joints', len(joints_name_list)) + M = kinDyn.mass_matrix_fun() + print(M(w_H_b, joints)) + + w_H_f = kinDyn.forward_kinematics_fun() + print(w_H_f('frame_name', w_H_b, joints)) diff --git a/docs/source/quickstart/index.rst b/docs/source/quickstart/index.rst new file mode 100644 index 00000000..c0195c2e --- /dev/null +++ b/docs/source/quickstart/index.rst @@ -0,0 +1,14 @@ +Quickstart +=========== + +This section contains some snippets of code that show how to use the library. + +.. _quickstart: + +.. toctree:: + :maxdepth: 2 + + casadi + jax + pytorch + pytorch_batched diff --git a/docs/source/quickstart/jax.rst b/docs/source/quickstart/jax.rst new file mode 100644 index 00000000..01b84c74 --- /dev/null +++ b/docs/source/quickstart/jax.rst @@ -0,0 +1,60 @@ +Jax usage +========= + +The following example shows how to call an instance of the ``adam.jax.KinDynComputations`` class and use it to compute the mass matrix and forward dynamics of a floating-base robot. + +.. tip:: + We suggest to ``jax.jit`` the functions as it will make them run faster! + +.. note:: + When the functions are ``jax.jit``-ed, the first time you run them, it will take a bit longer to execute as they are being compiled by Jax. + +.. code-block:: python + + import adam + from adam.jax import KinDynComputations + import icub_models + import numpy as np + import jax.numpy as jnp + from jax import jit, vmap + + # if you want to icub-models https://github.com/robotology/icub-models to retrieve the urdf + model_path = icub_models.get_model_file("iCubGazeboV2_5") + # The joint list + joints_name_list = [ + 'torso_pitch', 'torso_roll', 'torso_yaw', 'l_shoulder_pitch', + 'l_shoulder_roll', 'l_shoulder_yaw', 'l_elbow', 'r_shoulder_pitch', + 'r_shoulder_roll', 'r_shoulder_yaw', 'r_elbow', 'l_hip_pitch', 'l_hip_roll', + 'l_hip_yaw', 'l_knee', 'l_ankle_pitch', 'l_ankle_roll', 'r_hip_pitch', + 'r_hip_roll', 'r_hip_yaw', 'r_knee', 'r_ankle_pitch', 'r_ankle_roll' + ] + + kinDyn = KinDynComputations(model_path, joints_name_list) + # choose the representation, if you want to use the body fixed representation + kinDyn.set_frame_velocity_representation(adam.Representations.BODY_FIXED_REPRESENTATION) + # or, if you want to use the mixed representation (that is the default) + kinDyn.set_frame_velocity_representation(adam.Representations.MIXED_REPRESENTATION) + w_H_b = np.eye(4) + joints = np.ones(len(joints_name_list)) + M = kinDyn.mass_matrix(w_H_b, joints) + print(M) + w_H_f = kinDyn.forward_kinematics('frame_name', w_H_b, joints) + + # IMPORTANT! The Jax Interface function execution can be slow! We suggest to jit them. + # For example: + + def frame_forward_kinematics(w_H_b, joints): + # This is needed since str is not a valid JAX type + return kinDyn.forward_kinematics('frame_name', w_H_b, joints) + + jitted_frame_fk = jit(frame_forward_kinematics) + w_H_f = jitted_frame_fk(w_H_b, joints) + + # In the same way, the functions can be also vmapped + vmapped_frame_fk = vmap(frame_forward_kinematics, in_axes=(0, 0)) + # which can be also jitted + jitted_vmapped_frame_fk = jit(vmapped_frame_fk) + # and called on a batch of data + joints_batch = jnp.tile(joints, (1024, 1)) + w_H_b_batch = jnp.tile(w_H_b, (1024, 1, 1)) + w_H_f_batch = jitted_vmapped_frame_fk(w_H_b_batch, joints_batch) diff --git a/docs/source/quickstart/pytorch.rst b/docs/source/quickstart/pytorch.rst new file mode 100644 index 00000000..077ea9fc --- /dev/null +++ b/docs/source/quickstart/pytorch.rst @@ -0,0 +1,32 @@ +PyTorch usage +============= + +The following example shows how to call an instance of the ``adam.pytorch.KinDynComputations`` class and use it to compute the mass matrix and forward dynamics of a floating-base robot. + +.. code-block:: python + + import adam + from adam.pytorch import KinDynComputations + import icub_models + import numpy as np + + # if you want to icub-models https://github.com/robotology/icub-models to retrieve the urdf + model_path = icub_models.get_model_file("iCubGazeboV2_5") + # The joint list + joints_name_list = [ + 'torso_pitch', 'torso_roll', 'torso_yaw', 'l_shoulder_pitch', + 'l_shoulder_roll', 'l_shoulder_yaw', 'l_elbow', 'r_shoulder_pitch', + 'r_shoulder_roll', 'r_shoulder_yaw', 'r_elbow', 'l_hip_pitch', 'l_hip_roll', + 'l_hip_yaw', 'l_knee', 'l_ankle_pitch', 'l_ankle_roll', 'r_hip_pitch', + 'r_hip_roll', 'r_hip_yaw', 'r_knee', 'r_ankle_pitch', 'r_ankle_roll' + ] + + kinDyn = KinDynComputations(model_path, joints_name_list) + # choose the representation you want to use the body fixed representation + kinDyn.set_frame_velocity_representation(adam.Representations.BODY_FIXED_REPRESENTATION) + # or, if you want to use the mixed representation (that is the default) + kinDyn.set_frame_velocity_representation(adam.Representations.MIXED_REPRESENTATION) + w_H_b = np.eye(4) + joints = np.ones(len(joints_name_list)) + M = kinDyn.mass_matrix(w_H_b, joints) + print(M) diff --git a/docs/source/quickstart/pytorch_batched.rst b/docs/source/quickstart/pytorch_batched.rst new file mode 100644 index 00000000..0b4fe9c6 --- /dev/null +++ b/docs/source/quickstart/pytorch_batched.rst @@ -0,0 +1,40 @@ +PyTorch batched usage +===================== + +The following example shows how to call an instance of the ``adam.pytorch.KinDynComputationsBatch`` class and use it to compute the mass matrix and forward dynamics of a floating-base robot. + +.. note:: + The first time you run a function from this module, it will take a bit longer to execute as they are being compiled by Jax. + +.. code-block:: python + + + import adam + from adam.pytorch import KinDynComputationsBatch + import icub_models + + # if you want to icub-models + model_path = icub_models.get_model_file("iCubGazeboV2_5") + # The joint list + joints_name_list = [ + 'torso_pitch', 'torso_roll', 'torso_yaw', 'l_shoulder_pitch', + 'l_shoulder_roll', 'l_shoulder_yaw', 'l_elbow', 'r_shoulder_pitch', + 'r_shoulder_roll', 'r_shoulder_yaw', 'r_elbow', 'l_hip_pitch', 'l_hip_roll', + 'l_hip_yaw', 'l_knee', 'l_ankle_pitch', 'l_ankle_roll', 'r_hip_pitch', + 'r_hip_roll', 'r_hip_yaw', 'r_knee', 'r_ankle_pitch', 'r_ankle_roll' + ] + + kinDyn = KinDynComputationsBatch(model_path, joints_name_list) + # choose the representation you want to use the body fixed representation + kinDyn.set_frame_velocity_representation(adam.Representations.BODY_FIXED_REPRESENTATION) + # or, if you want to use the mixed representation (that is the default) + kinDyn.set_frame_velocity_representation(adam.Representations.MIXED_REPRESENTATION) + w_H_b = np.eye(4) + joints = np.ones(len(joints_name_list)) + + num_samples = 1024 + w_H_b_batch = torch.tensor(np.tile(w_H_b, (num_samples, 1, 1)), dtype=torch.float32) + joints_batch = torch.tensor(np.tile(joints, (num_samples, 1)), dtype=torch.float32) + + M = kinDyn.mass_matrix(w_H_b_batch, joints_batch) + w_H_f = kinDyn.forward_kinematics('frame_name', w_H_b_batch, joints_batch) From 382d37f42d6f5b1466ff0d7d2e472fd6d2db0e14 Mon Sep 17 00:00:00 2001 From: giulero Date: Fri, 28 Jun 2024 18:18:07 +0200 Subject: [PATCH 03/26] Action for rtd --- .github/workflows/read_the_docs.yml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 .github/workflows/read_the_docs.yml diff --git a/.github/workflows/read_the_docs.yml b/.github/workflows/read_the_docs.yml new file mode 100644 index 00000000..e712f286 --- /dev/null +++ b/.github/workflows/read_the_docs.yml @@ -0,0 +1,22 @@ +# .github/workflows/documentation-links.yml + +name: Read the Docs +on: + pull_request_target: + types: + - opened + # Execute this action only on PRs that touch + # documentation files. + # paths: + # - "docs/**" + +permissions: + pull-requests: write + +jobs: + documentation-links: + runs-on: ubuntu-latest + steps: + - uses: readthedocs/actions/preview@v1 + with: + project-slug: "adam" From 8811fae8a4ab41326b7ba4553e0895872c7e55be Mon Sep 17 00:00:00 2001 From: giulero Date: Fri, 28 Jun 2024 18:25:13 +0200 Subject: [PATCH 04/26] Trigger action --- docs/source/quickstart/pytorch_batched.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/quickstart/pytorch_batched.rst b/docs/source/quickstart/pytorch_batched.rst index 0b4fe9c6..9809e8e2 100644 --- a/docs/source/quickstart/pytorch_batched.rst +++ b/docs/source/quickstart/pytorch_batched.rst @@ -4,7 +4,7 @@ PyTorch batched usage The following example shows how to call an instance of the ``adam.pytorch.KinDynComputationsBatch`` class and use it to compute the mass matrix and forward dynamics of a floating-base robot. .. note:: - The first time you run a function from this module, it will take a bit longer to execute as they are being compiled by Jax. + The first time you run a function from this module, it will take a bit longer to execute as they are being compiled by JAX. .. code-block:: python From 65978c014dbfd62af9dc88ca9fa6e76462f4bda2 Mon Sep 17 00:00:00 2001 From: giulero Date: Fri, 28 Jun 2024 18:27:30 +0200 Subject: [PATCH 05/26] Fix project-slug --- .github/workflows/read_the_docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/read_the_docs.yml b/.github/workflows/read_the_docs.yml index e712f286..16074264 100644 --- a/.github/workflows/read_the_docs.yml +++ b/.github/workflows/read_the_docs.yml @@ -19,4 +19,4 @@ jobs: steps: - uses: readthedocs/actions/preview@v1 with: - project-slug: "adam" + project-slug: "adam-docs" From cab4cc6487ee7b41d0d099a2a32cbd8162cc47cc Mon Sep 17 00:00:00 2001 From: giulero Date: Fri, 28 Jun 2024 18:35:50 +0200 Subject: [PATCH 06/26] Add read the docs yaml --- .readthedocs.yaml | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..dd2aa46c --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,35 @@ +# Read the Docs configuration file for Sphinx projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.12" + # You can also specify other tool versions: + # nodejs: "20" + # rust: "1.70" + # golang: "1.20" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/conf.py + # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs + # builder: "dirhtml" + # Fail on all warnings to avoid broken references + # fail_on_warning: true + +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +# python: +# install: +# - requirements: docs/requirements.txt From 0e80060eafdcaa2ed2033e009d6873ec9f199cb4 Mon Sep 17 00:00:00 2001 From: giulero Date: Fri, 28 Jun 2024 18:37:35 +0200 Subject: [PATCH 07/26] Fix conf path --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index dd2aa46c..a83c2f35 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -16,7 +16,7 @@ build: # Build documentation in the "docs/" directory with Sphinx sphinx: - configuration: docs/conf.py + configuration: docs/source/conf.py # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs # builder: "dirhtml" # Fail on all warnings to avoid broken references From e0a1d80a3c8679b5e6dd84b4a0f0e0093269d144 Mon Sep 17 00:00:00 2001 From: giulero Date: Fri, 28 Jun 2024 18:38:54 +0200 Subject: [PATCH 08/26] Add requirement --- docs/requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/requirements.txt b/docs/requirements.txt index 79409d4e..faf860a1 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -12,3 +12,4 @@ sphinx_rtd_theme sphinx-toolbox furo myst-parser +sphinx-copybutton From 3a3837a089824f228742a589c64719ecf8cebd1c Mon Sep 17 00:00:00 2001 From: Giuseppe L'Erario Date: Fri, 28 Jun 2024 18:56:50 +0200 Subject: [PATCH 09/26] Update requirements.txt --- docs/requirements.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index faf860a1..79409d4e 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -12,4 +12,3 @@ sphinx_rtd_theme sphinx-toolbox furo myst-parser -sphinx-copybutton From 521dadbb237d163b10d06c1843751db60d51f67c Mon Sep 17 00:00:00 2001 From: Giuseppe L'Erario Date: Fri, 28 Jun 2024 19:03:04 +0200 Subject: [PATCH 10/26] Remove temporary copy_button --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 8c8a0d49..3de511ad 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -34,7 +34,7 @@ "sphinx.ext.napoleon", "sphinx.ext.viewcode", # "sphinx.ext.autosectionlabel", - "sphinx_copybutton", + # "sphinx_copybutton", "myst_parser", "sphinx.ext.napoleon", ] From 461ec7f3abbf40a4e19a24142044bf9822494637 Mon Sep 17 00:00:00 2001 From: Giuseppe L'Erario Date: Fri, 28 Jun 2024 19:07:12 +0200 Subject: [PATCH 11/26] Enable pip --- .readthedocs.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index a83c2f35..e952a46c 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -30,6 +30,6 @@ sphinx: # Optional but recommended, declare the Python requirements required # to build your documentation # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html -# python: -# install: -# - requirements: docs/requirements.txt +python: + install: + - requirements: docs/requirements.txt From 6bb4f2a5a224220ff430bbab504e0fae150ce366 Mon Sep 17 00:00:00 2001 From: Giuseppe L'Erario Date: Fri, 28 Jun 2024 19:09:34 +0200 Subject: [PATCH 12/26] Set back copybutton --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 3de511ad..8c8a0d49 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -34,7 +34,7 @@ "sphinx.ext.napoleon", "sphinx.ext.viewcode", # "sphinx.ext.autosectionlabel", - # "sphinx_copybutton", + "sphinx_copybutton", "myst_parser", "sphinx.ext.napoleon", ] From 04778931775288ab1843b21a038ff9d88b019075 Mon Sep 17 00:00:00 2001 From: giulero Date: Sat, 29 Jun 2024 12:15:25 +0200 Subject: [PATCH 13/26] Fix short underline --- docs/source/installation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/installation.rst b/docs/source/installation.rst index bda615f7..48fbf469 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -10,7 +10,7 @@ adam requires python 3.7 or later. 🐍 Conda installation ------------------- +--------------------- We suggest to install adam using `conda `_: @@ -19,7 +19,7 @@ We suggest to install adam using `conda `_: conda install adam-robotics -c conda-forge 📦 Pip installation ------------------- +-------------------- You can also install adam using `pip `_: From a0621f7c9d5ee0b321ea6f82bbf2de0458273df6 Mon Sep 17 00:00:00 2001 From: giulero Date: Sat, 29 Jun 2024 12:15:38 +0200 Subject: [PATCH 14/26] Add dep --- docs/requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/requirements.txt b/docs/requirements.txt index 79409d4e..a5d6c001 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -12,3 +12,4 @@ sphinx_rtd_theme sphinx-toolbox furo myst-parser +graphviz From 17415c2e3a44b8c19a7f91da42d549b903271457 Mon Sep 17 00:00:00 2001 From: giulero Date: Sat, 29 Jun 2024 12:32:59 +0200 Subject: [PATCH 15/26] Not sure this will fix. Adding all formats --- .github/workflows/read_the_docs.yml | 2 -- .readthedocs.yaml | 2 ++ 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/read_the_docs.yml b/.github/workflows/read_the_docs.yml index 16074264..a5e83ac1 100644 --- a/.github/workflows/read_the_docs.yml +++ b/.github/workflows/read_the_docs.yml @@ -1,5 +1,3 @@ -# .github/workflows/documentation-links.yml - name: Read the Docs on: pull_request_target: diff --git a/.readthedocs.yaml b/.readthedocs.yaml index e952a46c..dc064545 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -33,3 +33,5 @@ sphinx: python: install: - requirements: docs/requirements.txt + +formats: all From ab77e95f42f5b013d94c687a162ca0cf0742de7d Mon Sep 17 00:00:00 2001 From: giulero Date: Sat, 29 Jun 2024 12:33:19 +0200 Subject: [PATCH 16/26] Fix doc in jax.computations --- src/adam/jax/computations.py | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/src/adam/jax/computations.py b/src/adam/jax/computations.py index df5d9e44..c7a2bda5 100644 --- a/src/adam/jax/computations.py +++ b/src/adam/jax/computations.py @@ -52,7 +52,7 @@ def mass_matrix(self, base_transform: jnp.array, joint_positions: jnp.array): joint_positions (jnp.array): The joints position Returns: - M (jax): Mass Matrix + M (jnp.array): Mass Matrix """ [M, _] = self.rbdalgos.crba(base_transform, joint_positions) return M.array @@ -125,12 +125,9 @@ def forward_kinematics( frame, base_transform, joint_positions ).array - def forward_kinematics_fun(self, frame): - return lambda T, joint_positions: self.forward_kinematics( - frame, T, joint_positions - ) - - def jacobian(self, frame: str, base_transform, joint_positions): + def jacobian( + self, frame: str, base_transform: jnp.array, joint_positions: jnp.array + ): """Returns the Jacobian relative to the specified frame Args: From bf86978d6b72097cd5f8d76e88305fccabd63909 Mon Sep 17 00:00:00 2001 From: giulero Date: Sat, 29 Jun 2024 12:35:27 +0200 Subject: [PATCH 17/26] Adding paths --- docs/source/conf.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 8c8a0d49..3e1f6efa 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -4,10 +4,13 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html import os +import subprocess import sys -sys.path.insert(0, os.path.abspath("../..")) -import subprocess +sys.path.insert(0, os.path.abspath(".")) +sys.path.insert(0, os.path.abspath("../")) +sys.path.insert(0, os.path.abspath("../../")) +sys.path.insert(0, os.path.abspath("../src/")) # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information From ab220f4baa0a1e22988e515448797668949246c1 Mon Sep 17 00:00:00 2001 From: giulero Date: Sat, 29 Jun 2024 12:43:50 +0200 Subject: [PATCH 18/26] Adding adam importing --- docs/source/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index 3e1f6efa..f9c1c2a8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -7,6 +7,8 @@ import subprocess import sys +import adam + sys.path.insert(0, os.path.abspath(".")) sys.path.insert(0, os.path.abspath("../")) sys.path.insert(0, os.path.abspath("../../")) From b47d1096e781eacf6cc7d28ac7e55bfdea235152 Mon Sep 17 00:00:00 2001 From: giulero Date: Sat, 29 Jun 2024 12:58:23 +0200 Subject: [PATCH 19/26] Restructuring folder. Adding autoapi extension --- docs/{source => }/_templates/custom-class-template.rst | 0 docs/{source => }/_templates/custom-module-template.rst | 0 docs/{source => }/conf.py | 5 +++-- docs/{source => }/index.rst | 0 docs/{source => }/installation.rst | 0 docs/{source => }/modules/adam.core.rst | 0 docs/{source => }/modules/adam.geometry.rst | 0 docs/{source => }/modules/adam.model.std_factories.rst | 0 docs/{source => }/modules/adam.parametric.casadi.rst | 0 docs/{source => }/modules/adam.parametric.jax.rst | 0 .../modules/adam.parametric.model.parametric_factories.rst | 0 docs/{source => }/modules/adam.parametric.model.rst | 0 docs/{source => }/modules/adam.parametric.numpy.rst | 0 docs/{source => }/modules/adam.parametric.pytorch.rst | 0 docs/{source => }/modules/adam.parametric.rst | 0 docs/{source => }/modules/casadi.rst | 0 docs/{source => }/modules/index.rst | 0 docs/{source => }/modules/jax.rst | 0 docs/{source => }/modules/model.conversions.rst | 0 docs/{source => }/modules/model.rst | 0 docs/{source => }/modules/numpy.rst | 0 docs/{source => }/modules/pytorch.rst | 0 docs/{source => }/modules/pytorch_batched.rst | 0 docs/{source => }/quickstart/casadi.rst | 0 docs/{source => }/quickstart/index.rst | 0 docs/{source => }/quickstart/jax.rst | 0 docs/{source => }/quickstart/pytorch.rst | 0 docs/{source => }/quickstart/pytorch_batched.rst | 0 docs/requirements.txt | 2 ++ 29 files changed, 5 insertions(+), 2 deletions(-) rename docs/{source => }/_templates/custom-class-template.rst (100%) rename docs/{source => }/_templates/custom-module-template.rst (100%) rename docs/{source => }/conf.py (97%) rename docs/{source => }/index.rst (100%) rename docs/{source => }/installation.rst (100%) rename docs/{source => }/modules/adam.core.rst (100%) rename docs/{source => }/modules/adam.geometry.rst (100%) rename docs/{source => }/modules/adam.model.std_factories.rst (100%) rename docs/{source => }/modules/adam.parametric.casadi.rst (100%) rename docs/{source => }/modules/adam.parametric.jax.rst (100%) rename docs/{source => }/modules/adam.parametric.model.parametric_factories.rst (100%) rename docs/{source => }/modules/adam.parametric.model.rst (100%) rename docs/{source => }/modules/adam.parametric.numpy.rst (100%) rename docs/{source => }/modules/adam.parametric.pytorch.rst (100%) rename docs/{source => }/modules/adam.parametric.rst (100%) rename docs/{source => }/modules/casadi.rst (100%) rename docs/{source => }/modules/index.rst (100%) rename docs/{source => }/modules/jax.rst (100%) rename docs/{source => }/modules/model.conversions.rst (100%) rename docs/{source => }/modules/model.rst (100%) rename docs/{source => }/modules/numpy.rst (100%) rename docs/{source => }/modules/pytorch.rst (100%) rename docs/{source => }/modules/pytorch_batched.rst (100%) rename docs/{source => }/quickstart/casadi.rst (100%) rename docs/{source => }/quickstart/index.rst (100%) rename docs/{source => }/quickstart/jax.rst (100%) rename docs/{source => }/quickstart/pytorch.rst (100%) rename docs/{source => }/quickstart/pytorch_batched.rst (100%) diff --git a/docs/source/_templates/custom-class-template.rst b/docs/_templates/custom-class-template.rst similarity index 100% rename from docs/source/_templates/custom-class-template.rst rename to docs/_templates/custom-class-template.rst diff --git a/docs/source/_templates/custom-module-template.rst b/docs/_templates/custom-module-template.rst similarity index 100% rename from docs/source/_templates/custom-module-template.rst rename to docs/_templates/custom-module-template.rst diff --git a/docs/source/conf.py b/docs/conf.py similarity index 97% rename from docs/source/conf.py rename to docs/conf.py index f9c1c2a8..637ce3a7 100644 --- a/docs/source/conf.py +++ b/docs/conf.py @@ -7,8 +7,6 @@ import subprocess import sys -import adam - sys.path.insert(0, os.path.abspath(".")) sys.path.insert(0, os.path.abspath("../")) sys.path.insert(0, os.path.abspath("../../")) @@ -42,8 +40,11 @@ "sphinx_copybutton", "myst_parser", "sphinx.ext.napoleon", + "autoapi.extension", ] +autoapi_dirs = ["../src/"] + source_suffix = { ".rst": "restructuredtext", ".txt": "markdown", diff --git a/docs/source/index.rst b/docs/index.rst similarity index 100% rename from docs/source/index.rst rename to docs/index.rst diff --git a/docs/source/installation.rst b/docs/installation.rst similarity index 100% rename from docs/source/installation.rst rename to docs/installation.rst diff --git a/docs/source/modules/adam.core.rst b/docs/modules/adam.core.rst similarity index 100% rename from docs/source/modules/adam.core.rst rename to docs/modules/adam.core.rst diff --git a/docs/source/modules/adam.geometry.rst b/docs/modules/adam.geometry.rst similarity index 100% rename from docs/source/modules/adam.geometry.rst rename to docs/modules/adam.geometry.rst diff --git a/docs/source/modules/adam.model.std_factories.rst b/docs/modules/adam.model.std_factories.rst similarity index 100% rename from docs/source/modules/adam.model.std_factories.rst rename to docs/modules/adam.model.std_factories.rst diff --git a/docs/source/modules/adam.parametric.casadi.rst b/docs/modules/adam.parametric.casadi.rst similarity index 100% rename from docs/source/modules/adam.parametric.casadi.rst rename to docs/modules/adam.parametric.casadi.rst diff --git a/docs/source/modules/adam.parametric.jax.rst b/docs/modules/adam.parametric.jax.rst similarity index 100% rename from docs/source/modules/adam.parametric.jax.rst rename to docs/modules/adam.parametric.jax.rst diff --git a/docs/source/modules/adam.parametric.model.parametric_factories.rst b/docs/modules/adam.parametric.model.parametric_factories.rst similarity index 100% rename from docs/source/modules/adam.parametric.model.parametric_factories.rst rename to docs/modules/adam.parametric.model.parametric_factories.rst diff --git a/docs/source/modules/adam.parametric.model.rst b/docs/modules/adam.parametric.model.rst similarity index 100% rename from docs/source/modules/adam.parametric.model.rst rename to docs/modules/adam.parametric.model.rst diff --git a/docs/source/modules/adam.parametric.numpy.rst b/docs/modules/adam.parametric.numpy.rst similarity index 100% rename from docs/source/modules/adam.parametric.numpy.rst rename to docs/modules/adam.parametric.numpy.rst diff --git a/docs/source/modules/adam.parametric.pytorch.rst b/docs/modules/adam.parametric.pytorch.rst similarity index 100% rename from docs/source/modules/adam.parametric.pytorch.rst rename to docs/modules/adam.parametric.pytorch.rst diff --git a/docs/source/modules/adam.parametric.rst b/docs/modules/adam.parametric.rst similarity index 100% rename from docs/source/modules/adam.parametric.rst rename to docs/modules/adam.parametric.rst diff --git a/docs/source/modules/casadi.rst b/docs/modules/casadi.rst similarity index 100% rename from docs/source/modules/casadi.rst rename to docs/modules/casadi.rst diff --git a/docs/source/modules/index.rst b/docs/modules/index.rst similarity index 100% rename from docs/source/modules/index.rst rename to docs/modules/index.rst diff --git a/docs/source/modules/jax.rst b/docs/modules/jax.rst similarity index 100% rename from docs/source/modules/jax.rst rename to docs/modules/jax.rst diff --git a/docs/source/modules/model.conversions.rst b/docs/modules/model.conversions.rst similarity index 100% rename from docs/source/modules/model.conversions.rst rename to docs/modules/model.conversions.rst diff --git a/docs/source/modules/model.rst b/docs/modules/model.rst similarity index 100% rename from docs/source/modules/model.rst rename to docs/modules/model.rst diff --git a/docs/source/modules/numpy.rst b/docs/modules/numpy.rst similarity index 100% rename from docs/source/modules/numpy.rst rename to docs/modules/numpy.rst diff --git a/docs/source/modules/pytorch.rst b/docs/modules/pytorch.rst similarity index 100% rename from docs/source/modules/pytorch.rst rename to docs/modules/pytorch.rst diff --git a/docs/source/modules/pytorch_batched.rst b/docs/modules/pytorch_batched.rst similarity index 100% rename from docs/source/modules/pytorch_batched.rst rename to docs/modules/pytorch_batched.rst diff --git a/docs/source/quickstart/casadi.rst b/docs/quickstart/casadi.rst similarity index 100% rename from docs/source/quickstart/casadi.rst rename to docs/quickstart/casadi.rst diff --git a/docs/source/quickstart/index.rst b/docs/quickstart/index.rst similarity index 100% rename from docs/source/quickstart/index.rst rename to docs/quickstart/index.rst diff --git a/docs/source/quickstart/jax.rst b/docs/quickstart/jax.rst similarity index 100% rename from docs/source/quickstart/jax.rst rename to docs/quickstart/jax.rst diff --git a/docs/source/quickstart/pytorch.rst b/docs/quickstart/pytorch.rst similarity index 100% rename from docs/source/quickstart/pytorch.rst rename to docs/quickstart/pytorch.rst diff --git a/docs/source/quickstart/pytorch_batched.rst b/docs/quickstart/pytorch_batched.rst similarity index 100% rename from docs/source/quickstart/pytorch_batched.rst rename to docs/quickstart/pytorch_batched.rst diff --git a/docs/requirements.txt b/docs/requirements.txt index a5d6c001..69554ac4 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -13,3 +13,5 @@ sphinx-toolbox furo myst-parser graphviz +mock +sphinx-autoapi From a57cb022fe70b86f234ba0d436240cc2e80e97b4 Mon Sep 17 00:00:00 2001 From: giulero Date: Sat, 29 Jun 2024 12:59:46 +0200 Subject: [PATCH 20/26] Fix path --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index dc064545..f0fa032e 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -16,7 +16,7 @@ build: # Build documentation in the "docs/" directory with Sphinx sphinx: - configuration: docs/source/conf.py + configuration: docs/conf.py # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs # builder: "dirhtml" # Fail on all warnings to avoid broken references From a65c72f02880169b5532f0148b8de32b0e3ebf16 Mon Sep 17 00:00:00 2001 From: giulero Date: Sat, 29 Jun 2024 13:04:44 +0200 Subject: [PATCH 21/26] Add adam as dep --- docs/conf.py | 2 ++ docs/requirements.txt | 1 + 2 files changed, 3 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 637ce3a7..e83e945a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -7,6 +7,8 @@ import subprocess import sys +import adam + sys.path.insert(0, os.path.abspath(".")) sys.path.insert(0, os.path.abspath("../")) sys.path.insert(0, os.path.abspath("../../")) diff --git a/docs/requirements.txt b/docs/requirements.txt index 69554ac4..f66fca0d 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -15,3 +15,4 @@ myst-parser graphviz mock sphinx-autoapi +adam-robotics From 43a7a2d4fe3eea4d4a2a3bbdce36780eeff37d76 Mon Sep 17 00:00:00 2001 From: giulero Date: Sat, 29 Jun 2024 13:13:25 +0200 Subject: [PATCH 22/26] Change path --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index d0c3cbf1..ed880990 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,7 +5,7 @@ # from the environment for the first two. SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build -SOURCEDIR = source +SOURCEDIR = . BUILDDIR = build # Put it first so that "make" without argument is like "make help". From 56a66c34d172ad03ec337642a74cbe791a6f74b6 Mon Sep 17 00:00:00 2001 From: giulero Date: Sat, 29 Jun 2024 13:17:26 +0200 Subject: [PATCH 23/26] Update requirements --- docs/requirements.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index f66fca0d..ce72c191 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -15,4 +15,5 @@ myst-parser graphviz mock sphinx-autoapi -adam-robotics +adam-robotics[all] +idyntree From 0057e9c2a3264676604113d52b88c332fc7b7947 Mon Sep 17 00:00:00 2001 From: giulero Date: Sat, 29 Jun 2024 13:25:51 +0200 Subject: [PATCH 24/26] Some typo fix --- docs/conf.py | 2 ++ docs/modules/casadi.rst | 1 - docs/modules/index.rst | 3 --- 3 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index e83e945a..c64063f6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -59,6 +59,8 @@ templates_path = ["_templates"] exclude_patterns = [] +html_title = f"adam" + # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output diff --git a/docs/modules/casadi.rst b/docs/modules/casadi.rst index ae90f779..fcb2d00f 100644 --- a/docs/modules/casadi.rst +++ b/docs/modules/casadi.rst @@ -7,7 +7,6 @@ This module provides an interface to CasADi, a symbolic framework for automatic .. currentmodule:: adam.casadi - .. automodule:: adam.casadi.computations :members: :undoc-members: diff --git a/docs/modules/index.rst b/docs/modules/index.rst index 7ba8ef62..5b28d934 100644 --- a/docs/modules/index.rst +++ b/docs/modules/index.rst @@ -5,9 +5,6 @@ This section contains the documentation for the different modules of the library .. _modules: -.. Modules -.. ------- - .. toctree:: :maxdepth: 2 From 7459cf371f532b4d9007e5902bd23ab6c19b9937 Mon Sep 17 00:00:00 2001 From: giulero Date: Sat, 29 Jun 2024 13:33:14 +0200 Subject: [PATCH 25/26] Removing core here since it is in the API reference --- docs/modules/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/modules/index.rst b/docs/modules/index.rst index 5b28d934..8892a315 100644 --- a/docs/modules/index.rst +++ b/docs/modules/index.rst @@ -16,4 +16,3 @@ This section contains the documentation for the different modules of the library model model.conversions adam.parametric - adam.core From 29d78f51627316aceb8f510b2ba305eb6c8f064e Mon Sep 17 00:00:00 2001 From: giulero Date: Sat, 29 Jun 2024 13:46:32 +0200 Subject: [PATCH 26/26] Remove core file --- docs/modules/adam.core.rst | 28 ---------------------------- 1 file changed, 28 deletions(-) delete mode 100644 docs/modules/adam.core.rst diff --git a/docs/modules/adam.core.rst b/docs/modules/adam.core.rst deleted file mode 100644 index 6b2c7269..00000000 --- a/docs/modules/adam.core.rst +++ /dev/null @@ -1,28 +0,0 @@ -adam.core package -================= - -Submodules ----------- - -adam.core.constants module --------------------------- - -.. automodule:: adam.core.constants - :members: - :undoc-members: - :show-inheritance: - -adam.core.rbd\_algorithms module --------------------------------- - -.. automodule:: adam.core.rbd_algorithms - :members: - :show-inheritance: - -adam.core.spatial\_math module ------------------------------- - -.. automodule:: adam.core.spatial_math - :members: - :undoc-members: - :show-inheritance: