> This page is for version Release 3.0 (default).
> For other versions, use one of these documentation indexes:
> - Release 3.0 (default): https://docs.nvidia.com/isaaclab/3.0/llms.txt
> - Release 2.3: https://docs.nvidia.com/isaaclab/2.3/llms.txt
> - Release 2.2: https://docs.nvidia.com/isaaclab/2.2/llms.txt
> - Release 2.1: https://docs.nvidia.com/isaaclab/2.1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/isaaclab/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/isaaclab/_mcp/server.

# Tune Kamino

Kamino is a beta Newton solver selected through a task-exposed
`newton_kamino` preset. This guide isolates and measures a reproducible
problem before changing its solver settings. The generated API documentation
for `~isaaclab_newton.physics.KaminoPADMMSolverCfg` and
`~isaaclab_newton.physics.KaminoDVISolverCfg` remains authoritative for
current fields and defaults.

## Prerequisites

Read [Backends and Presets](/source/concepts/backends_and_presets) for preset semantics and
[Backend and Solver Presets](/source/features/hydra#backend-and-solver-presets) for task integration. Prepare the asset for
Newton with [/source/how-to/prepare_asset_for_newton](/source/how-to/prepare_asset_for_newton). Confirm that the
task exposes `newton_kamino` through its `--help` output or the
[environment catalog ](https://isaac-sim.github.io/IsaacLab/release/3.0.0/source/setup/environments.html); do not infer
Kamino support from another Newton preset.

## Start from an explicit baseline

Run one small visual smoke test before training or benchmarking:

```bash
uv run python scripts/environments/zero_agent.py --task Isaac-Cartpole-Direct --num_envs 4 --viz newton_gl physics=newton_kamino
```

Then fix the initial state, seed, action sequence, and reset distribution. For
that reproduction, record penetration, slip, energy, a task metric, a
convergence diagnostic, and runtime. Change one decision at a time so every
candidate can be compared with the same baseline.

## Choose PADMM or DVI

Choose PADMM first for contact-heavy tasks. DVI is a candidate for mechanisms
with relatively few active contacts. If a DVI task needs an explicit
`~isaaclab_newton.physics.KaminoDynamicsCfg` override, disable
preconditioning; otherwise leave the dynamics override unset so Newton selects
the compatible defaults.

## Validate reset and state consistency

Validate root and joint state writes through the Isaac Lab asset APIs before
tuning the solver. Kamino's maximal-coordinate body poses must agree with the
reduced joint state after every reset. Investigate body-pose and joint-state
disagreement, including custom reset code and reset overlaps, before changing
convergence or stabilization settings.

## Choose and size collision handling

Compare Kamino's internal detector with Newton's collision pipeline using the
same full reset and contact distribution. `use_collision_detector` on the
Kamino solver selects the internal path, which
`~isaaclab_newton.physics.KaminoCollisionDetectorCfg` configures; when
it is disabled, `~isaaclab_newton.physics.NewtonCollisionPipelineCfg`
configures Newton's path. Size the active path only from observed capacity
failures, missing contacts, or warnings, and use those generated APIs for the
exact controls. Collision capacity cannot correct invalid geometry or reset
penetration.

## Tune timestep and substeps

Hold the policy period and fixed reproduction constant. Only after the model
and reset are valid, compare a smaller simulation timestep or more
`isaaclab_newton.physics.NewtonCfg.num_substeps` for the same policy
period. Recheck the recorded physical, convergence, task, and runtime metrics;
do not change policy timing merely to hide an unstable simulation step.

## Tune convergence and stabilization

Tune `~isaaclab_newton.physics.KaminoPADMMCfg` iteration and residual
controls only for a reproducible PADMM convergence failure. For DVI, tune
`~isaaclab_newton.physics.KaminoDVICfg` alternating iterations and
tolerance only for the same kind of evidence. Change
`~isaaclab_newton.physics.KaminoConstraintsCfg` stabilization controls
only after collision and reset validation. More solver work cannot repair
inconsistent state, invalid collision geometry, or reset overlap.

## Optimize only after validation

Disable diagnostics before performance measurements. Retain only changes that
improve the recorded metrics, and separately measure sparse Jacobian, CUDA
graph, collision, substep, and iteration costs when each applies to the
selected solver and workload. For the parallel workflow, see [solver_tuning_mjwarp](/source/how-to/solver_tuning_mjwarp);
it does not replace Kamino-specific validation or tuning.

The diagnose-first order is: validate the baseline, reset state, and collision
path; compare timestep and substeps; investigate convergence and stabilization;
then optimize measured costs.