refactor(core): address API design findings for ergonomics and stability

- Renamed DEFAULT_GRAVITY to GRAVITY_ENABLED everywhere.
- Updated InertiaTensor with optional off-diagonals (reordered) and
removed .zero() in favor of .stability_floor().
- Added SensorType.RAY as an alias for Gazebo Classic compatibility.
- Updated SemanticBuilder methods to return self and introduced .done().
- Fixed cycle detection returning NO_ROOT instead of HAS_CYCLE in
robot_builder.py.
- Updated tests to reflect all API changes and validated clean suite.

Signed-off-by: arounamounchili <patouossa.mounchili@gmail.com>

Author: arounamounchili

CONTRIBUTING.md

@@ -216,7 +216,7 @@ def test_link_creation():
         name="test_link",
         visuals=[],
         collisions=[],
-        inertial=Inertial(mass=1.0, inertia=InertiaTensor.zero())
+        inertial=Inertial(mass=1.0, inertia=InertiaTensor.stability_floor())
     )
     assert link.name == "test_link"
     assert link.inertial.mass == 1.0

core/src/linkforge/core/__init__.py

@@ -47,9 +47,9 @@
 
 # Core Infrastructure: Constants and Exceptions
 from .constants import (
-    DEFAULT_GRAVITY,
     DEFAULT_LINK_MASS,
     EPSILON,
+    GRAVITY_ENABLED,
     PI,
 )
 from .exceptions import (
@@ -293,7 +293,7 @@
     # Constants
     "PI",
     "EPSILON",
-    "DEFAULT_GRAVITY",
+    "GRAVITY_ENABLED",
     "DEFAULT_LINK_MASS",
     # Logging
     "get_logger",

core/src/linkforge/core/composer/link_builder.py

@@ -983,7 +983,7 @@ def _finalize_inertial(self) -> Inertial | None:
                 if l_state.inertial_origin is None:
                     l_state.inertial_origin = source_origin
             else:
-                l_state.inertia = InertiaTensor.zero()
+                l_state.inertia = InertiaTensor.stability_floor()
 
         return Inertial(
             mass=l_state.mass,

core/src/linkforge/core/composer/robot_builder.py

@@ -230,16 +230,16 @@ def build(self, validate: bool = True) -> Robot:
         self._active_link_builders.clear()
 
         if validate:
-            # Trigger root search to verify connectivity (raises error if no root)
-            _ = self.robot.root_link
-
             if self.robot.has_cycle:
                 raise RobotValidationError(
                     ValidationErrorCode.HAS_CYCLE,
                     "Robot kinematic chain contains a cycle (not supported in URDF)",
                     target="KinematicTree",
                 )
 
+            # Trigger root search to verify connectivity (raises error if no root)
+            _ = self.robot.root_link
+
         return self.robot
 
     def export_urdf(self, validate: bool = True, pretty_print: bool = True) -> str:

core/src/linkforge/core/composer/semantic_builder.py

@@ -36,6 +36,10 @@ def __init__(self, builder: IComposer) -> None:
         """Initialize semantic builder."""
         self._builder = builder
 
+    def done(self) -> IComposer:
+        """Return to the parent RobotBuilder."""
+        return self._builder
+
     def group(
         self,
         name: str,
@@ -45,7 +49,7 @@ def group(
         subgroups: list[str] | None = None,
         base_link: str | None = None,
         tip_link: str | None = None,
-    ) -> IComposer:
+    ) -> SemanticBuilder:
         """Define a planning group for MoveIt.
 
         Args:
@@ -75,11 +79,11 @@ def group(
 
         semantic = self._builder.robot.semantic
         self._builder.robot.semantic = replace(semantic, groups=tuple(semantic.groups) + (group,))
-        return self._builder
+        return self
 
     def group_state(
         self, name: str, group: str, values: dict[str, float | tuple[float, ...]]
-    ) -> IComposer:
+    ) -> SemanticBuilder:
         """Define a named state (e.g. 'home') for a planning group.
 
         Args:
@@ -98,11 +102,11 @@ def group_state(
         self._builder.robot.semantic = replace(
             semantic, group_states=tuple(semantic.group_states) + (state,)
         )
-        return self._builder
+        return self
 
     def end_effector(
         self, name: str, group: str, parent_link: str, parent_group: str | None = None
-    ) -> IComposer:
+    ) -> SemanticBuilder:
         """Define an end effector for MoveIt.
 
         Args:
@@ -119,9 +123,9 @@ def end_effector(
         self._builder.robot.semantic = replace(
             semantic, end_effectors=tuple(semantic.end_effectors) + (ee,)
         )
-        return self._builder
+        return self
 
-    def passive_joint(self, name: str) -> IComposer:
+    def passive_joint(self, name: str) -> SemanticBuilder:
         """Mark a joint as passive (not actuated) for MoveIt.
 
         Args:
@@ -135,15 +139,15 @@ def passive_joint(self, name: str) -> IComposer:
         self._builder.robot.semantic = replace(
             semantic, passive_joints=tuple(semantic.passive_joints) + (pj,)
         )
-        return self._builder
+        return self
 
     def virtual_joint(
         self,
         name: str,
         child_link: str,
         parent_frame: str = "world",
         joint_type: str = SRDF_VJOIN_FIXED,
-    ) -> IComposer:
+    ) -> SemanticBuilder:
         """Define a virtual joint connecting the robot to the world frame.
 
         Args:
@@ -162,11 +166,11 @@ def virtual_joint(
         self._builder.robot.semantic = replace(
             semantic, virtual_joints=tuple(semantic.virtual_joints) + (vj,)
         )
-        return self._builder
+        return self
 
     def disable_collisions(
         self, link1: str, link2: str, reason: str = SRDF_REASON_ADJACENT
-    ) -> IComposer:
+    ) -> SemanticBuilder:
         """Instruct MoveIt to ignore collisions between two specific links.
 
         Args:
@@ -181,9 +185,11 @@ def disable_collisions(
         self._builder.robot.semantic = replace(
             semantic, disabled_collisions=tuple(semantic.disabled_collisions) + (dc,)
         )
-        return self._builder
+        return self
 
-    def enable_collisions(self, link1: str, link2: str, reason: str | None = None) -> IComposer:
+    def enable_collisions(
+        self, link1: str, link2: str, reason: str | None = None
+    ) -> SemanticBuilder:
         """Explicitly re-enable collision checking between two specific links.
 
         Args:
@@ -198,9 +204,9 @@ def enable_collisions(self, link1: str, link2: str, reason: str | None = None) -
         self._builder.robot.semantic = replace(
             semantic, enabled_collisions=tuple(semantic.enabled_collisions) + (ec,)
         )
-        return self._builder
+        return self
 
-    def disable_default_collisions(self, link: str) -> IComposer:
+    def disable_default_collisions(self, link: str) -> SemanticBuilder:
         """Disable all default collisions for a specific link.
 
         Args:
@@ -214,9 +220,9 @@ def disable_default_collisions(self, link: str) -> IComposer:
             semantic,
             no_default_collision_links=tuple(semantic.no_default_collision_links) + (link,),
         )
-        return self._builder
+        return self
 
-    def joint_property(self, joint_name: str, property_name: str, value: str) -> IComposer:
+    def joint_property(self, joint_name: str, property_name: str, value: str) -> SemanticBuilder:
         """Add a custom property/metadata to a joint.
 
         Args:
@@ -232,9 +238,9 @@ def joint_property(self, joint_name: str, property_name: str, value: str) -> ICo
         self._builder.robot.semantic = replace(
             semantic, joint_properties=tuple(semantic.joint_properties) + (jp,)
         )
-        return self._builder
+        return self
 
-    def approximate_link_collision(self, link: str, spheres: list[SrdfSphere]) -> IComposer:
+    def approximate_link_collision(self, link: str, spheres: list[SrdfSphere]) -> SemanticBuilder:
         """Add sphere-based collision approximation for a link.
 
         Args:
@@ -250,4 +256,4 @@ def approximate_link_collision(self, link: str, spheres: list[SrdfSphere]) -> IC
             semantic,
             link_sphere_approximations=tuple(semantic.link_sphere_approximations) + (lsa,),
         )
