Add basic simulation docs

docs/source/overview/gym/env.md

@@ -3,11 +3,11 @@
 ```{currentmodule} embodichain.lab.gym
 ```
 
-The {class}`envs.EmbodiedEnv` is the core environment class in EmbodiChain designed for complex Embodied AI tasks. It adopts a **configuration-driven** architecture, allowing users to define robots, sensors, objects, lighting, and automated behaviors (events) purely through configuration classes, minimizing the need for boilerplate code.
+The {class}`~envs.EmbodiedEnv` is the core environment class in EmbodiChain designed for complex Embodied AI tasks. It adopts a **configuration-driven** architecture, allowing users to define robots, sensors, objects, lighting, and automated behaviors (events) purely through configuration classes, minimizing the need for boilerplate code.
 
 ## Core Architecture
 
-Unlike the standard {class}`envs.BaseEnv`, the {class}`envs.EmbodiedEnv` integrates several manager systems to handle the complexity of simulation:
+Unlike the standard {class}`~envs.BaseEnv`, the {class}`~envs.EmbodiedEnv` integrates several manager systems to handle the complexity of simulation:
 
 * **Scene Management**: Automatically loads and manages robots, sensors, and scene objects defined in the configuration.
 * **Event Manager**: Handles automated behaviors such as domain randomization, scene setup, and dynamic asset swapping.
@@ -16,18 +16,18 @@ Unlike the standard {class}`envs.BaseEnv`, the {class}`envs.EmbodiedEnv` integra
 
 ## Configuration System
 
-The environment is defined by inheriting from {class}`envs.EmbodiedEnvCfg`. This configuration class serves as the single source of truth for the scene description.
+The environment is defined by inheriting from {class}`~envs.EmbodiedEnvCfg`. This configuration class serves as the single source of truth for the scene description.
 
-{class}`envs.EmbodiedEnvCfg` inherits from {class}`envs.EnvCfg` (the base environment configuration class, sometimes referred to as `BaseEnvCfg`), which provides fundamental environment parameters. The following sections describe both the base class parameters and the additional parameters specific to {class}`envs.EmbodiedEnvCfg`.
+{class}`~envs.EmbodiedEnvCfg` inherits from {class}`~envs.EnvCfg` (the base environment configuration class, sometimes referred to as `BaseEnvCfg`), which provides fundamental environment parameters. The following sections describe both the base class parameters and the additional parameters specific to {class}`~envs.EmbodiedEnvCfg`.
 
 ### BaseEnvCfg Parameters
 
-Since {class}`envs.EmbodiedEnvCfg` inherits from {class}`envs.EnvCfg`, it includes the following base parameters:
+Since {class}`~envs.EmbodiedEnvCfg` inherits from {class}`~envs.EnvCfg`, it includes the following base parameters:
 
 * **num_envs** (int): 
   The number of sub environments (arenas) to be simulated in parallel. Defaults to ``1``.
 
-* **sim_cfg** ({class}`embodichain.lab.sim.cfg.SimulationManagerCfg`): 
+* **sim_cfg** ({class}`~embodichain.lab.sim.SimulationManagerCfg`): 
   Simulation configuration for the environment, including physics settings, device selection, and rendering options. Defaults to a basic configuration with headless mode enabled.
 
 * **seed** (int | None): 
@@ -41,40 +41,40 @@ Since {class}`envs.EmbodiedEnvCfg` inherits from {class}`envs.EnvCfg`, it includ
 
 ### EmbodiedEnvCfg Parameters
 
-The {class}`envs.EmbodiedEnvCfg` class exposes the following additional parameters:
+The {class}`~envs.EmbodiedEnvCfg` class exposes the following additional parameters:
 
-* **robot** ({class}`embodichain.lab.sim.cfg.RobotCfg`): 
+* **robot** ({class}`~embodichain.lab.sim.cfg.RobotCfg`): 
   Defines the agent in the scene. Supports loading robots from URDF/MJCF with specified initial state and control mode. This is a required field.
 
