Simulation Framework

Simulation Framework#

The embodichain.lab.sim module is the runtime layer that connects robot assets, physics, rendering, sensing, kinematics, and motion generation. It is designed around a small set of composable components: a SimulationManager owns the simulation lifecycle, asset classes represent objects in the scene, sensors produce batched observations, solvers convert between joint space and task space, planners generate feasible trajectories, and atomic actions package common manipulation primitives. Task Program builds on this runtime without becoming a simulation submodule.

Like EmbodiChain’s environment and learning modules, the simulation framework is configuration driven. Scene elements are declared through config classes, spawned through the manager, and then stepped explicitly in a simulation loop. This makes the same scene description usable for interactive visualization, scripted data generation, and vectorized robot-learning environments.

Architecture#

The simulation stack can be read from the bottom up:

embodichain.lab.sim
|-- SimulationManager
|   `-- global physics, rendering, arenas, stepping, USD import/export
|-- assets
|   |-- rigid objects and rigid object groups
|   |-- articulations and robots
|   |-- soft objects and cloth
|   `-- lights, materials, shapes, and gizmos
|-- sensors
|   |-- cameras and stereo cameras
|   `-- contact sensors
|-- browser visualization
|   `-- Viser scene, cameras, overlays, and runtime telemetry
|-- motion
|   |-- solvers: forward, inverse, and differential kinematics
|   |-- planners: paths, time parameterization, and sampling
|   |-- workspace: reachability analysis and runtime queries
|   `-- expansion: candidates, coverage, and generation accounting
`-- atomic actions
    `-- reusable manipulation primitives built from assets, solvers, and planners

Semantic task declarations and execution sit above that runtime:

Task Program source
    -> decode / validate / compile
    -> Semantic Calls
    -> Atomic Skills
    -> simulation controllers

The SimulationManager is the entry point for most workflows. It creates the physics world, configures rendering and time stepping, lays out multiple parallel arenas, and exposes add_* methods for scene construction. Every asset and sensor is registered with the manager so that state updates, resets, rendering, and batched queries remain synchronized.

Submodule Relationships#

Submodule

Responsibility

Relationship to other modules

Simulation manager

Owns lifecycle, stepping, rendering, multiple arenas, and scene import/export.

Creates and coordinates assets, sensors, and physics state.

Assets

Define the simulated entities: rigid objects, object groups, articulations, robots, soft bodies, cloth, lights, shapes, and materials.

Provide the state and control surfaces consumed by sensors, solvers, planners, environments, and atomic actions.

Sensors

Produce perception data such as color, depth, segmentation, stereo disparity, and contacts.

Attach to world frames, robot links, or monitored bodies and return batched tensors for downstream policies or datasets.

Motion / solvers

Compute FK, IK, and differential kinematics for robots and articulations.

Translate task-space goals into joint-space commands used by planners, controllers, and actions.

Motion / planners

Generate joint-space or Cartesian trajectories with interpolation, timing, and feasibility handling.

Use robot state and solver results to produce trajectories that can be replayed in the manager loop.

Motion / workspace

Analyze reachability and cache workspace samples for runtime queries.

Supplies candidate robot configurations and poses for motion workflows.

Motion / trajectory augmentation

Vary annotated trajectories and track candidate budgets and coverage.

Receives planning, rollout, validation, and persistence results from explicit host integrations.

Atomic actions

Package complete manipulation primitives such as move, pick, and place.

Compose semantic targets, solvers, planners, and robot control into reusable higher-level skills.

Typical Data Flow#

A typical robot-learning or data-generation workflow follows this sequence:

  1. Create a SimulationManager from SimulationManagerCfg.

  2. Add assets such as objects, articulations, robots, lights, and materials.

  3. Add sensors for camera, stereo, or contact observations.

  4. Use solvers and planners to convert task goals into robot trajectories.

  5. Step the simulation with SimulationManager.update() and collect state or sensor tensors.

  6. Wrap the same simulation logic in a Gym environment when training or evaluating agents.

For manipulation tasks, atomic actions can replace the lower-level solver and planner calls. An action engine receives semantic targets or poses, resolves the motion primitive sequence, and returns a trajectory that can be replayed in the simulation.

For robot-independent task code, Task Program declares typed calls, scene identity, robot profiles, effects, and evidence. It owns program validation, compilation, live grounding, task segmentation, and structured results before delegating physical planning and execution to the same action engine.

Choosing Where to Start#

  • Start with Simulation Manager when creating a new simulation scene or learning how stepping, rendering, and parallel arenas work.

  • Use Simulation Assets when adding physical entities, materials, lights, or USD assets. The asset pages underneath it cover each object family in detail.

  • Use Sensors when adding camera, stereo, or contact observations.

  • Use Browser visualization with Viser when inspecting a headless or remote scene in a browser.

  • Use Robot Motion for the shared robot motion package and its boundaries.

  • Use Solvers when a robot needs FK, IK, or velocity-level kinematics.

  • Use Planners when a target pose or joint goal must become a time-ordered trajectory.

  • Use atomic actions when building scripted manipulation from reusable motion primitives.

  • Use Scene registry when Semantic Calls, snapshots, and planner obstacles must share one authoritative entity namespace.

  • Use Robot skill profiles to declare reusable embodiment resources, policy presets, and effect assurance.

  • Use Embodied Task Program when a task should declare semantic calls, settling, validation, or parallel barriers from JSON/YAML without implementing task-local motion generation.

Documentation Quality Notes#

The pages in this section should stay organized around the same workflow: configuration, construction through SimulationManager, runtime state or control APIs, and integration with sensors, planners, or Gym environments. When adding new simulation documentation, include tensor shapes for batched data, state the coordinate frame for poses and contacts, and link to the relevant object, solver, or planner page instead of duplicating API tables.

See Also#

Contents