newton.solvers.SolverBase

class newton.solvers.SolverBase(model, *, collision_pipeline=None, collision_frequency=None, collision_frequency_type=None)

Bases: object

Generic base class for solvers.

The implementation provides helper kernels to integrate rigid bodies and particles. Concrete solver back-ends should derive from this class and override step() as well as notify_model_changed() where necessary.

class CollisionFrequencyType(*values)

Bases: IntEnum

When, inside a step(), a solver-owned collision pipeline runs detection.

The frequency number in collision_frequency applies only to ITERATIONS; the other members ignore it. Skipping detection across steps carries no hidden solver state — set a slot to NONE between steps via set_collision_frequency().

AUTO = 4

Solver-specific default.

ITERATIONS = 3

Before initialization, then immediately before iterations k, 2k, and so on.

NONE = 0

Never detect; the user may run detection externally into contacts.

PRE_INIT = 1

Once per step, before solver initialization.

PRE_POST_INIT = 2

Before and after solver initialization (one detection each).

class CollisionSlot(*values)

Bases: IntEnum

Collision-detection categories scheduled by a solver.

RIGID = 0

Rigid-rigid and particle-shape collision detection.

SOFT_SELF_CONTACT = 1

Triangle-mesh soft self-contact detection.

classmethod register_custom_attributes(builder)

Register custom attributes for the solver.

Parameters:

builder (ModelBuilder) – The model builder to register the custom attributes to.

__init__(model, *, collision_pipeline=None, collision_frequency=None, collision_frequency_type=None)

Initialize common solver state and optional collision scheduling.

Parameters:

• model (Model) – Simulation model integrated by the solver.

• collision_pipeline (CollisionPipeline | None) – Collision pipeline owned and driven by the solver. The pipeline must use model, and the concrete solver must set supports_collision_pipeline.

• collision_frequency (Mapping[CollisionSlot, int] | None) – Per-slot iteration frequencies. Values must be at least one and are used only for slots scheduled with CollisionFrequencyType.ITERATIONS. Unspecified slots retain their defaults.

• collision_frequency_type (Mapping[CollisionSlot, CollisionFrequencyType] | None) – Per-slot detection points. Unspecified slots retain their defaults.

integrate_bodies(model, state_in, state_out, dt, angular_damping=0.0)

Integrate the rigid bodies of the model.

Parameters:

• model (Model) – The model to integrate.

• state_in (newton.State) – The input state.

• state_out (newton.State) – The output state.

• dt (float) – The time step (typically in seconds).

• angular_damping (float) – The angular damping factor. Defaults to 0.0.

integrate_particles(model, state_in, state_out, dt)

Integrate the particles of the model.

Parameters:

• model (Model) – The model to integrate.

• state_in (newton.State) – The input state.

• state_out (newton.State) – The output state.

• dt (float) – The time step (typically in seconds).

notify_model_changed(flags)

Notify the solver that parts of the Model were modified.

The flags argument is a bit-mask composed of the ModelFlags enums or custom int bits. Each flag represents a category of model data that may have been updated after the solver was created. Passing the appropriate combination of flags enables a solver implementation to refresh its internal buffers without having to recreate the whole solver object. Valid flags are:

• ModelFlags.JOINT_PROPERTIES: Joint transforms or coordinates have changed.

• ModelFlags.JOINT_DOF_PROPERTIES: Joint axis limits, targets, modes, DOF state, or force buffers have changed.

• ModelFlags.BODY_PROPERTIES: Rigid-body pose or velocity buffers have changed.

• ModelFlags.BODY_INERTIAL_PROPERTIES: Rigid-body mass or inertia tensors have changed.

• ModelFlags.SHAPE_PROPERTIES: Shape transforms or geometry have changed.

• ModelFlags.MODEL_PROPERTIES: Model global properties (e.g., gravity) have changed.

• ModelFlags.CONSTRAINT_PROPERTIES: Constraint definitions, coefficients, or enable flags have changed.

• ModelFlags.TENDON_PROPERTIES: Tendon stiffness or related tendon properties have changed.

• ModelFlags.ACTUATOR_PROPERTIES: Actuator gains, biases, limits, or force properties have changed.

Parameters:

flags (ModelFlags | int) – Bit-mask of ModelFlags or custom int bits indicating which model properties changed.

reset(state, world_mask=None, flags=None)

Reset the solver internal state data.

Modifies the given state in place. Derived solvers override this to reset solver-specific internal buffers or custom state attributes when environments are reset (e.g. during RL training).

The default implementation is a no-op so solvers that do not require special reset logic need not override this method.

Parameters:

• state (newton.State) – The simulation state to reset (modified in place).

• world_mask (wp.array[wp.bool] | None) –

  Optional boolean mask of shape (world_count + 1,) specifying which worlds to reset. Entries before the last select local worlds by index, and the final entry selects global entities whose world is -1. If None, all local and global entities are reset.

  Deprecated since version 1.5: Passing a mask with shape (world_count,) is deprecated. Use shape (world_count + 1,) with a final False entry to select local worlds only.

• flags (StateFlags | int | None) – Optional StateFlags or int bitmask controlling which state attributes need to be reset. If None, all state attributes are reset.

set_collision_frequency(*, collision_frequency=None, collision_frequency_type=None)

Change the detection schedule; takes effect at the next step().

The solver keeps no hidden cross-step scheduling state, so detecting every N steps is expressed by toggling a slot between CollisionFrequencyType.NONE and an active type from the calling loop. None keeps the corresponding current setting. Recapture an existing CUDA graph after changing the schedule.

Parameters:

• collision_frequency (Mapping[CollisionSlot, int] | None) – Frequency numbers keyed by CollisionSlot; used only by ITERATIONS slots (before iterations k, 2k, and so on) and must be at least one.

• collision_frequency_type (Mapping[CollisionSlot, CollisionFrequencyType] | None) – Detection points keyed by CollisionSlot.

step(state_in, state_out, control, contacts, dt)

Simulate the model for a given time step using the given control input.

Parameters:

• state_in (newton.State) – The input state.

• state_out (newton.State) – The output state.

• control (Control | None) – The control input. Defaults to None which means the control values from the Model are used.

• contacts (Contacts | None) – The contact information.

• dt (float) – The time step (typically in seconds).

update_contacts(contacts, state=None)

Update a Contacts object with forces from the solver state. Where the solver state contains other contact data, convert that data to the Contacts format.

Parameters:

• contacts (Contacts) – The object to update from the solver state.

• state (State | None) – Optional simulation state, used by some solvers.

property collision_frequency: dict[CollisionSlot, int]

Per-slot detection frequency numbers as a read-only copy.

property collision_frequency_type: dict[CollisionSlot, CollisionFrequencyType]

Per-slot CollisionFrequencyType values as a read-only copy.

collision_pipeline

The solver-owned collision pipeline, or None when detection is driven externally.

property contacts: Contacts | None

The solver-owned contacts buffer, or None when no pipeline is owned.

Unlike Model.contacts(), this property does not allocate; it returns the buffer created from the owned pipeline at construction. With a slot set to CollisionFrequencyType.NONE the user may fill this buffer externally, e.g. pipeline.collide(state, solver.contacts).

property device: Device

Get the device used by the solver.

Returns:

The device used by the solver.

Return type:

wp.Device

supports_collision_pipeline: bool = False

Whether this solver can own a CollisionPipeline and drive detection itself.

Currently only SolverVBD opts in; passing collision_pipeline to any other solver raises ValueError (drive detection externally instead).