Add Kamino solver tutorial

[AntoineRichard]

Description

Adds a dedicated Newton experimental tutorial for using the Kamino solver. The page explains that Kamino is selected through a Newton physics solver preset, shows the task changes needed to add a kamino preset, lists compatibility checks for assets, resets, sensors, and renderers, and documents the Kamino-specific solver parameters by category.

This addresses Kellys follow-up request on #5457 for a tutorial describing what needs to change to work with Kamino and for descriptions of Kamino-specific solver parameters.

Fixes # (issue)

Type of change

• Documentation update

Screenshots

Not applicable. Documentation-only RST 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 extensions config/extension.toml file
• I have added my name to the CONTRIBUTORS.md or my name already exists there

Notes:

• Ran ./isaaclab.sh -f successfully.
• Verified the literalinclude target and referenced labels locally.
• ./isaaclab.sh -d could not start in this checkout because there is no virtual environment and system Python is PEP 668 protected, so pip refused to install docs requirements. Because Sphinx did not run, the warning checklist item is intentionally left unchecked.
• No tests or changelog fragment were added because this is a documentation-only follow-up under docs/source; the current repository guidance uses source/<pkg>/changelog.d fragments only for touched source packages.

[isaaclab-review-bot]

🤖 Isaac Lab Review Bot

Summary

This PR adds documentation for using the Kamino solver within the Newton physics integration. It introduces a new tutorial page (using-kamino.rst) explaining how to enable Kamino through task physics presets, documents solver parameters, and provides a tuning workflow. The changes are purely documentation additions with no code modifications.

Architecture Impact

Self-contained. This is a documentation-only PR that adds a new RST file and updates the toctree/cross-references in existing documentation. No code paths are affected.

Implementation Verdict

Minor fixes needed

Test Coverage

Not applicable for documentation-only changes. The author notes they verified the literalinclude target and referenced labels locally, which is the appropriate validation for RST files.

CI Status

No CI checks available yet. For documentation PRs, the key validation would be that Sphinx builds successfully without warnings, which the author could not verify due to PEP 668 environment restrictions (noted in PR description).

Findings

🟡 Warning: using-kamino.rst:45-48 — Potential broken literalinclude reference
The literalinclude directive references:

.. literalinclude:: ../../../../source/isaaclab_tasks/isaaclab_tasks/direct/cartpole/cartpole_env_cfg.py
    :start-at: class CartpolePhysicsCfg
    :end-before: class CartpoleEnvCfg

While the author claims to have verified this locally, I cannot validate that class CartpolePhysicsCfg actually exists in the target file with a kamino preset at lines 18-37 as the emphasize-lines suggests. If this class or the kamino preset doesn't exist yet, the docs build will fail or show incorrect content. Consider adding a note in the PR description confirming the target file has been updated with the Kamino preset, or ensure this PR is merged after/with the code PR that adds it.

🔵 Improvement: using-kamino.rst:7-9 — Consider adding version/availability note
The documentation references :class:~isaaclab_newton.physics.NewtonCfg and `:class:`~isaaclab_newton.physics.KaminoSolverCfg without indicating which Isaac Lab version introduced these classes. Since Kamino is described as "beta," adding a .. versionadded:: directive would help users understand feature availability.

🔵 Improvement: using-kamino.rst:31-34 — Hardcoded task list may become stale
The list of tasks with Kamino presets (Isaac-Cartpole-Direct-v0, Isaac-Ant-Direct-v0, etc.) is hardcoded. Consider either:

• Adding a note that this list may not be exhaustive
• Pointing users to a programmatic way to discover which tasks support Kamino (e.g., grep for kamino in task configs)

🔵 Improvement: using-kamino.rst:110-118 — Missing default values in parameter tables
The parameter tables document descriptions but not default values. For tuning purposes, knowing defaults (e.g., what "euler" vs "moreau" means for integrator, or the default padmm_max_iterations) would significantly help users understand what the validated presets actually set. Consider adding a "Default" column or mentioning defaults inline.

🔵 Improvement: using-kamino.rst:22-28 — Command syntax may be confusing
The commands show --viz newton presets=newton where --viz newton is a flag and presets=newton appears to be a Hydra override. The lack of -- or other separator between argparse flags and Hydra overrides may confuse users. Consider adding a brief note clarifying this syntax, or using the more explicit +presets=newton if that's the correct Hydra syntax.

🔵 Improvement: solver-transitioning.rst:8 — Cross-reference ordering
The updated line reads:

separate backend; see :ref:`hydra-backend-solver-presets` and :ref:`newton-using-kamino`.

This is fine, but consider whether the Kamino reference should come first since it's more specific to the sentence's context (about Kamino being a preset rather than a backend).

[greptile-apps]

Greptile Summary

This PR adds a new using-kamino.rst tutorial page to the Newton physics integration experimental docs, wires it into the section index.rst toctree, and adds a cross-reference to it from solver-transitioning.rst. The tutorial covers how to select the Kamino solver via a physics preset, task/asset compatibility requirements, a reference table for all KaminoSolverCfg parameters, and a step-by-step tuning workflow.

Confidence Score: 4/5

Safe to merge; only P2 documentation style issues found, no runtime or correctness impact.

All findings are P2 style issues around the literalinclude snippet boundaries. Cross-references and file paths resolve correctly.