-        return self._builder
+        return self

core/src/linkforge/core/constants.py

@@ -90,7 +90,7 @@
 DEFAULT_CONTACT_KD: Final[float] = 1.0  # N·s/m
 
 # Simulation toggles
-DEFAULT_GRAVITY: Final[bool] = True
+GRAVITY_ENABLED: Final[bool] = True
 DEFAULT_SELF_COLLIDE: Final[bool] = False
 
 
@@ -178,6 +178,7 @@
 SENSOR_CAMERA: Final[str] = "camera"
 SENSOR_DEPTH_CAMERA: Final[str] = "depth_camera"
 SENSOR_LIDAR: Final[str] = "lidar"
+SENSOR_RAY: Final[str] = "ray"
 SENSOR_GPU_LIDAR: Final[str] = "gpu_lidar"
 SENSOR_IMU: Final[str] = "imu"
 SENSOR_GPS: Final[str] = "gps"

core/src/linkforge/core/models/link.py

@@ -21,9 +21,9 @@
     DEFAULT_CONTACT_KP,
     DEFAULT_FRICTION_MU,
     DEFAULT_FRICTION_MU2,
-    DEFAULT_GRAVITY,
     DEFAULT_SELF_COLLIDE,
     EPSILON,
+    GRAVITY_ENABLED,
     MIN_REASONABLE_INERTIA,
 )
 from ..exceptions import RobotPhysicsError, RobotValidationError, ValidationErrorCode
