# Newton Migration Guide: Transitioning from Deprecated warp.sim to Newton Physics

> Transition from deprecated warp.sim to Newton Physics with our comprehensive migration guide. Learn API reorganization, solver integration, and ground plane creation for a seamless upgrade.

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

---

**Newton is the modern successor to NVIDIA Warp's deprecated `warp.sim` module, requiring API reorganization from free functions to object-oriented `ModelBuilder` methods, unified solver classes with `step()` methods, and explicit ground plane creation.**

The Newton physics library represents a significant evolution of the simulation capabilities previously found in NVIDIA Warp's `warp.sim` module. As `warp.sim` has been officially deprecated, developers must migrate their robotics and physics simulations to Newton's restructured API. This Newton migration guide provides a comprehensive mapping between legacy `warp.sim` patterns and modern Newton implementations, covering solvers, model construction, and control interfaces.

## Solver Migration: From Integrators to Unified Solver Classes

### Mapping Legacy Integrators to Newton Solvers

Newton consolidates the scattered integrator classes from `warp.sim` into a unified `newton.solvers` module. The following table maps deprecated `warp.sim` classes to their Newton equivalents as defined in [[`newton/solvers.py`](https://github.com/newton-physics/newton/blob/main/newton/solvers.py)](https://github.com/newton-physics/newton/blob/main/newton/solvers.py):

| `warp.sim` (Deprecated) | Newton | Instantiation Pattern |
|---|---|---|
| `warp.sim.FeatherstoneIntegrator` | `newton.solvers.SolverFeatherstone` | `solver = SolverFeatherstone(model)` |
| `warp.sim.SemiImplicitIntegrator` | `newton.solvers.SolverSemiImplicit` | `solver = SolverSemiImplicit(model)` |
| `warp.sim.VBDIntegrator` | `newton.solvers.SolverVBD` | `solver = SolverVBD(model, compliance=0.001)` |
| `warp.sim.XPBDIntegrator` | `newton.solvers.SolverXPBD` | `solver = SolverXPBD(model, compliance=0.001)` |

### Unified Step Interface

All Newton solvers expose a consistent `step` method that replaces the legacy `simulate` call. The parameter order and semantics have been standardized:

```python

# Legacy warp.sim pattern

integrator.simulate(model, state0, state1, dt, None)

# Modern Newton pattern

solver.step(state0, state1, control, None, dt)

```

Note that Newton explicitly requires a `control` object as the third argument, where `warp.sim` accepted `None` implicitly.

## Model Construction: ModelBuilder API Changes

### Importer Migration (URDF, MJCF, USD)

Newton replaces `warp.sim`'s free-function importers with methods on the `ModelBuilder` class. According to [[`newton/__init__.py`](https://github.com/newton-physics/newton/blob/main/newton/__init__.py)](https://github.com/newton-physics/newton/blob/main/newton/__init__.py), the builder pattern centralizes model construction:

```python
import newton as nx

builder = nx.ModelBuilder()

# Legacy: warp.sim.parse_urdf("robot.urdf")

builder.add_urdf("robot.urdf")

# Legacy: warp.sim.parse_mjcf("scene.xml")

builder.add_mjcf("scene.xml")

# Legacy: warp.sim.parse_usd("scene.usd") or resolve_usd_from_url()

builder.add_usd("scene.usd")  # Accepts file paths or URLs directly

model = builder.finalize()

```

### Default Configuration Objects

Newton introduces configuration objects to replace keyword arguments scattered across legacy importers. These are accessed via `default_joint_cfg` and `default_shape_cfg` attributes:

```python

# Joint limits previously passed to importers

builder.default_joint_cfg.limit_lower = -1.0
builder.default_joint_cfg.limit_upper = 1.0

# Shape contact parameters previously in add_shape_* calls

builder.default_shape_cfg.ke = 1e5  # stiffness

builder.default_shape_cfg.kd = 1e2  # damping

```

### Explicit Ground Plane Creation

Newton removes automatic ground plane handling. You must explicitly add ground geometry using `add_ground_plane()`:

```python

# No longer automatic; must be explicit

builder.add_ground_plane(z=0.0, normal=(0, 0, 1), mu=0.8)

```

## Data Layout and Convention Changes

### Spatial Vector Ordering

Newton standardizes spatial vector ordering to `(linear, angular)` across all APIs. This affects direct indexing into `State.body_qd` and related arrays:

| Legacy `warp.sim` | Newton |
|---|---|
| `(ang_vel, lin_vel)` | `(lin_vel, ang_vel)` |

Update any code that manually constructs or decomposes spatial vectors to respect this ordering.

### Type System Updates

The `Model.shape_is_solid` attribute changed from `wp.uint8` to `bool`. Ensure that any custom kernels or external code accessing this field update their type expectations accordingly.

## Control Interface Refactoring

Newton completely restructures the control API to separate concerns between targets, forces, and actuator inputs.

### Target Separation and Force Control

The monolithic `target` array is replaced by explicit `joint_target_pos` and `joint_target_vel` arrays. Direct force application uses `joint_f`:

```python
ctrl = model.control()

# Position target for joint 0

ctrl.joint_target_pos[0] = 1.57

# Velocity target for joint 1  

ctrl.joint_target_vel[1] = 0.5

# Direct torque application (dimension = Model.joint_dof_count)

ctrl.joint_f[3] = 5.0

```

### Joint Target Modes

The legacy `JointMode` enum is replaced by `newton.JointTargetMode`. Select the appropriate mode to interpret the target arrays:

```python
from newton import JointTargetMode

# For pure force/torque control

ctrl.joint_target_mode = JointTargetMode.EFFORT

# For combined position/velocity tracking

ctrl.joint_target_mode = JointTargetMode.POSITION_VELOCITY

```

## Rendering System Updates

Newton consolidates rendering under the `newton.viewer` module. The legacy `warp.sim.render` subpackage is obsolete.

| Legacy `warp.sim` | Newton |
|---|---|
| `warp.sim.render.UsdRenderer` | `newton.viewer.ViewerUSD` |
| `warp.sim.render.OpenGLRenderer` | `newton.viewer.ViewerGL` |

Example usage:

```python
from newton.viewer import ViewerGL

viewer = ViewerGL()
viewer.set_model(model)
viewer.run()  # Opens interactive OpenGL window

```

## Practical Migration Examples

### Complete Featherstone Simulation

This example demonstrates the full migration path from `warp.sim.FeatherstoneIntegrator` to `newton.solvers.SolverFeatherstone`:

```python
import newton as nx
from newton.solvers import SolverFeatherstone

# Build model using new builder pattern

builder = nx.ModelBuilder()
builder.add_urdf("humanoid.urdf")
model = builder.finalize()

# Allocate state and control buffers

state0 = model.state()
state1 = model.state()
control = model.control()

# Initialize solver

solver = SolverFeatherstone(model)

# Simulation step (dt = 1/240 s)

solver.step(state0, state1, control, None, 1.0 / 240.0)

```

### Configuring Contact and Joint Properties

Replace inline importer arguments with builder configuration objects:

```python
builder = nx.ModelBuilder()

# Set global defaults before adding assets

builder.default_joint_cfg.limit_lower = -2.0
builder.default_joint_cfg.limit_upper = 2.0
builder.default_shape_cfg.ke = 1e5  # contact stiffness

builder.default_shape_cfg.kd = 1e2  # contact damping

# Explicit ground plane (no longer automatic)

builder.add_ground_plane(z=0.0, normal=(0, 0, 1), mu=0.8)

builder.add_urdf("quadruped.urdf")
model = builder.finalize()

```

## Summary

- **Solver Architecture**: Replace `warp.sim` integrator classes with unified `Solver*` classes from `newton.solvers`, using the `step(state0, state1, control, None, dt)` method signature.
- **Model Construction**: Migrate from free-function importers (`parse_urdf`, etc.) to `ModelBuilder` methods (`add_urdf`, `add_mjcf`, `add_usd`), configuring defaults via `default_joint_cfg` and `default_shape_cfg`.
- **Data Conventions**: Update spatial vector indexing to `(lin_vel, ang_vel)` order and change `shape_is_solid` type expectations from `uint8` to `bool`.
- **Control API**: Separate monolithic targets into `joint_target_pos`, `joint_target_vel`, and `joint_f` arrays, selecting modes via `JointTargetMode`.
- **Rendering**: Import `ViewerUSD` and `ViewerGL` from `newton.viewer` instead of `warp.sim.render`.

## Frequently Asked Questions

### How do I replace the deprecated warp.sim FeatherstoneIntegrator in Newton?

Use `newton.solvers.SolverFeatherstone`. Instantiate it with your model: `solver = SolverFeatherstone(model)`, then call `solver.step(state0, state1, control, None, dt)` instead of the legacy `integrator.simulate(model, state0, state1, dt, None)`. The solver classes are defined in [`newton/solvers.py`](https://github.com/newton-physics/newton/blob/main/newton/solvers.py).

### What happened to the parse_urdf and parse_mjcf functions in Newton?

These free functions have been replaced by methods on `ModelBuilder`. Create a `builder = newton.ModelBuilder()` instance, then call `builder.add_urdf("robot.urdf")` or `builder.add_mjcf("scene.xml")` followed by `model = builder.finalize()`. This consolidates model construction into a single fluent API.

### How do I set joint limits and contact properties in Newton?

Instead of passing these as arguments to importers, set them on the builder's default configuration objects before adding assets. Use `builder.default_joint_cfg.limit_lower` and `builder.default_joint_cfg.limit_upper` for joint limits, and `builder.default_shape_cfg.ke` (stiffness) and `builder.default_shape_cfg.kd` (damping) for contact properties.

### Why does my code fail when accessing State.body_qd after migrating to Newton?

Newton changed the spatial vector ordering from `(ang_vel, lin_vel)` to `(lin_vel, ang_vel)`. If your code manually indexes into `State.body_qd` or constructs spatial vectors, update the ordering so that linear components come first, followed by angular components. This change affects all spatial vector operations in the new API.