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

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):

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:

# 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), the builder pattern centralizes model construction:

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:

# 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():

# 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:

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:

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:

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:

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:

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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}