Extend functional APIs

[diegoferigo]

This PR extends the functional APIs with a lot of new functions:

• New jaxsim.api.com module.
• New jaxsim.api.com.com_linear_velocity function.
• New jaxsim.api.com.centroidal_momentum function.
• New jaxsim.api.com.centroidal_momentum_jacobian function.
• New jaxsim.api.com.locked_centroidal_spatial_inertia function.
• New jaxsim.api.com.average_centroidal_velocity function.
• New jaxsim.api.com.average_centroidal_velocity_jacobian function.
• New jaxsim.api.contact.collidable_point_forces function.
• New jaxsim.api.contact.collidable_point_dynamics function.
• New jaxsim.api.link.velocity function.
• New jaxsim.api.model.locked_spatial_inertia function.
• New jaxsim.api.model.total_momentum_jacobian function.
• New jaxsim.api.model.average_velocity function.
• New jaxsim.api.model.average_velocity_jacobian function.
• New jaxsim.api.model.link_contact_forces function.
• New jaxsim.math.transform module.
• New Adjoint.from_transform method.
• Added some missing docstrings.
• Extended tests for new functions.

These are particularly useful for (differentiable) model-based control, especially in centroidal coordinates cc @DanielePucci.

Refer to Traversaro2017a¹ and Section 3.9 of Traversaro2017b² for more details.

---

📚 Documentation preview 📚: https://jaxsim--117.org.readthedocs.build//117/

Footnotes

1. Traversaro, Pucci, Nori, A Unified View of the Equations of Motion used for Control Design of Humanoid Robots, 2017 url. ↩

2. Traversaro, Modelling, Estimation and Identification of Humanoid Robots Dynamics, 2017, url. ↩

[traversaro]

What happens for others velocity representation?

[diegoferigo]

This method always returns ${}^W \dot{\mathbf{p}}_G$, where $G = ({}^W \mathbf{p}_{\text{CoM}}, [W])$ like iDynTree.

[diegoferigo]

Do you think that it can be more uniform returning instead ${}^{G[W]}\boldsymbol{v}_{W,G} \in \mathbb{R}^3$ in inertial-fixed and mixed representations, and ${}^{G[B]}\boldsymbol{v}_{W,G} \in \mathbb{R}^3$ in body-fixed? There are some methods in iDynTree (and also here since I maintained the approach) doing that.

[traversaro]

Yes, that could make sense. Anyhow, I was actually confused by the data.switch_velocity_representation, but after checking it out now everything is clear.

[diegoferigo]

@traversaro I'm going to merge this PR with jaxsim.api.com.com_linear_velocity always returning ${}^W \dot{\mathbf{p}}_{\text{CoM}}$. We can discuss if it's sound returning something else in body-fixed coordinates in #108.

[traversaro]

Ok!

[traversaro]

By the way, I looked in iDynTree, and to me it seems that always returning ${}^W \dot{p}_{CoM}$ https://github.com/robotology/idyntree/blob/7e029b963d44fa2606bd608019ba9b82a4398741/src/high-level/src/KinDynComputations.cpp#L1941-L1958 is a bug/inconsistency in iDynTree, that we may want to fix.

[diegoferigo]

Ok if this is the intended usage, then I'll update directly this PR instead of doing it in #108.

[diegoferigo]

I forced pushed this fix, @traversaro can you please confirm that https://github.com/ami-iit/jaxsim/compare/3b63bb8cf6962c6e1e0f71e5120da480964d3f51..b3864af61e37c48ca24a83146a0f96b0d3063dab is what you had in mind?

[traversaro]

Minor comments.

[flferretti]

LGTM, thanks Diego!