newton.ik.IKObjective#

class newton.ik.IKObjective[source]#

Bases: object

Base class for inverse-kinematics objectives.

Each objective contributes one or more residual rows to the global IK system and can optionally provide an analytic Jacobian. Objective instances are shared across a batch of problems, so per-problem data such as targets should live in device arrays and be indexed through the problem_idx mapping supplied at evaluation time.

Subclasses should override residual_dim(), compute_residuals(), and compute_jacobian_autodiff(). They can additionally override supports_analytic() and compute_jacobian_analytic() when an analytic Jacobian is available.

__init__()#
bind_device(device)#

Bind this objective to the Warp device used by the solver.

compute_jacobian_analytic(body_q, joint_q, model, jacobian, joint_S_s, start_idx)#

Fill this objective’s Jacobian block analytically, if supported.

Parameters:

  • body_q (array(ndim=2, dtype=transformf)) – Batched body transforms for the current evaluation rows, shape [n_batch, body_count].

  • joint_q (array(ndim=2, dtype=float32)) – Batched joint coordinates for the current evaluation rows, shape [n_batch, joint_coord_count].

  • model (Model) – Shared articulation model.

  • jacobian (array(ndim=3, dtype=float32)) – Global Jacobian buffer to update, shape [n_batch, total_residual_count, joint_dof_count].

  • joint_S_s (array(ndim=2, dtype=vector(length=6, dtype=float32))) – Batched motion-subspace columns, shape [n_batch, joint_dof_count].

  • start_idx (int) – First residual row reserved for this objective.

compute_jacobian_autodiff(tape, model, jacobian, start_idx, dq_dof)#

Fill this objective’s Jacobian block with autodiff gradients.

Parameters:

  • tape (Tape) – Recorded Warp tape whose output is the global residual buffer.

  • model (Model) – Shared articulation model.

  • jacobian (array(ndim=3, dtype=float32)) – Global Jacobian buffer to update, shape [n_batch, total_residual_count, joint_dof_count].

  • start_idx (int) – First residual row reserved for this objective.

  • dq_dof (array(ndim=2, dtype=float32)) – Differentiable joint update variable for the current batch, shape [n_batch, joint_dof_count].

compute_residuals(body_q, joint_q, model, residuals, start_idx, problem_idx)#

Write this objective’s residual block into a global buffer.

Parameters:

  • body_q (array(ndim=2, dtype=transformf)) – Batched body transforms for the current evaluation rows, shape [n_batch, body_count].

  • joint_q (array(ndim=2, dtype=float32)) – Batched joint coordinates [m or rad] for the current evaluation rows, shape [n_batch, joint_coord_count].

  • model (Model) – Shared articulation model.

  • residuals (array(ndim=2, dtype=float32)) – Global residual buffer that receives this objective’s residual rows, shape [n_batch, total_residual_count].

  • start_idx (int) – First residual row reserved for this objective inside the global residual buffer.

  • problem_idx (array(ndim=1, dtype=int32)) – Mapping from evaluation rows to base problem indices, shape [n_batch]. Use this when objective data is stored once per original problem but the solver expands rows for multiple seeds or line-search candidates.

init_buffers(model, jacobian_mode)#

Allocate any per-objective buffers needed by the chosen backend.

Parameters:

  • model (Model) – Shared articulation model.

  • jacobian_mode (IKJacobianType) – Jacobian backend that will evaluate this objective.

residual_dim()#

Return the number of residual rows contributed by this objective.

set_batch_layout(total_residuals, residual_offset, n_batch)#

Register this objective’s rows inside the optimizer’s global system.

Parameters:

  • total_residuals (int) – Total number of residual rows across all objectives.

  • residual_offset (int) – First row reserved for this objective inside the global residual vector and Jacobian.

  • n_batch (int) – Number of evaluation rows processed together. This is the expanded solver batch, not necessarily the number of base IK problems.

Note

Per-problem buffers such as targets should still be sized by the base problem count and accessed through the problem_idx mapping supplied during residual and Jacobian evaluation.

supports_analytic()#

Return True when this objective implements an analytic Jacobian.