Python SDK /fastsim.unisim

fastsim.unisim

24 classes

Backend-agnostic scene and entity API. SceneManager provides access to all spawned robots, objects, and sensors regardless of the underlying simulator backend. Abstract base classes define the lifecycle contract for every entity type.

class

UniSim

abstract6 methods
fastsim.unisim.uni_sim.UniSimextendsABC

Abstract base class for all simulator backends. Subclass to integrate a new physics engine.

UniSim defines the minimal interface that every backend must implement: initialization, scene setup, stepping, and reset. The framework calls these methods; users typically do not interact with UniSim directly.

initializemethod
def initialize(self)None

Initialize the backend engine (create app/context, configure physics).

setup_scenemethod
def setup_scene(self)None

Build the scene from the loaded config (spawn all entities).

stepmethod
def step(self)None

Advance the simulation by one physics timestep.

resetmethod
def reset(self)None

Reset the simulation to its initial state.

closemethod
def close(self)None

Shut down the backend and release all resources.

is_runningmethod
def is_running(self)bool

Return True while the backend simulation context is active.

class

Spawnable

abstract6 methods
fastsim.unisim.spawnable.SpawnableextendsABC

Abstract base for all scene entities. Defines the spawn/remove/update lifecycle.

Every entity that can be placed in a scene (robots, objects, sensors, lights, bases) extends Spawnable. The framework calls spawn() once at scene setup, update_data() every tick, and remove() on cleanup.

spawnmethod
def spawn(self)None

Instantiate the entity in the simulation scene.

removemethod
def remove(self)None

Remove the entity from the simulation scene.

update_datamethod
def update_data(self)None

Synchronize internal state from the backend each tick.

get_datamethod
def get_data(self)dict

Return a dict snapshot of the entity's current state.

dict — Key-value state snapshot.
get_posemethod
def get_pose(self)Pose

Return the world-frame pose of the entity.

Pose — Current world pose.
set_posemethod
def set_pose(self, pose: Pose)None

Teleport the entity to a new world-frame pose.

NameTypeDefaultDescription
posePoseTarget world pose.
class

Articulation

abstract9 methods
fastsim.unisim.articulation.ArticulationextendsSpawnable

Abstract articulated body with joint state read/write and drive targets.

Articulation extends Spawnable with a joint-level API used by both robots and articulated objects. Position, velocity, and effort targets map to the underlying physics drive.

get_joint_positionmethod
def get_joint_position(self, joint_name: str | None = None)list

Read the current position of one or all joints.

NameTypeDefaultDescription
joint_nameoptstr|NoneNoneJoint name; if None, returns all joints.
list — List of joint position values (radians or metres).
get_joint_velocitymethod
def get_joint_velocity(self, joint_name: str | None = None)list

Read the current velocity of one or all joints.

NameTypeDefaultDescription
joint_nameoptstr|NoneNoneJoint name; if None, returns all joints.
list — List of joint velocity values.
set_joint_position_targetmethod
def set_joint_position_target(self, positions: list, joint_names: list | None = None)None

Set position drive targets for one or more joints.

NameTypeDefaultDescription
positionslistTarget positions (radians or metres).
joint_namesoptlist|NoneNoneJoint names; if None, all joints.
set_joint_velocity_targetmethod
def set_joint_velocity_target(self, velocities: list, joint_names: list | None = None)None

Set velocity drive targets for one or more joints.

NameTypeDefaultDescription
velocitieslistTarget velocities.
joint_namesoptlist|NoneNoneJoint names; if None, all joints.
set_joint_effort_targetmethod
def set_joint_effort_target(self, efforts: list, joint_names: list | None = None)None

Set effort (torque/force) targets for one or more joints.

NameTypeDefaultDescription
effortslistTarget effort values.
joint_namesoptlist|NoneNoneJoint names; if None, all joints.
write_data_to_simmethod
def write_data_to_sim(self)None

Flush buffered drive commands to the physics backend.

get_joint_namesmethod
def get_joint_names(self)list

Return the ordered list of joint names for this articulation.

list — List of joint name strings.
get_body_namesmethod
def get_body_names(self)list

Return the ordered list of rigid body (link) names.

