Skip to content

novaphy.ik

Inverse-kinematics utilities for NovaPhy articulations. The implemented API is a function-style layer (damped least-squares + Levenberg-Marquardt adaptive damping over flat per-link joints / bodies lists). A class-style layer (IKSolver / IKObjective / IKOptimizer family) is listed here as a placeholder for future implementation.

from novaphy.ik import ik_solver

q_sol, converged = ik_solver.solve_ik(joints_or_bundle, q0, target_xyz)

Import path

ik is not in the top-level novaphy.__all__ today. Import the module explicitly:

from novaphy.ik import ik_solver
# or
from novaphy.ik.ik_solver import solve_ik, solve_ik_pose

Demos and tests already use this pattern; see python/demos/demo_ik_arm.py and python/demos/ik_arm_demo/.

Algorithm Overview

The IK implementation uses Levenberg-Marquardt adaptive damping over the normal-equation form:

(J^T J + λ I) Δq = J^T e

with finite-difference Jacobians for the position rows and the geometric (angular-velocity) Jacobian for orientation rows. Orientation error is measured in axis-angle form derived from a robust quaternion path that stays well-conditioned at 180°. Adaptive damping accepts / rejects each step and updates λ accordingly.

Joint limits are supported via box clipping on q + step_size · Δq. Multi-seed sampling (solve_ik_pose_best_of_seeds) starts from several randomized seeds and returns the lowest-cost solution.

Implemented API (function-style)

Class / Function Description
JointBodyBundle Lightweight (joints, bodies) container that replaces the deleted Articulation struct.
solve_ik() Position-only IK with LM adaptive damping.
solve_ik_pose() Pose IK (position + orientation) with LM adaptive damping.
solve_ik_pose_best_of_seeds() Multi-seed sampling wrapper around solve_ik_pose.
compute_jacobian_position() Finite-difference position Jacobian (3 × nv).
compute_jacobian_angular_velocity() Geometric angular-velocity Jacobian (3 × nv).
get_ee_position() World-frame end-effector position from q.
get_ee_rotation() World-frame end-effector rotation matrix from q.
rotation_error_axis_angle() Robust axis-angle rotation error vector.

Placeholder API (class-style)

The following class-style symbols are listed as placeholders. They are not yet implemented — clicking through gives a "Scaffold — not implemented yet" page. When they ship, the function-style API stays as the low-level path and the class layer is built on top, adding objective composition, multi-seed sampling, and pluggable optimizer backends.

Class / Enum Description Status
IKSolver High-level front end with optional multi-seed sampling. Scaffold
IKObjective Base class for IK objectives. Scaffold
IKPositionObjective Match world position of a point on a link. Scaffold
IKRotationObjective Match world orientation of a link frame. Scaffold
IKJointLimitObjective Penalize per-DOF joint-limit violations. Scaffold
IKJacobianMode Jacobian backend selector (analytic / FD / autodiff). Scaffold
IKOptimizer Optimizer base class. Scaffold
IKLBFGS L-BFGS optimizer for batched IK. Scaffold
IKLevenbergMarquardt Levenberg-Marquardt optimizer for batched IK. Scaffold
IKSamplingMode Multi-seed sampling strategy enumeration. Scaffold

Demos

Demo What it shows
python/demos/demo_ik_arm.py Damped-least-squares IK on a serial arm.
python/demos/ik_arm_demo/benchmark.py Benchmark harness over solve_ik_pose and solve_ik_pose_best_of_seeds.
python/demos/ik_arm_demo/ik_logic.py Pose IK in a runtime loop.

See Also