@@ -46,11 +46,11 @@ class InertiaTensor:
     """
 
     ixx: float
-    ixy: float
-    ixz: float
     iyy: float
-    iyz: float
     izz: float
+    ixy: float = 0.0
+    ixz: float = 0.0
+    iyz: float = 0.0
 
     def __post_init__(self) -> None:
         """Validate inertia tensor values."""
@@ -78,15 +78,16 @@ def __post_init__(self) -> None:
             )
 
     @classmethod
-    def zero(cls) -> InertiaTensor:
-        """Create a minimal valid inertia tensor (for massless links)."""
+    def stability_floor(cls) -> InertiaTensor:
+        """Create a minimal valid inertia tensor for stability (e.g. massless links).
+
+        Returns a tensor with MIN_REASONABLE_INERTIA on the diagonals to prevent
+        physics solver instability.
+        """
         return cls(
-            MIN_REASONABLE_INERTIA,
-            0.0,
-            0.0,
-            MIN_REASONABLE_INERTIA,
-            0.0,
-            MIN_REASONABLE_INERTIA,
+            ixx=MIN_REASONABLE_INERTIA,
+            iyy=MIN_REASONABLE_INERTIA,
+            izz=MIN_REASONABLE_INERTIA,
         )
 
 
@@ -96,7 +97,7 @@ class Inertial:
 
     mass: float
     origin: Transform = Transform.identity()
-    inertia: InertiaTensor = field(default_factory=InertiaTensor.zero)
+    inertia: InertiaTensor = field(default_factory=InertiaTensor.stability_floor)
 
     def __post_init__(self) -> None:
         """Validate inertial properties.
@@ -122,7 +123,7 @@ class LinkPhysics:
     """
 
     self_collide: bool = DEFAULT_SELF_COLLIDE
-    gravity: bool = DEFAULT_GRAVITY
+    gravity: bool = GRAVITY_ENABLED
     mu: float = DEFAULT_FRICTION_MU
     mu2: float = DEFAULT_FRICTION_MU2
     kp: float = DEFAULT_CONTACT_KP
@@ -211,7 +212,7 @@ def mass(self) -> float:
     @property
     def inertia(self) -> InertiaTensor:
         """Get link inertia tensor (zero tensor if not defined)."""
-        return self.inertial.inertia if self.inertial else InertiaTensor.zero()
+        return self.inertial.inertia if self.inertial else InertiaTensor.stability_floor()
 
     @property
     def inertial_origin(self) -> Transform:

core/src/linkforge/core/models/sensor.py

@@ -50,18 +50,25 @@
     SENSOR_GPU_LIDAR,
     SENSOR_IMU,
     SENSOR_LIDAR,
+    SENSOR_RAY,
 )
 from ..exceptions import RobotValidationError, ValidationErrorCode
 from .gazebo import GazeboPlugin
 from .geometry import Transform
 
 
 class SensorType(StrEnum):
-    """Enumeration of supported sensor types in the LinkForge IR."""
+    """Enumeration of supported sensor types in the LinkForge IR.
+
+    Note on LIDAR vs RAY:
+    - LIDAR is the modern Gazebo Harmonic/GZ standard ("lidar")
+    - RAY is provided for Gazebo Classic / ROS1 compatibility ("ray")
+    """
 
     CAMERA = SENSOR_CAMERA
     DEPTH_CAMERA = SENSOR_DEPTH_CAMERA
     LIDAR = SENSOR_LIDAR
+    RAY = SENSOR_RAY
     GPU_LIDAR = SENSOR_GPU_LIDAR
     IMU = SENSOR_IMU
     GPS = SENSOR_GPS

core/src/linkforge/core/parsers/xml_base.py

@@ -317,8 +317,8 @@ def _parse_inertial_element(self, inertial_elem: ET.Element | None) -> Inertial
                 inertia = InertiaTensor(ixx=ixx, iyy=iyy, izz=izz, ixy=ixy, ixz=ixz, iyz=iyz)
             except RobotModelError:
                 # If triangle inequality is still violated, fall back to minimal valid
-                inertia = InertiaTensor.zero()
+                inertia = InertiaTensor.stability_floor()
         else:
-            inertia = InertiaTensor.zero()
+            inertia = InertiaTensor.stability_floor()
 
         return Inertial(mass=mass, origin=origin, inertia=inertia)

docs/source/reference/api/generators.md

@@ -65,7 +65,7 @@ robot = Robot(
             name="base_link",
             inertial=Inertial(
                 mass=10.0,
-                inertia=InertiaTensor(ixx=1.0, ixy=0.0, ixz=0.0, iyy=1.0, iyz=0.0, izz=1.0)
+                inertia=InertiaTensor(ixx=1.0, iyy=1.0, izz=1.0)
             )
         )
     ]