Add planner selection to atomic-action tutorials

agent_context/MAP.yaml

@@ -144,7 +144,7 @@ topics:
   aliases: [motion planning, trajectory planning, trajectory playback, fixed-cadence trajectory playback, motion expansion,
     trajectory expansion, trajectory augmentation, fixed scene trajectory augmentation, 轨迹播放, 轨迹扩增, 运动规划,
     轨迹规划]
-  keywords: [BasePlanner, PlanState, PlanResult, MotionGenerator, ToppraPlanner, CuroboPlanner, NeuralPlanner,
+  keywords: [BasePlanner, PlanState, PlanResult, MotionGenerator, ToppraPlanner, TrapezoidalPlanner, CuroboPlanner, NeuralPlanner,
     expansion, GenerationSession, TrajectoryAugmentationCfg, CandidateTrajectoryBatch,
     collision world, compute trajectory, trajectory resampling, trajectory warping, retime_to_control_grid,
     JointTrajectoryPlaybackCfg, play_joint_trajectory]

agent_context/topics/atomic-actions/execution.md

@@ -112,7 +112,11 @@ resample fractional durations.
 Primitive planner results are explicitly retimed before their controlled-joint
 paths are embedded into a full-robot `TimedTrajectory`. Off-grid duration rounds
 up to a whole control interval, qvel is recomputed from the executed samples,
-and now-invalid native acceleration samples are discarded.
+and now-invalid native acceleration samples are discarded. Composite primitives
+that combine planner output with fixed-length hand or multi-part phases may
+also resample the planner's position path to the phase count before assembly;
+the final composite trajectory then derives its velocity targets from the
+assembled positions and timing.
 
 Tracking recovery is separate from task-level semantic recovery:
 

agent_context/topics/motion-planning/motion-planning.md

@@ -69,7 +69,8 @@ Focused augmentation tests live under `tests/sim/motion/expansion/`.
 ## Choose the owning layer
 
 - `BasePlanner` and `PlanState` / `PlanResult` define planning interfaces.
-- `ToppraPlanner` owns time parameterization; `CuroboPlanner` owns collision-aware planning.
+- `ToppraPlanner` and `TrapezoidalPlanner` own joint-path time parameterization;
+  `CuroboPlanner` owns collision-aware planning.
 - `MotionGenerator` composes motion commands and trajectory helpers; `NeuralPlanner` is experimental.
 - [Planner details](planner-details.md) cover process/memory behavior, registration and validation.
 - [Collision worlds](collision-worlds.md) cover snapshots, pose updates, provenance and cache boundaries.
@@ -198,7 +199,8 @@ retains compatibility aliases; compute does not import simulation modules.
 
 `embodichain.compute.trajectory` owns pure interpolation, path resampling,
 time-domain differentiation/resampling, and keyframe-based warping. `interpolate_with_distance` retains keyframes;
-`resample_with_distance` treats interior points as optional path samples.
+`resample_with_distance` treats interior points as optional path samples and
+falls back to pure Torch when the Warp runtime cannot launch.
 MotionGenerator and atomic trajectory helpers import the compute API directly.
 `lab.sim.utility.action_utils` retains solver-dependent pose/IK adaptation and
 re-exports pure functions for compatibility. Warp implementations live in

agent_context/topics/motion-planning/planner-details.md

@@ -38,6 +38,11 @@ waypoints, with optional quintic corner blending. `TIME` sampling pads shorter
 batch rows at their exact final position with zero velocity and acceleration,
 starting at each row's actual endpoint. Padding has zero arrival intervals.
 
+When dispatched through `MotionGenerator`, `TrapezoidalPlanner` owns sparse
+joint-goal timing: the facade prepends the observed `start_qpos` when the
+caller supplies one and preserves the planner's native samples and
+derivatives.
+
 With `stop_at_waypoints=False`, straight runs are compressed using normalized
 edge directions and a cosine tolerance relative to the first edge of each
 retained run. Small waypoint spacing does not change the angular test, and

docs/source/overview/sim/atomic_actions/builtin_actions.md

@@ -1063,5 +1063,14 @@ python scripts/tutorials/atomic_action/pickup.py --headless --auto_play --device
 python scripts/tutorials/atomic_action/hand_over.py --headless --auto_play --device cpu
 ```
 
+The scripts share a `--planner` selector for the non-neural backends
+(`toppra`, `trapezoidal`, or `curobo`); `trapezoidal` is the default. See
+{doc}`/tutorial/atomic_actions` for backend-specific caveats and examples.
+The dynamic-obstacle recovery example remains cuRobo-only because it updates a
+live collision world.
+Every script also receives the same single global `sun` light from the shared
+tutorial scene setup; vectorized environments do not create per-arena point
+lights.
+
 See {doc}`/tutorial/atomic_actions` for engine setup, static compilation,
 closed-loop execution, effect verification, and custom-action guidance.

docs/source/overview/sim/motion/motion_generator.md

@@ -44,7 +44,7 @@ The built-in declarations are:
 
 * TOPPRA: `JOINT_MOVE`;
 * TrapezoidalPlanner: `JOINT_MOVE`, sparse joint waypoints, and preserved native
-  samples;
+  samples. During quantity sampling it retains every converted waypoint;
 * NeuralPlanner: `EEF_MOVE`;
 * cuRobo: `EEF_MOVE` and `JOINT_MOVE`.
 
@@ -54,6 +54,10 @@ TrapezoidalPlanner declares both `uses_sparse_joint_waypoints=True` and
 returns the planner's native `positions`, `velocities`, `accelerations`, and
 `dt` without normalizing them to `MotionGenOptions.sample_count`. See the
 [TrapezoidalPlanner guide](planners/trapezoidal_planner.md).
+When options are automatically resolved from a backend-neutral request, a
+requested quantity is treated as a lower bound if Cartesian-to-joint conversion
+produces more waypoints; an explicit `TrapezoidalPlanOptions.sample_interval`
+remains authoritative.
 
 ## Usage
 

docs/source/overview/sim/motion/planners/trapezoidal_planner.md

@@ -87,6 +87,10 @@ start, and does not run generic joint pre-interpolation. It also preserves the
 planner's native sample grid and its analytical velocity and acceleration
 outputs. `MotionGenOptions.sample_count` therefore does not replace an explicit
 `TrapezoidalPlanOptions.sample_interval`.
+When options are automatically resolved from a backend-neutral request, the
+requested quantity is treated as a lower bound if Cartesian-to-joint conversion
+produces more required waypoints; an explicit
+`TrapezoidalPlanOptions.sample_interval` remains authoritative.
 
 Every successful result with positions contains:
 

docs/source/tutorial/atomic_actions.rst

@@ -159,6 +159,74 @@ The ``motion_generator`` variable in the snippets below is a configured
 :class:`~embodichain.lab.sim.motion.motion_generator.MotionGenerator`; its robot, planner,
 device, cache, and collision world become the resources owned by the engine.
 
+All atomic-action tutorials use the shared scene setup, which creates exactly
+one global ``sun`` light (``main_light``) for the whole simulation. The sun
+uses a common downward direction and is not duplicated for each vectorized
+arena; tutorial-specific light positions are no longer needed.
+
+Selecting a motion planner
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Every runnable atomic-action tutorial accepts the shared ``--planner`` switch.
+It selects the non-neural backend used to construct its
+``MotionGenerator``:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 18 30 52
+
+   * - Value
+     - Backend
+     - Behavior and availability
+   * - ``toppra``
+     - :class:`~embodichain.lab.sim.motion.planners.ToppraPlanner`
+     - Time-optimal joint-space timing. Select this explicitly when comparing
+       against the trapezoidal default.
+   * - ``trapezoidal``
+     - :class:`~embodichain.lab.sim.motion.planners.TrapezoidalPlanner`
+     - Deterministic trapezoidal joint-space timing and the default for atomic
+       action tutorials. Cartesian targets are
+       converted through the shared IK/interpolation path before planning;
+       quantity sampling retains every converted waypoint. When options are
+       resolved from the backend-neutral request, ``MotionGenerator`` treats
+       the requested count as a lower bound; an explicitly supplied
+       ``TrapezoidalPlanOptions.sample_interval`` remains authoritative.
+       Fixed-length composite skill phases resample that position path back to
+       their requested phase count before combining arm and hand commands.
+   * - ``curobo``
+     - :class:`~embodichain.lab.sim.motion.planners.CuroboPlanner`
+     - CUDA-backed Cartesian/joint planning with collision-world support when
+       the tutorial supplies one. Select this explicitly when CUDA-backed
+       collision-aware planning is needed.
+
+``NeuralPlanner`` is intentionally not a choice here: it requires a
+tutorial-specific ONNX model and frame configuration rather than being a
+drop-in backend for these examples. For example, the same pose tutorial can
+be run with each supported backend as follows:
+
+Unless noted below, omitting ``--planner`` selects ``trapezoidal``.
+
+.. code-block:: bash
+
+   python scripts/tutorials/atomic_action/move_end_effector.py --device cpu
+   python scripts/tutorials/atomic_action/move_end_effector.py --device cpu --planner toppra
+   python scripts/tutorials/atomic_action/move_end_effector.py --device cuda --planner curobo
+
+The selector does not override a skill's explicit motion contract. In
+particular, ``dynamic_obstacle_recovery.py`` is deliberately cuRobo-only because
+it updates a live collision world; ``coordinated_pickment.py``,
+``coordinated_placement.py``, and ``hand_over.py`` use dual-arm planning that
+currently rejects cuRobo. ``control_dt.py`` intentionally uses
+``strategy="ik_interp"`` to compare control periods, so its planner choice is
+constructed for consistency but does not change that interpolation experiment.
+``coordinated_pickment.py`` likewise retains its synchronized multi-arm
+IK/keyframe implementation; its selector validates the backend but does not
+replace those custom synchronized phases.
+The exact Cartesian-linear portions of ``OpenDoor``, ``Press``, and ``Slide``
+likewise remain IK-grounded; their planner choice applies to the other
+motion-generation portions. ``Twist`` uses the selected planner for each of
+its pose segments.
+
 Control-part commands
 ---------------------
 

docs/source/tutorial/motion_gen.rst

@@ -5,7 +5,7 @@ Motion Generator
 
 .. currentmodule:: embodichain.lab.sim.motion.motion_generator
 
-The ``MotionGenerator`` class in EmbodiChain provides a unified and extensible interface for robot trajectory planning. It supports time-optimal trajectory generation (currently via TOPPRA), joint/Cartesian interpolation, and is designed for easy integration with RL, imitation learning, and classical control scenarios.
+The ``MotionGenerator`` class in EmbodiChain provides a unified and extensible interface for robot trajectory planning. It supports time-optimal trajectory generation via TOPPRA, deterministic trapezoidal joint-space timing, joint/Cartesian interpolation, and is designed for easy integration with RL, imitation learning, and classical control scenarios.
 
 Key Features
 ------------
@@ -193,7 +193,8 @@ API Reference
 Notes & Best Practices
 ~~~~~~~~~~~~~~~~~~~~~~
 
-- TOPPRA and NeuralPlanner do not maintain a collision world. Select the optional
+- TOPPRA, TrapezoidalPlanner, and NeuralPlanner do not maintain a collision
+  world. Select the optional
   cuRobo V2 backend for collision-aware planning and exact joint-trajectory
   collision validation; see :doc:`/overview/sim/motion/planners/curobo_planner`.
 - Planning inputs and outputs use environment-batched PyTorch tensors.