DexForce · acrlw · Aug 13, 2026 · Aug 13, 2026 · Aug 14, 2026 · Aug 14, 2026
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -8,4 +8,5 @@ sphinx-autosummary-accessors
 sphinxcontrib-bibtex
 sphinx-design
 sphinx_autodoc_typehints
-pypandoc_binary
+sphinxcontrib-mermaid
+pypandoc_binary
diff --git a/.../source/api_reference/embodichain/embodichain.learning.rl.policy_evaluation.rst b/.../source/api_reference/embodichain/embodichain.learning.rl.policy_evaluation.rst
@@ -0,0 +1,7 @@
+embodichain.learning.rl.policy_evaluation
+=========================================
+
+.. automodule:: embodichain.learning.rl.policy_evaluation
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api_reference/embodichain/embodichain.learning.rl.rst b/docs/source/api_reference/embodichain/embodichain.learning.rl.rst
@@ -18,6 +18,7 @@ collection logic, policy/model builders, and training entry points.
       buffer
       collector
       models
+      policy_evaluation
       train
       utils
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -40,6 +40,7 @@
     "sphinx.ext.viewcode",
     "sphinx_autodoc_typehints",  # optional, shows type hints
     "sphinx_design",
+    "sphinxcontrib.mermaid",
     "myst_parser",  # if you prefer Markdown pages
     "sphinx_copybutton",
 ]
@@ -59,6 +60,7 @@
 
 # If using MyST and writing .md API stubs:
 myst_enable_extensions = ["colon_fence", "deflist", "html_admonition"]
+myst_fence_as_directive = ["mermaid"]
 
 
 templates_path = ["_templates"]

diff --git a/docs/source/features/toolkits/grasp_generator.rst b/docs/source/features/toolkits/grasp_generator.rst
@@ -224,7 +224,7 @@ You can customize the run with additional arguments:
 
 .. code-block:: bash
 
-   python scripts/tutorials/grasp/grasp_generator.py --num_envs <n> --device <cuda/cpu> --renderer <legacy|hybrid|fast-rt|rt> --headless
+   python scripts/tutorials/grasp/grasp_generator.py --num_envs <n> --device <cuda/cpu> --renderer <auto|hybrid|fast-rt|offline-rt> --headless
 
 After confirming the grasp region in the browser, the script will compute a grasp pose, print the elapsed time, and then wait for you to press **Enter** before executing the full grasp trajectory in the simulation. Press **Enter** again to exit once the motion is complete.
 

diff --git a/docs/source/guides/cli.md b/docs/source/guides/cli.md
@@ -145,7 +145,7 @@ embodichain run-env --gym_config config.yaml \
 | ``--num_envs`` | ``1`` | Number of parallel environments |
 | ``--device`` | ``cpu`` | Device (``cpu`` or ``cuda``) |
 | ``--headless`` | ``False`` | Run in headless mode |
-| ``--renderer`` | ``auto`` | Renderer backend: ``auto``, ``hybrid``, ``fast-rt`` or ``rt`` |
+| ``--renderer`` | ``auto`` | Renderer backend: ``auto``, ``hybrid``, ``fast-rt`` or ``offline-rt`` |
 | ``--arena_space`` | ``5.0`` | Arena space size |
 | ``--gpu_id`` | ``0`` | GPU ID to use |
 | ``--preview`` | ``False`` | Enter interactive preview mode |
@@ -372,6 +372,56 @@ See the Profiling section under Run Env for report format. Outputs are written t
 
 ---
 