list — List of body/link name strings.
is_joint_stoppedmethod
def is_joint_stopped(self)bool

Return True when all joints have come to rest (velocity below threshold).

Inherited fromSpawnable6
spawnmethod
def spawn(self)None

Instantiate the entity in the simulation scene.

removemethod
def remove(self)None

Remove the entity from the simulation scene.

update_datamethod
def update_data(self)None

Synchronize internal state from the backend each tick.

get_datamethod
def get_data(self)dict

Return a dict snapshot of the entity's current state.

get_posemethod
def get_pose(self)Pose

Return the world-frame pose of the entity.

set_posemethod
def set_pose(self, pose: Pose)None

Teleport the entity to a new world-frame pose.

class

Robot

abstract6 methods
fastsim.unisim.robot.RobotextendsArticulation

Abstract robot with end-effector, IK, and motion planning support.

Robot extends Articulation with EE-level operations and planner integration. Concrete robot classes (GeneralRobot, SingleGripperArmRobot, …) inherit from Robot.

get_plannermethod
def get_planner(self)Planner

Return the motion planner instance attached to this robot.

Planner — The robot's planner, or None if none is configured.
get_ee_posemethod
def get_ee_pose(self)Pose

Return the current world-frame pose of the end-effector.

Pose — Current EE pose.
solve_ikmethod
def solve_ik(self, target_pose: Pose, enable_retract: bool = False)dict

Solve IK for a target EE pose using the robot's planner.

NameTypeDefaultDescription
target_posePoseTarget EE pose in world frame.
enable_retractoptboolFalseUse retract joint state as seed.
dict — Joint position solution dict.
set_ee_pose_targetmethod
def set_ee_pose_target(self, target_pose: Pose, sync: bool = True)None

Command the robot to move its EE to a target pose.

NameTypeDefaultDescription
target_posePoseDesired EE pose.
syncoptboolTrueBlock until the robot reaches the target.
get_ee_jacobianmethod
def get_ee_jacobian(self)np.ndarray

Compute the geometric Jacobian at the end-effector for the current configuration.

np.ndarray — 6×n Jacobian matrix (linear + angular rows).
Inherited fromArticulation9
get_joint_positionmethod
def get_joint_position(self, joint_name: str | None = None)list

Read the current position of one or all joints.

get_joint_velocitymethod
def get_joint_velocity(self, joint_name: str | None = None)list

Read the current velocity of one or all joints.

set_joint_position_targetmethod
def set_joint_position_target(self, positions: list, joint_names: list | None = None)None

Set position drive targets for one or more joints.

set_joint_velocity_targetmethod
def set_joint_velocity_target(self, velocities: list, joint_names: list | None = None)None

Set velocity drive targets for one or more joints.

set_joint_effort_targetmethod
def set_joint_effort_target(self, efforts: list, joint_names: list | None = None)None

Set effort (torque/force) targets for one or more joints.

write_data_to_simmethod
def write_data_to_sim(self)None

Flush buffered drive commands to the physics backend.

get_joint_namesmethod
def get_joint_names(self)list

Return the ordered list of joint names for this articulation.

get_body_namesmethod
def get_body_names(self)list

Return the ordered list of rigid body (link) names.

is_joint_stoppedmethod
def is_joint_stopped(self)bool

Return True when all joints have come to rest (velocity below threshold).

class

GeneralRobot

0 methods
fastsim.unisim.robot.GeneralRobotextendsRobot

General-purpose robot with no gripper or arm specialization. Inherits the full Robot API.

Inherited fromRobot6
get_plannermethod
def get_planner(self)Planner

Return the motion planner instance attached to this robot.

get_ee_posemethod
def get_ee_pose(self)Pose

Return the current world-frame pose of the end-effector.

get_ee_link_namemethod
def get_ee_link_name(self)str

Return the name of the link designated as the end-effector.

solve_ikmethod
def solve_ik(self, target_pose: Pose, enable_retract: bool = False)dict

Solve IK for a target EE pose using the robot's planner.

set_ee_pose_targetmethod
def set_ee_pose_target(self, target_pose: Pose, sync: bool = True)None

