Metadata-Version: 2.4
Name: srmp
Version: 0.2.0
Summary: Python bindings for Search-Based Robot Motion Planning (SRMP)
Author-Email: The SRMP Team <imishani@gmail.com>
Maintainer-Email: Itamar Mishani <imishani@gmail.com>, Ramkumar Natarajan <nrkumar93@gmail.com>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: numpy
Requires-Dist: meshcat
Requires-Dist: viser
Requires-Dist: yourdfpy
Provides-Extra: agent
Requires-Dist: google-genai==1.47.0; python_version < "3.10" and extra == "agent"
Requires-Dist: google-genai==2.17.0; python_version >= "3.10" and extra == "agent"
Description-Content-Type: text/markdown

![](https://raw.githubusercontent.com/imishani/srmp-docs/main/docs/source/_static/assets/srmp_logo.png)

**SRMP** is a motion planning library for robotic manipulation built on state-of-the-art search-based algorithms. It produces consistent, predictable motions backed by rigorous theoretical guarantees, and plans for up to dozens of manipulators at once while guaranteeing collision-free execution — between robots and with the environment.

## Why SRMP?

Existing motion planning frameworks often struggle with the demands of high-stakes applications, where predictability and repeatability are critical. SRMP addresses these challenges with search-based planning, giving motions that are both efficient and reliable — for single-arm manipulation, industrial automation, mobile manipulators and large-scale multi-robot coordination.

## Key features

- **Multi-robot motion planning** — first-of-its-kind support for coordinated motions in multi-manipulator systems.
- **Reliable, consistent trajectories** — predictable and repeatable, for high-precision and safety-critical use.
- **Two collision-checking backends** — coal mesh collision checking, and the VAMP SIMD backend for supported robots (sub-millisecond planning on uncluttered scenes).
- **Mobile manipulators** — whole-body planning for arm-on-base systems with base-aware heuristics.
- **Seamless integration** — works with MuJoCo, Sapien, Genesis, PyBullet and Isaac; MoveIt! plugin for deployment on real systems.
- **Python and C++** — one library for research and industrial workflows.

## Installation

```bash
pip install srmp
```

Prebuilt wheels for Python 3.9–3.14:

| Platform | Requirement |
|---|---|
| Linux x86-64 (manylinux) | CPU with **AVX2** (Intel Haswell 2013+ / AMD Zen+) — the VAMP backend is compiled for x86-64-v3. `import srmp` checks for it and raises a clear `ImportError` otherwise. |
| macOS Apple Silicon | macOS 11+ |

Other platforms, older CPUs, or building from source: see [instructions.md](https://gitlab.com/robot_planning/open/ims_manip/-/blob/main/instructions.md).

## Quick start

```python
import numpy as np
import srmp

planner = srmp.PlannerInterface()
planner.add_robot("panda")               # downloaded from the robot registry on first use

# An obstacle in the scene.
box = srmp.Pose()
box.p = np.array([0.5, 0.2, 0.4])
planner.add_box("box", np.array([0.1, 0.1, 0.4]), box)

# Weighted A* with a BFS workspace heuristic; the collision backend picks
# VAMP when the robot supports it, coal otherwise.
planner.make_planner(["panda"], {
    "planner_id": "wAstar", "heuristic": "bfs", "weight": "10",
    "validity_backend": "auto",
})

start = np.radians([50, 47, -10, -35, -22, 93, 39])

goal_pose = srmp.Pose()
goal_pose.p = np.array([0.642, -0.068, 0.505])
goal_pose.q = np.array([0.0, 0.0, 0.0, 1.0])
goal = srmp.GoalConstraint(srmp.GoalType.POSE, [goal_pose])

traj = planner.plan(start, goal)
print(len(traj.positions), "waypoints, backend:", planner.get_active_validity_backend())
```

Joint-space goals use `srmp.GoalConstraint(srmp.GoalType.JOINTS, q_goal)`. For several robots, `make_planner([...], ctx)` with more than one articulation and `plan_multi(...)`.

## Robots

Robot descriptions are downloaded on demand from the SRMP registry — `panda`, `ur5`, `ur10e`, `fetch`, `kinova_gen3`, `xarm6`, `ridgeback_ur10e` and others (`srmp.robots.list_available()`). Your own robot: `srmp.robots.register("name", urdf_path=..., srdf_path=..., end_effector=...)`, or pass a URDF path to `add_robot`.

The VAMP backend ships with modules matching the registry's `panda` and `ridgeback_ur10e` (its built-in `ur5` and `fetch` modules describe other robot models than the registry's, so those plan on coal); other robots plan on coal unless a VAMP plugin is installed for them (below). `validity_backend: "auto"` selects per robot, `"vamp"` insists and raises if unavailable.

### VAMP robot plugins (`srmp vamp`)

A plugin adds a robot to the VAMP backend without rebuilding srmp (Linux x86-64). By default every plugin is agreement-tested against coal before it is installed; that test checks the plugin's integrity, not that its spheres cover the robot.

- **Registry robots with a published plugin** (`kinova_gen3_robotiq_2f85` is the first): `add_robot("kinova_gen3_robotiq_2f85")` fetches it, checks it against the registry robot and agreement-tests it before first use (one line on stderr; up to a few minutes, once). Nothing published, or offline: coal, silently; adding a robot never starts a build. Overriding the SRDF, end effector, joint or link names skips the lookup.
- `srmp vamp fetch <robot>` does the same on request; `--no-verify` installs without the checks (recorded, and `list` says so).
- `srmp vamp add-robot --name <robot> --urdf <spherized.urdf> --end-effector <link> [--srdf <file>] [--mesh-robot <registry name or mesh URDF>]` builds your own: cricket and the compiler run in Docker images pulled from Docker Hub (asked first; `--build-images` builds them locally instead), else on a native toolchain. `--from-module <robot.hh> --spherized-urdf ... --spherized-srdf ... --end-effector ...` starts from an existing cricket module.
- `srmp vamp list [--json]` shows each plugin, whether it loads and what was checked; `srmp vamp remove <robot>` deletes one.
- After an srmp upgrade that changes the plugin ABI tag, `import srmp` warns and skips the affected plugins; `srmp vamp rebuild-all` rebuilds them from their cached modules (`--all` rebuilds every plugin), and `SRMP_VAMP_AUTO_REBUILD=1` does it at import. Registry prebuilts are fetched again for the new tag instead.

Plugins live in `~/.cache/srmp/vamp_plugins/` (`$SRMP_VAMP_PLUGIN_PATH` adds directories; its first entry becomes the install directory). Details: [instructions.md](https://gitlab.com/robot_planning/open/ims_manip/-/blob/main/instructions.md).

## Planners

Single robot: `Astar`, `wAstar`, `ARAstar`, `MHAstar`, `wPASE` (parallel), `MGS` (multi-graph search), `vamp_rrtc`. Multi-robot: `ECBS`, `xECBS`. Parameters, mobile-manipulator setup and motion-primitive files are covered in [instructions.md](https://gitlab.com/robot_planning/open/ims_manip/-/blob/main/instructions.md).

## Visualization and agent

- **Viser** and **MeshCat** visualizers: `srmp.ViserPlannerInterface`, `srmp.VisualPlannerInterface` — drop-in replacements for `PlannerInterface` with an interactive goal gizmo and plan panel.
- **Agentic mode**: `pip install "srmp[agent]"`, then `python -m srmp.agent.cli` or `python -m srmp.agent.gui` to drive the planner in natural language (Gemini by default).
- Scenes and plans round-trip through `save_scene` / `load_scene` / `save_plan` / `load_plan` — see [Saving and Loading](https://gitlab.com/robot_planning/open/ims_manip/-/blob/main/docs/saving-and-loading.md).

## Links

- Documentation: <https://srmp.readthedocs.io>
- Source and issues: <https://gitlab.com/robot_planning/open/ims_manip>
- Developer guide (building, backends, planner reference): [instructions.md](https://gitlab.com/robot_planning/open/ims_manip/-/blob/main/instructions.md)

## License

AGPL-3.0-or-later. See [LICENSE](https://gitlab.com/robot_planning/open/ims_manip/-/blob/main/LICENSE).
