newton.solvers.SolverKamino#

class newton.solvers.SolverKamino(model, config=None)[source]#

Bases: SolverBase

A physics solver for simulating constrained multi-body systems containing kinematic loops, under-/overactuation, joint-limits, hard frictional contacts and restitutive impacts.

This solver uses the Proximal-ADMM algorithm to solve the forward dynamics formulated as a Nonlinear Complementarity Problem (NCP) over the set of bilateral kinematic joint constraints and unilateral constraints that include joint-limits and contacts.

This solver is currently in Beta.

Experimental

SolverKamino’s public API and internal implementation may change without prior notice, including simulation feature support, performance, and bug fixes.

References

  • Tsounis, Vassilios, Ruben Grandia, and Moritz Bächer. On Solving the Dynamics of Constrained Rigid Multi-Body Systems with Kinematic Loops. arXiv preprint arXiv:2504.19771 (2025). https://doi.org/10.48550/arXiv.2504.19771

  • Carpentier, Justin, Quentin Le Lidec, and Louis Montaut. From Compliant to Rigid Contact Simulation: a Unified and Efficient Approach. 20th edition of the “Robotics: Science and Systems”(RSS) Conference. 2024. https://roboticsproceedings.org/rss20/p108.pdf

  • Tasora, A., Mangoni, D., Benatti, S., & Garziera, R. (2021). Solving variational inequalities and cone complementarity problems in nonsmooth dynamics using the alternating direction method of multipliers. International Journal for Numerical Methods in Engineering, 122(16), 4093-4113. https://onlinelibrary.wiley.com/doi/full/10.1002/nme.6693

After constructing ModelKamino, StateKamino, ControlKamino and ContactsKamino objects, this physics solver may be used to advance the simulation state forward in time.

Example

config = newton.solvers.SolverKamino.Config()
solver = newton.solvers.SolverKamino(model, config=config)

# simulation loop
for i in range(100):
    solver.step(state_in, state_out, control, contacts, dt)
    state_in, state_out = state_out, state_in
class Config(sparse_jacobian=False, sparse_dynamics=False, use_collision_detector=False, use_fk_solver=False, collision_detector=None, constraints=None, dynamics=None, padmm=None, fk=None, rotation_correction='twopi', integrator='euler', angular_velocity_damping=0.0, collect_solver_info=False, compute_solution_metrics=False)#

Bases: object

A container to hold all configurations of the SolverKamino solver.

static from_model(model, **kwargs)#

Creates a configuration container by attempting to parse custom attributes from a Model if available.

Note: If the model was imported from USD and contains custom attributes defined by the KaminoSceneAPI, those attributes will be parsed and used to populate the configuration container. Additionally, any sub-configurations that are provided as keyword arguments will also be used to populate the corresponding sections of the configuration, allowing for a combination of model-imported and explicit user-provided configurations. If certain configurations are not provided either via the model’s custom attributes or as keyword arguments, then default values will be used.

Parameters:

model (Model) – The Newton model from which to parse configurations.

static register_custom_attributes(builder)#

Register custom attributes for the SolverKamino.Config configurations.

Note: Currently, not all configurations are registered as custom attributes, as only those supported by the Kamino USD scene API have been included. More will be added in the future as latter is being developed.

Parameters:

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

__init__(sparse_jacobian=False, sparse_dynamics=False, use_collision_detector=False, use_fk_solver=False, collision_detector=None, constraints=None, dynamics=None, padmm=None, fk=None, rotation_correction='twopi', integrator='euler', angular_velocity_damping=0.0, collect_solver_info=False, compute_solution_metrics=False)#
validate()#

Validates the current values held by the SolverKamino.Config instance.

angular_velocity_damping: float = 0.0#

A damping factor applied to the angular velocity of bodies during state integration.

This can help stabilize simulations with large time steps or high angular velocities.

Defaults to 0.0 (i.e. no damping).

collect_solver_info: bool = False#

Enables/disables collection of solver convergence and performance info at each simulation step.

Enabling this option as it will significantly increase the runtime of the solver.

Defaults to False.

compute_solution_metrics: bool = False#

Enables/disables computation of solution metrics at each simulation step.

Enabling this option as it will significantly increase the runtime of the solver.

Defaults to False.

integrator: Literal['euler', 'moreau'] = 'euler'#

The time-integrator to use for state integration.

See available options in the integrators module.

Defaults to “euler”.

rotation_correction: Literal['twopi', 'continuous', 'none'] = 'twopi'#

The rotation correction mode to use for rotational DoFs.

See JointCorrectionMode for available options. Defaults to twopi.

sparse_dynamics: bool = False#

Flag to indicate whether the solver should use sparse data representations for the dynamics.

sparse_jacobian: bool = False#

Flag to indicate whether the solver should use sparse data representations for the Jacobian.

use_collision_detector: bool = False#

Flag to indicate whether the Kamino-provided collision detector should be used.

use_fk_solver: bool = False#

Flag to indicate whether the Kamino-provided FK solver should be enabled.

