Document Kamino solver presets

[AntoineRichard]

Description

Document Kamino solver selection through the existing Hydra preset system.

• Adds a "Backend and Solver Presets" section that explains how newton and kamino presets both use NewtonCfg but choose different solver configs.
• Notes that Kamino is experimental and depends on assets being structured for Kamino.
• Adds a brief mention from the Newton solver-transitioning page and updates the MuJoCo-Warp example to current public config APIs.

Fixes: N/A

Type of change

• Documentation update

Screenshots

N/A. Documentation-only change.

Checklist

• I have read and understood the contribution guidelines
• I have run the pre-commit checks with ./isaaclab.sh --format
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• I have updated the changelog and the corresponding version in the extension config file
• I have added my name to the CONTRIBUTORS.md or my name already exists there

[isaaclab-review-bot]

🤖 Isaac Lab Review Bot

Summary

This PR adds documentation for the Kamino solver preset system, explaining how users can select between MuJoCo-Warp and Kamino solvers through the existing Hydra preset mechanism. The changes also update outdated API references in the solver-transitioning documentation to reflect current public APIs. This is a documentation-only change with no code modifications.

Architecture Impact

Self-contained. This PR only modifies .rst documentation files and does not affect any runtime code paths.

Implementation Verdict

Ship it — with one minor documentation accuracy concern to verify.

Test Coverage

N/A — Documentation-only change. No tests required or expected.

CI Status

No CI checks available yet. Documentation builds should be verified.

Findings

🔵 Improvement: docs/source/features/hydra.rst:304-306 — Verify command line path accuracy

The example shows env.sim.physics=kamino but earlier in the same file (line 263), the CartpolePhysicsCfg is shown as a field directly under the environment config, not under env.sim. The correct path depends on how the actual task configs are structured. If physics is defined as env.backend or env.physics rather than env.sim.physics, this example could confuse users.

# Current
python train.py --task=Isaac-Cartpole-v0 env.sim.physics=kamino

# Verify this matches actual task config structure

🔵 Improvement: docs/source/features/hydra.rst:280-282 — Clarify "currently beta" vs "experimental"

The documentation uses both "currently beta" (line 281) and "experimental" (line 288 note). Consider using consistent terminology throughout both files. The solver-transitioning.rst uses "experimental" and "beta support" in close proximity as well (lines 4, 8). Pick one term for consistency.

🔵 Improvement: docs/source/experimental-features/newton-physics-integration/solver-transitioning.rst:5-6 — Cross-reference could be more discoverable

The cross-reference to :ref:hydra-backend-solver-presets`` is good, but users navigating from the experimental-features section might not realize the main Kamino documentation lives in the Hydra features page. Consider adding a brief sentence like "For full configuration examples and usage, see..." to make the primary documentation location clearer.

🔵 Improvement: docs/source/features/hydra.rst:268-272 — KaminoSolverCfg parameters not explained

The KaminoSolverCfg parameters (integrator, use_collision_detector, sparse_jacobian, padmm_max_iterations) are shown in the example but not explained anywhere. Unlike the MuJoCo-Warp parameters documented in solver-transitioning.rst, Kamino's parameters have no accompanying explanations. Users won't know what "moreau" integrator means or when to tune padmm_max_iterations.

Consider adding brief inline comments or a note pointing to where users can learn about these parameters:

solver_cfg=KaminoSolverCfg(
    integrator="moreau",  # Integration method
    use_collision_detector=True,
    sparse_jacobian=True,  # Performance optimization
    padmm_max_iterations=100,  # Solver convergence iterations
),

🔵 Improvement: docs/source/experimental-features/newton-physics-integration/solver-transitioning.rst:26-27 — Import statement includes unused SimulationCfg

The example imports SimulationCfg from isaaclab.sim, which is correct, but the full file context shows line 46 uses it. This is fine, but verify the import path isaaclab.sim.SimulationCfg is the canonical public API (vs. the old private _impl paths that were removed).

---

