simulo.Robot

The robot authoring contract — a multi-joint articulated system.

This is the surface authoring code may rely on when it creates a robot, adds it to a scene, and controls it: construction-time configuration, joint/body name queries, command targets (position, velocity, effort), state reads, and reset. Values that carry per-environment batches are typed TensorLike — the contract does not bind to a tensor library.

Real usage, from the shipped cartpole training app: construct with an Asset and a Pose, add it to the scene, then look up joint indices once and drive them every step:

self.robot = simulo.Robot(asset=cartpole, initial_pose=simulo.Pose.identity())
scene.add(self.robot, at="/World/Robot")

# later, once — resolve joint indices by name:
self._cart_dof_idx = self.robot.find_joints("slider_to_cart")

# every step — drive the resolved joints:
self.robot.set_joint_effort_target(
    self.action_scale * actions, joint_ids=self._cart_dof_idx
)

robot.state (e.g. robot.state.joint_positions) is the supported, typed way to read live state back; robot.reset(env_ids) resets it.

asset

Robot.asset: AssetSource

Model source (USD or URDF) defining the robot.

initial_pose

Robot.initial_pose: Pose

Pose the robot spawns at, in the world frame (identity when not given).

collision_enabled

Robot.collision_enabled: bool

Whether collision detection is enabled.

visual_only

Robot.visual_only: bool

If True, the robot is spawned visual-only, with no physics.

mass_scale

Robot.mass_scale: float

Scale factor applied to all link masses.

scale

Robot.scale: Tuple[float, float, float]

Per-axis spawn scale factor.

articulation

Robot.articulation: Any

Articulation physics and control configuration.

joint_config

Robot.joint_config: Optional[List[Any]]

Optional per-joint configurations.

disable_gravity

Robot.disable_gravity: bool

If True, gravity is disabled for this robot.

actuator_gains

Robot.actuator_gains: Optional[Dict[str, Any]]

Optional mapping of actuator-group names to gain configurations.

name

Robot.name: Optional[str]

property

Robot name — set by the scene when the robot is added.

path

Robot.path: Optional[str]

property

Scene path — set by the scene when the robot is added.

internals

Robot.internals: Any

property

The engine’s internal data object, for direct tensor access.

An explicitly engine-specific, unstable escape hatch: which attributes the returned object exposes depends on the simulation engine, is not part of this contract, and carries no compatibility promise — reaching into it is at your own risk. The supported, typed way to read live robot state is state. Raises RuntimeError until the simulation runtime has attached the robot — read it from on_start onward.

state

Robot.state: RobotStateProtocol

property

The grouped live robot state — the supported, typed state surface.

Always available (the accessor is the same object on every access); its members read straight through to the simulation’s state buffers and raise RuntimeError until the simulation runtime has attached the robot — read them from on_start onward.

sensors

Robot.sensors: List[Any]

property

Sensors attached to this robot via add_sensor().

actuators

Robot.actuators: List[Any]

property

Actuators attached to this robot via add_actuator().

num_joints

Robot.num_joints: int

property

Number of joints in the robot.

is_fixed_base

Robot.is_fixed_base: bool

property

Whether the robot’s base is fixed (not floating).

add_sensor()

Robot.add_sensor(sensor: Any, attach_to: str) -> RobotProtocol

Attach a sensor at a point relative to the robot root; returns the robot for chaining. The sensor is registered with the scene automatically when the robot is added.

add_actuator()

Robot.add_actuator(actuator: Any, attach_to: str) -> RobotProtocol

Attach an actuator at a point relative to the robot root; returns the robot for chaining. The actuator is registered with the scene automatically when the robot is added.

get_joint_names()

Robot.get_joint_names() -> List[str]

Ordered list of joint names.

find_joints()

Robot.find_joints(name_pattern: str) -> List[int]

Joint indices whose names match name_pattern (exact or regex).

find_bodies()

Robot.find_bodies(name_pattern: str) -> List[int]

Body/link indices whose names match name_pattern (exact or regex).

