Release v1.3.1 — IK Convergence Overhaul & TRAC-IK Solver

v1.3.1 — IK Convergence Overhaul & TRAC-IK Solver

Major overhaul of all inverse kinematics solvers, improving convergence rates
from ~70% to 96%+. Introduces the TRAC-IK module — a high-performance solver
combining Damped Least Squares (DLS) and Sequential Quadratic Programming
(SQP).

Highlights

Solver	Before (v1.3.0)	After (v1.3.1)
iterative_inverse_kinematics	~70%	90–100%
smart_inverse_kinematics	~70%	96–100%
robust_inverse_kinematics	~75%	96–100%
trac_ik (NEW)	—	96% at 200ms

New: TRAC-IK Module

A production-ready IK solver in ManipulaPy/trac_ik.py:

# Simplest usage — 96% success rate, 200ms default timeout
theta, success, solve_time = robot.trac_ik(target_pose)

# With parallel DLS+SQP for harder problems
theta, success, solve_time = robot.trac_ik(target_pose, timeout=0.5,
use_parallel=True)

# Convenience function
from ManipulaPy.trac_ik import trac_ik_solve
theta, success, solve_time = trac_ik_solve(robot, target_pose)

Algorithm details:
- SVD-robust Jacobian solve as the primary numerical path
- Levenberg-Marquardt adaptive damping with trust region
- Perturbation-based stagnation recovery (escapes local minima)
- Backtracking line search for step acceptance
- 5 diverse initial guesses: workspace heuristic, midpoint, zero, flipped
midpoint, random
- Sequential mode (default) with per-guess time budgeting — avoids Python GIL
contention
- Parallel mode (optional): 3-worker architecture running DLS tasks
concurrently with SQP fallback

Changed

- iterative_inverse_kinematics() — Complete redesign with geometric error
model, SVD-robust pseudoinverse, Levenberg-Marquardt damping, perturbation
recovery, and 5-scale backtracking line search. Default max_iterations
increased to 10,000.
- smart_inverse_kinematics() — New auto_fallback=True parameter automatically
tries robust_inverse_kinematics when the initial strategy fails.
- robust_inverse_kinematics() — Rewritten with 10 diverse initial-guess
strategies for broader workspace coverage.

Fixed

- IK convergence failures for targets requiring large joint rotations
- Jacobian singularity handling — SVD-based solve prevents NaN/Inf in
near-singular configurations
- Solver stagnation — automatic perturbation breaks out of local minima

Upgrade Guide

No breaking changes. All IK API signatures are backward compatible — existing
code works without modification. The solvers simply converge more reliably
now.

# Same API, better results
theta, success, iters = robot.iterative_inverse_kinematics(target, guess)

# New auto-fallback option
theta, success, iters = robot.smart_inverse_kinematics(
    target, strategy="workspace_heuristic", auto_fallback=True
)

# New TRAC-IK solver
theta, success, solve_time = robot.trac_ik(target, timeout=0.2)

Full Changelog: https://github.com/boelnasr/ManipulaPy/compare/v1.3.0...v1.3.1