[yuecideng]

Description

Add an independently packaged simple Newton solver and a two-environment example using EmbodiChain's SimulationManager and the public DexSim Scene API. The provider models independent spring-loaded prismatic sliders, with one transition implementation shared by native stepping and differentiable functional rollout.

The example exercises entry-point discovery, native/functional numerical parity, effort and parameter gradients, isolated trajectory storage, detached Scene publication, and selective functional/native reset. Newton initialization/reset now queries the finalized solver's declared control channels through Scene.dynamics_capabilities(): supported position hold targets and mimic initialization are preserved, while effort-only solvers avoid unsupported commands and retain native reset bookkeeping. Named solver configuration forwards to the SDK while preserving built-in defaults.

The supported model has fixed ancestors and independent prismatic leaves, zero gravity, and no moving-body collisions, mimic constraints, friction or position/velocity drives. Unsupported models fail explicitly. This example provides neither general robot/contact dynamics nor CUDA Graph support. Initial Cartesian losses require body poses initialized through a differentiable FK graph consistent with initial joint coordinates; the README explains that boundary.

Dependency: the optional solver requires the FunctionalDynamics service revision of DexSim MR !1483, including Scene.dynamics_capabilities() at current candidate 3e1fd3e40b086784c0b9cd96afa451f801b99bf3. The released SDK pin remains unchanged. Ordinary installations and API documentation imports work with that pin; selecting the solver requires a compatible integration SDK and otherwise raises a focused error. The README documents installation and feature acceptance. This PR is independent of NeRD PR #822 and adds no training framework or simulation registry.

No linked issue; implements the requested standalone solver demonstration.

Type of change

• New feature: independently discovered Newton solver and public Scene example.
• Bug fix: effort-only Newton reset compatibility.
• Documentation update: usage, supported models, dependency requirements and API reference.

Screenshots

N/A: bounded headless numerical example. The current matched installed wheels passed CPU/CUDA qualification with the output below:

published joint position: [0.0208730716, 0.0313096046]
partial reset:            [0.0,          0.0313096046]
effort gradient:          [0.0001204819, 0.0005074868]
force_scale gradient:     0.0035268480

Validation

Candidate: 3faf27d44adc4a910703249d34e9d8a681a141e7, based on main at f063f80bb9d546eaca7998b2b2a21f1d29d78513.

• Current integration checks passed: 67 checks in 14.21 s against current SDK Python sources plus the unchanged, previously validated a72350d27 native library; W1 Newton additionally passed in 18.87 s. Covers CPU/CUDA numerical expectations, model/control boundaries, both gradient settings and both reset owners, ordinary multi-articulation nonzero initial targets, and SDK capability-query compatibility. SDK extension tests: 54 passed. This is source-integration evidence, not a replacement-wheel claim.

• Released-SDK compatibility passed: the CI W1 mimic-target failure reproduced locally (27.96 s). A controlled comparison restoring only the previous reset method passed (15.35 s), proving that omitted initialization targets caused the regression. Initialization uses clear_dynamics=False with no subsequent coordinated clear. The new ordinary multi-articulation initial-hold case also failed before correction; after correction W1, initial-hold and helper checks passed 20 cases in 22.99 s using SDK 0.5.1rc1 build56c1241.

• Current installed-package acceptance passed: exact EmbodiChain wheel SHA256 6ce3ef53f060130b2e13f66b775cedb9f5b752c00a2c953b59dd3d1be1025a6f and actual SDK job305397 wheel SHA256 abdc73c99b4f3f22f522418f3ae8548614d3c64c07a18f5a8b6d0ebfd33570b8. Verified SDK build ID 3e1fd3e40 and packaged/installed source bytes. Packaged CPU and CUDA demos passed outside the checkout with PYTHONPATH unset. 68 focused checks passed against the installed matching SDK in 35.31 s, including the previously failed W1 initialization case, ordinary initial hold targets, and effort-only reset owners/modes. Runtime: Python 3.10.18, Torch 2.7.1+cu128, Newton 1.7.0, Warp 1.17.0. Existing upstream deprecation/native teardown warnings remain visible.

• API/documentation checks passed: 2806/2806 public exports documented; 9 API-checker tests passed. Real released-SDK autosummary with the type-hints extension passed with -W, while actual provider construction correctly rejected the incompatible SDK. The current 3faf27d CI Sphinx build succeeded with 803 warnings, unchanged from 9a7bbaa after the provider documentation fix. Comparing normalized warning/error signatures found no additions. Existing documentation diagnostics remain, so this is not a warning-free build.

• Formatting passed: black . with Black 26.3.1 before each commit, with no unrelated formatting changes.

• Current GitHub CI: all selected jobs and the final Test gate passed for exact 3faf27d44. The downloaded test plan matches all 15 files in the complete base-to-head diff. Final results: fast 9403 passed / 2 skipped, GPU 400 passed / 3 skipped, simulation 376 passed / 4 skipped. The distributed lane selected no cases under its existing marker expression; no distributed-lane coverage is claimed. The tag-only release job was not selected. Previous run #39842488508 passed fast (9399 / 2 skipped), GPU (400 / 3 skipped), documentation and build; simulation reported 374 passed / 4 skipped / 1 failed (the reproduced initialization regression above). No failure was waived and the correction keeps the original assertions.

• Current SDK CI: passed for exact 3e1fd3e40, including root/module evidence verification and the declared Python 3.10/3.11/3.12/documentation profile. Both final receipts match the tested source and target; formatting preflight and explicit worker admission also passed.

The released SDK lacks this optional interface, so ordinary CI explicitly skips the provider test module. That skip is not feature validation; the matching installed SDK checks and packaged demos above establish the optional feature acceptance, separately from the now-passing complete selected CI matrix. Existing native entity-balance warnings remain visible in demo teardown logs.

The test necessity review retained independent numerical oracles, actual metadata discovery, explicit rejection boundaries and both reset owners. Regressions were reproduced before fixes; existing example/static checks were reused, with no new tutorial-import tests or check exemptions. Independent specialist reviews covered the SDK integration and downstream solver; incremental architecture/API and physics/lifecycle reviews found no unresolved new defect. The pre-existing ordering of a later dynamics clear and mimic target handling is unchanged; this PR does not claim new validation of every mimic relation after all reset paths.

Context decision: updated the owning simulation physics guidance for named providers and publication timing. Robot context remains accurate because Robot inherits articulation reset and manager ownership is unchanged.

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 updated, if applicable. The integration SDK is not released yet; its requirement and installation procedure are explicit above and in the example README.

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The reviewed changes appear safe to merge; no new blocking issue was found.

Summary

Adds the optional simple Newton solver and a two-environment example using the public Scene API.

• Newton users can choose a spring-slider solver by name.
• Scene rollouts can publish results without changing their saved trajectory.
• Effort-only solvers reset joints without position targets.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Config[Named solver configuration] --> Provider[SimpleSolverProvider]
  Provider --> Native[Native stepping]
  Provider --> Functional[Functional rollout]
  Native --> Transition[Shared spring-slider transition]
  Functional --> Transition
  Transition --> State[Next physical state]
  State --> Publish[Optional detached Scene publication]

Loading

_{Reviews (4) · Last reviewed commit: "fix(sim): Preserve supported Newton init..." · Reviewed by Greptile}