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.

Note

Currently still in Beta, so we do not recommend using this solver for production use cases yet, as we expect many things to change in future releases. This includes both the public API and internal implementation; adding support for more simulation features (e.g. joints, constraints, actuators), performance optimizations, 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)

# 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

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 (int) – Bitmask of SolverNotifyFlags indicating which properties changed.

reset(state_out, world_mask=None, actuator_q=None, actuator_u=None, joint_q=None, joint_u=None, base_q=None, base_u=None)#

Resets the simulation state given a combination of desired base body and joint states, as well as an optional per-world mask array indicating which worlds should be reset. The reset state is written to state_out.

For resets given absolute quantities like base body poses, the state_out must initially contain the current state of the simulation.

Parameters:

  • state_out (State) – The output state container to which the reset state data is written.

  • 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

  • actuator_q (array | None) –

    Optional array of target actuated joint coordinates.

    Shape of (num_actuated_joint_coords,) and type wp.float32

  • actuator_u (array | None) –

    Optional array of target actuated joint DoF velocities.

    Shape of (num_actuated_joint_dofs,) and type wp.float32

  • joint_q (array | None) –

    Optional array of target joint coordinates.

    Shape of (num_joint_coords,) and type wp.float32

  • joint_u (array | None) –

    Optional array of target joint DoF velocities.

    Shape of (num_joint_dofs,) and type wp.float32

  • base_q (array | None) –

    Optional array of target base body poses.

    Shape of (num_worlds,) and type wp.transformf

  • base_u (array | None) –

    Optional array of target base body twists.

    Shape of (num_worlds,) and type wp.spatial_vectorf

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 (State) – The input state.

  • state_out (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)#

Converts Kamino contacts to Newton’s Contacts format.

Parameters:

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

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