crocoddyl  1.4.0
Contact RObot COntrol by Differential DYnamic programming Library (Crocoddyl)
doc/Overview.md
1 # Overview {#index}
2 <!--
3 ///////////////////////////////////////////////////////////////////////////////
4 // BSD 3-Clause License
5 //
6 // Copyright (C) 2018-2020, LAAS-CNRS, University of Edinburgh
7 // Author: Carlos Mastalli, Rohan Budhiraja, Nicolas Mansard
8 // Copyright note valid unless otherwise stated in individual files.
9 // All rights reserved.
10 ///////////////////////////////////////////////////////////////////////////////
11 -->
12 
13 \section OverviewIntro What is Crocoddyl?
14 
15 <img align="right" src="https://i.imgur.com/o2LfbDq.gif" width="250" padding="10"/>
16 
17 **[Crocoddyl](https://cmastalli.github.io/publications/crocoddyl20icra.html)** is an optimal control library for robot control under contact sequence.
18 Its solvers are based on novel and efficient Differential Dynamic Programming (DDP) algorithms.
19 **Crocoddyl** computes optimal trajectories along with optimal feedback gains.
20 It uses **[Pinocchio](https://github.com/stack-of-tasks/pinocchio)** for fast computation of robots dynamics and their analytical derivatives.
21 
22 **Crocoddyl** is open-source, mostly written in C++ with Python bindings, and distributed under the BSD licence.
23 It is one of the most efficient libraries for computing the optimal control with particular enphasis to contact dynamics.
24 
25 **Crocoddyl** is versatible:
26 
27  * various optimal control solvers (DDP, FDDP, BoxDDP, etc) - single and multi-shooting methods
28  * analytical and sparse derivatives via **[Pinocchio](https://github.com/stack-of-tasks/pinocchio)**
29  * Euclidian and non-Euclidian geometry friendly (handle geometrical systems)
30  * handle autonomous and nonautomous dynamical systems
31  * numerical differentiation support
32  * automatic differentiation support
33 
34 **Crocoddyl** is efficient and flexible:
35 
36  * cache friendly,
37  * multi-thread friendly
38  * Python bindings (including models and solvers abstractions)
39  * C++ 98/11/14/17/20 compliant
40  * extensively tested
41  * automatic code generation support
42 
43 <table >
44  <tr>
45  <td align="left"><img src="https://cmastalli.github.io/assets/img/publications/highly_dynamic_maneuvers.png" width="700"/></td>
46  <td align="right"><img src="https://i.imgur.com/RQR2Ovx.gif" width="500"/> <img src="https://i.imgur.com/kTW0ePh.gif" width="500"/></td>
47  </tr>
48 </table>
49 
50 
51 In this documentation, you will find the usual description of the library functionalities, a quick tutorial to catch over the mathematics behind the implementation, a bunch of examples about how to implement optimal control problems and a set of practical exercices for beginners.
52 
53 
54 \section OverviewInstall How to install Crocoddyl?
55 
56 Crocoddyl is best installed from APT packaging on Ubuntu 16.04 and 18.04, from our repository.
57 <-- On Mac OS X, we support the installation of Pinocchio through the Homebrew package manager. -->
58 On systems for which binaries are not provided, installation from source should be straightforward.
59 Every release is validated in the main Linux distributions and Mac OS X.
60 
61 <!--The full installation procedure can be found on the Github Pages of the project:
62 http://stack-of-tasks.github.io/pinocchio/download.html.-->
63 
64 \section OverviewSimple Simplest example with compilation command
65 
66 We start with a simple optimal control formulation to reach a goal position give the end-effector.
67 
68 <table class="manual">
69  <tr>
70  <th>arm_manipulation.py</th>
71  </tr>
72  <tr>
73  <td valign="top">
74  \include arm_manipulation.py
75  </td>
76  </tr>
77 </table>
78 
79 You can run this script as:
80 
81 \code python arm_manipulation.py \endcode
82 
83 \subsection OverviewSimpleExplain Explanation of the program
84 
85 This program loads a robot model through example-robot-data, creates a set of action models per node, configures different cost functions, and solves the optimal control problem with our Differential Dynamic Programming (DDP) solver.
86 
87 The first paragraph describes the optimal control problem that we want to solve "reaching-goal task with the Talos arm".
88 We have developed custom differential action model (action model in continuous time) and its analytical derivatives for forward dynamics without contact.
89 This differential action model is called `DifferentialActionModelFreeFwdDynamics`.
90 We use an Euler sympletic integrator to convert the differential action model into an action model.
91 Note that our solvers use action model.
92 
93 To handle the differential manifold of the configuration space, we have developed a state multibody class which can be used with any robotics problem.
94 We create two kind of action models in this example: running and terminal models.
95 In the terminal model we include the desired goal cost function.
96 For the running models, we also include regularization terms that are important for well posing the optimization problem.
97 
98 We create a trajectory with 250 nodes using the `ShootingProblem` class.
99 We decouple problem formulation and resoltion through this class.
100 Note that in Crocoddyl we have the freedom to specialized each node with different cost functions, dynamics and constraints.
101 
102 After that, we create our DDP solver and define a set of callbacks for analysis: display of iteration in Gepetto viewer, and print of iteration values.
103 Finally, we have created custom plot functions for easily check of results.
104 
105 
106 \section OverviewPython About Python wrappings
107 
108 Crocoddyl is written in C++, with a full template-based C++ API, for code generation and automatic differentiation purposes. All the functionalities are available in C++. Extension of the library should be preferably in C++.
109 
110 C++ interface is efficient and easy to code. It depends on virtualization with a minimal templatization for codegen and autodiff.
111 The Python API mirrors quite closely the C++ interface. The greatest difference is that the C++ interface is proposed using Eigen objects for matrices and vectors, that are exposed as NumPy matrices in Python.
112 
113 When working with Crocoddyl, we often suggest to first prototype your ideas in Python.
114 Models, costs and constraints can be derived in Python as well; making the whole prototyping process quite easy.
115 Both the auto-typing and the scripting make it much faster to develop. Once you are happy with your prototype, then translate it in C++ while binding the API to have a mirror in Python that you can use to extend your idea.
116 Currently, the codegen and autodiff are only available in C++ interface. However, it is in our plan to deploy in Python too. Your contributions are welcome!
117 
118 \section OverviewCite How to cite Crocoddyl
119 
120 Happy with Crocoddyl? Please cite us with the following format.
121 
122 ### Easy solution: cite our open access paper
123 The following is the preferred way to cite Crocoddyl or the feasibility-drive DDP solver.
124 The paper is publicly available in ([ArXiv](https://arxiv.org/abs/1909.04947 "Carlos Mastalli et al - Crocoddyl paper")).
125 
126 \include mastalli-icra20.bib
127 
128 
129 \section OverviewConclu Where to go from here?
130 
131 This documentation is mostly composed of several examples and tutorials for newcomers, along with a technical documentation and a reference guide. If you want to make sure Crocoddyl matches your needs, you may first want to check the list of features. Several examples in Python will then directly give you the keys to implement the most classical applications based on a Crocoddyl library. For nonexperts, we also provide the main mathematical fundamentals of optimal control. A long tutorial in Python contains everything you need if you are not a Python expert and want to start with Crocoddyl. This tutorial was first written as course material for the MEMMO winter school.
132 
133 That's it for beginners. We then give an overview of the technical choices we made to write the library and make it efficient. A description of the benchmarks we did to test the library efficiency is also provided.