# Troubleshooting Simulation Stability and Constraint Violations in Newton

> Fix Newton physics simulation instability and constraint violations by tuning angular damping, friction smoothing, and substeps parameters for common solver backends and integration methods.

- Repository: [Newton Physics/newton](https://github.com/newton-physics/newton)
- Tags: how-to-guide
- Published: 2026-03-19

---

**Newton physics simulations become unstable or violate constraints when velocity limits, angular damping, and substep counts are misconfigured for the chosen solver backend, which can be fixed by tuning `angular_damping`, `friction_smoothing`, and `substeps` parameters based on the specific integration method used.**

Newton is an open-source physics engine that provides multiple solver back-ends for simulating particles and rigid bodies. When troubleshooting simulation stability and constraint violations in Newton, developers must understand how the specific solver implementation—whether Featherstone, Semi-Implicit, or MuJoCo—handles numerical integration, contact resolution, and constraint enforcement.

## Common Causes of Instability and Constraint Violations

Newton’s simulation pipeline is built around **solver back-ends** that integrate particles and rigid bodies, resolve contacts, and enforce constraints. Numerical instability or constraint violations usually stem from specific architectural areas within the integration and constraint resolution systems.

### Particle Integration and Velocity Clipping

The `integrate_particles` function in [`newton/_src/solvers/solver.py`](https://github.com/newton-physics/newton/blob/main/newton/_src/solvers/solver.py) limits particle velocities to `v_max` to prevent numerical blow-up. Missing or insufficient velocity clipping allows velocities to grow unbounded, producing NaN or infinite values that propagate through the simulation.

```python

# From newton/_src/solvers/solver.py lines 53-56

# v1 is clamped to v_max to maintain stability

v1 = wp.clamp(v1, -v_max, v_max)

```

### Rigid-Body Integration and Angular Damping

Rotational energy can diverge rapidly without proper damping. The `integrate_rigid_body` function applies angular damping to dampen rotational velocity each step, preventing jittery rotations and constraint drift.

```python

# From newton/_src/solvers/solver.py lines 101-103

# w1 is the angular velocity, damped by angular_damping * dt

w1 *= 1.0 - angular_damping * dt

```

### Joint Force-Torque Computation

Joint stability depends on careful scaling of angular damping stiffness. In [`newton/_src/solvers/semi_implicit/kernels_body.py`](https://github.com/newton-physics/newton/blob/main/newton/_src/solvers/semi_implicit/kernels_body.py), the `angular_damping_scale` parameter is set to `0.01` by default to keep torque damping gentle and prevent oscillations from over-stiff joints.

```cpp
// From newton/_src/solvers/semi_implicit/kernels_body.py lines 59-62
float angular_damping_scale = 0.01f;
t_total += wp::transform_vector(X_wp, ang_err) * joint_attach_ke
          + w_err * joint_attach_kd * angular_damping_scale;

```

### Contact Handling and Sub-stepping

High-frequency contact chatter and interpenetration occur when time steps are too coarse or friction models are too aggressive. The test suite in [`newton/tests/test_rigid_contact.py`](https://github.com/newton-physics/newton/blob/main/newton/tests/test_rigid_contact.py) demonstrates recommended stability parameters: `angular_damping=0.15`, `friction_smoothing=2.0`, and `substeps=30`.

```python

# From newton/tests/test_rigid_contact.py lines 62-78 and 86-89

solver = newton.solvers.SolverSemiImplicit(
    model,
    angular_damping=0.15,      # Higher damping for stability

    friction_smoothing=2.0,      # Regularizes Coulomb friction

)
substeps = 30                  # Finer time resolution

```

### Constraint Enforcement Limitations

Only the MuJoCo solver backend implements equality and mimic constraints. Other solvers treat these constraints as unavailable, leading to "constraint not found" errors if used improperly. The solver support table in [`newton/solvers.py`](https://github.com/newton-physics/newton/blob/main/newton/solvers.py) documents these capability flags.

```python

# From newton/solvers.py lines 31-45

# Solver capability matrix showing MuJoCo supports equality constraints

# while Featherstone and Semi-Implicit do not

```

## Identifying Root Causes in Your Simulation

When troubleshooting simulation stability and constraint violations in Newton, inspect these four typical failure patterns:

1. **Insufficient damping or velocity limits** – The default `angular_damping=0.05` and implicit `v_max` work for modest scenes but fail during high-speed impacts or tall contact stacks. Increase `angular_damping` to `0.15` or higher for unstable rotations.

2. **Too coarse time step** – A single step of `dt = 1/60 s` with complex contact networks causes interpenetration. Increasing the **substep count** effectively halves the per-substep `dt`, improving contact resolution without changing the scene definition.

3. **Unsupported constraints** – Attempting to use equality constraints (CONNECT, WELD) with Featherstone or Semi-Implicit solvers triggers errors. Switch to `SolverMuJoCo` or remove the unsupported constraints.

4. **Extreme joint stiffness parameters** – Large `joint_attach_ke` or `joint_attach_kd` values without corresponding damping cause explosive joint forces. Reduce stiffness or increase the damping scale factor in custom kernels.

## Configuring Newton for Maximum Stability

### Tuning Solver Parameters

Start by configuring your solver with stability-focused parameters demonstrated in [`newton/tests/test_rigid_contact.py`](https://github.com/newton-physics/newton/blob/main/newton/tests/test_rigid_contact.py). This example creates a Semi-Implicit solver with enhanced damping and friction smoothing:

```python
import warp as wp
import newton

# Build a simple model (ground + a falling box)

builder = newton.ModelBuilder()
b = builder.add_body(xform=wp.transform(wp.vec3(0, 5, 0), wp.quat_identity()))
builder.add_shape_box(body=b, half_extents=wp.vec3(0.5, 0.5, 0.5))
builder.add_ground_plane()
model = builder.finalize()

# Choose a back-end and boost its stability settings

if False:  # replace with your solver choice

    solver = newton.solvers.SolverFeatherstone(
        model,
        angular_damping=0.15,          # stronger rotational damping

        friction_smoothing=2.0,        # smoother Coulomb friction

    )
else:
    solver = newton.solvers.SolverSemiImplicit(
        model,
        angular_damping=0.15,
        friction_smoothing=2.0,
    )

# Run the simulation with many substeps for extra robustness

state0, state1 = model.state(), model.state()
control = model.control()
contacts = model.contacts()
substeps = 30                # finer time resolution (default is 10)

dt = 1.0 / 60.0

for _ in range(120):
    newton.simulate(
        solver, model, state0, state1, control, contacts, dt, substeps
    )

```

Key parameters to adjust:
- **`angular_damping`**: Controls rotational energy dissipation (default `0.05`, stable scenes often need `0.15`)
- **`friction_smoothing`**: Regularizes the Coulomb friction model to prevent stick-slip artifacts (recommended `2.0`)
- **`substeps`**: Divides the simulation step into smaller increments (recommended `30` for contact-heavy scenes)

### Detecting NaN Values Early

Newton’s test suite includes NaN guards that you should replicate in production code. After each simulation step, inspect the body states for numerical corruption:

```python
import numpy as np

body_q = state0.body_q.numpy()
body_qd = state0.body_qd.numpy()

if np.any(np.isnan(body_q)) or np.any(np.isnan(body_qd)):
    raise RuntimeError(
        "NaNs detected – likely numerical instability. "
        "Try increasing angular_damping, friction_smoothing, or substeps."
    )

```

This pattern mirrors the validation logic in [`newton/tests/test_rigid_contact.py`](https://github.com/newton-physics/newton/blob/main/newton/tests/test_rigid_contact.py) lines 9-16, surfacing instability before it propagates through long simulation batches.

### Selecting the Appropriate Solver Backend

Constraint support varies by solver. If your scene requires equality constraints (CONNECT, WELD) or mimic joints, you must use the MuJoCo backend:

```python

# Equality constraints are only implemented in MuJoCo

solver = newton.solvers.SolverMuJoCo(model)

```

Attempting to use these constraints with `SolverFeatherstone` or `SolverSemiImplicit` triggers a "constraint not found" error because the solver capability table in [`newton/solvers.py`](https://github.com/newton-physics/newton/blob/main/newton/solvers.py) (lines 31-45) marks these features as unsupported for those backends.

### Custom Kernel Tuning (Advanced)

If you are implementing custom joint kernels, follow the stability pattern from [`newton/_src/solvers/semi_implicit/kernels_body.py`](https://github.com/newton-physics/newton/blob/main/newton/_src/solvers/semi_implicit/kernels_body.py). Apply a small damping scale factor to prevent torque oscillations:

```cpp
// From newton/_src/solvers/semi_implicit/kernels_body.py lines 59-62
float angular_damping_scale = 0.01f;  // keeps torque damping gentle
t_total += wp::transform_vector(X_wp, ang_err) * joint_attach_ke
          + w_err * joint_attach_kd * angular_damping_scale;

```

Adjust `angular_damping_scale` only after profiling; values too low create overly compliant joints, while values too high reintroduce oscillations.

## Key Source Files for Debugging

When troubleshooting simulation stability and constraint violations in Newton, inspect these specific files that govern the numerical pipeline:

| File | Why it matters for stability / constraints |
|------|--------------------------------------------|
| [`newton/_src/solvers/solver.py`](https://github.com/newton-physics/newton/blob/main/newton/_src/solvers/solver.py) | Core particle & rigid-body integration, velocity clipping to `v_max`, and angular damping application in `integrate_rigid_body`. |
| [`newton/_src/solvers/semi_implicit/kernels_body.py`](https://github.com/newton-physics/newton/blob/main/newton/_src/solvers/semi_implicit/kernels_body.py) | Joint force computation with `angular_damping_scale` factor (set to `0.01` for stability). |
| [`newton/_src/solvers/vbd/particle_vbd_kernels.py`](https://github.com/newton-physics/newton/blob/main/newton/_src/solvers/vbd/particle_vbd_kernels.py) | Numerical-stability comments for VBD particle contacts. |
| [`newton/_src/solvers/kamino/_src/linalg/utils/matrix.py`](https://github.com/newton-physics/newton/blob/main/newton/_src/solvers/kamino/_src/linalg/utils/matrix.py) | Tolerance settings that affect matrix solves in constraint projection. |
| [`newton/tests/test_rigid_contact.py`](https://github.com/newton-physics/newton/blob/main/newton/tests/test_rigid_contact.py) | Real-world example configuring solvers with `angular_damping=0.15`, `friction_smoothing=2.0`, and `substeps=30`. |
| [`newton/solvers.py`](https://github.com/newton-physics/newton/blob/main/newton/solvers.py) | Public API documenting which solvers support equality constraints (MuJoCo) versus unsupported configurations (Featherstone, Semi-Implicit). |
| [`newton/_src/geometry/contact_reduction.py`](https://github.com/newton-physics/newton/blob/main/newton/_src/geometry/contact_reduction.py) | Contact-subsampling strategy that caps contacts per pair to preserve stability. |
| [`newton/_src/solvers/solver_semi_implicit.py`](https://github.com/newton-physics/newton/blob/main/newton/_src/solvers/solver_semi_implicit.py) | Implements the Semi-Implicit back-end used in most stability examples. |

## Summary

- **Velocity clipping** in [`newton/_src/solvers/solver.py`](https://github.com/newton-physics/newton/blob/main/newton/_src/solvers/solver.py) automatically caps particle speeds to `v_max`, but rigid-body stability requires manual tuning of `angular_damping`.
- **Increasing `substeps`** (e.g., to 30) effectively reduces the integration time step without changing scene geometry, resolving interpenetration and high-frequency chatter.
- **Friction smoothing** (`friction_smoothing=2.0`) regularizes the Coulomb model to prevent stick-slip artifacts that destabilize contact stacks.
- **Solver selection** determines constraint support: only `SolverMuJoCo` handles equality constraints (CONNECT, WELD), while Featherstone and Semi-Implicit solvers reject these configurations.
- **NaN detection** should be implemented using the pattern in [`newton/tests/test_rigid_contact.py`](https://github.com/newton-physics/newton/blob/main/newton/tests/test_rigid_contact.py) to catch numerical instability before it corrupts long simulation runs.

## Frequently Asked Questions

### What causes Newton simulations to suddenly produce NaN values or explode?

NaN values typically originate from unbounded velocity growth when `angular_damping` is too low for the scene's energy levels or when contact impulses create high-frequency oscillations without sufficient `friction_smoothing`. The `integrate_particles` function in [`newton/_src/solvers/solver.py`](https://github.com/newton-physics/newton/blob/main/newton/_src/solvers/solver.py) clips velocities to prevent particle blow-up, but rigid bodies require explicit damping tuning. Check for NaNs after each step using `numpy.isnan()` on `state.body_q` and `state.body_qd` to catch instability early.

### How do I fix persistent constraint violations in Newton joint simulations?

Constraint violations occur when joint stiffness parameters (`joint_attach_ke`, `joint_attach_kd`) are set too high without corresponding damping, causing "explosive" force computations. In [`newton/_src/solvers/semi_implicit/kernels_body.py`](https://github.com/newton-physics/newton/blob/main/newton/_src/solvers/semi_implicit/kernels_body.py), the `angular_damping_scale` factor (default `0.01`) scales torque damping to maintain stability. Reduce stiffness values or increase the damping scale factor, and ensure you are using a solver that supports your constraint type—equality constraints require `SolverMuJoCo` according to the capability table in [`newton/solvers.py`](https://github.com/newton-physics/newton/blob/main/newton/solvers.py).

### Why does my rigid body simulation jitter or drift even at low speeds?

Jitter and drift typically indicate insufficient angular damping or inadequate contact substepping. The default `angular_damping=0.05` may be insufficient for tall stacks or high-friction contacts. Increase to `0.15` as demonstrated in [`newton/tests/test_rigid_contact.py`](https://github.com/newton-physics/newton/blob/main/newton/tests/test_rigid_contact.py). Additionally, increase `substeps` from the default (often 10) to 30 to reduce the effective time step and improve contact resolution without modifying scene geometry.

### Which Newton solver should I use for simulations with equality constraints?

Use `SolverMuJoCo` for any simulation requiring equality constraints such as CONNECT, WELD, or mimic joints. The solver capability matrix in [`newton/solvers.py`](https://github.com/newton-physics/newton/blob/main/newton/solvers.py) (lines 31-45) explicitly marks Featherstone and Semi-Implicit solvers as lacking support for these constraint types. Attempting to use equality constraints with unsupported solvers will raise "constraint not found" errors during simulation initialization.