The FK solver is used for computing consistent initial states given input joint positions, joint velocities and optional base body poses and twists.

It is specifically designed to handle the presence of: - kinematic loops - passive joints - over/under-actuation

class ResetConfig(body_poses=SolverKamino.ResetConfig.ToDefault(), body_velocities=SolverKamino.ResetConfig.ToDefault(), base_pose=SolverKamino.ResetConfig.ToDefault(), base_velocity=SolverKamino.ResetConfig.ToDefault())#

Bases: object

Configuration for a call to the reset() operation, specifying the behaviour (common or separate) for body poses, body velocities as well as floating base pose and velocity.

Example

# Reset all worlds to the initial state
reset_config = newton.solvers.SolverKamino.ResetConfig.to_default()
solver.reset(state=state, config=reset_config)

# Preserve the current body/joint state, while resetting time, forces/torques and solver internals
reset_config = newton.solvers.SolverKamino.ResetConfig.preserve()
solver.reset(state=state, config=reset_config)

# Set a custom pose from joint state with FK
wp.copy(state.joint_q, custom_joint_coords)
wp.copy(state.joint_qd, custom_joint_velocities)
reset_config = newton.solvers.SolverKamino.ResetConfig.from_joints()
solver.reset(state=state, config=reset_config)

# Advanced reset with custom configuration
# E.g. here, set custom actuator coords and base pose, and reset velocities to default (=zero)
reset_config = newton.solvers.SolverKamino.ResetConfig(
    body_poses=newton.solvers.SolverKamino.ResetConfig.FromActuatorQ(new_actuator_coords),
    body_velocities=newton.solvers.SolverKamino.ResetConfig.ToDefault(),
    base_pose=newton.solvers.SolverKamino.ResetConfig.FromBaseQ(new_base_pose),
    base_velocity=newton.solvers.SolverKamino.ResetConfig.ToDefault(),
)
solver.reset(state=state, config=reset_config)
class FromActuatorQ(actuator_q)#

Bases: object

Reset option, to set body poses from actuator coordinates, using position-level Forward Kinematics. Note: angles outside the [-2pi, 2pi] range around initial coordinates will be remapped automatically.

__init__(actuator_q)#
actuator_q: wp.array(dtype=wp.float32, ndim=1)#

Actuator coordinates array.

class FromActuatorU(actuator_u)#

Bases: object

Reset option, to set body velocities from actuator velocities, using velocity-level Forward Kinematics.

__init__(actuator_u)#
actuator_u: wp.array(dtype=wp.float32, ndim=1)#

Actuator velocities array.

class FromBaseQ(base_q)#

Bases: object

Reset option, to set a new pose for the base body, and transform all bodies accordingly. If a base joint is set, the prescribed pose is interpreted in the frame of the base joint; else it is directly interpreted as the new pose of the base body. Note: if a base joint is set that is not a free joint, no check is made that the new pose is compatible with the base joint’s DoFs. To guarantee a feasible pose, use instead FromJointQ.

__init__(base_q)#
base_q: wp.array(dtype=wp.transformf, ndim=1)#

Per-world base body pose array.

class FromBaseU(base_u)#

Bases: object

Reset option, to set a new velocity for the base body, and compose with body velocities accordingly. If a base joint is set, the prescribed velocity is interpreted in the frame of the base joint; else it is directly interpreted as the new velocity of the base body. Note: if a base joint is set that is not a free joint, no check is made that the new velocity is compatible with the base joint’s DoFs. To guarantee a feasible velocity, use instead FromJointU.

__init__(base_u)#
base_u: wp.array(dtype=wp.spatial_vectorf, ndim=1)#

Per-world base body velocity array.

class FromJointQ(joint_q=None)#

Bases: object

Reset option, to set body poses from actuator coordinates and/or base joint coordinates. Extracts relevant data from joint coordinates, and applies position-level Forward Kinematics and/or a global transformation at the base. Note: angles outside the [-2pi, 2pi] range around initial coordinates will be remapped automatically.

__init__(joint_q=None)#
class FromJointU(joint_u=None)#

Bases: object

Reset option, to set body velocities from actuator velocities and/or base joint velocity. Extracts relevant data from joint velocities, and applies velocity-level Forward Kinematics and/or a global composition with the base velocity.

__init__(joint_u=None)#
class Preserve#

Bases: object

Reset option, to preserve current values, assuming without check that they are consistent.

__init__()#
class ToDefault#

Bases: object

Reset option, to reset to default values (e.g., initial pose and zero velocity).

__init__()#
classmethod from_joints()#

Instantiates a reset config for running FK at the position and velocity level, to set new poses and velocities from current per-joint values in the state container.

classmethod preserve()#

Instantiates a reset config for preserving all state components.

classmethod to_default()#

Instantiates a reset config for resetting all state components to default values.

__init__(body_poses=SolverKamino.ResetConfig.ToDefault(), body_velocities=SolverKamino.ResetConfig.ToDefault(), base_pose=SolverKamino.ResetConfig.ToDefault(), base_velocity=SolverKamino.ResetConfig.ToDefault())#
base_pose: ToDefault | Preserve | FromJointQ | FromBaseQ = SolverKamino.ResetConfig.ToDefault()#