Command the robot to move its EE to a target pose.

get_ee_jacobianmethod
def get_ee_jacobian(self)np.ndarray

Compute the geometric Jacobian at the end-effector for the current configuration.

class

SingleGripperArmRobot

6 methods
fastsim.unisim.robot.SingleGripperArmRobotextendsRobot

Arm robot with a single parallel-jaw or suction gripper.

Adds gripper open/close commands and convenience arm-specific helpers on top of the base Robot API.

open_grippermethod
def open_gripper(self, sync: bool = True)None

Send the open command to the gripper.

NameTypeDefaultDescription
syncoptboolTrueBlock until gripper is fully open.
close_grippermethod
def close_gripper(self, sync: bool = True)None

Send the close command to the gripper.

NameTypeDefaultDescription
syncoptboolTrueBlock until gripper is fully closed.
set_arm_target_positionmethod
def set_arm_target_position(self, positions: list, joint_names: list | None = None)None

Set joint position targets for the arm joints only (excludes gripper).

NameTypeDefaultDescription
positionslistTarget joint positions for arm joints.
joint_namesoptlist|NoneNoneArm joint names; if None, uses default arm joint order.
is_arm_stoppedmethod
def is_arm_stopped(self)bool

Return True when all arm joints have come to rest.

is_gripper_openedmethod
def is_gripper_opened(self)bool

Return True when the gripper is fully open.

is_gripper_closedmethod
def is_gripper_closed(self)bool

Return True when the gripper is fully closed (or has grasped an object).

Inherited fromRobot6
get_plannermethod
def get_planner(self)Planner

Return the motion planner instance attached to this robot.

get_ee_posemethod
def get_ee_pose(self)Pose

Return the current world-frame pose of the end-effector.

get_ee_link_namemethod
def get_ee_link_name(self)str

Return the name of the link designated as the end-effector.

solve_ikmethod
def solve_ik(self, target_pose: Pose, enable_retract: bool = False)dict

Solve IK for a target EE pose using the robot's planner.

set_ee_pose_targetmethod
def set_ee_pose_target(self, target_pose: Pose, sync: bool = True)None

Command the robot to move its EE to a target pose.

get_ee_jacobianmethod
def get_ee_jacobian(self)np.ndarray

Compute the geometric Jacobian at the end-effector for the current configuration.

class

Object

abstract2 methods
fastsim.unisim.object.ObjectextendsSpawnable

Abstract scene object with position and scale. Parent of RigidObject, ArticulatedObject, and SoftObject.

get_scalemethod
def get_scale(self)list

Return the current scale of the object.

list — [sx, sy, sz] scale factors.
set_scalemethod
def set_scale(self, scale: list)None

Set the uniform or per-axis scale of the object.

NameTypeDefaultDescription
scalelist[sx, sy, sz] scale factors.
Inherited fromSpawnable6
spawnmethod
def spawn(self)None

Instantiate the entity in the simulation scene.

removemethod
def remove(self)None

Remove the entity from the simulation scene.

update_datamethod
def update_data(self)None

Synchronize internal state from the backend each tick.

get_datamethod
def get_data(self)dict

Return a dict snapshot of the entity's current state.

get_posemethod
def get_pose(self)Pose

Return the world-frame pose of the entity.

set_posemethod
def set_pose(self, pose: Pose)None

Teleport the entity to a new world-frame pose.

class

RigidObject

2 methods
fastsim.unisim.object.RigidObjectextendsObject

Physics-enabled rigid body. Responds to gravity, contacts, and impulses.

set_linear_velocitymethod
def set_linear_velocity(self, velocity: list)None

Set the linear velocity of the rigid body.

NameTypeDefaultDescription
velocitylist[vx, vy, vz] in m/s.
set_angular_velocitymethod
def set_angular_velocity(self, velocity: list)None

Set the angular velocity of the rigid body.

NameTypeDefaultDescription
velocitylist[wx, wy, wz] in rad/s.
Inherited fromObject2
get_scalemethod
def get_scale(self)list

Return the current scale of the object.

set_scalemethod
def set_scale(self, scale: list)None

Set the uniform or per-axis scale of the object.

class

ArticulatedObject

