Allow to use the link frame when setting or getting forces using the references helper

[diegoferigo]

Before this PR, the helper was expecting the following:

• JaxSimModelReferences.link_forces returned ${}_W \mathbf{f}_L$, ${}_B \mathbf{f}_L$, ${}_{B[W]} \mathbf{f}_L$ in inertial-fixed, body-fixed, and mixed representations, respectively.
• JaxSimModelReferences.apply_link_forces expected to receive ${}_W \mathbf{f}_L$, ${}_B \mathbf{f}_L$, ${}_{B[W]} \mathbf{f}_L$ in inertial-fixed, body-fixed, and mixed representations, respectively.

After this PR, if use_link_frame=True, these methods behave as follows:

• JaxSimModelReferences.link_forces returns ${}_W \mathbf{f}_L$, ${}_L \mathbf{f}_L$, ${}_{L[W]} \mathbf{f}_L$ in inertial-fixed, body-fixed, and mixed representations, respectively.
• JaxSimModelReferences.apply_link_forces expects to receive ${}_W \mathbf{f}_L$, ${}_L \mathbf{f}_L$, ${}_{L[W]} \mathbf{f}_L$ in inertial-fixed, body-fixed, and mixed representations, respectively.

---

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

[diegoferigo]

Note that the default in body-fixed and mixed is using $B$. This is useful since these forces can be automatically projected to the generalized coordinates using jaxsim.api.model.generalized_free_floating_jacobian (${}^B J_{W,L}^\top \, {}_{B} \mathbf{f}_L$ and ${}^{B[W]} J_{W,L}^\top \, {}_{B[W]} \mathbf{f}_L$, in body-fixed and mixed) as it is done for example here.

With this PR, I'm not sure if also this behavior should be changed. In other words, should all our functions accepting link_forces expect them in body-fixed and mixed be ${}_L \mathbf{f}$ and ${}_{L[W]} \mathbf{f}$ instead of ${}_B \mathbf{f}$ and ${}_{B[W]} \mathbf{f}$? We can convert them to $B$ internally, if needed. What would be more intuitive to users?

cc @traversaro for a quick feedback.

[traversaro]

Interesting, there is any reason why the jacobian is not returning the matrix $J$ such that

Representation	$J \nu$
Inertial	${}^W \mathrm{v}_{W,L}$
Mixed	${}^{L[W]} \mathrm{v}_{W,L}$
Body-fixed	${}^L \mathrm{v}_{W,L}$

?

I guess iDynTree does that, but I may be doing some wrong assumption.

[flferretti]

LGTM, thanks!

[diegoferigo]

Interesting, there is any reason why the jacobian is not returning the matrix $J$ such that [...]

I guess that the main reason that triggered the usage of $B$ and $B[W]$ in the output representation of the Jacobian is that our RBDA computes efficiently the doubly-left full Jacobian ${}^B J_{W,\_/B}$ (refer to #121). Therefore, the body-fixed representation of the jacobians computed with jaxsim.api.model.generalized_free_floating_jacobian considers $B$ instead of $L$. Instead, jaxsim.api.link.jacobian returns the Jacobian you were expecting, i.e. ${}^L J_{W,L}$ in body-fixed (see test here).

You can check for the test_model_jacobian for the intended usage. I guess all boils down to something related to this PR: what frame should the references helper use when the representation is set to body-fixed or inertial? If we want to complete ditch using $B$ and $B[W]$ for this (because it may not make a lot of sense), this could be the right moment - and I need to figure out if there are other motivations for this behavior to make sense.

[traversaro]

That for the explanation, this is much more clear.

Personally I would find a bit confusing any function that returns or accepts 6D forces written as ${}_W \mathbf{f}_L$, ${}_B \mathbf{f}_L$, ${}_{B[W]} \mathbf{f}_L$ instead of ${}_W \mathbf{f}_L$, ${}_L \mathbf{f}_L$, ${}_{L[W]} \mathbf{f}_L$ , especially in mixed mode (why I should write the force applied to the hand with the origin in the base link and the orientation of the world? The nice thing of mixed notation is that you preserve a reasonable point for expressing velocity and forces, if we expressed them as $B[W]$ we kind of lose that). If the methods are meant to be use used by users of jaxsim (and not only internally) my feeling is that the default should use , that is by the way compatible with jaxsim.api.link.jacobian and the old iDynTree methods.

[diegoferigo]

If the methods are meant to be use used by users of jaxsim (and not only internally) my feeling is that the default should use , that is by the way compatible with jaxsim.api.link.jacobian and the old iDynTree methods.

I totally agree. I'll have a look at this, it shouldn't require a lot of work. I'm not sure at this point if this PR makes sense to be merged, probably I'll include the relevant changes in the new PR with the updated Jacobians.

[diegoferigo]

Superseeded by #167. Closing.