Add Newton physics backend support

.agents/skills/add-robot/SKILL.md

@@ -17,7 +17,7 @@ Every robot config subclasses `RobotCfg` and overrides two hooks:
 
 - `_build_defaults(self, init_dict=None)` — read variant fields from `init_dict`,
   set them on `self`, then populate `urdf_cfg` / `control_parts` / `solver_cfg` /
-  `drive_pros` / `attrs`.
+  `joint_drive_props` / `attrs`.
 - `build_pk_serial_chain(self, device=...)` — return `{control_part: pk.SerialChain}`,
   reading the PK URDF from a single `_pk_urdf_path` source.
 
@@ -46,8 +46,8 @@ A cfg's `_build_defaults` must populate:
 - `urdf_cfg` (URDFCfg) or `fpath`
 - `control_parts` (Dict[str, List[str]]; joint names support regex)
 - `solver_cfg` (Dict[str, SolverCfg]; keys match `control_parts`)
-- `drive_pros` (JointDrivePropertiesCfg)
-- `attrs` (RigidBodyAttributesCfg)
+- `joint_drive_props` (JointDrivePropertiesCfg)
+- `attrs` (RigidBodyPhysicsCfg)
 
 `build_pk_serial_chain` must read from `_pk_urdf_path` (a property for
 constant-path robots, a method for variant-dependent paths). The PK chain's DOF
@@ -69,7 +69,7 @@ must match the matching `control_parts` entry (the test stub asserts this).
        self.urdf_cfg = URDFCfg(components=[...])
        self.control_parts = {"arm": ["JOINT[1-6]"]}
        self.solver_cfg = {"arm": OPWSolverCfg(end_link_name="link6", root_link_name="base_link")}
-       self.drive_pros = JointDrivePropertiesCfg(stiffness={"JOINT[1-6]": 1e4})
+       self.joint_drive_props = JointDrivePropertiesCfg(stiffness={"JOINT[1-6]": 1e4})
    ```
 
    Variant-aware template (reads version / arm_kind):
@@ -79,7 +79,7 @@ must match the matching `control_parts` entry (the test stub asserts this).
        init_dict = init_dict or {}
        self.version = MyRobotVersion(init_dict.get("version", "v1"))
        self.arm_kind = MyRobotArmKind(init_dict.get("arm_kind", "default"))
-       ...  # then urdf_cfg / control_parts / solver_cfg / drive_pros / attrs
+       ...  # then urdf_cfg / control_parts / solver_cfg / joint_drive_props / attrs
    ```
 
 4. **Implement `build_pk_serial_chain`** reading from `_pk_urdf_path`:
@@ -149,8 +149,8 @@ Do not copy those semantic declarations into the robot class.
 | `urdf_cfg` | URDFCfg | URDF file and components |
 | `control_parts` | Dict[str, List[str]] | Joint groups for control |
 | `solver_cfg` | Dict[str, SolverCfg] | IK solver configurations |
-| `drive_pros` | JointDrivePropertiesCfg | Joint stiffness, damping, force |
-| `attrs` | RigidBodyAttributesCfg | Rigid-body physics attributes |
+| `joint_drive_props` | JointDrivePropertiesCfg | Joint drive, limits, friction, and armature |
+| `attrs` | RigidBodyPhysicsCfg | Rigid-body physics attributes |
 | variant fields | enum / str / bool | Optional subclass fields |
 | `_pk_urdf_path` | property or method → str | URDF for the FK/IK serial chain |
 
@@ -160,5 +160,5 @@ Do not copy those semantic declarations into the robot class.
 - Registry: `embodichain/lab/sim/robots/__init__.py`
 - Docs: `docs/source/resources/robot/<name>.md`
 - Tests: `tests/sim/objects/test_robot_cfg.py`
-- Base class: `embodichain/lab/sim/cfg.py` (`RobotCfg`)
+- Base class: `embodichain/lab/sim/cfg/robot.py` (`RobotCfg`)
 - Guide: `docs/source/guides/add_robot.rst` · Tutorial: `docs/source/tutorial/add_robot.rst`

.agents/skills/add-solver/SKILL.md

@@ -219,7 +219,7 @@ exactly:
   `test_ur_solver.py`) to sample joint configs within limits with a safety
   margin.
 - A `BaseSolverTest` class with:
-  - `setup_simulation(self, sim_device)` — builds a `SimulationManagerCfg`,
+  - `setup_simulation(self, device)` — builds a `SimulationManagerCfg`,
     a `RobotCfg` whose `solver_cfg={"arm": <Name>SolverCfg(...)}` uses the new
     solver, and adds the robot via `self.sim.add_robot(cfg=cfg)`.
   - `test_ik(self)` — the round-trip contract:

.agents/skills/add-task-env/SKILL.md

@@ -86,6 +86,8 @@ For new task-first compositions, prefer:
 This is a component, not a runnable deployment. It owns:
 
 - `environment_id`;
+- exactly one explicit `physics: default|newton` backend and its optional,
+  backend-matching `physics_config`;
 - ordinary environment values such as episode limits and environment count;
 - physical simulation entities under `simulation`; and
 - manager configuration under `env`.
@@ -117,8 +119,10 @@ embodiment:
 
 The original inline Gym format remains supported. When extending an existing
 inline `env.json` or `env.yaml`, preserve that representation unless the user
-asked for component extraction. Never select a component and repeat its owned
-inline fields in the same deployment.
+asked for component extraction. Every inline runnable config declares exactly
+one `physics: default|newton` backend. Never select a component and repeat its
+owned inline fields, including `physics` or `physics_config`, in the same
+deployment. Use separate environment files for backend-specific settings.
 
 ### Optional Python entry point
 
@@ -173,6 +177,7 @@ trainer-routing smoke test when dependencies permit.
 - [ ] Task family, optional subdomain, task name, and runnable IDs are stable
 - [ ] Python and config paths share the same task-first hierarchy
 - [ ] Environment component and runnable deployment ownership are not mixed
+- [ ] Each environment file declares one backend and only matching physics fields
 - [ ] A Python task module exists only when the selected route needs it
 - [ ] No solution-method directory or same-named task package was introduced
 - [ ] Existing components and manager functors were reused where possible

.agents/skills/add-test/SKILL.md

@@ -83,7 +83,7 @@ from embodichain.lab.sim import SimulationManager, SimulationManagerCfg
 
 class TestMySimComponent:
     def setup_method(self):
-        config = SimulationManagerCfg(headless=True, sim_device="cpu")
+        config = SimulationManagerCfg(headless=True, device="cpu")
         self.sim = SimulationManager(config)
         # ... setup ...
 

AGENTS.md

@@ -65,6 +65,12 @@ omit the Python task module. Follow the authoritative
 [configuration and registration contract](agent_context/topics/env-framework/configuration.md)
 and `/add-task-env` before adding a deployment.
 
+Every inline runnable Gym config and reusable physical environment declares
+exactly one `physics: default|newton` backend. An environment component owns
+its optional matching `physics_config`; a deployment cannot repeat or override
+either field. Launcher `--physics` may confirm the file-owned backend but does
+not switch it. Use a separate environment config for each backend.
+
 ## Code and validation
 
 - Run **`black==26.3.1`**, using `black .`, before every commit.

agent_context/MAP.yaml

@@ -8,30 +8,38 @@ defaults:
 topics:
 - id: simulation-system
   title: Simulation System
-  aliases: [simulation system, simulation manager, motion module, sim motion, 运动能力模块, 仿真系统, 仿真管理器]
+  aliases: [simulation system, simulation manager, Newton physics backend, motion module, sim motion, camera attachment, 运动能力模块, 仿真系统, 仿真管理器]
   keywords: [SimulationManager, SimulationManagerCfg, RenderCfg, DLSSCfg, DLSS, frame_time_delta_ms,
-    offscreen_dlss_enabled, explicit physics stepping, arena, DexSim, ArticulationJointKinematics,
-    get_parent_joint_chain, enable_gravity]
+    offscreen_dlss_enabled, explicit physics stepping, arena, DexSim, PhysicsBackendCfg,
+    DefaultPhysicsCfg, NewtonPhysicsCfg, AutoSolverCfg, DexUniSolverCfg, DexUni, runtime control, deformable, particle set,
+    ArticulationJointKinematics, get_parent_joint_chain, asset_physics_mode, joint_drive_props, enable_gravity, quaternion, xyzw]
   paths: [topics/simulation-system/simulation-system.md]
   source_of_truth:
   - embodichain/lab/sim/motion/__init__.py
   - embodichain/lab/sim/sim_manager.py
   - embodichain/lab/sim/__init__.py
-  - embodichain/lab/sim/cfg.py
+  - embodichain/lab/sim/cfg/
+  - embodichain/lab/sim/physics/
+  - embodichain/lab/sim/spawn/
   - embodichain/lab/sim/common.py
+  - embodichain/lab/sim/_startup_summary.py
+  - embodichain/lab/sim/_runtime_controls.py
   - embodichain/lab/sim/objects/articulation.py
