Added usage section in ReadMe and basic example for simulator

[CarlottaSartore]

This PR:

• Adds the usage section in the main readme
• Simplifies the main readme entry in favour of the usage section
• Added an example that shows the basic usage of jaxsim as simulator
• Renamed the example_physics_engine in example_physics_engine_advanced

---

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

[CarlottaSartore]

When loading the icub model, I encountered in the following warning:

jaxsim[141861] DEBUG Found model 'iCub' in SDF resource
/home/carlotta/miniforge3/envs/jaxsim/lib/python3.13/site-packages/rod/sdf/model.py:166: UserWarning: Gimbal lock detected. Setting third angle to zero since it is not possible to uniquely determine all angles.
  switch_frame_convention(

I am having issues in backtracking the source, @flferretti do you perhaps know which part of rod raises this warning ? thanks !

[flferretti]

When loading the icub model, I encountered in the following warning:

jaxsim[141861] DEBUG Found model 'iCub' in SDF resource
/home/carlotta/miniforge3/envs/jaxsim/lib/python3.13/site-packages/rod/sdf/model.py:166: UserWarning: Gimbal lock detected. Setting third angle to zero since it is not possible to uniquely determine all angles.
  switch_frame_convention(

I am having issues in backtracking the source, @flferretti do you perhaps know which part of rod raises this warning ? thanks !

Hi @CarlottaSartore, thanks for the contribution! The warning is not raised from rod, but rather from scipy.spatial.transform.Rotation in https://github.com/ami-iit/rod/blob/c67a77da59bfe6d5d7df8abf2c4878b78877079a/src/rod/sdf/common.py#L101

[traversaro]

Related: scipy/scipy#19512 and https://mail.python.org/archives/list/[email protected]/message/LXT4ZGNP4OVAARSKEOM5AGQCANH6ZV5K/ . I totally agree that this should not be a warning, or there should be a way to provide this conversion without triggering a warning, but unfortunately there was not a follow up in the mailing list.

[flferretti]

Early comment: can we use robot_description.icub_description instead of adding an additional dependency?

- import icub_models
- model_path = icub_models.get_model_file("iCubGazeboV2_5")

+ import robot_description.icub_description
+ model_path = robot_description.icub_description.URDF_PATH

[traversaro]

Early comment: can we use robot_description.icub_description instead of adding an additional dependency?

- import icub_models
- model_path = icub_models.get_model_file("iCubGazeboV2_5")

+ import robot_description.icub_description
+ model_path = robot_description.icub_description.URDF_PATH

I strongly prefer use any other robot in that case. There is nothing ensuring that the robot_description.icub_description model is updated or it even matches the real iCub robot, so I would prefer to avoid IIT users getting used to get IIT's model from robot_description. Just to give you an example, the model used is the iCubGazeboV2_5, see https://github.com/robot-descriptions/robot_descriptions.py/blob/b3cf619db307d98aad0f02f79e4818bcc89fe55d/robot_descriptions/icub_description.py#L22 . The Gazebo in the name indicates the the inertia used in the model are completely wrong for compatibility with the default settings of Gazebo Classic with the ODE physics engines (see robotology/icub-models#33 for more details). Most users are (unfortunately) already not aware of this, and it would be even more confusing if there is no Gazebo in the name, as it happens if one calls robot_description.icub_description.

[flferretti]

Early comment: can we use robot_description.icub_description instead of adding an additional dependency?

- import icub_models
- model_path = icub_models.get_model_file("iCubGazeboV2_5")

+ import robot_description.icub_description
+ model_path = robot_description.icub_description.URDF_PATH

I strongly prefer use any other robot in that case. There is nothing ensuring that the robot_description.icub_description model is updated or it even matches the real iCub robot, so I would prefer to avoid IIT users getting used to get IIT's model from robot_description.

I see, thanks for the explanation! I was wondering though if we need the actual IIT model since this is just an example

[traversaro]

I was wondering though if we need the actual IIT model since this is just an example

The problem is that lab users starts from examples, that they copy and they start using assuming that that is the "best way" to do, especially if the info come from an official repo of the lab. I really do not look forward to having to explain each new student in the lab why they should not be using robot_description.icub_description if that is what is used in the jaxsim README.

[traversaro]

(I also edited my previous comments for more details).

[CarlottaSartore]

I see, thanks for the explanation! I was wondering though if we need the actual IIT model since this is just an example

I opted to use the icub models since it is the model of a humanoid robots, and I wanted to use a robot since this is the main goal of the simulator, and the icub is the model I am the more confident with.
A different solution could be as we do in the example, thus downloading ergoCub from the ergoCub software repository, this would require more lines but we will still use a humanoid robot without adding any dependencies (even if I liked the simplicity of the include, i took inspiration from https://github.com/ami-iit/adam)

[traversaro]

If it helps reach consensus, feel free to use robot_description with iCub, even if I am not super-enthusiastic about it.

A different solution could be as we do in the example, thus downloading ergoCub from the ergoCub software repository,

The tricky aspect there is that you also need to download the meshes if you want the visualizer to work.

[flferretti]

Thanks @traversaro, I understood the problem. It seems to me that the available options are:

1. Use a different robot, e.g. stickbot --> not the most exciting model, but it does its job
2. Still use iCub/ErgoCub from the official repos --> definitely more interesting, but requires more lines of code and downloading the meshes from source for visualization

[flferretti]

Thanks a lot for working on this @CarlottaSartore! I added some comments

[traversaro]

Use a different robot, e.g. stickbot --> not the most exciting model, but it does its job

Stickbot is nice as it is a self-contained URDF. I think there is also some value in showing to users how to load a physical URDF. My assumption is that most users will want to use the simulator with their own model for which they either have the absolute file path or the relocatable package://package/name/of/the/mode.urdf . In that case, use any Python helper such as icub-models or robot_descriptions obfuscate a bit that workflow for users.

[CarlottaSartore]

Concerning the usage of model descriptor, I would stay with the icub models dependency. even though it introduces a new dependencies it shows how:

• simply load a humanoid robot
• simply load ergoCub robot
• does not lead to strange models (as ergoCUb gazebo)
• is a real humanoid robots with meshes (unlike stickbot )

[xela-95]

Thanks @CarlottaSartore ! It LGTM! I will update the title of the examples/jaxsim_as_physics_engine_advanced.ipynb notebook since up to now it's the same of the non advanced one :)

[CarlottaSartore]

Thanks @CarlottaSartore ! It LGTM! I will update the title of the examples/jaxsim_as_physics_engine_advanced.ipynb notebook since up to now it's the same of the non advanced one :)

Thanks @xela-95 you're right! I have also updated the example readme with the new example !

[CarlottaSartore]

now the tests are passing! Can we merge this PR or is there any other fbk ? @xela-95 @flferretti

[flferretti]

Thanks a lot @CarlottaSartore! I added some final minor comments and then we can merge for me

[xela-95]

Thanks @CarlottaSartore ! LGTM 🚀

[CarlottaSartore]

branch rebased, merging !