Add jaxsim.api.references with functional resources to handle model references

[diegoferigo]

This PR introduces helpers to manipulate the following inputs of a simulated model:

• Joint force references: these are the torques (or linear forces) references synthesized by a joint controller from the user. They are not guaranteed to be the same as those actuated since there might be friction or other contributions e.g. for enforcing joint limits.
• Link forces: these are the 6D forces applied to the origin ${}^W \mathbf{o}_{L_i}$ of each link frame $L_i$. The coordinates of the 6D forces are expressed in the active JaxSimModelReferences.velocity_representation.

---

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

[flferretti]

Thanks Diego, LGTM!

Could you please clarify where and how this should be used? In js.model.step or is it to be loaded in js.data.JaxsimModelData.state`?

[diegoferigo]

Right now I'm just creating the storage. You can try the following for the moment:

import jaxsim.api as js
from jaxsim import integrators

model: js.model.JaxSimModel = ...
data: js.data.JaxSimModelData = ...

ref = js.references.JaxSimModelReferences.zero(
    model=model, velocity_representation=data.velocity_representation
)

ref = ref.set_joint_force_references(
    forces=jnp.ones(model.number_of_joints())[0:5],
    model=model,
    joint_names=model.joint_names()[0:5],
)

integrator: integrators.Integrator = ...
d = integrator.init(x0=data.state, t0=0.0, dt=0.001)

_ = js.model.step(
    model=model,
    data=data,
    integrator=integrator,
    integrator_state=d,
    joint_forces=ref.joint_force_references(),
    external_forces=ref.link_forces(),
)

[flferretti]

Alright, thanks a lot for the explanation!