.. Copyright (c) 2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md).
.. All rights reserved.
..
.. SPDX-License-Identifier: BSD-3-Clause

.. _physx-solver-tuning:

Tune the PhysX Solver
=====================

Use this guide after the PhysX backend can construct the task and its assets.
Before changing solver settings, reproduce one issue with a fixed initial
state, seed, and action sequence. Record the failure, contact behavior, and
task metric for that reproduction, then change one scene-level setting at a
time. The generated API documentation for
:class:`~isaaclab_physx.physics.PhysxCfg` remains authoritative for exact
fields and current defaults.

Start from an explicit baseline
-------------------------------

Make the scene-level PhysX choices visible in the task configuration first.
This baseline is a representative starting point for a contact-rich task, not a
universal recommendation:

.. code-block:: python

    from isaaclab.sim import SimulationCfg
    from isaaclab_physx.physics import PhysxCfg

    physx_cfg = PhysxCfg(
        solver_type=1,
        min_position_iteration_count=8,
        max_position_iteration_count=64,
        min_velocity_iteration_count=1,
        max_velocity_iteration_count=4,
        enable_ccd=False,
        enable_stabilization=False,
        bounce_threshold_velocity=0.2,
        friction_offset_threshold=0.04,
        friction_correlation_distance=0.025,
    )

    sim_cfg = SimulationCfg(dt=1 / 120, physics=physx_cfg)

Keep per-actor properties such as contact materials, articulation iteration
counts, and USD-authored collision settings on the schema configuration side;
scene-level PhysX tuning does not replace that authoring path.

Choose TGS or PGS
-----------------

Keep ``solver_type=1`` (TGS) as the first candidate for articulated robots and
contact-rich manipulation. TGS is the established default and usually gives the
best stability for modern Isaac Lab tasks. Compare ``solver_type=0`` (PGS) only
when the fixed reproduction still shows poor behavior after validating the
asset, controller, and contact geometry, or when a stiff legacy asset behaves
better with PGS.

If a grasping or stiff-contact workload remains sensitive after the solver
choice is fixed, test ``solve_articulation_contact_last`` on the same
reproduction and keep it only when it measurably improves the recorded contact
or task metric.

Tune solver iterations
----------------------

PhysX clamps each actor's solver work through the scene-level iteration ranges:
``min_position_iteration_count`` and ``max_position_iteration_count`` for
position iterations, plus ``min_velocity_iteration_count`` and
``max_velocity_iteration_count`` for velocity iterations.

Increase position iterations first when the fixed reproduction shows
penetration, joint constraint drift, or grasp instability. Increase velocity
iterations only when the same reproduction shows unstable restitution or a
velocity-level convergence issue that position iterations do not correct. Stop
when the measured behavior plateaus; more iterations cannot repair invalid
collision geometry, reset overlap, or a controller that injects instability.

Tune contacts and stability
---------------------------

Validate colliders, material properties, and reset overlap before changing
scene-wide contact settings. Then use the same fixed reproduction to tune:

* ``enable_ccd`` for fast-moving bodies that tunnel through thin geometry when
  using CPU dynamics. CCD is not supported with GPU dynamics; Isaac Lab forces
  it off and emits a warning if ``enable_ccd=True`` is requested on a GPU
  simulation.
* ``enable_stabilization`` only for low-rate simulations where ``dt`` is larger
  than about ``1 / 30`` seconds; this extra pass can make reported
  contact-sensor force magnitudes inaccurate, so keep it disabled when those
  forces are part of the observation or evaluation path.
* ``bounce_threshold_velocity`` [m/s] for the relative speed above which
  contacts bounce.
* ``friction_offset_threshold`` [m] for the contact distance at which PhysX
  starts applying friction forces.
* ``friction_correlation_distance`` [m] for the distance used to merge nearby
  contacts into one friction anchor.

Treat each of these as a measured contact-model change. Recheck penetration,
slip, bounce, contact counts, task success, and runtime after every adjustment.

Size GPU buffers
----------------

Most PhysX GPU scene-buffer capacities are fixed and do not grow dynamically.
When a scene exceeds one of these capacities, PhysX can drop contacts or fail
with a ``[PhysX]`` warning. Treat those warnings as hard failures for the
reproduction and increase only the capacity that overflowed.

The most common fixed capacities to raise for large vectorized or contact-rich
scenes are:

* ``gpu_max_rigid_contact_count``
* ``gpu_max_rigid_patch_count``
* ``gpu_found_lost_pairs_capacity``
* ``gpu_found_lost_aggregate_pairs_capacity``
* ``gpu_total_aggregate_pairs_capacity``
* ``gpu_collision_stack_size``

``gpu_heap_capacity`` is different: it sets the initial capacity of the GPU
and pinned-host-memory heaps, and PhysX allocates additional memory when those
heaps need to grow. Increase the initial heap capacity when measurements show
that repeated growth is undesirable, not because it is a fixed upper bound.

Measure the busiest reset and contact state, add task-specific headroom, and
then verify that the same fixed reproduction remains stable. Buffer sizing
cannot correct invalid geometry, solver divergence, or a controller issue.

See also
--------

* :class:`~isaaclab_physx.physics.PhysxCfg`
* :doc:`/source/concepts/schema_cfgs`
* :ref:`physics-backends-physx`
* :doc:`/source/concepts/solver_differences`