Telekinesis Agentic Skill Library

Appearance

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.

SUPPORTED ROBOTS

Available on all supported manipulators.

UNITS

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

The Skill ​

python
robot.setup_kinematics_solver(solver="multi_start_clik")

The Code ​

python
"""
Pre-initialize an IK solver for the Synapse SDK.

``setup_kinematics_solver`` initializes an IK solver by name and caches
it on the robot, so subsequent ``inverse_kinematics`` calls skip the
solver-construction cost. 

Supported solver names: ``"clik"``, ``"multi_start_clik"``, ``"tracik"``.

Universal Robots (UR10e) is used here purely for illustration. It supports all robots.

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 the robot (no connect required — IK runs on the kinematic model)
    robot = universal_robots.UniversalRobotsUR10E()

    # 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}")
    except (RuntimeError, TypeError, ValueError) as e:
        logger.error(f"IK failed: {type(e).__name__}: {e}")


if __name__ == "__main__":
    main()

The Explanation of the Code ​

python
from telekinesis.synapse.robots.manipulators import universal_robots

robot = universal_robots.UniversalRobotsUR10E()

Create the robot. UR10e is used here for illustration; the same pattern works for every supported brand. No connect() is required - IK runs against the kinematic model.

python
solvers = robot.supported_kinematics_solvers

Read the list of solvers compiled into your Synapse install. Always cross-check against this before requesting one by name. Currently supported:

SolverDescription
"clik"Closed-loop IK from a single seed. Fastest, sensitive to the seed.
"multi_start_clik"Multi-start CLIK. Default in inverse_kinematics; more robust at the cost of extra solves.
"tracik"TRAC-IK solver. Available only when the C++ TRAC-IK backend is built.
python
robot.setup_kinematics_solver(solver="multi_start_clik")

Instantiate the named solver against the robot's URDF (using urdf_path, model_dir, and default_tcp) and cache it on the robot. The construction cost is paid here so the first inverse_kinematics call is fast.

python
active_kinematics_solver = robot.active_kinematics_solver

Confirm which solver is currently cached. Subsequent IK calls use this until a different solver name is passed - at which point setup_kinematics_solver runs again automatically and swaps the cache.

python
q = robot.inverse_kinematics(target_pose=target_pose)

Solve IK against the pre-warmed solver. No need to pass solver= again - the cached instance is reused.

How to Tune the Parameters ​

ParameterTypeDefaultDescription
solverstr-Solver name. Must be present in robot.supported_kinematics_solvers. Common values: "clik", "multi_start_clik", "tracik".

Return Value ​

TypeDescription
NoneThe solver is cached on the robot. Read robot.active_kinematics_solver to confirm.

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.