# adam
[![adam](https://github.com/ami-iit/ADAM/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/ami-iit/ADAM/actions/workflows/tests.yml)
[![](https://img.shields.io/badge/license-LGPL-19c2d8.svg)](https://github.com/ami-iit/ADAM/blob/main/LICENSE)
**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:
- [Jax](https://github.com/google/jax)
- [CasADi](https://web.casadi.org/)
- [PyTorch](https://github.com/pytorch/pytorch)
- [NumPy](https://numpy.org/)
**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.
**adam** is based on Roy Featherstone's Rigid Body Dynamics Algorithms.
---
<p align="center">
<b>β οΈ REPOSITORY UNDER DEVELOPMENT β οΈ</b>
<br>We cannot guarantee stable API
</p>
---
## π Dependencies
- [`python3`](https://wiki.python.org/moin/BeginnersGuide)
Other requisites are:
- `urdf_parser_py`
- `jax`
- `casadi`
- `pytorch`
- `numpy`
They will be installed in the installation step!
## πΎ Installation
The installation can be done either using the Python provided by apt (on Debian-based distros) or via conda (on Linux and macOS).
### π Installation with pip
Install `python3`, if not installed (in **Ubuntu 20.04**):
```bash
sudo apt install python3.8
```
Create a [virtual environment](https://docs.python.org/3/library/venv.html#venv-def), if you prefer. For example:
```bash
pip install virtualenv
python3 -m venv your_virtual_env
source your_virtual_env/bin/activate
```
Inside the virtual environment, install the library from pip:
- Install **Jax** interface:
```bash
pip install adam-robotics[jax]
```
- Install **CasADi** interface:
```bash
pip install adam-robotics[casadi]
```
- Install **PyTorch** interface:
```bash
pip install adam-robotics[pytorch]
```
- Install **ALL** interfaces:
```bash
pip install adam-robotics[all]
```
If you want the last version:
```bash
pip install adam-robotics[selected-interface]@git+https://github.com/ami-iit/ADAM
```
or clone the repo and install:
```bash
git clone https://github.com/ami-iit/adam.git
cd adam
pip install .[selected-interface]
```
### π¦ Installation with conda
#### Installation from conda-forge package
```bash
mamba create -n adamenv -c conda-forge adam-robotics
```
If you want to use `jax` or `pytorch`, just install the corresponding package as well.
### π¨ Installation from repo
Install in a conda environment the required dependencies:
- **Jax** interface dependencies:
```bash
mamba create -n adamenv -c conda-forge jax numpy lxml prettytable matplotlib urdfdom-py
```
- **CasADi** interface dependencies:
```bash
mamba create -n adamenv -c conda-forge casadi numpy lxml prettytable matplotlib urdfdom-py
```
- **PyTorch** interface dependencies:
```bash
mamba create -n adamenv -c conda-forge pytorch numpy lxml prettytable matplotlib urdfdom-py
```
- **ALL** interfaces dependencies:
```bash
mamba create -n adamenv -c conda-forge jax casadi pytorch numpy lxml prettytable matplotlib urdfdom-py
```
Activate the environment, clone the repo and install the library:
```bash
mamba activate adamenv
git clone https://github.com/ami-iit/ADAM.git
cd adam
pip install --no-deps .
```
## π Usage
The following are small snippets of the use of **adam**. More examples are arriving!
Have also a look at te `tests` folder.
### Jax interface
```python
import adam
from adam.jax 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'
]
# Specify the root link
root_link = 'root_link'
kinDyn = KinDynComputations(model_path, joints_name_list, root_link)
# 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)
```
### CasADi interface
```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'
]
# Specify the root link
root_link = 'root_link'
kinDyn = KinDynComputations(model_path, joints_name_list, root_link)
# 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))
```
### PyTorch interface
```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'
]
# Specify the root link
root_link = 'root_link'
kinDyn = KinDynComputations(model_path, joints_name_list, root_link)
# 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)
```
## π¦ΈββοΈ Contributing
**adam** is an open-source project. Contributions are very welcome!
Open an issue with your feature request or if you spot a bug. Then, you can also proceed with a Pull-requests! :rocket:
## Todo
- [x] Center of Mass position
- [x] Jacobians
- [x] Forward kinematics
- [x] Mass Matrix via CRBA
- [x] Centroidal Momentum Matrix via CRBA
- [x] Recursive Newton-Euler algorithm (still no acceleration in the algorithm, since it is used only for the computation of the bias force)
- [ ] Articulated Body algorithm
Raw data
{
"_id": null,
"home_page": "https://github.com/ami-iit/ADAM",
"name": "adam-robotics",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "robotics,urdf,rigid body dynamics,featherstone,automatic-differentiation,optimization,casadi,jax,pytorch,reinforcement-learning,motion-planning",
"author": "Giuseppe L'Erario",
"author_email": "gl.giuseppelerario@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c1/94/1bb4b0c307a29c0edf275539d670bd727096c6840520213f7eba76a43997/adam-robotics-0.0.9.tar.gz",
"platform": null,
"description": "# adam\n\n[![adam](https://github.com/ami-iit/ADAM/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/ami-iit/ADAM/actions/workflows/tests.yml)\n[![](https://img.shields.io/badge/license-LGPL-19c2d8.svg)](https://github.com/ami-iit/ADAM/blob/main/LICENSE)\n\n**Automatic Differentiation for rigid-body-dynamics AlgorithMs**\n\n**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:\n\n- [Jax](https://github.com/google/jax)\n- [CasADi](https://web.casadi.org/)\n- [PyTorch](https://github.com/pytorch/pytorch)\n- [NumPy](https://numpy.org/)\n\n**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.\n\n**adam** is based on Roy Featherstone's Rigid Body Dynamics Algorithms.\n\n---\n\n<p align=\"center\">\n <b>\u26a0\ufe0f REPOSITORY UNDER DEVELOPMENT \u26a0\ufe0f</b>\n <br>We cannot guarantee stable API\n</p>\n\n---\n\n## \ud83d\udc0d Dependencies\n\n- [`python3`](https://wiki.python.org/moin/BeginnersGuide)\n\nOther requisites are:\n\n- `urdf_parser_py`\n- `jax`\n- `casadi`\n- `pytorch`\n- `numpy`\n\nThey will be installed in the installation step!\n\n## \ud83d\udcbe Installation\n\nThe installation can be done either using the Python provided by apt (on Debian-based distros) or via conda (on Linux and macOS).\n\n### \ud83d\udc0d Installation with pip\n\nInstall `python3`, if not installed (in **Ubuntu 20.04**):\n\n```bash\nsudo apt install python3.8\n```\n\nCreate a [virtual environment](https://docs.python.org/3/library/venv.html#venv-def), if you prefer. For example:\n\n```bash\npip install virtualenv\npython3 -m venv your_virtual_env\nsource your_virtual_env/bin/activate\n```\n\nInside the virtual environment, install the library from pip:\n\n- Install **Jax** interface:\n\n ```bash\n pip install adam-robotics[jax]\n ```\n\n- Install **CasADi** interface:\n\n ```bash\n pip install adam-robotics[casadi]\n ```\n\n- Install **PyTorch** interface:\n\n ```bash\n pip install adam-robotics[pytorch]\n ```\n\n- Install **ALL** interfaces:\n\n ```bash\n pip install adam-robotics[all]\n ```\n\nIf you want the last version:\n\n```bash\npip install adam-robotics[selected-interface]@git+https://github.com/ami-iit/ADAM\n```\n\nor clone the repo and install:\n\n```bash\ngit clone https://github.com/ami-iit/adam.git\ncd adam\npip install .[selected-interface]\n```\n\n### \ud83d\udce6 Installation with conda\n\n#### Installation from conda-forge package\n\n```bash\nmamba create -n adamenv -c conda-forge adam-robotics\n```\n\nIf you want to use `jax` or `pytorch`, just install the corresponding package as well.\n\n### \ud83d\udd28 Installation from repo\n\nInstall in a conda environment the required dependencies:\n\n- **Jax** interface dependencies:\n\n ```bash\n mamba create -n adamenv -c conda-forge jax numpy lxml prettytable matplotlib urdfdom-py\n ```\n\n- **CasADi** interface dependencies:\n\n ```bash\n mamba create -n adamenv -c conda-forge casadi numpy lxml prettytable matplotlib urdfdom-py\n ```\n\n- **PyTorch** interface dependencies:\n\n ```bash\n mamba create -n adamenv -c conda-forge pytorch numpy lxml prettytable matplotlib urdfdom-py\n ```\n\n- **ALL** interfaces dependencies:\n\n ```bash\n mamba create -n adamenv -c conda-forge jax casadi pytorch numpy lxml prettytable matplotlib urdfdom-py\n ```\n\nActivate the environment, clone the repo and install the library:\n\n```bash\nmamba activate adamenv\ngit clone https://github.com/ami-iit/ADAM.git\ncd adam\npip install --no-deps .\n```\n\n## \ud83d\ude80 Usage\n\nThe following are small snippets of the use of **adam**. More examples are arriving!\nHave also a look at te `tests` folder.\n\n### Jax interface\n\n```python\nimport adam\nfrom adam.jax import KinDynComputations\nimport icub_models\nimport numpy as np\n\n# if you want to icub-models https://github.com/robotology/icub-models to retrieve the urdf\nmodel_path = icub_models.get_model_file(\"iCubGazeboV2_5\")\n# The joint list\njoints_name_list = [\n 'torso_pitch', 'torso_roll', 'torso_yaw', 'l_shoulder_pitch',\n 'l_shoulder_roll', 'l_shoulder_yaw', 'l_elbow', 'r_shoulder_pitch',\n 'r_shoulder_roll', 'r_shoulder_yaw', 'r_elbow', 'l_hip_pitch', 'l_hip_roll',\n 'l_hip_yaw', 'l_knee', 'l_ankle_pitch', 'l_ankle_roll', 'r_hip_pitch',\n 'r_hip_roll', 'r_hip_yaw', 'r_knee', 'r_ankle_pitch', 'r_ankle_roll'\n]\n# Specify the root link\nroot_link = 'root_link'\nkinDyn = KinDynComputations(model_path, joints_name_list, root_link)\n# choose the representation, if you want to use the body fixed representation\nkinDyn.set_frame_velocity_representation(adam.Representations.BODY_FIXED_REPRESENTATION)\n# or, if you want to use the mixed representation (that is the default)\nkinDyn.set_frame_velocity_representation(adam.Representations.MIXED_REPRESENTATION)\nw_H_b = np.eye(4)\njoints = np.ones(len(joints_name_list))\nM = kinDyn.mass_matrix(w_H_b, joints)\nprint(M)\n```\n\n### CasADi interface\n\n```python\nimport adam\nfrom adam.casadi import KinDynComputations\nimport icub_models\nimport numpy as np\n\n# if you want to icub-models https://github.com/robotology/icub-models to retrieve the urdf\nmodel_path = icub_models.get_model_file(\"iCubGazeboV2_5\")\n# The joint list\njoints_name_list = [\n 'torso_pitch', 'torso_roll', 'torso_yaw', 'l_shoulder_pitch',\n 'l_shoulder_roll', 'l_shoulder_yaw', 'l_elbow', 'r_shoulder_pitch',\n 'r_shoulder_roll', 'r_shoulder_yaw', 'r_elbow', 'l_hip_pitch', 'l_hip_roll',\n 'l_hip_yaw', 'l_knee', 'l_ankle_pitch', 'l_ankle_roll', 'r_hip_pitch',\n 'r_hip_roll', 'r_hip_yaw', 'r_knee', 'r_ankle_pitch', 'r_ankle_roll'\n]\n# Specify the root link\nroot_link = 'root_link'\nkinDyn = KinDynComputations(model_path, joints_name_list, root_link)\n# choose the representation you want to use the body fixed representation\nkinDyn.set_frame_velocity_representation(adam.Representations.BODY_FIXED_REPRESENTATION)\n# or, if you want to use the mixed representation (that is the default)\nkinDyn.set_frame_velocity_representation(adam.Representations.MIXED_REPRESENTATION)\nw_H_b = np.eye(4)\njoints = np.ones(len(joints_name_list))\nM = kinDyn.mass_matrix_fun()\nprint(M(w_H_b, joints))\n```\n\n### PyTorch interface\n\n```python\nimport adam\nfrom adam.pytorch import KinDynComputations\nimport icub_models\nimport numpy as np\n\n# if you want to icub-models https://github.com/robotology/icub-models to retrieve the urdf\nmodel_path = icub_models.get_model_file(\"iCubGazeboV2_5\")\n# The joint list\njoints_name_list = [\n 'torso_pitch', 'torso_roll', 'torso_yaw', 'l_shoulder_pitch',\n 'l_shoulder_roll', 'l_shoulder_yaw', 'l_elbow', 'r_shoulder_pitch',\n 'r_shoulder_roll', 'r_shoulder_yaw', 'r_elbow', 'l_hip_pitch', 'l_hip_roll',\n 'l_hip_yaw', 'l_knee', 'l_ankle_pitch', 'l_ankle_roll', 'r_hip_pitch',\n 'r_hip_roll', 'r_hip_yaw', 'r_knee', 'r_ankle_pitch', 'r_ankle_roll'\n]\n# Specify the root link\nroot_link = 'root_link'\nkinDyn = KinDynComputations(model_path, joints_name_list, root_link)\n# choose the representation you want to use the body fixed representation\nkinDyn.set_frame_velocity_representation(adam.Representations.BODY_FIXED_REPRESENTATION)\n# or, if you want to use the mixed representation (that is the default)\nkinDyn.set_frame_velocity_representation(adam.Representations.MIXED_REPRESENTATION)\nw_H_b = np.eye(4)\njoints = np.ones(len(joints_name_list))\nM = kinDyn.mass_matrix(w_H_b, joints)\nprint(M)\n```\n\n## \ud83e\uddb8\u200d\u2642\ufe0f Contributing\n\n**adam** is an open-source project. Contributions are very welcome!\n\nOpen an issue with your feature request or if you spot a bug. Then, you can also proceed with a Pull-requests! :rocket:\n\n## Todo\n\n- [x] Center of Mass position\n- [x] Jacobians\n- [x] Forward kinematics\n- [x] Mass Matrix via CRBA\n- [x] Centroidal Momentum Matrix via CRBA\n- [x] Recursive Newton-Euler algorithm (still no acceleration in the algorithm, since it is used only for the computation of the bias force)\n- [ ] Articulated Body algorithm\n",
"bugtrack_url": null,
"license": "",
"summary": "Automatic Differentiation for rigid-body-dynamics AlgorithMs",
"version": "0.0.9",
"project_urls": {
"Homepage": "https://github.com/ami-iit/ADAM"
},
"split_keywords": [
"robotics",
"urdf",
"rigid body dynamics",
"featherstone",
"automatic-differentiation",
"optimization",
"casadi",
"jax",
"pytorch",
"reinforcement-learning",
"motion-planning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "607699252a8655f5f630179c16b93b95d750d2cea1cbbf07f8b09583bf9a59d6",
"md5": "87486f29fcb7803e283164cfa29972d5",
"sha256": "58a4a7c4952102e260be632249332da49f535275c1ea1beed0eb909220203fb3"
},
"downloads": -1,
"filename": "adam_robotics-0.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "87486f29fcb7803e283164cfa29972d5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 60335,
"upload_time": "2024-01-18T10:53:56",
"upload_time_iso_8601": "2024-01-18T10:53:56.635547Z",
"url": "https://files.pythonhosted.org/packages/60/76/99252a8655f5f630179c16b93b95d750d2cea1cbbf07f8b09583bf9a59d6/adam_robotics-0.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c1941bb4b0c307a29c0edf275539d670bd727096c6840520213f7eba76a43997",
"md5": "d48696dde5c6c13e65086d64e7c9fbff",
"sha256": "cfd9de1ba9533af06f13d0772495132de5f25310bdab57c3cec2a63a30646201"
},
"downloads": -1,
"filename": "adam-robotics-0.0.9.tar.gz",
"has_sig": false,
"md5_digest": "d48696dde5c6c13e65086d64e7c9fbff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 61979,
"upload_time": "2024-01-18T10:53:58",
"upload_time_iso_8601": "2024-01-18T10:53:58.327522Z",
"url": "https://files.pythonhosted.org/packages/c1/94/1bb4b0c307a29c0edf275539d670bd727096c6840520213f7eba76a43997/adam-robotics-0.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-18 10:53:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ami-iit",
"github_project": "ADAM",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "adam-robotics"
}