get_jacobians()

Robot.get_jacobians(body_indices: Optional[List[int]] = ...) -> Optional[TensorLike]

Jacobian matrices for the given bodies, shape (num_envs, num_bodies, 6, num_joints); None when unavailable.

get_mass_matrix()

Robot.get_mass_matrix(joint_ids: Optional[List[int]] = ...) -> Optional[TensorLike]

Generalized mass matrix, shape (num_envs, num_joints, num_joints); None when unavailable.

get_gravity_compensation()

Robot.get_gravity_compensation(joint_ids: Optional[List[int]] = ...) -> Optional[TensorLike]

Joint torques that counteract gravity, shape (num_envs, num_joints); None when unavailable.

get_body_velocity_in_base_frame()

Robot.get_body_velocity_in_base_frame(body_name: str) -> Optional[Tuple[TensorLike, TensorLike]]

(linear_velocity, angular_velocity) of a body relative to the robot’s base frame, each (num_envs, 3); (None, None) when unavailable.

get_body_pose_in_base_frame()

Robot.get_body_pose_in_base_frame(body_name: str) -> Optional[Any]

(position, quaternion) of a body relative to the robot’s base frame; (None, None) when unavailable.

set_joint_state()

Robot.set_joint_state(
    positions: TensorLike,
    velocities: Optional[TensorLike] = ...,
    env_ids: Optional[TensorLike] = ...,
) -> None

Write joint positions/velocities directly (teleport or reset, not control).

set_joint_position_target()

Robot.set_joint_position_target(
    positions: TensorLike,
    joint_ids: Optional[TensorLike] = ...,
    env_ids: Optional[TensorLike] = ...,
) -> None

Set target joint positions for position control.

set_joint_velocity_target()

Robot.set_joint_velocity_target(
    velocities: TensorLike,
    joint_ids: Optional[TensorLike] = ...,
    env_ids: Optional[TensorLike] = ...,
) -> None

Set target joint velocities for velocity control.

set_joint_effort_target()

Robot.set_joint_effort_target(
    efforts: TensorLike,
    joint_ids: Optional[TensorLike] = ...,
) -> None

Set target joint efforts (torques/forces). Commands are buffered and flushed automatically before the next physics step.

set_root_pose()

Robot.set_root_pose(pose: TensorLike, env_ids: Optional[TensorLike] = ...) -> None

Set the base pose directly (teleport, not control), world frame, shape (num_envs, 7).

set_root_velocity()

Robot.set_root_velocity(velocity: TensorLike, env_ids: Optional[TensorLike] = ...) -> None

Set the base velocity directly (teleport, not control), world frame, shape (num_envs, 6).

get_body_pose()

Robot.get_body_pose(body_name: str) -> Optional[TensorLike]

Pose of a body in the world frame, shape (num_envs, 7); None when unavailable.

get_body_velocity()

Robot.get_body_velocity(body_name: str) -> Optional[TensorLike]

Velocity of a body in the world frame, shape (num_envs, 6); None when unavailable.

get_joint_state()

Robot.get_joint_state() -> Tuple[Optional[TensorLike], Optional[TensorLike]]

(joint_positions, joint_velocities), each (num_envs, num_joints); (None, None) when unavailable.

get_root_pose()

Robot.get_root_pose() -> Optional[TensorLike]

Base pose in the world frame, shape (num_envs, 7); None when unavailable.

get_root_velocity()

Robot.get_root_velocity() -> Optional[TensorLike]

Base velocity in the world frame, shape (num_envs, 6); None when unavailable.

reset()

Robot.reset(env_ids: Optional[TensorLike] = ...) -> None

Reset the robot to its default state for the given environments (all environments when not given).

reset_to_default()

Robot.reset_to_default() -> None

Reset all environments to the default joint state.

update()

Robot.update(dt: float) -> None

Refresh the robot’s state from the simulation. Called automatically each step by the runtime.

Declared as:

@runtime_checkable
class RobotProtocol(Protocol)