0 methods
fastsim.unisim.object.ArticulatedObjectextendsArticulation,Object

An articulated scene object (e.g. a drawer, door) that is not a robot.

Inherits joint control from Articulation and object positioning from Object. Useful for interactive props with multiple moving parts.

Inherited fromArticulation9
get_joint_positionmethod
def get_joint_position(self, joint_name: str | None = None)list

Read the current position of one or all joints.

get_joint_velocitymethod
def get_joint_velocity(self, joint_name: str | None = None)list

Read the current velocity of one or all joints.

set_joint_position_targetmethod
def set_joint_position_target(self, positions: list, joint_names: list | None = None)None

Set position drive targets for one or more joints.

set_joint_velocity_targetmethod
def set_joint_velocity_target(self, velocities: list, joint_names: list | None = None)None

Set velocity drive targets for one or more joints.

set_joint_effort_targetmethod
def set_joint_effort_target(self, efforts: list, joint_names: list | None = None)None

Set effort (torque/force) targets for one or more joints.

write_data_to_simmethod
def write_data_to_sim(self)None

Flush buffered drive commands to the physics backend.

get_joint_namesmethod
def get_joint_names(self)list

Return the ordered list of joint names for this articulation.

get_body_namesmethod
def get_body_names(self)list

Return the ordered list of rigid body (link) names.

is_joint_stoppedmethod
def is_joint_stopped(self)bool

Return True when all joints have come to rest (velocity below threshold).

Inherited fromObject2
get_scalemethod
def get_scale(self)list

Return the current scale of the object.

set_scalemethod
def set_scale(self, scale: list)None

Set the uniform or per-axis scale of the object.

class

SoftObject

abstract10 methods
fastsim.unisim.object.SoftObjectextendsObject

Abstract deformable / soft-body object with particle-level state access.

Provides APIs for querying and controlling particle positions, velocities, and deformation gradients. Concrete implementations (e.g. IsaacLabSoftObject) map these to the simulator's soft-body solver. Supports cloth, volumetric, and inflatable body types.

get_particle_positionsmethod
def get_particle_positions(self)np.ndarray

Return all particle positions as an (N, 3) array in world space.

np.ndarray — Particle positions with shape (N, 3)
get_particle_velocitiesmethod
def get_particle_velocities(self)np.ndarray

Return all particle velocities as an (N, 3) array in world space.

np.ndarray — Particle velocities with shape (N, 3)
set_particle_positionsmethod
def set_particle_positions(self, positions: np.ndarray)None

Overwrite particle positions with an (N, 3) array in world space.

NameTypeDefaultDescription
positionsnp.ndarrayNew particle positions, shape (N, 3)
set_particle_velocitiesmethod
def set_particle_velocities(self, velocities: np.ndarray)None

Overwrite particle velocities with an (N, 3) array in world space.

NameTypeDefaultDescription
velocitiesnp.ndarrayNew particle velocities, shape (N, 3)
get_particle_countmethod
def get_particle_count(self)int

Return the total number of simulated particles.

int — Number of particles
get_deformation_gradientmethod
def get_deformation_gradient(self)np.ndarray

Return per-element deformation gradients as an (M, 3, 3) array.

M is the number of finite-element cells (tetrahedra, hexahedra, or triangles for cloth). Returns an empty array when the simulator does not expose element-level data.

np.ndarray — Deformation gradients with shape (M, 3, 3)
updatemethod
def update(self, dt: float)None

Advance internal bookkeeping by one simulation step.

NameTypeDefaultDescription
dtfloatStep duration in seconds
write_data_to_simmethod
def write_data_to_sim(self)None

Flush all pending state writes (positions, velocities) to the simulator.

write_to_sim_if_dirtymethod
def write_to_sim_if_dirty(self)None

Flush state to the simulator only when the internal dirty flag is set.

Inherited fromObject2
get_scalemethod
def get_scale(self)list

Return the current scale of the object.

set_scalemethod
def set_scale(self, scale: list)None

Set the uniform or per-axis scale of the object.

class

Sensor

abstract1 method
fastsim.unisim.sensor.SensorextendsSpawnable

Abstract sensor entity. All sensors extend this class.

