[yuecideng]

Description

Atomic Skill demonstrations were split between the installed examples/ tree and a tutorial directory containing both compatibility wrappers and independent scene implementations. All runnable per-skill and specialized demonstrations now live under examples/sim/atomic_action/; the tutorial directory contains only two executable, explained API walkthroughs.

• Move assembly, coordinated manipulation, recovery, articulation-link grasping, MoveEndEffector, and control-period demonstrations into examples/. Preserve the distinct paper-cup transport scene as move_held_object_cup.py alongside the fixed cube scene.
• Replace the old tutorial entries with single_arm.py (PickUp→Place) and dual_arm.py (HandOver). Both construct typed invocations and reuse the canonical examples' physical setup and calibration. The tutorial chapter includes their live source snippets.
• Update benchmark imports, tests, installed-example coverage, CI impact selection, runnable catalogs, reference pages, and project context. Shared example helpers have one implementation; runtime code and tests no longer import the tutorial scripts.
• Fix free Cartesian trajectory preparation: sparse joint planners receive requested IK goals rather than dense intermediate samples that become mandatory stops. Explicit Cartesian-linear requests retain their samples and backend-owned timing constraints.
• Repair horizontal-stick HandOver with DH PGC-140-50, matching TCP/opening-axis calibration, grasp geometry, closing commands, joint layout and contact selectors. The can scene retains Robotiq 2F-140.
• Give the control-period demonstration enough samples to compare identical geometry under the current acceleration limit (100 points; 1.98 s versus 7.92 s at the two command periods).

Dependencies: none. No linked issue.

Migration

Use embodichain run-example sim/atomic_action --skill ... for the fixed scenes and embodichain run-example sim/atomic_action/<name> for standalone demonstrations. The old per-skill paths in scripts/tutorials/atomic_action/ are removed. Filename mappings include hand_over → handover, move_joints → move_joint, and the old cup-based move_held_object → move_held_object_cup.

Teaching entry points:

python scripts/tutorials/atomic_action/single_arm.py --headless --auto_play
python scripts/tutorials/atomic_action/dual_arm.py --is_horizontal --headless --auto_play

Type of change

• Breaking change: standalone tutorial paths/imports move to examples; typed Atomic Skill APIs remain compatible.

Validation

• 860 passed, 4 slow tests deselected, across the affected motion, Atomic, example, launcher, packaging, CI selection and visualization modules, including GPU checks:

  python -m pytest -q --run-gpu \
    tests/sim/motion/test_motion_generator_batched.py \
    tests/sim/atomic_actions/test_actions.py \
    tests/sim/atomic_actions/test_primitives_helpers.py \
    tests/sim/atomic_actions/test_trajectory_ops.py \
    tests/sim/motion/planners/test_trapezoidal_planner.py \
    tests/examples/atomic_action \
    tests/cli/test_run_example.py tests/test_example_package.py \
    tests/ci/test_select_tests.py \
    tests/visualization/test_example_tutorial_coverage.py \
    tests/sim/atomic_actions/test_newton_collision_pipeline_schedule.py

• 42 passed in the context map/tool tests; context.py check passes.
• All nine migrated standalone entries passed real run-example ... --help subprocess checks. Both teaching scripts ran in native UR5/Default physics; dual-arm runs covered the can and PGC stick fixtures. The control-period example ran and checked its equal geometry and 4× timing ratio.
• black==26.10.1: black . and formatting checks pass. API documentation gate: 3045/3045 exports documented.
• Full Sphinx dummy build succeeds. No warnings are attributed to the modified tutorial/reference pages; unrelated existing API/autodoc warnings remain.
• Test necessity: retain the focused sparse/dense timing regressions, move existing helper coverage to tests/examples/atomic_action/test_support.py, and extend the existing distribution test to cover the migrated scripts. The two teaching scripts use syntax/import/native smoke validation; no tutorial-only test files were added.
• Context: update Atomic example ownership, affordance-sampling helper paths, and motion-planning guidance. The generic launcher and simulation/control-clock ownership remain accurate, so no separate overview or new topic is needed.

Native single-seed UR5/Default-physics observations at 100 Hz:

Motion	Before	After
MoveEndEffector	3970 samples	413 samples
PickUp	6791 samples	761 samples
Place phase	11539 samples	950 samples

The repaired PGC stick was physically lifted and transferred: final object-position errors were 0.28 mm (TOPPRA) and 1.60 mm (trapezoidal), versus 230.93 mm for the old trapezoidal/Robotiq stick scene. These are fixed-scene observations, not a general physical-success-rate claim. PGC configs/contact selectors were checked for UR5, Franka and UR10; live handover replay covered UR5/Default physics.

Screenshots

Native before/after and paired-planner videos were inspected locally. Their measured outcomes are summarized above; generated media and recording scripts are not committed.

Checklist

• I have run the black . command to format the code base.
• I reviewed affected documentation and agent context, updated it where needed, or explained why no update was needed.
• Public API changes are reflected in the API docs (python docs/scripts/check_api_docs.py), if applicable.
• I verified appropriate behavioral coverage, reviewed the necessity of added or extended tests, and explained when no new tests were needed.
• Dependencies have been reviewed; no dependency changes are required.

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; no blocking issues were found.

Summary

The PR moves runnable Atomic Skill demos into examples/sim/atomic_action/ and leaves two teaching walkthroughs under scripts/tutorials/atomic_action/.

• Free Cartesian moves now keep sparse IK goals for joint planners.
• Runnable Atomic Skill demos now live in one installed examples catalog.
• Horizontal-stick handovers now pair PGC grippers with matching grasp calibration.
• Tutorials now show typed PickUp–Place and two-arm HandOver flows.
• The control-period demo now compares 100 samples at two command periods.

No actionable new issues were found in the changes since the previous review. No previous review threads were supplied.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  Launcher["run-example"] --> Examples["Canonical examples"]
  Tutorials["Single-arm and dual-arm walkthroughs"] --> Helpers["Shared scene and robot helpers"]
  Examples --> Helpers
  Benchmarks["Atomic Skill benchmarks"] --> Examples
  Examples --> Engine["AtomicActionEngine"]
  Tutorials --> Engine
  Engine --> Motion["MotionGenerator"]
  Motion --> Planner["Selected planner"]

Loading

_{Reviews (2) · Last reviewed commit: "refactor(examples): consolidate atomic d..." · Reviewed by Greptile}