-* **sensor** (List[{class}`embodichain.lab.sim.cfg.SensorCfg`]): 
+* **sensor** (List[{class}`~embodichain.lab.sim.sensor.SensorCfg`]): 
   A list of sensors attached to the scene or robot. Common sensors include {class}`~embodichain.lab.sim.sensors.StereoCamera` for RGB-D and segmentation data. Defaults to an empty list.
 
-* **light** ({class}`envs.EmbodiedEnvCfg.EnvLightCfg`): 
+* **light** ({class}`~envs.EmbodiedEnvCfg.EnvLightCfg`): 
   Configures the lighting environment. The {class}`EnvLightCfg` class contains:
 
   * ``direct``: List of direct light sources (Point, Spot, Directional) affecting local illumination. Defaults to an empty list.
   * ``indirect``: Global illumination settings (Ambient, IBL) - *planned for future release*.
 
-* **rigid_object** (List[{class}`embodichain.lab.sim.cfg.RigidObjectCfg`]): 
+* **rigid_object** (List[{class}`~embodichain.lab.sim.cfg.RigidObjectCfg`]): 
   List of dynamic or kinematic simple bodies. Defaults to an empty list.
 
-* **rigid_object_group** (List[{class}`embodichain.lab.sim.cfg.RigidObjectGroupCfg`]): 
+* **rigid_object_group** (List[{class}`~embodichain.lab.sim.cfg.RigidObjectGroupCfg`]): 
   Collections of rigid objects that can be managed together. Efficient for many similar objects. Defaults to an empty list.
 
-* **articulation** (List[{class}`embodichain.lab.sim.cfg.ArticulationCfg`]): 
+* **articulation** (List[{class}`~embodichain.lab.sim.cfg.ArticulationCfg`]): 
   List of complex mechanisms with joints (doors, drawers). Defaults to an empty list.
 
-* **background** (List[{class}`embodichain.lab.sim.cfg.RigidObjectCfg`]): 
+* **background** (List[{class}`~embodichain.lab.sim.cfg.RigidObjectCfg`]): 
   Static or kinematic objects serving as obstacles or landmarks in the scene. Defaults to an empty list.
 
 * **events** (Union[object, None]): 
-  Event settings for domain randomization and automated behaviors. Defaults to None, in which case no events are applied through the event manager. Please refer to the {class}`embodichain.lab.gym.managers.EventManager` class for more details.
+  Event settings for domain randomization and automated behaviors. Defaults to None, in which case no events are applied through the event manager. Please refer to the {class}`~envs.managers.EventManager` class for more details.
 
 * **observations** (Union[object, None]): 
-  Custom observation specifications. Defaults to None, in which case no additional observations are applied through the observation manager. Please refer to the {class}`embodichain.lab.gym.managers.ObservationManager` class for more details.
+  Custom observation specifications. Defaults to None, in which case no additional observations are applied through the observation manager. Please refer to the {class}`~envs.managers.ObservationManager` class for more details.
 
 * **dataset** (Union[object, None]): 
-  Dataset collection settings. Defaults to None, in which case no dataset collection is performed. Please refer to the {class}`embodichain.lab.gym.managers.DatasetManager` class for more details.
+  Dataset collection settings. Defaults to None, in which case no dataset collection is performed. Please refer to the {class}`~envs.managers.DatasetManager` class for more details.
 
 * **extensions** (Union[Dict[str, Any], None]): 
   Task-specific extension parameters that are automatically bound to the environment instance. This allows passing custom parameters (e.g., ``episode_length``, ``obs_mode``, ``action_scale``) without modifying the base configuration class. These parameters are accessible as instance attributes after environment initialization. For example, if ``extensions = {"episode_length": 500}``, you can access it via ``self.episode_length``. Defaults to None.
@@ -114,26 +114,26 @@ class MyTaskEnvCfg(EmbodiedEnvCfg):
 
 ## Manager Systems
 