+  - embodichain/lab/sim/objects/backends/
+  - embodichain/lab/sim/objects/deformable/
   - embodichain/lab/sim/objects/gizmo.py
   - embodichain/lab/gym/envs/base_env.py
-  watch_paths: [embodichain/lab/sim/sim_manager.py, embodichain/lab/sim/cfg.py, embodichain/lab/sim/objects/,
-    tests/sim/]
+  watch_paths: [embodichain/lab/sim/sim_manager.py, embodichain/lab/sim/cfg/, embodichain/lab/sim/physics/,
+    embodichain/lab/sim/spawn/, embodichain/lab/sim/objects/, tests/sim/]
   related_topics: [env-framework, robot-system, sensor-system, sim-visualization, ik-solvers, motion-planning,
     atomic-actions, rl-learning, configclass-pattern, robot-workspace]
   status: active
 - id: env-framework
   title: Environment Framework
   aliases: [env framework, environment framework, task registration, list task, 环境框架, 任务环境]
   keywords: [BaseEnv, EmbodiedEnv, EnvCfg, register_env, list-task, run-env, target_control_frequency,
-    sim_steps_per_control, step_dt, environment.component, embodiment.component, ControllerAction, EnvProfiler]
+    sim_steps_per_control, step_dt, environment.component, embodiment.component, file-owned physics backend,
+    physics_config, ControllerAction, EnvProfiler, startup_summary, dexsim_startup_info]
   paths: [topics/env-framework/env-framework.md]
   source_of_truth:
   - embodichain/cli/main.py
@@ -41,6 +49,7 @@ topics:
   - embodichain/lab/gym/utils/_component_composition.py
   - embodichain/lab/gym/utils/registration.py
   - embodichain/lab/gym/envs/base_env.py
+  - embodichain/lab/gym/envs/_startup_summary.py
   - embodichain/lab/gym/envs/embodied_env.py
   - embodichain/lab/gym/envs/demo.py
   - embodichain/lab/gym/utils/profiler.py
@@ -91,21 +100,23 @@ topics:
 - id: robot-system
   title: Robot System
   aliases: [robot system, robot config, 机器人配置, 机器人系统]
-  keywords: [RobotCfg, control_parts, build_pk_serial_chain, DexforceW1Cfg, CobotMagicCfg, FrankaPandaCfg,
-    URRobotCfg, DualArmRobotCfg, merge_robot_cfg, JointDrivePropertiesCfg]
+  keywords: [RobotCfg, RobotPresetCfg, control_parts, build_pk_serial_chain, DexforceW1Cfg, CobotMagicCfg,
+    FrankaPandaCfg, URRobotCfg, DualArmRobotCfg, merge_robot_cfg, JointDrivePropertiesCfg,
+    asset_physics_mode, target_mode, mimic joint, quaternion, xyzw]
   paths: [topics/robot-system/robot-system.md]
   source_of_truth:
   - embodichain/lab/sim/objects/robot.py
   - embodichain/lab/sim/robots/
-  - embodichain/lab/sim/cfg.py
-  watch_paths: [embodichain/lab/sim/robots/, embodichain/lab/sim/objects/robot.py, embodichain/lab/sim/cfg.py]
+  - embodichain/lab/sim/cfg/
+  - embodichain/lab/gym/envs/embodied_env.py
+  watch_paths: [embodichain/lab/sim/robots/, embodichain/lab/sim/objects/robot.py, embodichain/lab/sim/cfg/]
   related_topics: [simulation-system, ik-solvers, motion-planning, sensor-system, sim-visualization, robot-workspace]
   status: active
 - id: sensor-system
   title: Sensor System
   aliases: [sensor system, camera attachment, 传感器, 相机挂载]
-  keywords: [CameraCfg, StereoCameraCfg, ContactSensorCfg, SensorCfg, get_sensor_obs, resolve_parent_nodes,
-    scatter_contact_data, tiled image]
+  keywords: [CameraCfg, StereoCameraCfg, ContactSensorCfg, ContactQuery, Newton contact, SensorCfg,
+    get_sensor_obs, resolve_parent_nodes, scatter_contact_data, tiled image, quaternion, xyzw]
   paths: [topics/sensor-system/sensor-system.md]
   source_of_truth:
   - embodichain/lab/sim/sensors/base_sensor.py