+## Policy Evaluation
+
+Evaluate the latest checkpoint from an EmbodiChain training run:
+
+```bash
+embodichain eval-policy outputs/my_policy_<timestamp>
+```
+
+Open a simulator task in the Viewer:
+
+```bash
+embodichain eval-policy outputs/my_policy_<timestamp> \
+    --checkpoint best \
+    --viewer \
+    --renderer hybrid
+```
+
+Evaluate an explicit EmbodiChain checkpoint:
+
+```bash
+embodichain eval-policy \
+    --checkpoint /path/to/policy.pt \
+    --config /path/to/train.yaml \
+    --gym-config /path/to/gym.yaml
+```
+
+### Main arguments
+
+| Argument | Default | Description |
+|---|---|---|
+| ``RUN`` | *(optional)* | Training run containing ``run-manifest.json`` |
+| ``--checkpoint`` | ``latest`` with RUN | ``latest``, ``best``, or a checkpoint path |
+| ``--config`` | RUN manifest | Training configuration override |
+| ``--gym-config`` | RUN manifest | Simulator task configuration override |
+| ``--episodes`` | Training configuration | Number of completed task episodes |
+| ``--num-envs`` | Training configuration | Number of parallel Headless environments |
+| ``--viewer`` | Headless | Open the original simulator task in the DexSim Viewer |
+| ``--control-steps`` | Viewer runs continuously | Exact number of Policy actions |
+| ``--duration`` | *(optional)* | Duration converted to integer control steps |
+| ``--renderer`` | Training configuration or ``hybrid`` | Viewer renderer |
+| ``--device`` | Training configuration | PyTorch inference device |
+| ``--sim-device`` | Inference device | Simulation device |
+| ``--output`` | RUN or checkpoint evaluations | Evaluation output parent directory |
+
+External Motion Profiles use the same command with `--profile`. See
+{doc}`policy_evaluation` for training-run layout, execution paths, Viewer
+controls, output reports, and the complete ANYmal-C example.
+
+---
+
 ## Annotate Grasp
 
 Launch the browser-based grasp-region annotation tool.

diff --git a/docs/source/guides/index.rst b/docs/source/guides/index.rst
@@ -13,4 +13,5 @@ Practical guides for common tasks in EmbodiChain.
    add_robot
    preview_asset
    run_env
+   policy_evaluation
    cli