-The manager systems in {class}`envs.EmbodiedEnv` provide modular, configuration-driven functionality for handling complex simulation behaviors. Each manager uses a **functor-based** architecture, allowing you to compose behaviors through configuration without modifying environment code. Functors are reusable functions or classes (inheriting from {class}`envs.managers.Functor`) that operate on the environment state, configured through {class}`envs.managers.cfg.FunctorCfg`.
+The manager systems in {class}`~envs.EmbodiedEnv` provide modular, configuration-driven functionality for handling complex simulation behaviors. Each manager uses a **functor-based** architecture, allowing you to compose behaviors through configuration without modifying environment code. Functors are reusable functions or classes (inheriting from {class}`~envs.managers.Functor`) that operate on the environment state, configured through {class}`~envs.managers.cfg.FunctorCfg`.
 
 ### Event Manager
 
 The Event Manager automates changes in the environment through event functors. Events can be triggered at different stages:
 
 * **startup**: Executed once when the environment initializes. Useful for setting up initial scene properties that don't change during episodes.
-* **reset**: Executed every time ``env.reset()`` is called. Applied to specific environments that need resetting (via ``env_ids`` parameter). This is the most common mode for domain randomization.
+* **reset**: Executed every time {meth}`~envs.Env.reset()` is called. Applied to specific environments that need resetting (via ``env_ids`` parameter). This is the most common mode for domain randomization.
 * **interval**: Executed periodically every N steps (specified by ``interval_step``, defaults to 10). Can be configured per-environment (``is_global=False``) or globally synchronized (``is_global=True``).
 
-Event functors are configured using {class}`envs.managers.cfg.EventCfg`. For a complete list of available event functors, please refer to {doc}`event_functors`.
+Event functors are configured using {class}`~envs.managers.cfg.EventCfg`. For a complete list of available event functors, please refer to {doc}`event_functors`.
 
 ### Observation Manager
 
-While {class}`envs.EmbodiedEnv` provides default observations organized into two groups:
+While {class}`~envs.EmbodiedEnv` provides default observations organized into two groups:
 
 * **robot**: Contains ``qpos`` (joint positions), ``qvel`` (joint velocities), and ``qf`` (joint forces).
 * **sensor**: Contains raw sensor outputs (images, depth, segmentation masks, etc.).
 
-The Observation Manager allows you to extend the observation space with task-specific information. Observations are configured using {class}`envs.managers.cfg.ObservationCfg` with two operation modes:
+The Observation Manager allows you to extend the observation space with task-specific information. Observations are configured using {class}`~envs.managers.cfg.ObservationCfg` with two operation modes:
 
 * **modify**: Update existing observations in-place. The observation must already exist in the observation dictionary. Useful for normalization, transformation, or filtering existing data. Example: Normalize joint positions to [0, 1] range based on joint limits.
 * **add**: Compute and add new observations to the observation space. The observation name can use hierarchical keys separated by ``/`` (e.g., ``"object/fork/pose"``).
@@ -144,7 +144,7 @@ For a complete list of available observation functors, please refer to {doc}`obs
 
 For Imitation Learning (IL) tasks, the Dataset Manager automates data collection through dataset functors. It currently supports:
 
-* **LeRobot Format** (via {class}`envs.managers.datasets.LeRobotRecorder`):
+* **LeRobot Format** (via {class}`~envs.managers.datasets.LeRobotRecorder`):
   Standard format for LeRobot training pipelines. Includes support for task instructions, robot metadata, success flags, and optional video recording.
 
 ```{note}
@@ -163,11 +163,11 @@ The manager operates in a single mode ``"save"`` which handles both recording an
  * ``use_videos``: Whether to save video recordings of episodes.
  * ``export_success_only``: Filter to save only successful episodes (based on ``info["success"]``).
 
-The dataset manager is called automatically during ``env.step()``, ensuring all observation-action pairs are recorded without additional user code.
+The dataset manager is called automatically during {meth}`~envs.Env.step()`, ensuring all observation-action pairs are recorded without additional user code.
 
 ## Creating a Custom Task
 