Overall, this is clean documentation work that correctly updates deprecated API paths and provides clear explanations of the preset system for solver selection. The changes are accurate and well-structured.

[greptile-apps]

Greptile Summary

This documentation-only PR adds a "Backend and Solver Presets" section to hydra.rst explaining how the Kamino solver is selected as a preset within the Newton backend (not as a separate backend), and updates solver-transitioning.rst to reference this new section, modernise the import paths to the public API, and rename nefc_per_env to njmax/nconmax to match the current API. All code snippets and cross-references look correct.

Confidence Score: 4/5

Safe to merge; documentation-only change with no runtime impact

All findings are P2 style suggestions. The code snippets reference correct public APIs, cross-references are valid, and the new Kamino section is accurate. One minor duplication of the experimental note across two files, but it does not cause any functional concern.

No files require special attention

Important Files Changed

Filename	Overview
docs/source/experimental-features/newton-physics-integration/solver-transitioning.rst	Updates imports to public API, renames nefc_per_env→njmax/nconmax, adds cross-reference to Kamino preset section, and inserts a near-duplicate experimental note also present in hydra.rst
docs/source/features/hydra.rst	Adds a well-structured "Backend and Solver Presets" section documenting Kamino as a solver preset within the Newton backend, with CLI examples and a clear experimental caveat

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    CLI[CLI argument\ne.g. presets=kamino] --> PR[Preset resolver]
    PR -->|preset name = physx| PhysxCfg[PhysxCfg\nPhysX backend]
    PR -->|preset name = newton| NewtonMJWarp[NewtonCfg\nsolver=MJWarpSolverCfg]
    PR -->|preset name = kamino| NewtonKamino[NewtonCfg\nsolver=KaminoSolverCfg]
    PR -->|no match / default| Default[default field\nPhysxCfg]
    NewtonMJWarp --> Newton[Newton backend]
    NewtonKamino --> Newton
    PhysxCfg --> PhysX[PhysX backend]
    Default --> PhysX

Loading

_{Reviews (1): Last reviewed commit: "Document Kamino solver presets" | Re-trigger Greptile}

[greptile-apps]

Duplicated experimental note

The Kamino experimental note on lines 10–14 is nearly identical to the one added in hydra.rst (lines 292–297). Since solver-transitioning.rst already cross-references the Hydra presets page via :ref:\hydra-backend-solver-presets`, readers will encounter the same caveat twice in close succession. Consider removing the inline note here and relying solely on the one in hydra.rst`, or replacing it with a forward-reference phrase (e.g. "see the note in the linked section") to avoid the duplication.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

"Beta" vs "experimental" terminology inconsistency

The prose on line 290 describes Kamino support as "currently beta", while both the .. note:: block immediately below and the corresponding note in solver-transitioning.rst use the term "experimental". These two terms carry different connotations — "beta" implies a more mature, near-release state; "experimental" implies early/unstable. Aligning them to a single term avoids reader confusion about the actual stability level.

[greptile-apps]

Hardcoded task list will go stale

The enumerated set of tasks that support the kamino preset (Isaac-Cartpole-Direct-v0, Isaac-Ant-Direct-v0, Isaac-Cartpole-v0, Isaac-Ant-v0) is embedded directly in the docs. As tasks are added or removed, this list will silently diverge from reality. Consider pointing to a discoverable location (a registry call, a grep pattern, or a separate changelog) or adding a comment reminding maintainers to keep this list in sync.

[greptile-apps]

Kamino-specific parameters have no inline explanation

The KaminoSolverCfg snippet introduces four parameters (integrator, use_collision_detector, sparse_jacobian, padmm_max_iterations) without any descriptive bullet list, while the MJWarp parameters (njmax, nconmax, ls_iterations, etc.) are all explained in detail nearby in solver-transitioning.rst. A short explanation or cross-reference to API docs for these Kamino parameters would help users tune the solver without hunting through separate references.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[kellyguo11]

could we have another tutorial to describe what changes are needed to work with kamino? and maybe some descriptions of the kamino-specific solver parameters

[AntoineRichard]

Yes, PR here: #5483