pinocchio  2.6.3
A fast and flexible implementation of Rigid Body Dynamics algorithms and their analytical derivatives
doc/a-features/intro.md
1 # Main features of Pinocchio
2 
3 Pinocchio has been written in C++ for efficiency reasons and uses the
4 Eigen library for linear algebra routines. It comes with
5 Python bindings for easy code prototyping. We describe here the main
6 features implemented in Pinocchio.
7 
8 ## Spatial algebra
9 
10 Spatial algebra is a mathematical notation
11 commonly employed in rigid body dynamics to represent and manipulate
12 physical quantities such as velocities, accelerations and forces.
13 Pinocchio is based on this mathematical notation. Dedicated classes are
14 provided to represent coordinate transformations in the 3D Euclidean
15 space (named SE3), spatial motion vectors (Motion), spatial force
16 vectors (Force), and spatial inertias (Inertia). Along with the
17 available methods, this endows Pinocchio with an efficient software
18 library for spatial algebra calculations.
19 
20 ## Model and data
21 
22 A fundamental paradigm of Pinocchio is the strict separation between
23 *model* and *data*. By *model*, we mean the physical description of the
24 robot, including kinematic and possibly inertial parameters defining its
25 structure. This information is held by a dedicated class which, once
26 created, is never modified by the algorithms of Pinocchio. By *data*, we
27 mean all values which are the result of a computation. *Data* vary
28 according to the joint configuration, velocity, etc\... of the system.
29 It contains for instance the velocity and the acceleration of each link.
30 It also stores intermediate computations and final results of the
31 algorithms in order to prevent memory allocation. With this splitting,
32 all the algorithms in Pinocchio follow the signature:
33 
34 ```
35 algorithm(model, data, arg1, arg2, ...)
36 ```
37 
38 where are the arguments of the function (e.g. configuration or
39 velocity). Keeping model and data separated reduces memory footprint
40 when performing several different tasks on the same robot, notably when
41 this involves parallel computation. Each process can employ its own data
42 object, while sharing the same model object. The fact that a model
43 object never changes within an algorithm of Pinocchio enhances the
44 predictability of the code.
45 
46 A model can be created using the C++ API or loaded from an external
47 file, which can be either URDF, Lua (following the RBDL standard) or
48 Python.
49 
50 ## Supported kinematic models
51 
52 Within a model, a robot is represented as a kinematic tree, containing a
53 collection of all the joints, information about their connectivity, and,
54 optionally, the inertial quantities associated to each link. In
55 Pinocchio a joint can have one or several degrees of freedom, and it
56 belongs to one of the following categories:
57 - **Revolute** joints, rotating around a fixed axis, either one of \f$X,Y,Z\f$ or a custom one;
58 - **Prismatic** joints, translating along any fixed axis, as in the revolute case;
59 - **Spherical** joints, free rotations in the 3D space;
60 - **Translation** joint, for free translations in the 3D space;
61 - **Planar** joints, for free movements in the 2D space;
62 - **Free-floating** joints, for free movements in the 3D space. Planar and free-floating joints are meant to be
63  employed as the basis of kinematic tree of mobile robots (humanoids, automated vehicles, or objects in manipulation
64  planning).
65 - More complex joints can be created as a collection of ordinary ones through the concept of **Composite** joint.
66 
67 ## Dealing with Lie group geometry
68 
69 Each type of joints is characterized by its own specific configuration
70 and tangent spaces. For instance, the configuration and tangent spaces
71 of a revolute joint are both the real axis line \f$\mathbb{R}\f$, while for
72 a Spherical joint the configuration space corresponds to the set of
73 rotation matrices of dimension 3 and its tangent space is the space of
74 3-dimensional real vectors \f$\mathbb{R}^{3}\f$. Some configuration spaces
75 might not behave as a vector space, but have to be endowed with the
76 corresponding integration (exp) and differentiation (log) operators.
77 Pinocchio implements all these specific integration and differentiation
78 operators.
79 
80 ## Geometric models
81 
82 Aside the kinematic model, Pinocchio defines a geometric model, i.e. the
83 volumes attached to the kinematic tree. This model can be used for
84 displaying the robot and computing quantities associated to collisions.
85 Like the kinematic model, the fixed quantities (placement and shape of
86 the volumes) are stored in a *GeometricModel* object, while buffers and
87 quantities used by associated algorithms are defined in a object. The
88 volumes are represented using the FCL library . Bodies
89 of the robot are attached to each joint, while obstacles of the
90 environment are defined in the world frame. Collision and distance
91 algorithms for the kinematic trees are implemented, based on FCL
92 methods.
93 
94 ## Main algorithms
95 
96 The implementation of the basic algorithms, including all those listed
97 in this section, is recursive. The recursive formulation allows the
98 software to avoid repeated computations and to exploit the sparsity
99 induced by the kinematic tree. For the dynamics algorithms, we largely
100 drew inspiration from Featherstone algorithms, with slight
101 improvements.
102 
103 ### Forward kinematics
104 
105 Pinocchio implements direct kinematic computations up to the second
106 order. When a robot configuration is given, a forward pass is performed
107 to compute the spatial placements of each joint and to store them as
108 coordinate transformations. If the velocity is given, it also computes
109 the spatial velocities of each joint (expressed in local frame), and
110 similarly for accelerations.
111 
112 ### Kinematic Jacobian
113 
114 the spatial Jacobian of each joint can be easily computed with a single
115 forward pass, either expressed locally or in the world frame.
116 
117 ### Inverse dynamics
118 
119 the Recursive Newton-Euler Algorithm (RNEA) computes the
120 inverse dynamics: given a desired robot configuration, velocity and
121 acceleration, the torques required to execute this motion are computed
122 and stored. The algorithm first performs a forward pass (equivalent to
123 second-order kinematics). It then performs a backward pass, computing
124 the wrenches transmitted along the structure and extracting the joint
125 torques needed to obtain the computed link motions. With the appropriate
126 inputs, this algorithm can also be employed to compute specific terms of
127 the dynamic model, such as the gravity effects.
128 
129 ### Joint space inertia matrix
130 
131 the Composite Rigid Body Algorithm (CRBA) is
132 employed to compute the joint space inertia matrix of the robot. We have
133 implemented some slight modifications of the original algorithm that
134 improve the computational efficiency.
135 
136 ### Forward dynamics
137 
138 the Articulated Body Algorithm (ABA)
139 computes the unconstrained forward dynamics: given a robot
140 configuration, velocity, torque and external forces, the resulting joint
141 accelerations are computed.
142 
143 ### Additional algorithms
144 
145 beside the algorithms above, other methods are provided, most notably
146 for constrained forward dynamics, impulse dynamics, inverse of the joint
147 space inertia and centroidal
148 dynamics.
149 
150 ## Analytical derivatives
151 
152 Beside proposing standard forward and inverse dynamics algorithms,
153 Pinocchio also provides efficient implementations of their analytical
154 derivatives. These derivatives are for
155 instance of primary importance in the context of whole-body trajectory
156 optimization or more largely, for numerical optimal control. To the best
157 of our knowledge, Pinocchio is the first rigid body framework which
158 implements this feature natively.
159 
160 ## Automatic differentiation and source code generation
161 
162 In addition to analytical derivatives, Pinocchio supports automatic
163 differentiation. This is made possible through the full *scalar*
164 templatization of the whole C++ code and the use of any external library
165 that does automatic differentiation: ADOL-C, CasADi, CppAD and others. It is
166 important to keep in mind that these automatic derivatives are often
167 much slower than the analytical ones.
168 
169 Another unique but central feature of Pinocchio is its ability to
170 generate code both at compile time and at runtime. This is achieved by
171 using another external toolbox called CppADCodeGen built on top of
172 CppAD. From any function using Pinocchio, CppADCodeGen is
173 able to generate on the fly its code in various languages: C, Latex,
174 etc. and to make some simplifications of the math expressions. Thanks to
175 this procedure, a code tailored for a specific robot model can be
176 generated and used externally to Pinocchio.