get_observationmethod
def get_observation(self)Any

Return the latest observation produced by this sensor.

Any — Sensor-specific observation data.
Inherited fromSpawnable6
spawnmethod
def spawn(self)None

Instantiate the entity in the simulation scene.

removemethod
def remove(self)None

Remove the entity from the simulation scene.

update_datamethod
def update_data(self)None

Synchronize internal state from the backend each tick.

get_datamethod
def get_data(self)dict

Return a dict snapshot of the entity's current state.

get_posemethod
def get_pose(self)Pose

Return the world-frame pose of the entity.

set_posemethod
def set_pose(self, pose: Pose)None

Teleport the entity to a new world-frame pose.

class

Camera

3 methods
fastsim.unisim.sensor.CameraextendsSensor

RGB/depth camera sensor with configurable intrinsics.

get_rgbmethod
def get_rgb(self)np.ndarray

Return the latest RGB image as a uint8 array (H×W×3).

np.ndarray — RGB image array, shape [H, W, 3], dtype uint8.
get_depthmethod
def get_depth(self)np.ndarray

Return the latest depth image in metres (H×W).

np.ndarray — Depth array, shape [H, W], dtype float32.
get_intrinsicsmethod
def get_intrinsics(self)np.ndarray

Return the camera intrinsic matrix K (3×3).

np.ndarray — 3×3 intrinsic matrix.
Inherited fromSensor1
get_observationmethod
def get_observation(self)Any

Return the latest observation produced by this sensor.

class

Base

abstract0 methods
fastsim.unisim.base.BaseextendsSpawnable

Abstract scene base / environment entity (ground, stage, arena).

Inherited fromSpawnable6
spawnmethod
def spawn(self)None

Instantiate the entity in the simulation scene.

removemethod
def remove(self)None

Remove the entity from the simulation scene.

update_datamethod
def update_data(self)None

Synchronize internal state from the backend each tick.

get_datamethod
def get_data(self)dict

Return a dict snapshot of the entity's current state.

get_posemethod
def get_pose(self)Pose

Return the world-frame pose of the entity.

set_posemethod
def set_pose(self, pose: Pose)None

Teleport the entity to a new world-frame pose.

class

EmptyBase

0 methods
fastsim.unisim.base.EmptyBaseextendsBase

Empty base with no geometry or physics — useful for tabletop scenes where the ground is provided externally.

This class is used via inheritance; no additional methods documented.See methods:Base
class

UsdBase

1 method
fastsim.unisim.base.UsdBaseextendsBase

Loads a USD stage file as the scene environment.

get_usd_pathmethod
def get_usd_path(self)str

Return the resolved filesystem path to the loaded USD stage.

str — Absolute USD file path.
class

GroundPlaneBase

0 methods
fastsim.unisim.base.GroundPlaneBaseextendsBase

Infinite ground plane with collision physics — the default base for most manipulation tasks.

This class is used via inheritance; no additional methods documented.See methods:Base
class

Light

abstract1 method
fastsim.unisim.light.LightextendsSpawnable

Abstract light entity. All light types extend this class.

set_intensitymethod
def set_intensity(self, intensity: float)None

Set the light intensity.

NameTypeDefaultDescription
intensityfloatIntensity value in candelas or nits depending on light type.
Inherited fromSpawnable6
spawnmethod
def spawn(self)None

Instantiate the entity in the simulation scene.

removemethod
def remove(self)None

Remove the entity from the simulation scene.

update_datamethod
def update_data(self)None

Synchronize internal state from the backend each tick.

get_datamethod
def get_data(self)dict

Return a dict snapshot of the entity's current state.

get_posemethod
def get_pose(self)Pose

Return the world-frame pose of the entity.

set_posemethod
def set_pose(self, pose: Pose)None

Teleport the entity to a new world-frame pose.

class

GeneralLight

1 method
fastsim.unisim.light.GeneralLightextendsLight

General-purpose light supporting sphere, rectangle, and distant light types.

set_colormethod
def set_color(self, color: list)None

Set the light colour as an RGB tuple.