diff --git a/docs/source/guides/policy_evaluation.md b/docs/source/guides/policy_evaluation.md
@@ -0,0 +1,196 @@
+# Policy Evaluation
+
+`embodichain eval-policy` evaluates a saved EmbodiChain policy after training.
+It reconstructs the policy and environment from the training configuration,
+loads the selected checkpoint, and writes a standalone evaluation report.
+
+The command runs Headless by default. Add `--viewer` to open the original
+simulator task in the DexSim Viewer.
+
+## Training output
+
+`train-rl` records the files required by a later evaluation:
+
+```text
+outputs/<experiment>_<timestamp>/
+├── checkpoints/
+│   └── policy_*.pt
+├── configs/
+│   ├── train.yaml
+│   └── gym.yaml
+├── logs/
+├── videos/
+│   ├── train/
+│   └── eval/
+└── run-manifest.json
+```
+
+`configs/gym.yaml` is present for simulator tasks. The first evaluation adds:
+
+```text
+evaluations/
+└── <timestamp>-policy/
+    └── evaluation.json
+```
+
+`run-manifest.json` connects the run directory to its configuration snapshots
+and checkpoints:
+
+```json
+{
+  "schema_version": 1,
+  "configs": {
+    "train": "configs/train.yaml",
+    "gym": "configs/gym.yaml"
+  },
+  "checkpoints": {
+    "best": "checkpoints/cart_pole_grpo_best.pt",
+    "latest": "checkpoints/cart_pole_grpo_step_4096.pt"
+  }
+}
+```
+
+All paths in the manifest are relative to the run directory. `best` is `null`
+when training did not select a best checkpoint.
+
+## Evaluate a training run
+
+The shortest command selects `latest` and runs the configured number of
+Headless evaluation episodes:
+
+```bash
+embodichain eval-policy outputs/<experiment>_<timestamp>
+```
+
+Select the best checkpoint and override the episode count:
+
+```bash
+embodichain eval-policy outputs/<experiment>_<timestamp> \
+  --checkpoint best \
+  --episodes 10
+```
+
+Open the original simulator task in the Viewer:
+
+```bash
+embodichain eval-policy outputs/<experiment>_<timestamp> \
+  --checkpoint best \
+  --viewer \
+  --renderer hybrid \
+  --device cuda:0 \
+  --sim-device gpu
+```
+
+The Viewer uses one environment and keeps running until the window closes. Use
+`--episodes`, `--control-steps`, or `--duration` to select another stopping
+condition. `--renderer` accepts `hybrid`, `fast-rt`, and `offline-rt`.
+
+For a checkpoint created before `run-manifest.json` was introduced, provide
+its training configuration directly:
+
+```bash
+embodichain eval-policy \
+  --checkpoint /path/to/policy.pt \
+  --config /path/to/train.yaml \
+  --gym-config /path/to/gym.yaml \
+  --viewer
+```
+
+`--gym-config` can be omitted when the training configuration already refers to
+the task configuration.
+
+## Execution paths
+
+```mermaid
+flowchart LR
+    Run[Training run] --> Manifest[run-manifest.json]
+    Manifest --> Config[Training config]
+    Manifest --> Checkpoint[Checkpoint]
+    Config --> Runtime[EmbodiChain RL runtime]
+    Checkpoint --> Runtime
+    Runtime --> Headless[Headless episode evaluation]
+    Runtime --> Viewer[DexSim MotionPolicyEvaluator]
+    Headless --> Report[evaluation.json]
+    Viewer --> Report
+    Profile[External Motion Profile] --> Viewer
+```
+
+Headless evaluation calls the existing `evaluate_episodes()` path. Viewer
+evaluation keeps the task's original observation, action processing, reset,
+reward, termination, objects, and sensors:
+
+```mermaid
+sequenceDiagram
+    participant Evaluator as MotionPolicyEvaluator
+    participant Adapter as EmbodiChainTaskPolicyAdapter
+    participant Task as EmbodiChainTaskEnvironment
+    participant Policy as EmbodiChain Policy
+    participant Env as Original task Environment
+
+    Evaluator->>Task: reset()
+    Task->>Env: reset()
+    Env-->>Task: observation and task state
+    Task-->>Evaluator: EvaluationFrame
+    loop Each control step
+        Evaluator->>Adapter: infer(frame)
+        Adapter->>Policy: deterministic inference
+        Policy-->>Adapter: action
+        Adapter-->>Evaluator: PolicyOutput
+        Evaluator->>Task: step(action)
+        Task->>Env: action processing and env.step()
+        Env-->>Task: observation, reward, termination and info
+        Task-->>Evaluator: EnvironmentStep
+    end
+```
+
+| Input | Headless | Viewer |
+|---|---:|---:|
+| EmbodiChain lightweight RL environment | Yes | — |
+| EmbodiChain simulator RL environment | Yes | Yes |
+| Registered external Motion Profile | Yes | Yes |
+
+Policy reconstruction follows the model definition stored in the training
+configuration. The Viewer path has been validated with CartPole GRPO and
+PushCube PPO checkpoints.
+
+## Viewer controls
+
+| Key | Action |
+|---|---|
+| `Backspace` | Reset the task and camera framing |
+| `T` | Switch between tracking and free camera modes when the Environment provides a tracking target |
+| `R` | Start or stop recording |
+| `Esc` | Close the Viewer |
+
+While tracking is active, drag with the left mouse button to orbit and use the
+mouse wheel to zoom.
+
+## External policy example
+
+The repository includes a concrete ANYmal-C velocity example under
+`examples/learning/policy_evaluation/`. It prepares a public TorchScript
+checkpoint and robot assets, registers an adjacent Motion Profile, and forwards
+the remaining arguments to `eval-policy`.
+
+```bash
+python examples/learning/policy_evaluation/prepare_resources.py
+python examples/learning/policy_evaluation/eval_policy.py \
+  --viewer \
+  --renderer hybrid \
+  --sim-device gpu
+```
+
+Use W/S for `vx`, A/D for `vy`, Q/E for `yaw`, and M to zero the command. See
+the [example README](https://github.com/DexForce/EmbodiChain/tree/main/examples/learning/policy_evaluation)
+for the resource layout, observation construction, action conversion, and
+Profile implementation.
+
+This example tracks the robot root in the ground plane. Press `T` to switch
+between tracking and free view.
+
+## Evaluation report
+
+`evaluation.json` records the selected checkpoint and configs, task and device
+information, episode results, and aggregated metrics. Reports are written to
+`<run>/evaluations/` for a training run and next to an explicit checkpoint by
+default. Use `--output` to select another parent directory.
diff --git a/docs/source/guides/preview_asset.md b/docs/source/guides/preview_asset.md
@@ -149,7 +149,7 @@ asset.set_local_pose(pose)
 | `--use_usd_properties` | disabled | Use physical properties stored in the USD file. |
 | `--fix_base` / `--no-fix_base` | fixed | Fix or unfix articulation bases. |
 | `--sim_device` | `cpu` | Simulation device. |
-| `--renderer` | `hybrid` | Renderer: `hybrid`, `fast-rt`, or `rt`. |
+| `--renderer` | `hybrid` | Renderer: `hybrid`, `fast-rt`, or `offline-rt`. |
 | `--env_map` | none | Built-in IBL resource name or absolute `.hdr`, `.png`, or `.exr` path. |
 | `--headless` | disabled | Run without the native window. |
 | `--preview` | disabled | Enter the interactive terminal after loading. |

diff --git a/docs/source/overview/sim/sim_manager.md b/docs/source/overview/sim/sim_manager.md
@@ -68,7 +68,7 @@ The {class}`~cfg.RenderCfg` class controls the rendering backend and quality set
 
 | Parameter | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `renderer` | `str` | `"auto"` | Renderer backend to use. Options are `'auto'` (pick a default based on the detected GPU), `'hybrid'` (ray tracing for shadows/reflections + rasterization), `'fast-rt'` (full ray tracing), and `'rt'` (offline ray-traced renderer for maximum visual fidelity). |
+| `renderer` | `str` | `"auto"` | Renderer backend to use. Options are `'auto'` (pick a default based on the detected GPU), `'hybrid'` (ray tracing for shadows/reflections + rasterization), `'fast-rt'` (full ray tracing), and `'offline-rt'` (offline ray-traced renderer for maximum visual fidelity). |
 | `spp` | `int` | `1` | Samples per pixel for ray-traced rendering. Must be at least 1. |
 | `tone_mapping_enabled` | `bool` | `False` | Whether to map HDR RGB output with the modified Reinhard curve. |
 | `tone_mapping_exposure` | `float` | `1.0` | Non-negative fixed linear exposure multiplier applied before tone mapping. |

diff --git a/docs/source/tutorial/rl.rst b/docs/source/tutorial/rl.rst
@@ -264,6 +264,19 @@ All outputs are written to ``./outputs/<exp_name>_<timestamp>/``:
 
 - **logs/**: TensorBoard logs
 - **checkpoints/**: Model checkpoints
+- **configs/**: Training config and referenced gym config snapshots
+- **evaluations/**: Timestamped policy evaluation reports
+- **run-manifest.json**: Training configs and best/latest checkpoint index used by ``eval-policy``
+
+A training run can be evaluated Headless or opened in its simulator task:
+
+.. code-block:: bash
+
+   embodichain eval-policy outputs/<exp_name>_<timestamp>
+   embodichain eval-policy outputs/<exp_name>_<timestamp> --viewer
+
+See :doc:`../guides/policy_evaluation` for EmbodiChain ``.pt`` training
+runs and the external Motion Profile example.
 
 Training Process
 ~~~~~~~~~~~~~~~
@@ -452,9 +465,9 @@ Best Practices
 
 - **Configuration**: Use JSON for all hyperparameters. This makes experiments reproducible and easy to track.
 
-- **Logging**: Metrics are automatically logged to TensorBoard and Weights & Biases. Check ``outputs/<exp_name>/logs/`` for TensorBoard logs.
+- **Logging**: Metrics are automatically logged to TensorBoard and Weights & Biases. Check ``outputs/<exp_name>_<timestamp>/logs/`` for TensorBoard logs.
 
-- **Checkpoints**: Regular checkpoints are saved to ``outputs/<exp_name>/checkpoints/``. Use these to resume training or evaluate policies.
+- **Checkpoints**: Regular checkpoints are saved to ``outputs/<exp_name>_<timestamp>/checkpoints/``. Use these to resume training or evaluate policies.
 
 See Also
 --------
@@ -464,3 +477,4 @@ See Also
 - :doc:`basic_env` — Creating basic Gymnasium environments
 - :doc:`modular_env` — Advanced modular environments with managers
 - :doc:`/resources/task/index` — List of available RL task environments
+- :doc:`/guides/policy_evaluation` — Headless and Viewer evaluation of EmbodiChain ``.pt`` checkpoints and external Motion Profiles
diff --git a/embodichain/__main__.py b/embodichain/__main__.py
@@ -81,6 +81,11 @@ class Command:
         target="embodichain.learning.rl.train:cli",
         help="Train an RL agent from a JSON or YAML config.",
     ),
+    Command(
+        name="eval-policy",
+        target="embodichain.learning.rl.policy_evaluation.cli:cli",
+        help="Evaluate a trained policy in Headless or Viewer mode.",
+    ),
     Command(
         name="annotate-grasp",
         target="embodichain.toolkits.graspkit.scripts.annotate_grasp:cli",
-Original file line number
+Diff line change
@@ Expand Up @@
           buffer
           collector
           models
+          policy_evaluation
           train
           utils
@@ Expand Down @@