docs/source/experimental-features/newton-physics-integration/using-kamino.rst — review the literalinclude boundaries around the import and trailing decorator.

Important Files Changed

Filename	Overview
docs/source/experimental-features/newton-physics-integration/using-kamino.rst	New 230-line tutorial for the Kamino solver; cross-references and label are valid, but the literalinclude snippet omits the required import and ends with a trailing decorator from the next class.
docs/source/experimental-features/newton-physics-integration/index.rst	Adds using-kamino to the toctree; straightforward one-line addition with no issues.
docs/source/experimental-features/newton-physics-integration/solver-transitioning.rst	Adds a cross-reference to newton-using-kamino alongside the existing hydra-backend-solver-presets ref; both labels resolve correctly.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User: presets=kamino] --> B{Task defines kamino preset?}
    B -- No --> C[Kamino not enabled]
    B -- Yes --> D[CartpolePhysicsCfg.kamino\nNewtonCfg + KaminoSolverCfg]
    D --> E[Newton model built from USD assets]
    E --> F{Newton model OK?}
    F -- No --> G[Fix asset/task config first\npresets=newton must pass]
    F -- Yes --> H[Kamino solver selected\nP-ADMM + FK-reset path]
    H --> I[Tune: num_substeps\npadmm_max_iterations\nP-ADMM tolerances]
    I --> J[Stable task ready for training]

Loading

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

[greptile-apps]

Literalinclude snippet omits the import statement

The literalinclude directive uses :start-at: class CartpolePhysicsCfg, which begins at line 24 of cartpole_env_cfg.py. This skips the import block at the top of the file, so the rendered snippet will not show:

from isaaclab_newton.physics import KaminoSolverCfg, MJWarpSolverCfg, NewtonCfg

However, the very next paragraph explicitly lists "Import KaminoSolverCfg" as one of the important pieces. Readers copying from the snippet won't see where to put that import. Consider adding a separate short code block showing the import, or extending the range to include the import lines.

[greptile-apps]

Snippet ends with a dangling decorator from the next class

:end-before: class CartpoleEnvCfg stops just before class CartpoleEnvCfg(DirectRLEnvCfg): (file line 66), but line 65 is @configclass — the decorator for that next class. The rendered snippet will close with a bare @configclass on its own, which may confuse readers into thinking it belongs to CartpolePhysicsCfg. Consider using :end-before: @configclass instead, or specify an explicit :lines: range.

[isaaclab-review-bot]

🤖 Isaac Lab Review Bot

Summary

This follow-up addresses several concerns from the previous review. The author has added default values inline in all parameter table descriptions, which resolves the most significant documentation usability issue.

Previous Findings Status

• ✅ Default values in parameter tables — Addressed. All parameters now include inline defaults (e.g., Default: ``"euler"```, Default: ``200```, etc.).
• ⚠️ literalinclude reference — Partially addressed. The :end-at: marker was changed from :end-before: class CartpoleEnvCfg to :end-at: ovphysx: OvPhysxCfg = OvPhysxCfg(), which is more specific but still depends on the target file having the CartpolePhysicsCfg class with the Kamino preset.
• Remaining items (version note, hardcoded task list, command syntax clarification, cross-reference ordering) were minor improvements and not addressed, which is acceptable.

Implementation Verdict

Ship it

New Findings

No new issues introduced. The documentation is comprehensive, the parameter defaults are now well-documented, and the tuning workflow provides clear guidance for users adopting Kamino.

[AntoineRichard]

@kellyguo11 Tutorial for Kamino.

[camevor]

Looks good, thanks!

[camevor]

Question: Could we simplify this, i.e. to automate most of the Kamino-specific adaptions? If yes, the doc could mention this.

[camevor]

This sounds as if Kamino were different from Newton

[camevor]

I recommend looser tolerances for these, e.g. closer to 1e-4, unless accuracy is particularly important.

[AntoineRichard]

@kellyguo11 after chatting with @camevor it's quite we need to rename our current newton preset to mjwarp.

[isaaclab-review-bot]

🤖 Isaac Lab Review Bot

Summary

This is a documentation-only PR adding a Kamino solver tutorial. The previous review's main concern (missing default values in parameter tables) was addressed in an earlier commit. No new changes since that fix.

Implementation Verdict

Ship it

Findings

No new issues. The documentation is comprehensive, well-structured, and provides clear guidance for users adopting the Kamino solver. The inline defaults in parameter tables, cross-references to related docs, and step-by-step tuning workflow are all solid.

[isaaclab-review-bot]

🤖 Isaac Lab Review Bot

Summary

Follow-up review on documentation-only PR. No new commits since the previous review — the diff and file contents are identical to the last review cycle.

Implementation Verdict

Ship it

Findings

Previous concern about missing default values was already addressed. No new changes to review. The documentation is comprehensive and ready to merge.

[isaaclab-review-bot]

🤖 Isaac Lab Review Bot

Summary

No new commits since the previous review — the diff and file contents remain identical. The documentation for the Kamino solver tutorial is comprehensive, well-structured, and ready to merge.

Implementation Verdict

Ship it

Findings

No new issues. Previous review already approved this documentation-only change. The literalinclude path and cross-references have been verified locally by the author.