FastSim Portable Kinematics Solver

This package provides deterministic FK and IK without importing a simulator. It loads a URDF once, selects a serial chain by its base and tip link, and solves with damped least squares. The same model and request therefore produce the same joint solution when FastSim switches between Isaac Lab, MuJoCo, and PyBullet.

Install

bash

python -m pip install fastsim-kinematics-solver-spi fastsim-kinematics-solver-portable

First solve

Run the complete example from this repository:

bash

python examples/quickstart.py

The important calls are intentionally small:

python

from fastsim_kinematics_solver_portable import PortableKinematicsSolver
from fastsim_kinematics_solver_spi import IKRequest, JointState, Pose

solver = PortableKinematicsSolver.from_urdf(urdf_text)
result = solver.solve(
    IKRequest(
        request_id="pick-pregrasp",
        run_id="run-1",
        generation=1,
        robot_entity_id="robot",
        base_frame_id="base_link",
        tip_frame_id="tool_link",
        target=Pose("base_link", (0.45, 0.10, 0.35), (0.0, 0.0, 0.0, 1.0)),
        start=JointState(("joint1", "joint2"), (0.0, 0.0), ("rad", "rad")),
    )
)

Use result.status before reading result.solutions. Expected failures are data, not exceptions: no_solution, timeout, cancelled, unsupported, and invalid_request each include a stable failure_code and a short message. Joint IDs and units must follow the selected URDF chain exactly. In FastSim, run_id and generation come from the active Run; they are echoed so the Application layer can reject a stale result after reset.

Honest v1 capability boundary

URDF fixed, revolute, continuous, and prismatic joints are supported.
Branching robot trees are supported; each call selects exactly one base-to-tip serial chain. This covers choosing either arm of a dual-arm robot.
Serial prismatic/revolute joints used as virtual base axes are supported.
FK is deterministic. IK supports a warm start, deterministic seeded initialization, joint locking, limits, tolerances, iteration limits, timeout, and cooperative cancellation.
Only collision_mode=none and max_solutions=1 are implemented in v1. Other requests return unsupported; they never silently fall back to weaker behavior.
Closed chains, planar/floating URDF joints, mimic joints, and collision-aware IK are not implemented in this provider.

FastSim discovers the provider from fastsim.kinematics_solvers under kinematics-solver://fastsim/portable. Creating a provider computes the URDF digest once. solve() does no file IO, simulator calls, network calls, or hashing.