@@ -122,14 +133,15 @@ topics:
   title: Simulation Visualization
   aliases: [browser visualization, viser, sim visualization, 仿真可视化]
   keywords: [VisualizationCfg, ViserServerCfg, SceneManifest, visualization, EntityGizmoManipulator, robot_ik_gizmo,
-    GizmoCfg, backpressure, capture_visualization]
+    GizmoCfg, backpressure, capture_visualization, Newton deformable, particle set, render topology, quaternion, xyzw]
   paths: [topics/sim-visualization/sim-visualization.md]
   source_of_truth:
   - embodichain/lab/visualization/protocol.py
   - embodichain/lab/visualization/runtime.py
   - embodichain/lab/visualization/
   - embodichain/lab/sim/sim_manager.py
   - embodichain/lab/sim/objects/gizmo.py
+  - embodichain/lab/sim/objects/deformable/
   - embodichain/lab/scripts/preview_asset.py
   watch_paths: [embodichain/lab/visualization/, embodichain/lab/sim/objects/gizmo.py, embodichain/lab/sim/sim_manager.py,
     tests/visualization/]
@@ -140,7 +152,7 @@ topics:
   aliases: [motion planning, trajectory planning, motion expansion, trajectory expansion, trajectory augmentation, fixed scene trajectory augmentation, 轨迹扩增, 运动规划, 轨迹规划]
   keywords: [BasePlanner, PlanState, PlanResult, MotionGenerator, ToppraPlanner, CuroboPlanner, NeuralPlanner,
     expansion, GenerationSession, TrajectoryAugmentationCfg, CandidateTrajectoryBatch,
-    collision world, compute trajectory, trajectory resampling, trajectory warping]
+    collision world, compute trajectory, trajectory resampling, trajectory warping, quaternion, xyzw, wxyz]
   paths: [topics/motion-planning/motion-planning.md]
   source_of_truth:
   - embodichain/lab/sim/motion/planners/base_planner.py
@@ -163,7 +175,8 @@ topics:
   title: RL Learning Pipeline
   aliases: [rl learning, rl config, reinforcement learning, 强化学习, 训练配置]
   keywords: [train-rl, Trainer, trainer.gym_config, learning_env, RolloutKind, DifferentiableTrainer,
-    PPO, GRPO, APG, SyncCollector]
+    PPO, GRPO, APG, SyncCollector, ScheduledDifferentiableVecEnv, DifferentiableRolloutSpec,
+    complete rollout, full horizon, gradient accumulation, action adjoint, observation normalization]
   paths: [topics/rl-learning/rl-learning.md]
   source_of_truth:
   - embodichain/learning/rl/train.py
@@ -172,12 +185,28 @@ topics:
   - embodichain/learning/rl/utils/trainer.py
   - embodichain/learning/rl/differentiable_trainer.py
   - embodichain/learning/rl/evaluation.py
+  - embodichain/learning/rl/gradients.py
+  - embodichain/learning/rl/normalization.py
   - embodichain/learning/rl/utils/config.py
   - embodichain/learning/rl/algo/
   - embodichain_tasks/configs/tasks/
   watch_paths: [embodichain/learning/rl/, embodichain_tasks/configs/tasks/, tests/learning/]
   related_topics: [simulation-system, env-framework, manager-functor, configclass-pattern]
   status: active
+- id: differentiable-env
+  title: Differentiable Environment (APG)
+  aliases: [differentiable env, DifferentiableEnv, apg, analytic policy gradient, differentiable rl,
+    Warp tape autograd, NewtonStepFunc, 可微环境]
+  keywords: [differentiable, gradient, apg, autograd, warp tape, requires_grad, semi_implicit,
+    DifferentiableEnv, NewtonStepFunc, quaternion, xyzw]
+  paths: [topics/differentiable-env/differentiable-env.md]
+  source_of_truth:
+  - embodichain/lab/gym/envs/differentiable_env.py
+  - embodichain/lab/sim/cfg/simulation.py
+  - embodichain/lab/sim/diff/
+  - embodichain_tasks/embodichain_tasks/special/franka_reach_apg.py
+  related_topics: [env-framework, rl-learning]
+  status: active
 - id: configclass-pattern
   title: Configclass Pattern
   aliases: [configclass pattern, 配置类]
@@ -227,7 +256,7 @@ topics:
   title: Embodied Task Program
   aliases: [task program, semantic call, 任务程序, 语义调用]
   keywords: [TaskProgramCfg, program.yaml, integration.yaml, scene_binding, SceneManifest, SkillPolicyPreset,
-    EffectAssurance, CompiledTaskProgram, TaskProgramDemoBridge, execution_policy]
+    EffectAssurance, CompiledTaskProgram, TaskProgramDemoBridge, execution_policy, SemanticPose, quaternion_xyzw]
   paths: [topics/task-programs/task-programs.md]
   source_of_truth:
   - embodichain/lab/task_program/