Reset option for the floating base pose:

  • ToDefault: reset the base pose to its initial value.

  • Preserve: preserve the current base pose, as read from current joint coordinates (if a base joint was set) or body poses (otherwise).

  • FromJointQ: read the base pose from joint coordinates, assuming a base joint was set. Behaves like ToDefault otherwise (as a fallback).

  • FromBaseQ: use the provided base pose.

Body poses and velocities are transformed (if needed) to match the prescribed base pose, while preserving relative poses and velocities.

base_velocity: ToDefault | Preserve | FromJointU | FromBaseU = SolverKamino.ResetConfig.ToDefault()#

Reset option for the floating base velocity:

  • ToDefault: reset the base velocity to zero.

  • Preserve: preserve the current base velocity, as read from current joint velocities (if a base joint was set) or body velocities (otherwise), up to transformation due to the new base pose if applicable.

  • FromJointU: read the base velocity from joint velocities, assuming a base joint was set. Behaves like ToDefault otherwise (as a fallback).

  • FromBaseU: use the provided base velocity.

Body velocities are updated to match the prescribed base velocity, while preserving relative velocities.

body_poses: ToDefault | Preserve | FromJointQ | FromActuatorQ = SolverKamino.ResetConfig.ToDefault()#

Reset option for body poses:

  • ToDefault: reset poses to their initial values.

  • Preserve: preserve poses in the state container, assuming they are consistent.

  • FromJointQ: extract actuator coordinates from joint coordinates, and compute consistent body poses with a position-level forward kinematics solve.

  • FromActuatorQ: compute consistent body poses for the prescribed actuator coordinates with a position-level forward kinematics solve.

body_velocities: ToDefault | Preserve | FromJointU | FromActuatorU = SolverKamino.ResetConfig.ToDefault()#

Reset option for body velocities:

  • ToDefault: reset velocities to zero.

  • Preserve: if body poses are preserved, preserve velocities in the state container, assuming they are consistent. Otherwise, behaves like FromJointU, transferring current joint velocities in the state container, to the extent possible, to the new body poses.

  • FromJointU: extract actuator velocities from joint velocities, and compute consistent body velocities with a velocity-level forward kinematics solve.

  • FromActuatorU: compute consistent body velocities for the prescribed actuator velocities with a velocity-level forward kinematics solve.

static register_custom_attributes(builder)#

Register custom attributes for SolverKamino.

Parameters:

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

__init__(model, config=None)#

Constructs a Kamino solver for the given model and optional configurations.

Parameters:

  • model (Model) – The Newton model for which to create the Kamino solver instance.

  • config (Config | None) –

    Explicit user-provided configurations for the Kamino solver.

    If None, configurations will be parsed from the Newton model’s custom attributes using SolverKamino.Config.from_model(), e.g. to be loaded from USD assets. If that also fails, then default configurations will be used.

notify_model_changed(flags)#

Propagate Newton model property changes to Kamino’s internal ModelKamino.

Parameters:

flags (ModelFlags | int) – Bitmask of ModelFlags or custom int bits indicating which properties changed.

reset(state, world_mask=None, flags=None, *, config=None)#

Reset the Kamino solver state.

Performs a configurable in-place reset of the simulation state, in all or a subset of worlds, setting body poses and velocities selectively to default or current values, or as per joint coordinates/velocities, using a forward kinematics solve. This is optionally combined with a reset of the pose and velocity of the floating base.

All state components are reset consistently with the new body poses and velocities (unless prescribed otherwise by state flags), and solver-internal buffers are cleared.

Parameters:

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

  • world_mask (array | None) – Optional array of per-world masks indicating which worlds should be reset. Shape of (num_worlds,) and type wp.int8 | wp.bool.

  • flags (StateFlags | int | None) – Optional StateFlags or int bitmask controlling which state attributes need to be reset. If None, all state attributes are reset. Note: currently, this is implementing simply by caching attributes that should not be reset, and restoring them after the Kamino-internal reset. For complex/partial resets, it is recommended to use config instead.

  • config (ResetConfig | None) – Optional reset configuration, controlling the reset behavior for body poses/velocities as well as floating base pose/velocity. If not provided, all components are reset to default (initial) values.

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

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

When contacts is not None (i.e. produced by Model.collide()), those contacts are converted to Kamino’s internal format and used directly, bypassing Kamino’s own collision detector. When contacts is None, Kamino’s internal collision pipeline runs as a fallback.

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 from Newton’s collision pipeline, or None to use Kamino’s internal collision detector.

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

update_contacts(contacts, state=None)#

Converts Kamino contacts to Newton’s Contacts format.

Note: produces undefined behavior if a different Newton Contacts object was passed to step().

Parameters:

  • contacts (Contacts) – The Newton Contacts object to populate.

  • state (State | None) – Simulation state providing body_q for converting world-space contact positions to body-local frame.