Documentation on Model Data variables, names, interpretation and notation.

[Danfoa]

Hi first of all I would like to thank you for providing this amazing framework, It has allowed me to understand and potentiate my robotics research in huge amounts.

I do sadly have to criticize that the lack of documentation might be one of the reasons why not everybody is using Pinocchio right now to do rigid body dynamics.

I have faced quite an amount of frustration trying to figure out the nomenclature and interpretation of the variables in the Data class, even after thoughtfully reviewing the Pinocchio paper and the spatial dynamics nomenclature. Are there any plans for increasing this documentation, bridging the gap between the theory and the code implementation?

I am aware that probably this is an already planned subject as there is a link for it, but I just want to say, that having this documentation will boost the usability of your framework by a large amount.

In my case for instance, I am struggling to connect all the variables in the model data to the spatial algebra notations of the centroidal dynamics. Especially the X_G. You see it's important to clarify this since sadly different notations are used by many authors (even within spatial algebra) for the same variables.

[jcarpent]

Thanks a lot for your feeback @Danfoa.
Unfortunately, we are lacking manpower to cover all the missing features of Pinocchio, especially the documentation.
It seems you have done a lot of work in this direction. Could you contribute to this in Pinocchio?

[jcarpent]

Related to Pinocchio, we have made a big effort to document all the algorithms and the whole Python bindings.
Yet, the Data and Model class should be documented, but not at a sufficient level. We can do make some improvements, and @Danfoa you are really welcome to help us with it.

For Spatial classes, the full documentation is missing, especially with Latex formula.

[jcarpent]

In my case for instance, I am struggling to connect all the variables in the model data to the spatial algebra notations of the centroidal dynamics. Especially the X_G. You see it's important to clarify this since sadly different notations are used by many authors (even within spatial algebra) for the same variables.

For this question, I would say that there is no need for X_G quantity. It is an intermediate quantity that is not fundamental for robot control. It is then not exposed within Data.

[Danfoa]

I would be very much happy to contribute. I will then post on this discussion doubts that I have before actually making any commits, and will open soon a PR for documentation on the data models.

In the topic of the intermediate variables, I would advocate to also expose these variables to the user in the same manner as in the model.data (if the quantity was required for computation, store and expose its latest value). This is because the flexibility of use would increase. I am aware that there must be a tradeoff between usability and simplicity, but this is probably a debate to have for each variable individually as users find other uses for it.

As an example in my research, I am penalizing the kinetic energy of the robot due to the relative motion of the joints. That is, as presented in Centroidal Dynamics of a Human Robot the spatial velocity vector could be decomposed in the common spatial link velocities and the relative link velocities:

v = v_c + v' = X_G * v_G + v'

I could also make good use of the Inertia matrix in spatial algebra I, instead of only having access to the inertia matrix of classical standard equations of motion of the robot H(q) which I believe you name M on the model.data

As a first question, I have found it impossible to find information on the vcom variable in the model.data. At first, I thought it was a spatial vector velocity of each link com, however, it appears to be only 3D, so it is not spatial. What's even more curious is that the world link appears to have non-cero vcom values, which is also confusing.

As I am currently prototyping with the python binder, I have also found it difficult to navigate my way through the docstring, I believe the autogenerated docstring could be indexed by hand, to expose the more relevant classes and functions informations. For instance, I am unable to know where is the vcom variable computed from or even stored.

I know this might be a dumm question as I am aware the wrapper is autogenerated, but without the inside understanding of the framework, not being able to find it through the search bar is already a huge impediment.

[jcarpent]

As I am currently prototyping with the python binder, I have also found it difficult to navigate my way through the docstring, I believe the autogenerated docstring could be indexed by hand, to expose the more relevant classes and functions informations. For instance, I am unable to know where is the vcom variable computed from or even stored.

I'm working on this now. Trying to improve the whole exposition of Python documentation within IDE.

[jcarpent]

As a first question, I have found it impossible to find information on the vcom variable in the model.data. At first, I thought it was a spatial vector velocity of each link com, however, it appears to be only 3D, so it is not spatial. What's even more curious is that the world link appears to have non-cero vcom values, which is also confusing.

The center of mass is a 3D quantity. The same applies for its time derivatives.
If you want to work with spatial quantities, you then need to use the notion of SpatialMomentum (Data.oh[joint_id]) which has a spatial meaning.

[jcarpent]

In the topic of the intermediate variables, I would advocate to also expose these variables to the user in the same manner as in the model.data (if the quantity was required for computation, store and expose its latest value). This is because the flexibility of use would increase. I am aware that there must be a tradeoff between usability and simplicity, but this is probably a debate to have for each variable individually as users find other uses for it.

I do agree and this is what we are doing with Data. Yet, for your case, X_G is not at all required: this is why we are not computing at all and we don't have it within Data.

[jcarpent]

I would be very much happy to contribute. I will then post on this discussion doubts that I have before actually making any commits, and will open soon a PR for documentation on the data models.

I can't wait for this. Thanks in advance.

[Danfoa]

As a first question, I have found it impossible to find information on the vcom variable in the model.data. At first, I thought it was a spatial vector velocity of each link com, however, it appears to be only 3D, so it is not spatial. What's even more curious is that the world link appears to have non-cero vcom values, which is also confusing.

The center of mass is a 3D quantity. The same applies for its time derivatives.
If you want to work with spatial quantities, you then need to use the notion of SpatialMomentum (Data.oh[joint_id]) which has a spatial meaning.

Thanks for the quick responses. Regarding the reason why link 0 has non-zero velocity? Any insights? I documentation is right this is the world link. Does this has to do with a floating base model?