NameTypeDefaultDescription
colorlist[r, g, b] in [0, 1] range.
Inherited fromLight1
set_intensitymethod
def set_intensity(self, intensity: float)None

Set the light intensity.

class

RobotFactory

static-only1 method
fastsim.unisim.robot.RobotFactory

Static factory for creating Robot instances from name and config.

createstaticmethod
@staticmethod def create(name: str, config: dict)Robot

Instantiate and return a Robot for the given name and config dict.

NameTypeDefaultDescription
namestrRobot entity name.
configdictRobot configuration dict.
Robot — Constructed Robot instance.
class

ObjectFactory

static-only1 method
fastsim.unisim.object.ObjectFactory

Static factory for creating Object instances from name and config.

createstaticmethod
@staticmethod def create(name: str, config: dict)Object

Instantiate and return an Object for the given name and config dict.

NameTypeDefaultDescription
namestrObject entity name.
configdictObject configuration dict.
Object — Constructed Object instance.
class

SensorFactory

static-only1 method
fastsim.unisim.sensor.SensorFactory

Static factory for creating Sensor instances from name and config.

createstaticmethod
@staticmethod def create(name: str, config: dict)Sensor

Instantiate and return a Sensor for the given name and config dict.

NameTypeDefaultDescription
namestrSensor entity name.
configdictSensor configuration dict.
Sensor — Constructed Sensor instance.
class

BaseFactory

static-only1 method
fastsim.unisim.base.BaseFactory

Static factory for creating Base instances from name and config.

createstaticmethod
@staticmethod def create(name: str, config: dict)Base

Instantiate and return a Base for the given name and config dict.

NameTypeDefaultDescription
namestrBase entity name.
configdictBase configuration dict.
Base — Constructed Base instance.
class

LightFactory

static-only1 method
fastsim.unisim.light.LightFactory

Static factory for creating Light instances from name and config.

createstaticmethod
@staticmethod def create(name: str, config: dict)Light

Instantiate and return a Light for the given name and config dict.

NameTypeDefaultDescription
namestrLight entity name.
configdictLight configuration dict.
Light — Constructed Light instance.
class

SceneManager

static-only8 methods
fastsim.unisim.scene_manager.SceneManager

Static registry and factory for all scene entities (robots, objects, sensors, spawnables).

SceneManager is the single source of truth for every entity active in the simulation. Query entities by name, bulk-retrieve all entities of a kind, or access low-level Spawnable handles for advanced use.

get_robotstaticmethod
@staticmethod def get_robot(name: str)Robot

Retrieve a Robot entity by name.

NameTypeDefaultDescription
namestrThe name of the robot as defined in the scene config.
Robot — The matching Robot instance.
get_objectstaticmethod
@staticmethod def get_object(name: str)Object

Retrieve an Object entity by name.

NameTypeDefaultDescription
namestrThe name of the object as defined in the scene config.
Object — The matching Object instance.
get_sensorstaticmethod
@staticmethod def get_sensor(name: str)Sensor

Retrieve a Sensor entity by name.

NameTypeDefaultDescription
namestrThe name of the sensor as defined in the scene config.
Sensor — The matching Sensor instance.
get_all_robotsstaticmethod
@staticmethod def get_all_robots()dict

Return all registered robots as a name→Robot mapping.

dict — Dict mapping robot names to Robot instances.
get_all_objectsstaticmethod
@staticmethod def get_all_objects()dict

Return all registered objects as a name→Object mapping.

dict — Dict mapping object names to Object instances.
get_all_sensorsstaticmethod
@staticmethod def get_all_sensors()dict

Return all registered sensors as a name→Sensor mapping.

dict — Dict mapping sensor names to Sensor instances.
get_spawnablestaticmethod
@staticmethod def get_spawnable(name: str)Spawnable

Retrieve the low-level Spawnable handle for any named entity.

NameTypeDefaultDescription
namestrEntity name.
Spawnable — The underlying Spawnable object.
setup_scene_from_configstaticmethod
@staticmethod def setup_scene_from_config(scene_cfg: dict)None

Parse the scene config section and spawn all configured entities.

NameTypeDefaultDescription
scene_cfgdictThe parsed scene configuration dict (usually from ConfigManager.scene_config).