-To create a new task, inherit from {class}`envs.EmbodiedEnv` and implement the task-specific logic.
+To create a new task, inherit from {class}`~envs.EmbodiedEnv` and implement the task-specific logic.
 
 ```python
 from embodichain.lab.gym.envs import EmbodiedEnv, EmbodiedEnvCfg
@@ -203,7 +203,7 @@ class MyTaskEnv(EmbodiedEnv):
 ```
 
 ```{note}
-The ``create_demo_action_list`` method is specifically designed for expert demonstration data generation in Imitation Learning scenarios. For Reinforcement Learning tasks, you should override the ``get_reward`` method instead.
+The {meth}`~envs.EmbodiedEnv.create_demo_action_list` method is specifically designed for expert demonstration data generation in Imitation Learning scenarios. For Reinforcement Learning tasks, you should override the {meth}`~envs.EmbodiedEnv.get_reward` method instead.
 ```
 
 For a complete example of a modular environment setup, please refer to the {ref}`tutorial_modular_env` tutorial.

docs/source/overview/gym/event_functors.md

@@ -3,7 +3,7 @@
 ```{currentmodule} embodichain.lab.gym.envs.managers
 ```
 
-This page lists all available event functors that can be used with the Event Manager. Event functors are configured using {class}`envs.managers.cfg.EventCfg` and can be triggered at different stages: ``startup``, ``reset``, or ``interval``.
+This page lists all available event functors that can be used with the Event Manager. Event functors are configured using {class}`~envs.managers.cfg.EventCfg` and can be triggered at different stages: ``startup``, ``reset``, or ``interval``.
 
 ## Physics Randomization
 

docs/source/overview/gym/observation_functors.md

@@ -3,7 +3,7 @@
 ```{currentmodule} embodichain.lab.gym.envs.managers
 ```
 
-This page lists all available observation functors that can be used with the Observation Manager. Observation functors are configured using {class}`envs.managers.cfg.ObservationCfg` and can operate in two modes: ``modify`` (update existing observations) or ``add`` (add new observations).
+This page lists all available observation functors that can be used with the Observation Manager. Observation functors are configured using {class}`~cfg.ObservationCfg` and can operate in two modes: ``modify`` (update existing observations) or ``add`` (add new observations).
 
 ## Pose Computations
 
@@ -57,8 +57,11 @@ This page lists all available observation functors that can be used with the Obs
   - Normalize joint positions or velocities to [0, 1] range based on joint limits. Supports both ``qpos_limits`` and ``qvel_limits``. Operates in ``modify`` mode.
 ```
 
+```{currentmodule} embodichain.lab.sim.objects
+```
+
 ```{note}
