ssik 1.0.0__tar.gz

ssik-1.0.0/.gitignore

@@ -0,0 +1,58 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+.eggs/
+build/
+dist/
+wheels/
+.venv/
+venv/
+env/
+
+# Generated by hatch-vcs
+src/ssik/_version.py
+
+# Build artefacts
+*.so
+*.dylib
+*.dll
+*.o
+*.obj
+_skbuild/
+CMakeCache.txt
+CMakeFiles/
+cmake_install.cmake
+Makefile
+
+# Generated solvers (development; the package will use ~/.cache/ssik/ at runtime)
+generated/
+
+# Tests
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking / lint caches
+.mypy_cache/
+.ruff_cache/
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# mkdocs build output
+site/
+*.cpython-*-darwin.so
+*.cpython-*-linux-gnu.so
+src/ssik/**/*.c
+src/ssik/**/*.html
+# Cython artefacts from per-arm artifact compile (#137 Slice 3).
+tests/artifacts/*.c
+tests/artifacts/*.html
+build/

ssik-1.0.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Siddhartha Srinivasa
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ssik-1.0.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: ssik
+Version: 1.0.0
+Summary: Analytical inverse kinematics for 6R and 7R revolute arms. Returns every IK branch at machine precision.
+Project-URL: Repository, https://github.com/personalrobotics/ssik
+Project-URL: Issues, https://github.com/personalrobotics/ssik/issues
+Author: Siddhartha Srinivasa
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: ik-geo,inverse-kinematics,kinematics,robotics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: cython>=3.1
+Requires-Dist: numpy>=2.0
+Requires-Dist: scipy>=1.13
+Requires-Dist: sympy>=1.10
+Provides-Extra: urdf
+Requires-Dist: urchin>=0.0.27; extra == 'urdf'
+Description-Content-Type: text/markdown
+
+# ssik
+
+[![PyPI](https://img.shields.io/pypi/v/ssik.svg)](https://pypi.org/project/ssik/)
+[![Python](https://img.shields.io/pypi/pyversions/ssik.svg)](https://pypi.org/project/ssik/)
+[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE)
+
+Analytical inverse kinematics for 6R and 7R revolute robot arms. Each arm becomes a single self-contained Python module — `import franka_panda_ik; franka_panda_ik.solve(T)` — that returns **every IK branch** at machine-precision FK closure.
+
+## Install
+
+```bash
+pip install ssik
+```
+
+Python 3.11+. Wheels for Linux x86_64, macOS arm64, macOS x86_64, Windows x86_64.
+
+## Quickstart
+
+```python
+from ssik.prebuilt import franka_panda_ik
+import numpy as np
+
+T_target = np.eye(4); T_target[:3, 3] = [0.5, 0.1, 0.3]
+sols = franka_panda_ik.solve(T_target)      # every analytical IK branch
+```
+
+`sols` is a `list[Solution]`. Each `Solution` carries `q` (the joint vector), `fk_residual` (‖FK(q) − T‖), and which polish path fired. Empty list = pose is unreachable.
+
+## The artifact model
+
+ssik is built around **per-arm artifact modules**. Each artifact is a single `.py` file with the per-arm KinBody constants, the dispatched solver, and any cached symbolic preprocessing already baked in. **No URDF parsing, no `urchin`, no `sympy` on the runtime import path.** A robot stack that imports `<arm>_ik.py` carries no algorithmic complexity beyond what the build pipeline already resolved.
+
+This is the same idea OpenRAVE's IKFast had — generate per-arm specialised IK code at design time, run pure numeric at deployment — but without IKFast's brittleness on non-Pieper geometries.
+
+There are two artifact paths:
+
+### Use a prebuilt arm (`ssik.prebuilt`)
+
+The wheel ships 8 ready-to-import artifacts:
+
+| Module | Arm | Class |
+|---|---|---|
+| `ur5_ik` | Universal Robots UR5 | three-parallel 6R |
+| `puma560_ik` | KUKA Puma 560 | Pieper 6R (spherical wrist) |
+| `jaco2_ik` | Kinova JACO 2 | **non-Pieper 6R** |
+| `iiwa14_ik` | KUKA iiwa LBR 14 | SRS 7R |
+| `gen3_ik` | Kinova Gen3 7-DOF | **approximate-SRS 7R** |
+| `franka_panda_ik` | Franka Panda | anthropomorphic 7R |
+| `rizon4_ik` | Flexiv Rizon 4 | **non-SRS 7R** |
+| `kassow_kr810_ik` | Kassow KR810 | **non-SRS 7R** |
+
+```python
+from ssik.prebuilt import iiwa14_ik
+sols = iiwa14_ik.solve(T_target)
+```
+
+For trajectory tracking and IK-based teleop, the canonical pattern is "give me the IK closest to where the robot is now":
+
+```python
+# Robot's current configuration (from joint sensors, last command, etc.).
+q_current = np.array([0.0, -0.5, 0.0, 0.7, 0.0, 1.2, 0.0])
+
+# Target pose updates every control tick (VR controller, planner, etc.).
+T_target = ...
+
+# max_solutions=1 + q_seed: solver visits lock-samples in nearest-to-seed
+# order and short-circuits on the first in-limits branch (~5-6× faster
+# than the full sweep on 7R jointlock arms; sub-ms on 6R / SRS arms).
+sols = franka_panda_ik.solve(T_target, max_solutions=1, q_seed=q_current)
+q_command = sols[0].q if sols else q_current
+```
+
+### Build an artifact for your own arm
+
+For any arm not in the prebuilt set, run `ssik build` once against the URDF:
+
+```bash
+ssik build my_arm.urdf --base base_link --ee tool0
+# → my_arm_ik.py
+```
+
+Build time depends on solver class:
+- **<1 s** for tier-0 closed-form (UR-class, Pieper, SRS-class 7R)
+- **~30 s** for non-Pieper 6R (Raghavan–Roth symbolic derivation)
+- **7–20 min** for non-SRS 7R (cached Husty–Pfurner per lock sample)
+
+Ship the emitted `.py` alongside your robot stack. Once built, use it exactly like a prebuilt:
+
+```python
+import my_arm_ik
+sols = my_arm_ik.solve(T_target)
+```
+
+Re-run `ssik build` after `pip install -U ssik` if you want the latest solver fixes. Old artifacts keep working — they're frozen against the ssik version that built them. `ssik build` requires the URDF extras: `pip install ssik[urdf]`.
+
+### Development path: `Manipulator.from_urdf` (not for deployment)
+
+For one-off experiments before committing to a build artifact, ssik also exposes the runtime classifier as a Python class:
+
+```python
+import ssik
+arm = ssik.Manipulator.from_urdf("my_arm.urdf", base="base_link", ee="tool0")
+sols = arm.solve(T_target, max_solutions=1, q_seed=q_current)
+```
+
+Every fresh process re-runs URDF parsing, topology classification, and (for non-Pieper sub-chains) first-call sympy preprocessing — so this path is **strictly slower than the build-artifact path in production** and requires `urchin` + `sympy` on the runtime path (`pip install ssik[urdf]`). Once dispatch is settled, switch to `ssik build`.
+
+Contributors extending ssik's own test fixtures (vs deploying for their own arm) use `ssik add-arm`; see [CONTRIBUTING.md](CONTRIBUTING.md#adding-a-new-arm-fixture).
+
+## What `solve()` returns
+
+A `list[Solution]`. Each `Solution` has:
+
+- `q` — joint-angle vector (length DOF)
+- `fk_residual` — `‖FK(q) − T‖_F` (Frobenius norm against the original URDF / spec FK)
+- `refinement_used` — `"none"` or `"lm"` if Levenberg–Marquardt polish fired
+
+A single 6-DOF target pose admits up to **16 analytical IK branches** (8 typical for a Pieper-class arm: 4 shoulder × 2 elbow, with the wrist deterministic). For 7R redundant arms the IK is a 1-parameter family; ssik discretises it into 32–256 branches per pose depending on the swivel-sample count.
+
+By default `solve()` runs **`respect_limits=True`**: out-of-URDF-limit branches are dropped (with a `q ± 2π` rescue pass first). On 7R jointlock arms the limits filter runs *during* the lock-sweep so `max_solutions=1` short-circuits on the first in-limits candidate rather than wasting samples on branches the postprocess would discard. Pass `respect_limits=False` for the raw geometric set.
+
+The `allow_refinement=True` opt-in runs LM polish per algebraic candidate at a few hundred microseconds per branch — useful when an algebraic candidate lands just above `fk_atol` near a kinematic singularity.
+
+## Tuning knobs
+
+### `TolerancePolicy` — six thresholds, one object
+
+`solve()` accepts an optional `policy=` kwarg. The default `ssik.DEFAULT_TOLERANCE_POLICY` works for every shipped fixture; reach for a custom policy when a real arm's URDF has structural near-degeneracies (axes that *almost* but not exactly meet) or when you want tighter / looser FK closure than the defaults provide.
+
+```python
+from ssik import TolerancePolicy, DEFAULT_TOLERANCE_POLICY
+
+policy = TolerancePolicy(
+    axis_parallel=1e-8,         # ||a × b||: when two axes are "parallel"
+    axis_intersect=1e-8,        # perpendicular distance: when two lines "meet"
+    subproblem_feasibility=1e-9,# is_ls boundary inside SP1-SP6
+    subproblem_numerical=1e-5,  # FK-closure filter on algebraic candidates
+    subproblem_degeneracy=1e-12,# rank-drop threshold; below this, return []
+    subproblem_dedup=1e-3,      # angle-space tolerance for collapsing duplicates
+)
+sols = my_arm_ik.solve(T_target, policy=policy)
+```
+
+The fields are named for *why* they exist so log messages can say `"SP6 sign branch rejected: closure 1.2e-4 > subproblem_numerical 1e-5"` instead of citing magic numbers.
+
+### `ssik.postprocess` — composable filters
+
+`solve()` returns the geometric IK set. For application-specific filtering, four helpers in `ssik.postprocess` compose into the typical "robot-aware IK" pipeline:
+
+```python
+from ssik.postprocess import (
+    respect_limits, wrap_to_limits, nearest_to_seed, take_first,
+)
+
+sols = my_arm_ik.solve(T_target, respect_limits=False)  # raw geometric set
+sols = wrap_to_limits(sols, my_arm_ik._KB)              # try q ± 2π to bring in
+sols = respect_limits(sols, my_arm_ik._KB)              # drop anything still outside
+sols = nearest_to_seed(sols, q_current)                 # sort by wrap-to-pi distance
+sols = take_first(sols, k=4)                            # top-k after ranking
+```
+
+By default `solve()` already runs `wrap_to_limits` + `respect_limits`; the standalone helpers exist for callers who want a different order, a different metric, or to add their own filters (collision-aware filtering, dexterity scoring, custom seed metrics) between the layers.
+
+Out of scope: collision filtering (use FCL or similar at the application layer) and continuous-trajectory smoothness (typically a separate planner concern).
+
+## How it compares
+
+Numerical-IK libraries take a seed, run damped least-squares to a **single** converged configuration, and stop. ssik returns **every analytical branch** at machine precision. Branch enumeration matters for motion planning (try every branch, pick the one with best clearance), for dexterity analysis (the manipulability ellipsoid is per-branch), and for trajectory continuation across kinematic singularities.
+
+EAIK (Ostermeier 2024) is the canonical Python wrapper around C++ subproblem-decomposition solvers. It's analytical on the kinematic families it recognises and refuses everything else. Numbers below from [`examples/04_compare_vs_eaik.py`](examples/04_compare_vs_eaik.py) over 100 random reachable poses per arm, Apple M3 single-thread, mean ± 95% CI via 1000-resample bootstrap. FK residual is the Frobenius norm `‖FK(q) − T‖` against the original URDF / spec FK.
+
+| Arm (class) | EAIK | ssik |
+|---|---|---|
+| UR5 (Pieper 6R, three-parallel) | 5 ± 0 µs / FK 2e-15 / 4 sols | 556 ± 12 µs / FK 2e-9 / 4 sols |
+| Puma 560 (Pieper 6R, spherical wrist) | 5 ± 1 µs / FK 3e-14 / 8 sols | 245 ± 3 µs / FK 2e-14 / 8 sols |
+| JACO 2 (**non-Pieper 6R**) | **refuses** ("6R-Unknown Kinematic Class") | 1.02 ± 0.04 ms / FK 3e-6 / 2 sols |
+| iiwa14 (SRS 7R) | **refuses** ("only 1-6R robots are solvable") | 5.10 ± 0.07 ms / FK 4e-13 / 96 sols |
+| Gen3 (**approximate-SRS 7R**, 12 mm offset) | **refuses** ("only 1-6R") | 41.83 ± 1.15 ms / FK 1e-12 / 47 sols |
+| Franka Panda (anthropomorphic 7R) | **refuses** ("only 1-6R") | 28.03 ± 2.57 ms / FK 7e-13 / 9 sols |
+| Rizon 4 (**non-SRS 7R**) | **refuses** ("only 1-6R") | 30.88 ± 8.80 ms / FK 4e-9 / 35 sols |
+| Kassow KR810 (**non-SRS 7R**) | **refuses** ("only 1-6R") | 28.06 ± 10.63 ms / FK 7e-8 / 24 sols |
+
+EAIK is ~100× faster than ssik on Pieper-class 6R — that is its native sweet spot, and ssik does not try to compete there. The interesting cells are the **refuses** ones: non-Pieper 6R (JACO 2) and every 7R arm. Those are the geometries ssik exists for. The "refuses (...)" strings are EAIK's actual error messages, captured verbatim by the bench harness. A numerical-IK comparison (MINK) is tracked separately in [#236](https://github.com/personalrobotics/ssik/issues/236).
+
+## Under the hood
+
+The algorithmic ingredients are not novel — Raghavan–Roth (1990), Manocha–Canny (1994), Singh–Kreutz (1989), Husty–Pfurner (2007). What's new is making the textbook pipelines survive on real ill-conditioned arms (AE-3 leftvar selection on JACO 2 drops `cond(m_quad)` from 3.75 × 10^16 to 127), composing them with a uniform dispatch layer, and packaging the whole thing as a deployable artifact.
+
+Cython hot loops cover the leaf primitives (POE forward kinematics, the Levenberg–Marquardt polish and analytical Jacobian); the rest is pure Python so it stays inspectable.
+
+**Bulletproof testing**: every solver lands with N-way cross-solver agreement on shared fixtures, FK closure ≤ 1e-10 on every retained IK, 500+ Hypothesis-fuzzed random poses per fixture, and an explicit speed bench that has to clear a regression gate. The current suite has **1300+ tests across 11 fixture arms**. Negative-result spikes (a Cython estimate that misses by 2-5×, a codegen-bake on a part that's 0.3% of runtime) are published as closed issues with profile data so the next contributor doesn't repeat the path.
+
+## Documentation
+
+- [docs/arm_coverage.md](docs/arm_coverage.md) — per-arm fixture tables, tested speeds, source URDFs
+- [docs/architecture.md](docs/architecture.md) — solver tier catalog, dispatch flow, build artifact internals, algorithmic lineage
+- [CONTRIBUTING.md](CONTRIBUTING.md) — repo layout, dev setup, testing discipline
+
+## Related libraries
+
+ssik does not compete with these on the arms they cover. Pick the right tool for your geometry.
+
+- [**EAIK**](https://github.com/OstermD/EAIK) (Ostermeier 2024) — Python wrapper around C++ subproblem-decomposition solvers. Analytical, returns all branches on Pieper-class 6R and canonical SRS 7R (with a manual joint lock). Refuses arms outside its recognised kinematic families. Directly benchmarked in the table above.
+- [**IK-Geo**](https://github.com/rpiRobotics/ik-geo) (Elias–Wen 2022/2025) — the reference C++/Rust implementation of subproblem decomposition. Same coverage profile as EAIK. Has Python bindings (`ik-geo` on PyPI); currently pins `pyo3==0.20.3` so the wheel is incompatible with Python 3.13 — track upstream for an update.
+- [**IKFast**](http://openrave.org/docs/latest_stable/openravepy/ikfast/) (Diankov 2010, part of OpenRAVE) — the original analytical-IK codegen tool. Symbolic preprocessing in sympy → per-arm C++. Works well on the kinematic families it was tuned for (Pieper-class 6R, spherical-wrist 7R via joint lock); the symbolic pipeline fails on modern sympy for non-Pieper geometries (`mpmath.polyroots` NoConvergence, `Matrix.inv` / `Matrix.det` stalls). LGPL-licensed.
+- [**MINK**](https://github.com/kevinzakka/mink) (Zakka) — Mujoco-native numerical IK via damped least-squares. Iterative, takes a seed, converges to a single configuration. Handles any kinematic geometry but returns one IK, not all branches, and FK closure is proportional to the convergence tolerance (typically 1e-3 to 1e-6 rather than machine precision).
+- [**TracIK**](https://traclabs.com/projects/trac-ik/) (Beeson & Ames 2015) — combined SQP / pseudoinverse Jacobian solver; the ROS Industrial default numerical IK. URDF-native. Same one-branch-per-seed semantics as MINK. The maintained Python binding (`pytracik`) ships a broken arm64 wheel; the ROS-native binding works fine inside ROS.
+- [**KDL-LMA**](https://github.com/orocos/orocos_kinematics_dynamics) — OROCOS KDL's Levenberg-Marquardt numerical IK. Older and less robust than TracIK or MINK on the same problem class.
+
+## License
+
+[BSD-3-Clause](LICENSE). The library incorporates clean-room reimplementations of algorithms from BSD-3-licensed IK-Geo (Elias–Wen 2022/2025) and from the academic publications of Raghavan–Roth (1990), Manocha–Canny (1994), Singh–Kreutz (1989), and Husty–Pfurner (2007). Algorithmic lineage is documented in module docstrings.
+
+## Citation
+
+```bibtex
+@software{ssik,
+  author = {Srinivasa, Siddhartha},
+  title  = {ssik: analytical inverse kinematics for 6R and 7R revolute arms},
+  url    = {https://github.com/personalrobotics/ssik},
+  year   = {2026},
+}
+```

ssik-1.0.0/README.md

@@ -0,0 +1,223 @@
+# ssik
+
+[![PyPI](https://img.shields.io/pypi/v/ssik.svg)](https://pypi.org/project/ssik/)
+[![Python](https://img.shields.io/pypi/pyversions/ssik.svg)](https://pypi.org/project/ssik/)
+[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE)
+
+Analytical inverse kinematics for 6R and 7R revolute robot arms. Each arm becomes a single self-contained Python module — `import franka_panda_ik; franka_panda_ik.solve(T)` — that returns **every IK branch** at machine-precision FK closure.
+
+## Install
+
+```bash
+pip install ssik
+```
+
+Python 3.11+. Wheels for Linux x86_64, macOS arm64, macOS x86_64, Windows x86_64.
+
+## Quickstart
+
+```python
+from ssik.prebuilt import franka_panda_ik
+import numpy as np
+
+T_target = np.eye(4); T_target[:3, 3] = [0.5, 0.1, 0.3]
+sols = franka_panda_ik.solve(T_target)      # every analytical IK branch
+```
+
+`sols` is a `list[Solution]`. Each `Solution` carries `q` (the joint vector), `fk_residual` (‖FK(q) − T‖), and which polish path fired. Empty list = pose is unreachable.
+
+## The artifact model
+
+ssik is built around **per-arm artifact modules**. Each artifact is a single `.py` file with the per-arm KinBody constants, the dispatched solver, and any cached symbolic preprocessing already baked in. **No URDF parsing, no `urchin`, no `sympy` on the runtime import path.** A robot stack that imports `<arm>_ik.py` carries no algorithmic complexity beyond what the build pipeline already resolved.
+
+This is the same idea OpenRAVE's IKFast had — generate per-arm specialised IK code at design time, run pure numeric at deployment — but without IKFast's brittleness on non-Pieper geometries.
+
+There are two artifact paths:
+
+### Use a prebuilt arm (`ssik.prebuilt`)
+
+The wheel ships 8 ready-to-import artifacts:
+
+| Module | Arm | Class |
+|---|---|---|
+| `ur5_ik` | Universal Robots UR5 | three-parallel 6R |
+| `puma560_ik` | KUKA Puma 560 | Pieper 6R (spherical wrist) |
+| `jaco2_ik` | Kinova JACO 2 | **non-Pieper 6R** |
+| `iiwa14_ik` | KUKA iiwa LBR 14 | SRS 7R |
+| `gen3_ik` | Kinova Gen3 7-DOF | **approximate-SRS 7R** |
+| `franka_panda_ik` | Franka Panda | anthropomorphic 7R |
+| `rizon4_ik` | Flexiv Rizon 4 | **non-SRS 7R** |
+| `kassow_kr810_ik` | Kassow KR810 | **non-SRS 7R** |
+
+```python
+from ssik.prebuilt import iiwa14_ik
+sols = iiwa14_ik.solve(T_target)
+```
+
+For trajectory tracking and IK-based teleop, the canonical pattern is "give me the IK closest to where the robot is now":
+
+```python
+# Robot's current configuration (from joint sensors, last command, etc.).
+q_current = np.array([0.0, -0.5, 0.0, 0.7, 0.0, 1.2, 0.0])
+
+# Target pose updates every control tick (VR controller, planner, etc.).
+T_target = ...
+
+# max_solutions=1 + q_seed: solver visits lock-samples in nearest-to-seed
+# order and short-circuits on the first in-limits branch (~5-6× faster
+# than the full sweep on 7R jointlock arms; sub-ms on 6R / SRS arms).
+sols = franka_panda_ik.solve(T_target, max_solutions=1, q_seed=q_current)
+q_command = sols[0].q if sols else q_current
+```
+
+### Build an artifact for your own arm
+
+For any arm not in the prebuilt set, run `ssik build` once against the URDF:
+
+```bash
+ssik build my_arm.urdf --base base_link --ee tool0
+# → my_arm_ik.py
+```
+
+Build time depends on solver class:
+- **<1 s** for tier-0 closed-form (UR-class, Pieper, SRS-class 7R)
+- **~30 s** for non-Pieper 6R (Raghavan–Roth symbolic derivation)
+- **7–20 min** for non-SRS 7R (cached Husty–Pfurner per lock sample)
+
+Ship the emitted `.py` alongside your robot stack. Once built, use it exactly like a prebuilt:
+
+```python
+import my_arm_ik
+sols = my_arm_ik.solve(T_target)
+```
+
+Re-run `ssik build` after `pip install -U ssik` if you want the latest solver fixes. Old artifacts keep working — they're frozen against the ssik version that built them. `ssik build` requires the URDF extras: `pip install ssik[urdf]`.
+
+### Development path: `Manipulator.from_urdf` (not for deployment)
+
+For one-off experiments before committing to a build artifact, ssik also exposes the runtime classifier as a Python class:
+
+```python
+import ssik
+arm = ssik.Manipulator.from_urdf("my_arm.urdf", base="base_link", ee="tool0")
+sols = arm.solve(T_target, max_solutions=1, q_seed=q_current)
+```
+
+Every fresh process re-runs URDF parsing, topology classification, and (for non-Pieper sub-chains) first-call sympy preprocessing — so this path is **strictly slower than the build-artifact path in production** and requires `urchin` + `sympy` on the runtime path (`pip install ssik[urdf]`). Once dispatch is settled, switch to `ssik build`.
+
+Contributors extending ssik's own test fixtures (vs deploying for their own arm) use `ssik add-arm`; see [CONTRIBUTING.md](CONTRIBUTING.md#adding-a-new-arm-fixture).
+
+## What `solve()` returns
+
+A `list[Solution]`. Each `Solution` has:
+
+- `q` — joint-angle vector (length DOF)
+- `fk_residual` — `‖FK(q) − T‖_F` (Frobenius norm against the original URDF / spec FK)
+- `refinement_used` — `"none"` or `"lm"` if Levenberg–Marquardt polish fired
+
+A single 6-DOF target pose admits up to **16 analytical IK branches** (8 typical for a Pieper-class arm: 4 shoulder × 2 elbow, with the wrist deterministic). For 7R redundant arms the IK is a 1-parameter family; ssik discretises it into 32–256 branches per pose depending on the swivel-sample count.
+
+By default `solve()` runs **`respect_limits=True`**: out-of-URDF-limit branches are dropped (with a `q ± 2π` rescue pass first). On 7R jointlock arms the limits filter runs *during* the lock-sweep so `max_solutions=1` short-circuits on the first in-limits candidate rather than wasting samples on branches the postprocess would discard. Pass `respect_limits=False` for the raw geometric set.
+
+The `allow_refinement=True` opt-in runs LM polish per algebraic candidate at a few hundred microseconds per branch — useful when an algebraic candidate lands just above `fk_atol` near a kinematic singularity.
+
+## Tuning knobs
+
+### `TolerancePolicy` — six thresholds, one object
+
+`solve()` accepts an optional `policy=` kwarg. The default `ssik.DEFAULT_TOLERANCE_POLICY` works for every shipped fixture; reach for a custom policy when a real arm's URDF has structural near-degeneracies (axes that *almost* but not exactly meet) or when you want tighter / looser FK closure than the defaults provide.
+
+```python
+from ssik import TolerancePolicy, DEFAULT_TOLERANCE_POLICY
+
+policy = TolerancePolicy(
+    axis_parallel=1e-8,         # ||a × b||: when two axes are "parallel"
+    axis_intersect=1e-8,        # perpendicular distance: when two lines "meet"
+    subproblem_feasibility=1e-9,# is_ls boundary inside SP1-SP6
+    subproblem_numerical=1e-5,  # FK-closure filter on algebraic candidates
+    subproblem_degeneracy=1e-12,# rank-drop threshold; below this, return []
+    subproblem_dedup=1e-3,      # angle-space tolerance for collapsing duplicates
+)
+sols = my_arm_ik.solve(T_target, policy=policy)
+```
+
+The fields are named for *why* they exist so log messages can say `"SP6 sign branch rejected: closure 1.2e-4 > subproblem_numerical 1e-5"` instead of citing magic numbers.
+
+### `ssik.postprocess` — composable filters
+
+`solve()` returns the geometric IK set. For application-specific filtering, four helpers in `ssik.postprocess` compose into the typical "robot-aware IK" pipeline:
+
+```python
+from ssik.postprocess import (
+    respect_limits, wrap_to_limits, nearest_to_seed, take_first,
+)
+
+sols = my_arm_ik.solve(T_target, respect_limits=False)  # raw geometric set
+sols = wrap_to_limits(sols, my_arm_ik._KB)              # try q ± 2π to bring in
+sols = respect_limits(sols, my_arm_ik._KB)              # drop anything still outside
+sols = nearest_to_seed(sols, q_current)                 # sort by wrap-to-pi distance
+sols = take_first(sols, k=4)                            # top-k after ranking
+```
+
+By default `solve()` already runs `wrap_to_limits` + `respect_limits`; the standalone helpers exist for callers who want a different order, a different metric, or to add their own filters (collision-aware filtering, dexterity scoring, custom seed metrics) between the layers.
+
+Out of scope: collision filtering (use FCL or similar at the application layer) and continuous-trajectory smoothness (typically a separate planner concern).
+
+## How it compares
+
+Numerical-IK libraries take a seed, run damped least-squares to a **single** converged configuration, and stop. ssik returns **every analytical branch** at machine precision. Branch enumeration matters for motion planning (try every branch, pick the one with best clearance), for dexterity analysis (the manipulability ellipsoid is per-branch), and for trajectory continuation across kinematic singularities.
+
+EAIK (Ostermeier 2024) is the canonical Python wrapper around C++ subproblem-decomposition solvers. It's analytical on the kinematic families it recognises and refuses everything else. Numbers below from [`examples/04_compare_vs_eaik.py`](examples/04_compare_vs_eaik.py) over 100 random reachable poses per arm, Apple M3 single-thread, mean ± 95% CI via 1000-resample bootstrap. FK residual is the Frobenius norm `‖FK(q) − T‖` against the original URDF / spec FK.
+
+| Arm (class) | EAIK | ssik |
+|---|---|---|
+| UR5 (Pieper 6R, three-parallel) | 5 ± 0 µs / FK 2e-15 / 4 sols | 556 ± 12 µs / FK 2e-9 / 4 sols |
+| Puma 560 (Pieper 6R, spherical wrist) | 5 ± 1 µs / FK 3e-14 / 8 sols | 245 ± 3 µs / FK 2e-14 / 8 sols |
+| JACO 2 (**non-Pieper 6R**) | **refuses** ("6R-Unknown Kinematic Class") | 1.02 ± 0.04 ms / FK 3e-6 / 2 sols |
+| iiwa14 (SRS 7R) | **refuses** ("only 1-6R robots are solvable") | 5.10 ± 0.07 ms / FK 4e-13 / 96 sols |
+| Gen3 (**approximate-SRS 7R**, 12 mm offset) | **refuses** ("only 1-6R") | 41.83 ± 1.15 ms / FK 1e-12 / 47 sols |
+| Franka Panda (anthropomorphic 7R) | **refuses** ("only 1-6R") | 28.03 ± 2.57 ms / FK 7e-13 / 9 sols |
+| Rizon 4 (**non-SRS 7R**) | **refuses** ("only 1-6R") | 30.88 ± 8.80 ms / FK 4e-9 / 35 sols |
+| Kassow KR810 (**non-SRS 7R**) | **refuses** ("only 1-6R") | 28.06 ± 10.63 ms / FK 7e-8 / 24 sols |
+
+EAIK is ~100× faster than ssik on Pieper-class 6R — that is its native sweet spot, and ssik does not try to compete there. The interesting cells are the **refuses** ones: non-Pieper 6R (JACO 2) and every 7R arm. Those are the geometries ssik exists for. The "refuses (...)" strings are EAIK's actual error messages, captured verbatim by the bench harness. A numerical-IK comparison (MINK) is tracked separately in [#236](https://github.com/personalrobotics/ssik/issues/236).
+
+## Under the hood
+
+The algorithmic ingredients are not novel — Raghavan–Roth (1990), Manocha–Canny (1994), Singh–Kreutz (1989), Husty–Pfurner (2007). What's new is making the textbook pipelines survive on real ill-conditioned arms (AE-3 leftvar selection on JACO 2 drops `cond(m_quad)` from 3.75 × 10^16 to 127), composing them with a uniform dispatch layer, and packaging the whole thing as a deployable artifact.
+
+Cython hot loops cover the leaf primitives (POE forward kinematics, the Levenberg–Marquardt polish and analytical Jacobian); the rest is pure Python so it stays inspectable.
+
+**Bulletproof testing**: every solver lands with N-way cross-solver agreement on shared fixtures, FK closure ≤ 1e-10 on every retained IK, 500+ Hypothesis-fuzzed random poses per fixture, and an explicit speed bench that has to clear a regression gate. The current suite has **1300+ tests across 11 fixture arms**. Negative-result spikes (a Cython estimate that misses by 2-5×, a codegen-bake on a part that's 0.3% of runtime) are published as closed issues with profile data so the next contributor doesn't repeat the path.
+
+## Documentation
+
+- [docs/arm_coverage.md](docs/arm_coverage.md) — per-arm fixture tables, tested speeds, source URDFs
+- [docs/architecture.md](docs/architecture.md) — solver tier catalog, dispatch flow, build artifact internals, algorithmic lineage
+- [CONTRIBUTING.md](CONTRIBUTING.md) — repo layout, dev setup, testing discipline
+
+## Related libraries
+
+ssik does not compete with these on the arms they cover. Pick the right tool for your geometry.
+
+- [**EAIK**](https://github.com/OstermD/EAIK) (Ostermeier 2024) — Python wrapper around C++ subproblem-decomposition solvers. Analytical, returns all branches on Pieper-class 6R and canonical SRS 7R (with a manual joint lock). Refuses arms outside its recognised kinematic families. Directly benchmarked in the table above.
+- [**IK-Geo**](https://github.com/rpiRobotics/ik-geo) (Elias–Wen 2022/2025) — the reference C++/Rust implementation of subproblem decomposition. Same coverage profile as EAIK. Has Python bindings (`ik-geo` on PyPI); currently pins `pyo3==0.20.3` so the wheel is incompatible with Python 3.13 — track upstream for an update.
+- [**IKFast**](http://openrave.org/docs/latest_stable/openravepy/ikfast/) (Diankov 2010, part of OpenRAVE) — the original analytical-IK codegen tool. Symbolic preprocessing in sympy → per-arm C++. Works well on the kinematic families it was tuned for (Pieper-class 6R, spherical-wrist 7R via joint lock); the symbolic pipeline fails on modern sympy for non-Pieper geometries (`mpmath.polyroots` NoConvergence, `Matrix.inv` / `Matrix.det` stalls). LGPL-licensed.
+- [**MINK**](https://github.com/kevinzakka/mink) (Zakka) — Mujoco-native numerical IK via damped least-squares. Iterative, takes a seed, converges to a single configuration. Handles any kinematic geometry but returns one IK, not all branches, and FK closure is proportional to the convergence tolerance (typically 1e-3 to 1e-6 rather than machine precision).
+- [**TracIK**](https://traclabs.com/projects/trac-ik/) (Beeson & Ames 2015) — combined SQP / pseudoinverse Jacobian solver; the ROS Industrial default numerical IK. URDF-native. Same one-branch-per-seed semantics as MINK. The maintained Python binding (`pytracik`) ships a broken arm64 wheel; the ROS-native binding works fine inside ROS.
+- [**KDL-LMA**](https://github.com/orocos/orocos_kinematics_dynamics) — OROCOS KDL's Levenberg-Marquardt numerical IK. Older and less robust than TracIK or MINK on the same problem class.
+
+## License
+
+[BSD-3-Clause](LICENSE). The library incorporates clean-room reimplementations of algorithms from BSD-3-licensed IK-Geo (Elias–Wen 2022/2025) and from the academic publications of Raghavan–Roth (1990), Manocha–Canny (1994), Singh–Kreutz (1989), and Husty–Pfurner (2007). Algorithmic lineage is documented in module docstrings.
+
+## Citation
+
+```bibtex
+@software{ssik,
+  author = {Srinivasa, Siddhartha},
+  title  = {ssik: analytical inverse kinematics for 6R and 7R revolute arms},
+  url    = {https://github.com/personalrobotics/ssik},
+  year   = {2026},
+}
+```