Setup Kinematics Solver

SUMMARY

Setup Kinematics Solver initializes a C++ inverse-kinematics solver by name and caches it on the robot object. The cached solver is reused across inverse_kinematics calls until a different solver is requested. Use it to pre-warm the solver of your choice before entering a tight IK loop.

UNITS

solver is a string token (no units). Returns None.

The Skill

robot.setup_kinematics_solver(solver="multi_start_clik")

The Code

"""
Pre-initialize an IK solver, then solve IK with it.

Supports Universal Robots (UR), Epson, and virtual.

Usage:
    python setup_kinematics_solver.py
"""

from loguru import logger

from telekinesis.synapse.robots.manipulators import universal_robots


def main():
    """Pre-initialize the multi_start_clik solver, then solve IK with it."""

    #===================== Create Robot ==========================================
    robot = universal_robots.UniversalRobotsUR10E(name='UR10e')

    # ==================== Run Skill ============================================
    # Get all supported kinematics solvers
    solvers = robot.supported_kinematics_solvers
    logger.info(f"Supported solvers: {solvers}")

    # Pre-load the desired solver so the first inverse_kinematics call is fast
    robot.setup_kinematics_solver(solver="multi_start_clik")

    # Check active kinematic solver
    active_kinematics_solver = robot.active_kinematics_solver
    logger.info(f"Active kinematics solver: {active_kinematics_solver}")

    # Solve IK using the cached solver (no need to pass ``solver=`` again)
    target_pose = [0.5, 0.2, 0.3, 180.0, 0.0, 0.0]
    try:
        q = robot.inverse_kinematics(target_pose=target_pose)
        logger.success(f"IK solution: {q}")

        # ================ Visualization (Optional) ==============================
        robot.set_joint_positions(joint_positions=q)
        robot.visualize_rerun(live=False)
    except (RuntimeError, TypeError, ValueError) as e:
        logger.error(f"IK failed: {type(e).__name__}: {e}")


if __name__ == "__main__":
    main()

Parameter Configuration

Parameter	Type	Default	Description
solver	str	required	Solver name. Must be present in robot.supported_kinematics_solvers. Common values: "clik", "multi_start_clik", "tracik".

Returns

Type	Description
None	The solver is cached on the robot. Read robot.active_kinematics_solver to confirm.

Raises

Exception	Condition
ValueError	solver is not one of the names in robot.supported_kinematics_solvers
RuntimeError	The C++ IK backends are not built into the Synapse install

Where to Use the Skill

• Pre-warming - Pay the solver instantiation cost once at startup before entering a real-time IK loop
• Solver selection - Explicitly select a solver appropriate for your workload (single-shot vs. multi-start vs. TRAC-IK)
• Benchmarking - Initialize each candidate solver in turn to compare convergence and timing

When Not to Use the Skill

Do not use Setup Kinematics Solver when:

• You are happy with the default - inverse_kinematics will auto-select and cache the "multi_start_clik" solver on the first call. Manual setup is only required when you want a different solver or earlier instantiation.
• C++ solvers are unavailable - a RuntimeError is raised if the C++ IK backends are not built into your Synapse install. Reinstall with the C++ extensions or use the Python fallback paths.