-To get robot end-effector poses, you can use the robot's ``compute_fk()`` method directly in your observation functors or task code.
+To get robot end-effector poses, you can use the robot's {meth}`~Robot.compute_fk()` method directly in your observation functors or task code.
 ```
 
 ## Usage Example

docs/source/overview/sim/index.rst

@@ -8,16 +8,17 @@ Overview of the Simulation Framework:
 - Components
 
   - Simulation Manager
-  - Simulation Object
-  - Material
+  - Simulation Assets
   - Virtual Sensor
   - Kinematics Solver
   - Motion Generation
 
-
 .. toctree::
    :maxdepth: 1
    :glob:
-
+
+   sim_manager.md
+   sim_assets.md
+   sim_sensor.md
    solvers/index
    planners/index

docs/source/overview/sim/sim_articulation.md

@@ -0,0 +1,114 @@
+# Articulation
+
+```{currentmodule} embodichain.lab.sim
+```
+
+The {class}`~objects.Articulation` class represents the fundamental physics entity for articulated objects (e.g., robots, grippers, cabinets, doors) in EmbodiChain.
+
+## Configuration
+
+Articulations are configured using the {class}`~cfg.ArticulationCfg` dataclass.
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `fpath` | `str` | `None` | Path to the asset file (URDF/MJCF). |
+| `init_pos` | `tuple` | `(0,0,0)` | Initial root position `(x, y, z)`. |
+| `init_rot` | `tuple` | `(0,0,0)` | Initial root rotation `(r, p, y)` in degrees. |
+| `fix_base` | `bool` | `True` | Whether to fix the base of the articulation. |
+| `drive_props` | `JointDrivePropertiesCfg` | `...` | Default drive properties. |
+
+### Drive Configuration
+
+The `drive_props` parameter controls the joint physics behavior. It is defined using the `JointDrivePropertiesCfg` class.
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `stiffness` | `float` / `Dict` | `1.0e4` | Stiffness (P-gain) of the joint drive. Unit: $N/m$ or $Nm/rad$. |
+| `damping` | `float` / `Dict` | `1.0e3` | Damping (D-gain) of the joint drive. Unit: $Ns/m$ or $Nms/rad$. |
+| `max_effort` | `float` / `Dict` | `1.0e10` | Maximum effort (force/torque) the joint can exert. |
+| `max_velocity` | `float` / `Dict` | `1.0e10` | Maximum velocity allowed for the joint ($m/s$ or $rad/s$). |
+| `friction` | `float` / `Dict` | `0.0` | Joint friction coefficient. |
+| `drive_type` | `str` | `"force"` | Drive mode: `"force"` or `"acceleration"`. |
+
+### Setup & Initialization
+
+```python
+import torch
+from embodichain.lab.sim import SimulationManager, SimulationManagerCfg
+from embodichain.lab.sim.objects import Articulation, ArticulationCfg
+
+# 1. Initialize Simulation
+device = "cuda" if torch.cuda.is_available() else "cpu"
+sim_cfg = SimulationManagerCfg(sim_device=device)
+sim = SimulationManager(sim_config=sim_cfg)
+
+# 2. Configure Articulation
+art_cfg = ArticulationCfg(
+    fpath="assets/robots/franka/franka.urdf",
+    init_pos=(0, 0, 0.5),
+    fix_base=True
+)
+
+# 3. Spawn Articulation
+# Note: The method is 'add_articulation'
+articulation: Articulation = sim.add_articulation(cfg=art_cfg)
+
+# 4. Initialize Physics
+sim.reset_objects_state()
+```
+## Articulation Class
+State Data (Observation)
+State data is accessed via getter methods that return batched tensors.
+
+| Property | Shape | Description |
+| :--- | :--- | :--- |
+| `get_local_pose` | `(N, 7)` | Root link pose `[x, y, z, qw, qx, qy, qz]`. |
+| `get_qpos` | `(N, dof)` | Joint positions. |
+| `get_qvel` | `(N, dof)` | Joint velocities. |
+
+
+
+```python
+# Example: Accessing state
+# Note: Use methods (with brackets) instead of properties
+print(f"Current Joint Positions: {articulation.get_qpos()}")
+print(f"Root Pose: {articulation.get_local_pose()}")
+```
+### Control & Dynamics
+You can control the articulation by setting joint targets.
+
+### Joint Control
+```python
+# Set joint position targets (PD Control)
+# Get current qpos to create a target tensor of correct shape
+current_qpos = articulation.get_qpos()
+target_qpos = torch.zeros_like(current_qpos)
+
+# Set target position
+# target=True: Sets the drive target. The physics engine applies forces to reach this position.
+# target=False: Instantly resets/teleports joints to this position (ignoring physics).
+articulation.set_qpos(target_qpos, target=True)
+
+# Important: Step simulation to apply control
+sim.update()
+```
+### Drive Configuration
+Dynamically adjust drive properties.
+
+```python
+# Set stiffness for all joints
+articulation.set_drive(
+    stiffness=torch.tensor([100.0], device=device), 
+    damping=torch.tensor([10.0], device=device)
+)
+```
+### Kinematics
+Supports differentiable Forward Kinematics (FK) and Jacobian computation.
+```python
+# Compute Forward Kinematics
+# Note: Ensure 'build_pk_chain=True' in cfg
+if getattr(art_cfg, 'build_pk_chain', False):
+    ee_pose = articulation.compute_fk(
+        qpos=articulation.get_qpos(), # Use method call
+        end_link_name="ee_link" # Replace with actual link name
+    )
+```