agent_context/topics/atomic-actions/atomic-actions.md

@@ -71,6 +71,12 @@ a physical effect.
 - [Planning and execution](execution.md): invocation resolution, control grid, row-local recovery and verification.
 - [Articulation geometry](articulation-geometry.md): topology/mesh ownership and directional affordance contracts.
 
+The `scripts/tutorials/atomic_action/place.py` tutorial configures matching
+Newton contact stiffness and damping on the cube and gripper collision links
+before `SimulationManager.prepare()`. MuJoCo-Warp's default response is too
+compliant for this force-closure replay and otherwise lets the cube slip near
+its pickup pose instead of reaching the place target.
+
 ## Semantic integration boundary
 
 `semantics` contains:

agent_context/topics/differentiable-env/differentiable-env.md

@@ -0,0 +1,97 @@
+# differentiable-env
+
+> Topic: Newton-backed kinematic environments for analytic policy gradient
+> (APG) through the Warp-tape ↔ PyTorch-autograd bridge.
+
+## Public entry point
+
+Use
+`embodichain.lab.gym.envs.differentiable_env.DifferentiableEnv`.
+It inherits `EmbodiedEnv`, preserves its scene lifecycle, and replaces the
+normal physics step with a task-defined kinematics callback recorded on a
+Warp tape.
+
+The resolution path is:
+
+    DifferentiableEnv.step(action)
+      → NewtonStepFunc.apply(action, sim_state)
+      → _apply_action_kernel(action_wp, tape)
+      → _make_kinematic_step_fn()()
+      → _read_outputs(final_state)
+      → Warp tape backward → action.grad
+
+## Invariants
+
+- The configured physics backend must be `NewtonPhysicsCfg`.
+- `NewtonPhysicsCfg.requires_grad` must be `True`.
+- Default physics and other backends fail during `DifferentiableEnv`
+  construction.
+- `DifferentiableEnv` always supplies a named kinematics callback; its bridge
+  contract has no dynamics mode, solver substeps, or control buffer.
+- The environment never invokes the configured Newton solver or collision
+  pipeline.
+- Newton gradient configuration still selects the semi-implicit solver, but
+  `DifferentiableEnv` never advances it.
+- Gradient mode disables Newton CUDA graph capture.
+
+## Subclass contract
+
+Task authors implement three hooks:
+
+- `_apply_action_kernel(action_wp, tape)` launches Warp work that maps the
+  PyTorch action bridge array into task-owned kinematic state.
+- `_make_kinematic_step_fn()` returns a zero-argument callback such as
+  `newton.eval_fk(...)`. The callback returns the state consumed by the output
+  hook.
+- `_read_outputs(final_state)` returns `obs`, `reward`, `terminated`, and
+  `truncated`, plus `_order` and `_grad_track` metadata used by
+  `NewtonStepFunc`.
+
+There is no public `_apply_dynamics_action_kernel` or
+`differentiable_step_mode` extension point. Differentiable dynamics are a
+future feature, not a `DifferentiableEnv` capability.
+
+## Autograd and reset rules
+
+Action, kinematics, and gradient-producing output kernels must execute while
+the Warp tape is open. Each tracked output names its backing Warp array in
+`_grad_track`; an output mapped to `None` does not seed Warp backward.
+
+A grad-tracked terminal step returns the terminal observation and exposes
+`requires_reset_after_backward` plus `deferred_reset_ids` in `info`. Reset
+those rows only after backward. A no-grad terminal step resets them
+synchronously.
+
+## Franka reference task
+
+`embodichain_tasks.special.franka_reach_apg.FrankaReachApgEnv` is the canonical
+example. Its path is:
+
+    action → new_joint_q → newton.eval_fk → body_q → reward kernel → action.grad
+
+The task snapshots live joint positions before opening the tape and writes the
+detached next joint state back after the bridge returns. It does not exercise
+Newton dynamics.
+
+## Dynamics boundary
+
+The public differentiable package exposes no solver stepper, trajectory, or
+gradient-rollout API. Add those capabilities as a separate future design when
+Newton dynamics are ready for end-to-end validation.
+
+## Source of truth
+
+- `embodichain/lab/gym/envs/differentiable_env.py`
+- `embodichain/lab/sim/cfg/simulation.py`
+- `embodichain/lab/sim/diff/`
+- `embodichain_tasks/embodichain_tasks/special/franka_reach_apg.py`
+
+## Focused validation
+
+- `tests/gym/envs/test_differentiable_embodied_env.py`
+- `tests/sim/test_sim_manager_cfg.py`
+
+## Related topics
+
+- env-framework
+- rl-learning