search

loco-3d / crocoddyl

Crocoddyl is an optimal control library for robot control under contact sequence. Its solver is based on various efficient Differential Dynamic Programming (DDP)-like algorithms
BSD 3-Clause "New" or "Revised" License
854 stars 174 forks source link
code-generation conda crocoddyl differential-dynamic-programming legged-robotics model-predictive-control motion-planning optimal-control robotics ros trajectory-optimization

readme

Crocoddyl Logo

Documentation Code style: black

Introduction

Crocoddyl is an optimal control library for robot control under contact sequence. Its solvers are based on novel and efficient differential dynamic programming (DDP) algorithms. Crocoddyl computes optimal trajectories and feedback gains. It uses Pinocchio for fast computation of robot dynamics and analytical derivatives.

If you want to learn more about Crocoddyl and its solvers, we suggest reading [1] [2] [3] and visiting PUBLICATIONS.md. If you want to follow the current developments and contribute, please directly refer to the devel branch.

:crocodile: Crocoddyl features

Crocoddyl is versatile:

Crocoddyl is efficient and flexible:

:penguin: Installation

Crocoddyl can be easily installed on various Linux (Ubuntu, Fedora, etc.) and Unix distributions (Mac OS X, BSD, etc.). Below, there are different ways to install Crocoddyl.

:dragon: From

Just run the following command in the terminal:

   conda install crocoddyl -c conda-forge

Conda installation supports conda install.

:snake: From

Just run the following command in the terminal:

  pip install --user crocoddyl

:turtle: With ROS

Just clone it (with --recursive) into a catkin workspace and compile it.

:package: From Debian / Ubuntu packages, with robotpkg

  1. If you have never added robotpkg's software repository, do it now:

    sudo tee /etc/apt/sources.list.d/robotpkg.list <<EOF
deb [arch=amd64] http://robotpkg.openrobots.org/packages/debian/pub $(lsb_release -sc) robotpkg
EOF

curl http://robotpkg.openrobots.org/packages/debian/robotpkg.key | sudo apt-key add -
sudo apt update
  2. Install Crocoddyl and its Python bindings: 
    sudo apt install robotpkg-py3\*-crocoddyl
  3. Configure your environment variables: 
    export PATH=/opt/openrobots/bin:$PATH
export PKG_CONFIG_PATH=/opt/openrobots/lib/pkgconfig:$PKG_CONFIG_PATH
export LD_LIBRARY_PATH=/opt/openrobots/lib:$LD_LIBRARY_PATH
export PYTHONPATH=/opt/openrobots/lib/python3.10/site-packages:$PYTHONPATH

:file_folder: From source

  1. Install Crocoddyl's mandatory dependencies:
  2. (optional) Install Crocoddyl's optional dependencies
    • OpenMP                                        (for multi-threading support)
    • CppADCogen                                (for code-generation support)
    • Ipopt                                               (for Ipopt support)
    • example-robot-data                     (for robotic examples, install Python loaders)
    • gepetto-viewer-corba                  (for display in Gepetto viewer, i.e., GepettoDisplay)
    • meshcat-python                            (for display in Meshcat, i.e., MeshcatDisplay)
    • whole_body_state_rviz_plugin    (for display in ROS, i.e., RvizDisplay)
    • crocoddyl_msgs                            (for display in ROS, i.e., RvizDisplay)
    • urdf_parser_py                              (for display in ROS, i.e., RvizDisplay)
    • jupyter                                            (for notebooks)
    • matplotlib                                       (for plotting)
  3. Clone it (with --recursive), create a build directory inside, and: 
    cmake .. && make && make install

:mag: Documentation

Crocoddyl's Doxygen documentation is available here. Alternatively, you can also check out the Jupyter notebooks. Start in the following order.

Moreover, after installation, you could run the examples as follows:

python -m crocoddyl.examples.quadrupedal_gaits "display" "plot" # enable display and plot

or run examples, unit tests and benchmarks from your build directory as

cd build
make test
make -s examples-quadrupedal_gaits INPUT="display plot" # enable display and plot
make -s benchmarks-cpp-quadrupedal_gaits INPUT="100 walk" # number of trials ; type of gait

where it is possible to enable display and/or plots generated by our examples using the environment variables:

export CROCODDYL_DISPLAY=1
export CROCODDYL_PLOT=1

:telescope: Citing Crocoddyl

To cite Crocoddyl in your academic research, please use the following BibTeX lines:

@inproceedings{mastalli20crocoddyl,
  author={Mastalli, Carlos and Budhiraja, Rohan and Merkt, Wolfgang and Saurel, Guilhem and Hammoud, Bilal
  and Naveau, Maximilien and Carpentier, Justin and Righetti, Ludovic and Vijayakumar, Sethu and Mansard, Nicolas},
  title={{Crocoddyl: An Efficient and Versatile Framework for Multi-Contact Optimal Control}},
  booktitle = {IEEE International Conference on Robotics and Automation (ICRA)},
  year={2020}
}

Please consider citing our selected publications and contributions described in PUBLICATIONS.md.

Crocoddyl's contributions extend beyond efficient software development. Please also consider citing the algorithm contributions of our different solvers and formulations:

Finally, please also consider citing Pinocchio, which contributes to the efficient implementation of rigid body algorithms and their derivatives. For more details on how to cite Pinocchio visit: https://github.com/stack-of-tasks/pinocchio.

:open_book: Selected publications

[1] C. Mastalli, R. Budhiraja, W. Merkt, G. Saurel, B. Hammoud, M. Naveau, J. Carpentier, L. Righetti, S. Vijayakumar and N. Mansard. Crocoddyl: An Efficient and Versatile Framework for Multi-Contact Optimal Control, IEEE International Conference on Robotics and Automation (ICRA), 2020

[2] C. Mastalli, W. Merkt, J. Marti-Saumell, H. Ferrolho, J. Sola, N. Mansard and S. Vijayakumar. A Feasibility-Driven Approach to Control-Limited DDP, Autonomous Robots, 2022

[3] C. Mastalli, S. P. Chhatoi, T. Corbères, S. Tonneau and S. Vijayakumar. Inverse-Dynamics MPC via Nullspace Resolution, IEEE Transactions on Robotics, 2023

:computer: Questions and Issues

You have a question or an issue? Please open a new issue.

:mag: Steering Committee

Crocoddyl is managed by a steering committee which meets every two weeks to discuss ongoing developments. The committee is led by Carlos Mastalli, Nicolas Mansard, Guilhem Saurel and Justin Carpentier are other members of the committee.

:copyright: Credits

:writing_hand: Written by

:construction_worker: With contributions from

:trophy: Acknowledgments

Crocoddyl development was supported by the EU MEMMO project and the EU RoboCom++ project. It is maintained by the Robot Motor Intelligence (RoMI) Lab @ Heriot-Watt University, the Gepetto team @ LAAS-CNRS, and the Willow team @ INRIA.