batches 0.11.0__tar.gz

batches-0.11.0/.gitignore

@@ -0,0 +1,8 @@
+target/
+data/
+.venv*/
+CLAUDE.local.md
+__pycache__/
+# The extension an editable install builds into the Python package.
+python/batchplan/*.so
+python/batchplan/*.pyd

batches-0.11.0/AGENTS.md

@@ -0,0 +1,137 @@
+# Agent instructions
+
+This file is for coding agents that use batchplan in a program. To change batchplan itself, read [`CLAUDE.md`](CLAUDE.md): its design rules, invariants and working rules. The guides under [`docs/`](docs/README.md) explain each topic in full; this page gathers what an agent needs first and links to them. From Python, the `batchplan` package makes the same calls by the same names; [Python](docs/python.md) says how they map and what it binds so far.
+
+## Use batchplan: make once, warm up, reuse
+
+Build the robot and its device once, warm the device, upload each scene once, and reuse all three for every request. Results are per problem: read each one's answer or its reason, never assume a batch succeeded together.
+
+```rust,no_run
+use batchplan::glam::{Quat, Vec3};
+use batchplan::{
+    Device, Error, Obstacle, PlanFailure, PlanOptions, PlanProblem, Pose, Robot, RobotOptions,
+    Trajectory, World,
+};
+
+fn main() -> Result<(), Error> {
+    // Once per robot: load it, check its spheres, make its device and warm it up.
+    let options = RobotOptions {
+        ee_links: vec!["tool0".into()],
+        ..Default::default()
+    };
+    let robot = Robot::load("assets/ur5e/ur_description/urdf/ur5e.urdf", &options)?;
+    for link in robot.qualify()?.links {
+        println!("{}: spheres reach {:.1} mm past it", link.link, link.overhang * 1e3);
+    }
+    let device = Device::gpu(&robot).or_else(|_| Device::cpu(&robot))?;
+    device.warmup()?;
+
+    // Once per scene, and again whenever it changes: obstacles in the robot's frame, with the
+    // links that always touch the table it stands on allowed to.
+    let table = Obstacle::cuboid(Vec3::new(0.3, 0.0, -0.02), Vec3::new(0.6, 0.6, 0.02));
+    let mut world = World::new(vec![table]);
+    let mounted = world.always_touching(&robot);
+    world.touch.extend(mounted);
+    let worlds = device.upload(&[world])?;
+
+    // Per request: a pose in the robot's frame (quaternions x, y, z, w), from the measured state
+    // in `robot.joint_names()` order.
+    let target = Pose::new(Vec3::new(0.4, 0.2, 0.3), Quat::from_xyzw(1.0, 0.0, 0.0, 0.0));
+    let start = robot.default_q();
+    // IK from the start finds where the path ends: the nearest collision-free solution.
+    let problem = PlanProblem::new(0, start, target);
+    let plans = batchplan::plan(&device, &worlds, &[problem], &PlanOptions::default())?;
+    match (plans.best(0), &plans.failures[0]) {
+        (Some(path), _) => {
+            let trajectory = Trajectory::try_new(&robot, path, 1.0)?;
+            trajectory.check(&robot)?;
+            let samples = trajectory.sample(100.0)?; // positions, velocities, accelerations
+            println!("{} samples over {:.2} s", samples.len(), trajectory.duration());
+        }
+        (None, Some(PlanFailure::StartCollides { contacts })) => {
+            println!("the start collides: {contacts:?}");
+        }
+        (None, Some(PlanFailure::GoalUnreachable)) => println!("no IK seed reaches the pose"),
+        (None, why) => println!("no plan: {why:?}"),
+    }
+    Ok(())
+}
+```
+
+### Conventions
+
+- **Units.** Meters, radians (meters for prismatic joints), seconds, `f32` throughout.
+- **Poses** are `Pose { position, rotation }` with [glam](https://docs.rs/glam) types, re-exported as `batchplan::glam`. glam's quaternions are x, y, z, w (`Quat::from_xyzw`), as ROS messages are; MuJoCo and Eigen's constructor are w, x, y, z. Rotations must be unit quaternions.
+- **Frames.** Targets, obstacles and depth-camera poses are all in the robot's frame: its description's root link, or `world` for a robot made with `Robot::assemble`. Transform camera and map data into it first.
+- **Joint order** is `robot.joint_names()`: the actuated joints after locking, numbered breadth first, so two arms' joints interleave. Map a controller's names to it; never assume the description's order. Planar, ball and floating joints become one-axis joints named `<joint>_x`, `_theta` and so on ([robots](docs/robots.md#kinematics)).
+- **Hands** are the IK frames of `RobotOptions::ee_links`, numbered in that order. For a gripper, use a frame between the fingertips, z out of the hand and y along the closing direction: what `grasps` assumes.
+
+### Lifecycle
+
+- **Robot.** `Robot::load` fits collision spheres unless given a model: a fraction of a second for an arm at the default budget, seconds for thousands of spheres; save `robot.collision_model()` and pass it back as `RobotOptions::collision_model` to load the same spheres every time.
+- **Device.** One per robot (`Device::gpu`, falling back to `Device::cpu`), made once: never inside a control loop or per request. `device.warmup()` before timing anything ([devices](docs/devices.md#make-once-warm-up-reuse)).
+- **Worlds.** `device.upload(&worlds)` once per scene. Uploads are cheap (0.1–0.2 ms for 512 tabletop worlds), so a scene that changes is uploaded again; there is no partial update ([changing a scene](docs/perception.md#changing-a-scene)).
+- **Locked joints that move**, as a torso or head the robot plans without: `robot.relock(&values)` then `device.with_robot(&relocked)`, which compiles nothing and keeps the uploaded worlds. Fit the collision model with those joints free and load with it: a model records the joints it was fitted with locked, whose pairs that meet only at other values would go unchecked, and `relock` refuses to move them ([robots](docs/robots.md#kinematics)).
+- **Held objects.** `holding: Some(held)` on a `PlanProblem`, `IkProblem`, `ToolPath` or `Sequence`, with the device without the object: one call takes problems holding different objects or grasps, a batch per hold ([holding objects](docs/robots.md#holding-objects)). On a GPU, warm up a device holding any object in each hand you will hold in: the first call holding there builds its kernels. For a device that holds one, `robot.attach(&AttachedObject)` then `device.with_robot(&held)`: the same GPU or threads, and the uploaded worlds still work, unless they name what a hand comes to hold (`Touch::held`). The held robot's GPU kernels are its own: warm its device up too before timing it. `robot.detach(name)` reverses it. Attachment is collision only: there is no payload mass or inertia, so timing a heavy carry ignores the load; slow it with a speed scale ([trajectories](docs/planning.md#executable-trajectories)).
+- **Finger openings.** `Pick::locked` and `Held::locked` hold the robot's locked joints (the fingers) at given values for that task or hold, many openings in one call; empty is as loaded ([tasks](docs/planning.md#picking-up-and-setting-down)). Don't build a relocked device per opening for calls that take them.
+- **Live loops** call `Follower::tick` or `servo` each period and nothing that builds: pass the measured state to `tick` so a robot held back or pushed is followed from where it is (held there, `Blocked`, with `FollowerOptions::replan` off). A controller in another process takes each replan from `FollowStatus::Replanned { at, trajectory }`, with `FollowerOptions::lead` for the time sending it takes. `Stopping { contacts }` and `Collides { at, contacts }` name what is in the way, links and obstacles as `PlanFailure::StartCollides` names them ([live motion](docs/planning.md#live-motion)).
+
+### Choose the call
+
+| Task | Call | Guide |
+|---|---|---|
+| Forward kinematics | `robot.ee_pose(q, hand)`, `robot.link_pose(q, link)`, `robot.spheres(q)` | [robots](docs/robots.md) |
+| Configurations for hand poses | `solve_ik`; `ik::failures` for why one has none | [IK](docs/planning.md#inverse-kinematics) |
+| A collision-free path to a configuration or a hand pose | `plan`, then `time` (one path: `Trajectory::try_new`) | [planning](docs/planning.md#planning-a-path) |
+| The hand along straight lines | `follow` | [tool paths](docs/planning.md#moving-the-hand-along-a-path) |
+| A hand kept upright, in a box or relative to another hand | `HandConstraint` on the problem | [constraints](docs/planning.md#constraints-along-the-path) |
+| Picking up and setting down | `grasps`, `pick`, `place` | [tasks](docs/planning.md#picking-up-and-setting-down) |
+| Passing an object from one hand to another | `pick` with `GraspOptions::along` (toward an end), then `handover` | [tasks](docs/planning.md#picking-up-and-setting-down) |
+| A program of picks and places planned together | `pick` and `place` with `transit: false`, then one `plan` and `join` | [tasks](docs/planning.md#picking-up-and-setting-down) |
+| Motions run without stopping between them | `join` | [joins](docs/planning.md#joining-motions) |
+| A motion that comes fast and arrives slowly | `Trajectory::with_hand_speed` with a cap near the grasp (`HandSpeed::near`); many paths: `time`; in `pick`/`place`: `TaskOptions::tool_speed_near` | [timing](docs/planning.md#executable-trajectories) |
+| Running a motion while the world changes | `Follower`, `servo` | [live motion](docs/planning.md#live-motion) |
+| Obstacles from depth images or point clouds | `SdfGrid`, `OccupancyMap`, `DepthImage::robot_mask` | [perception](docs/perception.md) |
+| Training data | `datagen`, `npy::export`, `lerobot::export` | [training data](docs/training-data.md) |
+
+IK finds configurations; a plan finds the path to one, or to a pose, solving IK from the start itself. Solve IK first only to choose among its solutions. Every call takes many problems, each naming its world: batch them rather than calling once per problem, since each GPU call has a fixed cost.
+
+### Qualify the robot
+
+A robot that loads may still have spheres unfit to plan with. Before planning with a new robot or a hand-tuned collision model ([qualifying a robot](docs/robots.md#qualifying-a-robot)):
+
+1. `robot.qualify()`: each link's `overhang` past its geometry, the `uncovered` share of its surface and its `thickness`, and each hand's `tips`. Fingers whose overhang or tip is a large part of the smallest object you will grasp will collide with what it stands on; give them a tighter tolerance (`RobotOptions::sphere_tolerances`) or a finer `SphereOptions::voxel_size`.
+2. `world.always_touching(&robot)` with the table the robot stands on: links that touch it in every configuration need a touch, or every plan's start collides.
+3. Fingers that are part of the palm's link, as the SO-101's fixed jaw: name them in `RobotOptions::finger_links`, or grasps where they meet the object fail.
+4. `device.contacts(&worlds, &item_world, &q, 0.0)` at the default configuration, the SRDF's named states and a few others: each should collide with nothing.
+
+### Read results
+
+- `ik.best(i)`, `plans.best(i)` and `solved()` return only valid answers; `IkResult::success` and `PlanResult::valid` are per seed, problem-major (`problem * seeds + seed`).
+- A plan is B-spline control points, not a trajectory: time a call's paths together with `time`, or one with `Trajectory::try_new` (`Trajectory::moving` from a moving start), sample it with `at` or `sample`, and `check` it before it runs on hardware. Never send control points to a controller.
+- With `start_tolerance`, use the corrected start retained in the result’s problem; goals and start motion remain as given ([measured starts](docs/planning.md#measured-starts-at-joint-limits)).
+- Plans do not depend on the batch or the device; with a `time_budget`, they depend on the machine's speed. IK starts every problem from the same seeds in any batch, but a GPU rounds differently from the CPU, and differently on either side of where it switches how many invocations share a configuration (4,096 configurations, more for robots with many spheres), so solutions there can differ slightly, and so can plans to poses, which end where IK solves them.
+
+### Diagnose a failed request, in order
+
+Check these before raising budgets:
+
+1. **The input.** An `Error::Input` names what was refused and the value given: shapes, joint order, unit quaternions, joint limits (strict by default; [measured starts can opt into correction](docs/planning.md#measured-starts-at-joint-limits)), frames.
+2. **The start.** `PlanFailure::StartCollides { contacts }` names each link and obstacle, or pair of links. A link touching the table in every configuration needs a touch (`always_touching`); a start inside a held object's spheres needs the object attached.
+3. **The goal.** `PlanFailure::GoalCollides`, and for a pose goal `GoalUnreachable`, which more `PlanOptions::goal_ik` iterations may fix, or more seeds `kept` past its screening (`screening: 0` gives every seed every iteration); for IK, `ik::failures` tells `Unreachable` from `Collides { contacts }`.
+4. **The search.** `NoPath`: more `rrt.max_iterations`, or the way is blocked. `NoSpline`: more `control_points`, or a slower start motion. `OutOfTime`: a longer `time_budget`.
+5. **Tasks.** A `TaskFailure` prints where and why every candidate stopped; each `CandidateStop` has the step, the reason and the contacts, whose obstacles are numbered as in the task's world; in a place, `world.obstacles.len()` is the object where it is set down, and in a handover, the object where it changes hands. `grasps` says why it found none. Grasps near a support need `GraspOptions::tip` and `floor`, which keeps the open fingers over it too; from above, they keep at least `overlap` of the fingers (1 cm) in the object, so an object whose top is less than that over the floor has none.
+
+### Footguns
+
+- glam's quaternion order is x, y, z, w; a w-first source passed straight through turns the hand.
+- `PlanOptions::seeds` is 0: no trajectory optimization unless asked for.
+- A world's touches name links; what a problem's `holding` may touch is named with `Touch::held(obstacle, hand)`, one hand's per upload, on the device that holds nothing.
+- `holding` takes the device without the object: one already holding a `Held` in that hand is an `Error::Input`.
+- `grasps` returns poses in the object's frame; with a `floor`, pass the obstacle as it stands in the world.
+- A task's world holds for all its steps unless `transit_world` or `depart_world` name others: what the hand may touch at the grasp, it may touch all the way from the start.
+- `TaskPlan::transit` is `None` for a task with `transit: false`, whose start is a seed and is not checked.
+- `Robot::lower` and `upper` are ranges; continuous joints turn without limit and wrap.
+- `Follower::tick` with `None` trusts the trajectory; on hardware, pass the measured state.
+- `FollowStatus::Stopping { contacts }` numbers obstacles as in the worlds of the tick the stop began at, on every tick of the stop: map them through those worlds, not the current ones.
+- A `Follower` on a tool path (`follow`) needs `FollowerOptions::replan` off: a replan leaves the path for a free-space motion to its end. Off, a collision ahead stops it on the path and a robot past `tolerance` is held where it is, both `Blocked` at rest ([live motion](docs/planning.md#live-motion)). On a way joined into a move in, give it a `Detour` instead: it replans only the way, to where the move in starts, and takes the move in up from rest there (`Resumed`).

batches-0.11.0/CHANGELOG.md

@@ -0,0 +1,452 @@
+# Changelog
+
+What changed in each release, for people upgrading, in the format of
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versions follow
+[Cargo's semver](https://doc.rust-lang.org/cargo/reference/semver.html): before 1.0, a new minor
+version (0.9 → 0.10) may break the interface, and a patch (0.9.0 → 0.9.1) breaks nothing.
+[Contributing](CONTRIBUTING.md#releases) says how releases are made.
+
+## [Unreleased]
+
+## [0.11.0] - 2026-11-14
+
+### Added
+
+- **Breaking:** `PlanOptions::start_tolerance` and `ToolPathOptions::start_tolerance` optionally
+  clamp measured starts just past a joint limit before the normal collision and constraint checks.
+  Both default to zero, preserving strict validation. Larger or nonfinite violations are input
+  errors; continuous joints, goals and start velocities are unchanged. `pick`, `place` and
+  `handover` use `TaskOptions::plan.start_tolerance` for their initial states. Results retain the
+  corrected starts. Exact options literals need the new field; Python options expose it too.
+- **Breaking:** picks and holds say where the fingers are: `Pick::locked` and `Held::locked` hold
+  the robot's locked joints (as `Robot::relock` takes them) at those values for that task, or
+  while the object is held, so a rim between walls can be picked with the fingers part open and
+  a hold checked where they closed. One call takes tasks and holds at many openings, a relocked
+  robot for each group; empty, the default, is as loaded, to the bit. A `Pick` or `Held` literal
+  needs `locked: HashMap::new()`. In Python, `Pick(..., locked={...})`, `Held(..., locked={...})`.
+- **Breaking:** `Occlusion::Band(distance)`, for `SdfGrid::from_depth` and `OccupancyMap::grid`:
+  solid within `distance` behind an observed surface, as seen from the camera, and free past it,
+  in the robot's shadow and along pixels without a reading. In a map, unobserved space within
+  `distance` of an occupied voxel is solid, in any direction, and the robot's shadow is free. A
+  band that is not finite or is negative is an input error. `Occlusion` is no longer `Eq` (the
+  band is an `f32`); from depth images, the other rules build the same grids as before.
+- One hand can pass what it holds to another: `handover(&device, &worlds, &[Handover], &TaskOptions)`,
+  with `Handover::new(&robot, world, start, held, to)`. Candidates are each meeting with each of the
+  taker's grasps; both hands' IK solves at the meeting with the object standing there, each hand's
+  straight move holds the other arm still, and the way to the meeting holds the object in the
+  giver's hand. Every candidate that gets through comes back quickest first, naming its `meeting`
+  (`TaskPlan::meeting`) and the taker's `held`. `handover_poses` proposes meetings where both arms
+  reach and `handover_grasps` the taker's grasps at the object's other end. In Python, the same
+  names.
+- **Breaking:** `grasps` can hold an object toward its ends: `GraspOptions::along`, a fraction of
+  half the side the fingers close on (0, the middle, as before), for a pick whose object one hand
+  passes to another. A `GraspOptions` literal needs the new field (`along: 0.0`); literals with
+  `..GraspOptions::default()` are unaffected. In Python, `GraspOptions(along=0.75)`.
+- **Breaking:** a tool path can hold joints still: `ToolPath::hold` lists joints that stay where
+  `start` has them along the whole path, as `PlanProblem::hold` and `IkProblem::hold` do, for a
+  hand whose arm shares joints (a torso) with one that holds what it reaches for. The hand follows
+  with the joints left, and stops where they cannot keep it on the path. A `ToolPath` literal
+  needs the new field (`hold: vec![]`). In Python, `ToolPath(..., hold=[0, 1])`.
+- **Breaking:** the straight moves of `pick` and `place` can be capped near the grasp or release
+  alone: `TaskOptions::tool_speed_near` (meters) holds `tool_speed` within that distance of where
+  the hand grasps or lets go, which the move in ends at and the move away starts from, and the
+  rest of each move runs as fast as the joints allow. The handovers of `datagen::handover` take
+  it too. `None`, the default, caps both moves all along, as before, to the bit. A `TaskOptions`
+  literal needs the new field (`tool_speed_near: None`). In Python,
+  `TaskOptions(tool_speed_near=0.02)`.
+- **Breaking:** a `Follower` can follow a motion that joins a way to a move in, replanning only
+  the way: `FollowerOptions::detour` takes a `Detour { from, until, then }`. The follower keeps
+  the path before `from` and after `until`. Where the rest of the motion collides within that
+  window, it plans to `then`'s first state (the move in as planned apart), from no sooner than
+  `from`, then takes up `then` from rest there and reports `FollowStatus::Resumed { at,
+  trajectory }`; along `then` it keeps the path. `None`, the default, changes nothing. A
+  `FollowerOptions` literal needs the new field (`detour: None`).
+
+- `CollisionModel::to_json` and `CollisionModel::from_json` give and take the JSON text `save`
+  and `load` write and read, for a model sent where no file goes. In Python, `model.to_json()`
+  and `CollisionModel.from_json(text)`.
+
+- **Breaking:** a `Pick` or `Place` can leave its transit out and run each step in a world of its
+  own. With `transit: false` a task solves its grasps or releases and its two straight moves
+  alone, without checking its start, and keeps every candidate that passes them, so a program of
+  tasks solves all its moves in two calls and the ways between them in one `plan`
+  (`TaskPlan::begin` and `end` are where a way ends and the next begins), then joins them.
+  `transit_world` and `depart_world` name the worlds of the start and the planned path and of the
+  move away where they are not the task's `world`: the same obstacles, shaped or touched
+  otherwise, as a transit that touches nothing the grasp may. `TaskPlan::transit` is an `Option`,
+  `None` for a task without one, and `TaskPlan::motions` gives a plan's motions in order. Code
+  reading `plan.transit` unwraps it or reads `plan.motions()`, and a struct literal that writes
+  out every field of `Pick` or `Place` needs the three new ones. In Python, `Pick` and `Place`
+  take `transit`, `transit_world` and `depart_world`, and `TaskPlan` has `motions` and `begin`.
+- **Breaking:** `join` checks a sequence's blends with what a hand holds: `Sequence::holding`, a
+  pick's `Held`, as `PlanProblem::holding`, so a carry joins into the move in of its place on the
+  device without the object. A `Sequence` literal needs the new field (`holding: None`).
+- A world can let what a hand comes to hold touch an obstacle: `Touch::held(obstacle, hand)`, for
+  one hand in an upload, on the device that holds nothing. `solve_ik`, `follow` and `plan`
+  problems with `holding` then rest their objects on what they are set down on in one call
+  against one upload, as a device holding the object does with the world uploaded to it;
+  problems that hold nothing are checked as without it. In Python, `Touch.held`.
+- `time(&device, &paths, speed_scale, &hand_speeds)` times many planned paths in one call on the
+  device's threads, each as `Trajectory::try_new` times one, or under its own list of hand speed
+  caps (`&[]` caps none), and gives each path's trajectory or error in order. In Python,
+  `time(device, paths, speed_scale=1.0, hand_speeds=None)`.
+- **Breaking:** a hand speed cap can hold on part of a path: `HandSpeed::near`
+  (`Near { point, radius }`) caps the hand only while its frame is within `radius` of `point`,
+  so a way joined into the move to a grasp comes as fast as the joints allow and arrives slowly,
+  and `Trajectory::with_hand_speed` takes several caps, each holding where it is. A `HandSpeed`
+  literal needs `near: None`, and `with_hand_speed` takes a slice (`&[speed]`). A 15 cm way
+  joined into a 6 cm move capped at 5 cm/s takes 2.21 s where the two take 2.26 s one after the
+  other and the joined path 4.41 s capped throughout (a Panda, `tests/join.rs`). In Python,
+  `HandSpeed(hand, linear, angular, near=Near(point, radius))`, and `with_hand_speed` takes one
+  cap or a list.
+
+- Publish the Python bindings as `batches` on PyPI (`import batchplan`). Version tags publish
+  the Rust crate and Python wheels and source together, using trusted publishing.
+
+- **Breaking:** `plan` takes the hands' poses as a goal: `PlanProblem::goal` is a `Goal`, a
+  configuration (`Goal::Joints`) or a pose or `None` per hand (`Goal::Poses`), and
+  `PlanProblem::new` takes either, a `Pose` for a one-handed robot. `plan` solves IK for every
+  pose goal of the call in one batch, seeded from each start and keeping its held joints, what it
+  holds and its constraints, and plans to the collision-free solution nearest the start up to
+  whole turns. Poses no seed reaches collision-free are solved again with four times the seeds, up
+  to sixteen times, while a `time_budget` lasts; those still unreached fail as
+  `PlanFailure::GoalUnreachable`, or `GoalCollides` where IK reaches them only in collision.
+  `PlanOptions::goal_ik` sets that IK. `PlanProblem::new` takes a configuration as a `Vec<f32>`,
+  `&[f32]`, `&Vec<f32>`, `[f32; N]` or `&[f32; N]`; convert any other form with `to_vec()`. Code
+  reading a goal as a slice reads `goal.joints()`, a struct literal wraps a configuration in
+  `Goal::Joints`, and code that writes out every field of `PlanOptions` needs the new one. The benchmark's ik+plan mode plans to the
+  goal pose this way. In Python, `PlanProblem` takes a `Pose`, or a `Pose` or `None` per hand, as
+  its goal, beside `PlanOptions.goal_ik` and `PlanFailure.GoalUnreachable`.
+- Python bindings, in `python/`: the `batchplan` package, built with maturin
+  ([Python](docs/python.md)). Robots, assembled ones among them, obstacles and worlds, devices, IK
+  (`solve_ik`, `ik_failures`), planning with hand constraints (`plan`), timing (`Trajectory`),
+  tool paths (`follow`), whole tasks (`pick`, `place`, `grasps`, `place_poses`) and held objects,
+  with NumPy arrays in and out, `batchplan::Error`'s kinds as exception classes, and the
+  interpreter released while each call works. Values are frozen and changed with
+  `replace(**changes)`, as Rust's struct update syntax does. Install it from the repository with
+  `pip install "git+https://github.com/natsuku-lab/batchplan#subdirectory=python"`, which needs a
+  Rust toolchain.
+- **Breaking:** `PlanProblem::holding`, `IkProblem::holding` and `ToolPath::holding`: an object a
+  hand holds (a `Held`, as `TaskPlan::held` gives it), per problem. One `plan`, `solve_ik` or
+  `follow` call takes problems holding nothing, different objects, or one object by different
+  grasps, and gives each what a device holding its object alone gives: it groups them by what
+  they hold and runs a batch per group, in parallel, on the device's GPU or threads. Holding per
+  problem took a device and a call per hold. Pass the device without the object; one already
+  holding a `Held` in that hand is an `Error::Input`. Code that writes out every field of
+  `IkProblem`, `PlanProblem` or `ToolPath` needs the new one (`holding: None`).
+- `SphereOptions` implements `PartialEq`.
+- **Breaking:** `GraspOptions::overlap`, 1 cm by default: the least the fingers reach into the
+  object in a grasp from above over a `floor`. An object flatter than `tip` and the floor's
+  clearance is now held from above with the fingertips at the floor and the frame over its top,
+  as long as its top is at least `overlap` over the floor. `grasps` left out every grasp from
+  above of such an object: an 8.8 x 4.8 x 1.85 cm package got only grasps from the sides, which
+  put the hand into the table. Every grasp from above over a floor now keeps at least `overlap`
+  of the fingers in the object, where it kept the frame inside it, so with `tip` under 1 cm (the
+  default 0 among them) some it returned are left out. Code that writes out every field of
+  `GraspOptions` needs the new one.
+- **Breaking:** `FollowerOptions::replan`, on by default. Off, a `Follower` keeps its
+  trajectory's path, as a motion along a tool path must: where the rest of the motion collides,
+  it stops on the path, and where the robot is measured past `tolerance`, it holds it there,
+  `Blocked`. In either case it used to plan a free-space motion to the goal, off the path. Code
+  that writes out every field of `FollowerOptions` needs the new one.
+
+### Changed
+
+- Faster sphere fitting, with the same fitted collision models. Dense surface checks test four
+  spheres at once: on one thread, fitting the stand with a 512-sphere budget takes 19% less time
+  on an M4 Pro and 30% less on a Ryzen AI Max+ 395; the Panda with a 1,200-sphere budget takes
+  4% and 11% less, respectively.
+  These isolate fitting from self-collision analysis. The
+  [benchmark guide](docs/benchmarks.md#fitting-collision-spheres) gives the runs and
+  `examples/fitting.rs` reproduces the fixtures.
+- Faster CPU collision checks, contact queries, IK, planning, tasks, depth-grid construction and
+  occupancy updates, with results the same to the bit. In six alternating runs, the best CPU
+  times for 1,000 IK targets among clutter fell 9% on a Ryzen AI Max+ 395 and 4% on an M4 Pro;
+  256 plans with four optimized seeds took 22% and 6% less time, respectively. The
+  [benchmark guide](docs/benchmarks.md#how-the-speed-came) gives the times, lower quartiles and
+  build configurations. This workspace builds batchplan as one
+  codegen unit (`[profile.release.package.batchplan] codegen-units = 1`), so a change measured here
+  no longer moves with how rustc splits the crate; a crate that depends on batchplan can do the same.
+- Published crates exclude development agent instructions and skills; the library-user
+  `AGENTS.md` guide remains included.
+- A world with a distance grid uploads without checking the grid's every value again: a grid is
+  checked when it is made, and nothing changes one after. `pick` and `place` upload their worlds
+  by the dozen, so a grid in the world cost each call that many passes over its values. The
+  searches' and tool paths' collision checks and the CPU device's `clearance` also look a grid
+  up without its gradient, which they never read.
+- IK on the CPU device, and trajectory optimization's repairs on either, skip the self-collision
+  sphere pairs that cannot add to the cost: a sphere past the margin from another link's
+  bounding sphere is not checked against that link's spheres. Results are the same to the bit.
+  A robot fitted with many spheres gains most: a `place` of four holds on a Panda of 512 spheres
+  takes 11 ms on an M4 Pro where it took 18 ([Benchmarks](docs/benchmarks.md#how-the-speed-came)).
+- **Breaking:** IK screens its seeds. Every seed takes `IkOptions::screening` steps (8 by
+  default), then only `IkOptions::kept` of each problem's (4) take the rest of `iterations`: those
+  not yet at their targets, the nearest first, then seeds that have arrived. Where the steps push
+  away from collisions (`collision_step` above 0, for a robot with collision spheres),
+  collision-free seeds go before the others; elsewhere whether a seed collides after the
+  screening says little about where it ends, and they go by their errors alone. The seeds left behind are returned as the screening left
+  them. Code that writes out every field of `IkOptions` needs the two new ones, and
+  `screening: 0` is the IK of before, as are problems of more than 32,768 seeds. On a GPU the
+  screening, the choice and the remaining steps are one round trip, a small call is one
+  submission, and its buffers are kept for the next. On an M4 Pro, 1,000 targets for a Panda
+  with collision spheres take 36–39 ms where they took 68–82, and its CPU threads 95 ms where
+  212, with 945 solved where 944; one target and ten take no longer than before, with the push
+  or without. In RoboKit's IK benchmark on an RTX 4090 (a Panda without spheres), 1,000 targets
+  take 3.1–3.3 ms where they took 3.6–3.7 and 2,000 take 6.1–6.3 ms where 7.2; 10 took
+  0.77–0.80 ms where 0.71 before the changes for small calls, which are not measured there
+  ([Historical benchmark][historical-robokit]). The 2,600 pose-goal problems solve as
+  before (98.3%). In Python, `IkOptions.screening` and `IkOptions.kept`.
+- Batched IK spends less time around the solve: a problem's seeds share its targets instead
+  of each carrying a copy, large batches are seeded on the device's threads, buffers go to the
+  GPU without an extra copy, and a robot without collision spheres skips the collision push,
+  which is zero for it. The same results, bit for bit. In RoboKit's IK benchmark on an RTX 4090
+  (a Panda, collision off, 64 seeds of 30 steps), 1,000 targets take 4.5 ms where they took
+  10.8, 2,000 take 9.1 ms where 23.2, and one takes 0.9 ms where 1.26
+  ([Historical benchmark][historical-robokit]).
+- **Breaking:** `IkOptions::collision_step` must be finite: an infinite or NaN one is an input
+  error. NaN and negative infinity used to mean no push, and positive infinity solved nothing
+  (the CPU left every seed where it started).
+- **Breaking:** `Device::gpu` no longer chooses DX12's software renderer (WARP, "Microsoft Basic
+  Render Driver"), which every Windows machine has: it fails as it does where there is no
+  adapter, naming the renderer it left out, so `Device::gpu(..).or_else(|_| Device::cpu(..))`
+  falls to the CPU device. On a four-core machine that renderer had not finished one pick after
+  82 minutes, where the CPU device takes 16 ms. `Device::gpu_named` still takes it by name.
+- A distance grid costs a link nothing while the link keeps away from the grid's box: the
+  collision checks rule the grid out by its box and the least value on the box's faces, as they
+  rule other obstacles out by their distance, where every sphere used to be looked up in every
+  grid. Among cluttered tabletops, IK for 1,000 targets with a grid 2 m from the arm in every
+  world takes 28.8 ms on an M4 Pro's GPU where it took 35.7, and 67 ms on its CPU where 107;
+  with the grid beside the table, 31.7 ms where 35.7, and 72 ms where 108
+  (`examples/latency.rs`). `world_clearance` for a link past the margin from a grid is a bound
+  from below, as it is for other obstacles. Uploads without a grid run the code they ran: the
+  rule is in kernels, and in copies of the CPU's checks, that only worlds uploaded with a grid
+  run ([Benchmarks](docs/benchmarks.md#how-the-speed-came)).
+- A GPU device is made sooner: its kernels' pipelines compile each on a thread of its own. With
+  the driver's shader cache empty, `Device::gpu` takes 1.4 s on an M4 Pro where it took 2.6,
+  though it now builds the kernels of uploads with grids as well, `Device::warmup` 0.7 s where
+  2.0, and `Device::with_robot` for a robot holding an object 1.7 s where 3.0. The second set
+  costs memory: a GPU device keeps 66 to 88 MB after it is made where it kept 35 to 37, and
+  about 20 MB for each held shape where 9.
+- GPU kernels leave naga fewer loops to count, and trajectory optimization on a GPU leaves out
+  paths that are done. naga counts the rounds of every shader loop to rule out endless ones,
+  which cost IK's short loops more than their work. One hand's damped least squares is now
+  written out term by term for each robot, as its kinematics are, and the kernels' loops of a
+  known count (over the joints, the hands, the line search's steps) are written out when the
+  kernels are built. A path whose optimization is over, a steepest-descent search having found
+  nothing better, takes no part in later rounds, as the CPU's already stopped. Of the lanes a
+  small batch gives each configuration, one works out the IK step and the others take the
+  configuration from it, and a robot's own link of 24 spheres or more takes them two to a round.
+  On an M4 Pro, one target's default IK takes 0.34 ms where it took 1.14 for a Panda without
+  collision spheres, and 0.92 ms where 2.03 with them; 1,000 targets take 1.7 and 22.1 ms where
+  3.8 and 30.0; 256 plans with 4 optimized seeds take 83 ms where 94, and 16 take 15.9 ms where
+  23.7 (`examples/latency.rs`). On a Radeon 8060S, before the last two of these changes, one
+  target took 0.18 ms where 1.12, and 1.10 ms where 2.70. In RoboKit's IK benchmark on an RTX
+  4090 one target takes 0.33–0.42 ms and ten 0.35–0.43, where RoboKit takes 0.57–0.59 and
+  0.55–0.56 ([Historical benchmark][historical-robokit]). The crate has no `unsafe`: the
+  kernels are built with every check naga makes, the loop counters among them, which on an M4
+  Pro make optimized plans 4–7% slower and IK for hands that share joints 13–20%. Three kinds of
+  call are slower than before: IK with the push for a robot of several hundred spheres (4–5%),
+  plans to goals past an obstacle (5%) and `evaluate` (1.5–4%)
+  ([Benchmarks](docs/benchmarks.md#how-the-speed-came)). A GPU's results move in their last
+  places, IK's and trajectory optimization's alike: a seed in thousands arrives or does not.
+- Trajectories are sooner: time-optimal timing uses the full velocity and acceleration limits,
+  and where its smoothed time map overshoots a limit, slows the profile there instead of
+  stretching the whole motion for it. Planned Panda motions take 6.6% less time on average, the
+  hand's straight moves 3.0%, replans from a moving start 5.7%, and the 2,600 benchmark
+  problems' motions 5.0%, within the same limits (`Trajectory::check`); more joins are worth
+  blending. Timing costs less than it did (a Ryzen thread): a path from rest 9% less, and one
+  from a moving start 59% less (475 µs where 1,172), timed once with its start at the full
+  limits, its candidate time maps turned down at a quarter of the checking density, and each
+  map measured over the joints in contiguous rows. A moving start's timing and a stop's are
+  also held to their limits either side of where they cross the path's knots, between the
+  samples checked, where jerk could pass its limit by up to 12%, and in a stop acceleration
+  by up to 20% and jerk by 19%: of 960 stops asked early in planned Panda motions 52 are
+  refused where 40 were. Replans from a moving start take 11% less time one at a time on a
+  Panda and 70% less on an SO-101; a batch of 96 Panda replans takes 65 ms where it took 61
+  (within the runs' spread), since a moving start no timing fits costs more to turn down
+  (2.0 ms where 1.6). A spline that cannot follow the start motion is then tried again,
+  stopping at every waypoint, with less of that timing, which takes a further quarter off a
+  Panda's replans one at a time and a sixth off the SO-101's (an M4 Pro)
+  ([Benchmarks](docs/benchmarks.md#timing-up-to-the-limits)).
+- **Breaking:** `IkOptions::default()` is 64 seeds of 30 steps of at most 1 rad, where it was 32
+  seeds of 60 steps of at most 0.3 rad: at 0.3 rad, about half the seeds ran out of steps before
+  converging. The same problems solve. Results carry 64 seeds per problem, and `TaskOptions`,
+  `DemoOptions`, `PickPlaceOptions` and `PlanOptions::goal_ik` inherit the new IK; pass the old
+  values to keep the old results.
+- **Breaking:** An IK step that would move no joint by more than 1e-6 rad is not taken, on the
+  CPU and the GPU alike: a seed that has come to rest stays exactly there, and CPU threads skip
+  its remaining steps, which makes their IK about a fifth faster. Seeds can differ from before
+  by a few microradians. Together with the new defaults, the 2,600 benchmark problems plan to
+  pose goals 1.8 times as fast in batches on a Radeon 8060S (6,225 against 3,489 per second, and
+  in 5 ms instead of 9 for one) and 1.18 times as fast on 32 CPU threads (3,344 against 2,836);
+  IK for 512 tabletop targets takes 71 ms instead of 84 on those threads.
+- `solve_ik` on a GPU checks the solved configurations' clearances in the same submission, from
+  the configurations already on the GPU, and reads everything back at once: one wait per 65,536
+  seeds instead of three, about 0.4 ms less per call.
+- **Breaking:** `Robot::load`, `Robot::from_urdf` and `Robot::assemble` refuse a collision
+  model whose spheres have a non-finite center or radius or a negative one, or whose
+  self-collision buffer for a link is not finite or would shrink one of its spheres below nothing,
+  naming the link and the value (`Error::Load`; `Error::Input` from `from_urdf`). Spheres fitted to
+  geometry that is not finite, or so large it overflows, are refused alike. Such models loaded
+  before, and a sphere smaller than nothing checked as farther from what it touched than it was.
+- **Breaking:** `Held` is `batchplan::Held`, no longer also `batchplan::task::Held`.
+- A device keeps the spheres it fits to held objects, the latest 64, and shares them with the
+  devices `with_robot` makes from it. `pick`, `place` and every call holding a cylinder or a
+  capsule fitted it again, which takes milliseconds; a box or a ball is covered in microseconds.
+- **Breaking:** `FollowStatus::Stopping { contacts }` and `FollowStatus::Collides { at, contacts }`
+  name what is in the way, as `Device::contacts` lists it: what the rest of the motion collided
+  with where it was first found to, numbered as in the worlds of the tick the stop began at and
+  repeated on every tick of the stop while it is clear, and what the robot collides with at
+  `at`. A graze a GPU device's check finds just outside what its CPU threads list names the
+  nearest within 0.1 mm. They said only that something collided. `Stopping` was a unit variant.
+- **Breaking:** `grasps` keeps the open fingers above `GraspOptions::floor` too, `opening` apart
+  and reaching `tip` past the frame, where it kept only the frame and the point between the
+  fingertips. A grasp tilted about a bar over a support, as a drawer's handle, swung one open
+  finger into it: of a bar whose top is 3.7 cm over a plate, every one of the 12 grasps tilted
+  from above at 16 turns put a Panda's finger into the plate. They are now held as far out as
+  keeps the finger over the floor, and left out where that holds less than `overlap`: the 4 left
+  all pick it. Grasps from the side that close upright on an object standing on the table, their
+  lower finger below the table's top, are left out too, so an object only those fit, such as a
+  box too wide across its top to grasp from above, gets an `Error::Input` where it got them. An
+  infinite `opening` is an `Error::Input`.
+
+### Fixed
+
+- A map no longer frees what another surface hides because the arm once hid it too: a voxel no
+  image has observed is the robot's shadow only while nothing else has hidden it, whichever image
+  came first. Under `Occlusion::OccupiedExceptRobotShadow` such a voxel is solid, where it read
+  free.
+- An obstacle whose rotation is a little off a unit quaternion (up to a thousandth is accepted)
+  is turned, not stretched. Its frame was built from the quaternion as given, which scaled it
+  by up to 0.4%: a 1.2 m box reached 2 mm past its ends, and a search, which first rules
+  obstacles out by bounding spheres of their stated size, could pass a configuration that
+  `evaluate` found 2 mm inside one. Frames are now built from the rotation made unit, on both
+  devices and in `Obstacle::distance`; a rotation that is unit to rounding is used as it is, so
+  results for those do not move. The same holds for a held object's shapes (`Robot::attach`
+  and a problem's `holding`), whose spheres sat up to 0.2% nearer or farther along the object,
+  for the obstacles `MeshModel::clearance` checks, and for a depth image's camera, whose
+  readings were placed 0.2% nearer or farther (5 mm at 3 m) in `SdfGrid::from_depth`,
+  `OccupancyMap::integrate` and `DepthImage::robot_mask`. A hold's grasp places its object by
+  the grasp made unit, and `Robot::assemble` a part by its base made unit. A camera's pose and
+  a part's base are now checked as other poses are: one that is not finite, or whose rotation
+  is more than a thousandth off unit, is an `Error::Input`, where it built a wrong grid or
+  robot without a word.
+
+- GPU devices on Windows using the FXC DX12 shader compiler can build the hand-frame kernels.
+
+- A plan from a moving start is optimized (`PlanOptions::seeds`) unless its path is within 2% of
+  the straight line from the start: the line was measured from the path's first control point,
+  which lies behind a moving start, so paths that bent by half as much again were left
+  unoptimized.
+- `Trajectory::stop` stops a motion from more of the states it passes through, and sooner. It
+  refused where a joint ran within 0.6% of its velocity limit, since a stop's velocity was held
+  to the margin under the limit even where it starts, and often while a motion still gathered
+  speed, since braking at once breaks the jerk limit there, or stopped only by creeping to the
+  path's end. It now also tries carrying on for one span with the motion's jerk, half of it or
+  none before braking, and keeps the stop that ends soonest along the path. Trajectories timed
+  up to the limits pass through such states more often. Through the first fifth of 48 planned
+  Panda motions, 52 of 960 stops are refused where 153 were and one takes longer than going on
+  where 66 did; of 19 states at a velocity limit, 9 stop where none did. A quarter of the way
+  along 438 motions, stops last 0.633 s where they lasted 0.646, and take 0.62 ms to find where
+  they took 0.73 (`examples/timing.rs`, which now times them, on an M4 Pro). A `Follower` that
+  must stop where none is found keeps to its trajectory, which comes to rest at the path's end.
+- Optimized seeds (`PlanOptions::seeds`) are validated as searched splines are checked: at samples no
+  farther apart than `shortcut.resolution`, keeping the margin from the world searched splines keep
+  away from their ends (2 mm, or `shortcut.clearance` if less). Validation kept no margin and
+  sampled each span `validate_substeps` times however far it moved, so optimization, which pulls
+  paths taut against obstacles, returned valid paths that collided between samples, as on picks
+  under a table. Their lengths, which `best` compares, are measured at those samples too.
+- `plan` refuses a start or a joint goal that is not finite. A continuous joint's range has no
+  limits, so a start at infinity there passed the limit check and planned a path of infinite
+  control points marked valid.
+- `Trajectory::at` and `Trajectory::sample` keep each position between the control points it
+  blends, so a path that runs along a joint limit never samples past it. Rounding left samples a
+  unit or two in the last place past (up to 4.8e-7 rad), which limit checks with no tolerance
+  refuse.
+- `pick` builds each holding device where it moves with it again, so building one overlaps the
+  other grasps' moves. 0.10.0 built them all first, which cost picks on a GPU device about 1.5%:
+  64 picks of the tasks example (`cargo run --release --example tasks -- 64`) took 185.5 ms on
+  an M4 Pro and take 183.2 ms now, against 181.5 ms in 0.9.0 (medians of seven alternated runs).
+  The rest of that gap is in grasping and moving in, whose code did not change.
+- `grasps` refuses an object whose size is negative or not finite, or whose rotation is not a
+  unit quaternion, naming it, as uploading a world does.
+
+## [0.10.0] - 2026-11-07
+
+### Changed
+
+- **Breaking:** `Robot::attach` refuses a shape whose size is negative or not finite, or whose
+  rotation is not a unit quaternion to within 1e-3, as uploading a world does, naming the shape.
+  0.9.0 attached such shapes with spheres that did not cover them. Normalize a rotation read
+  with few digits, such as (0, 0, 0.71, 0.71), before attaching it.
+- The model's `source` also gives the largest of each link's reach over its own tolerance.
+- `Robot::attach` fits a single shape in its own frame and places its spheres by the shape's
+  pose, so where it sits on its link no longer changes them, and `pick`, `place` and attaching
+  `Held::attachment` give a held object the same spheres.
+- `pick` and `place` fit each held object once and place its spheres by each grasp, where they
+  attached it at each grasp and fitted it again: picks of cylinders and capsules spend less of
+  their time attaching.
+
+### Fixed
+
+- `place` refuses a held object whose size is not finite, as an input error naming its task.
+- A pick's contacts where it lifts the object name obstacles as the task's world numbers them:
+  every obstacle after the picked one came back one index too low.
+- Where the budget reaches every tolerance but cannot hold each link within its own, what it has
+  left holds the spheres tighter. It used to go unspent, with spheres reaching up to twice their
+  link's tolerance. A stand of two boxes held to 2 cm (`tests/robot.rs`) reached 36.6 mm with 379
+  of 512 spheres, and now 24.1 mm with 502; the Panda at 1,200 spheres reached 9.5 mm against
+  5 mm, and now 5.8 mm. The search for the least growth makes such fits two to three times as
+  long: the Panda's at 1,200 spheres takes 0.20 s, where it took 0.10 s, and the stand's at 512
+  0.13 s, where it took 0.05 s.
+- Covers are refined until they reach every surface sample, where they stopped after 8 rounds,
+  so large boxes keep to their tolerance where the budget allows: the stand reached 25.7 mm at
+  1,024 spheres, and now 20.0 mm.
+
+## [0.9.0] - 2026-11-06
+
+### Changed
+
+- Fitted spheres reach less far past thin parts. Each link's spheres reach at most twice its
+  tolerance, scaled by what the budget allows, and less as the budget grows. Where the budget
+  affords it, each closed link is held within its own tolerance. Parts thinner than 0.1 mm and
+  vertices whose averaged normal leads out of the geometry may reach a little farther: at 2,048
+  spheres the Panda's base reaches 5.18 mm against 5 mm. The model's `source` names the scale.
+  Fitted models change, and saved models load as before.
+- Spheres held that tight leave slivers of surface about a millimeter deep outside them:
+  `LinkQualification::uncovered` reaches about 2% of a link, where it was a fraction of a
+  percent.
+- `Robot::qualify` measures on samples the fit did not draw.
+
+## [0.8.0] - 2026-11-06
+
+### Added
+
+- `Robot::relock` holds joints locked at load at new values, and `Device::with_robot` takes the
+  relocked robot without compiling kernels or uploading worlds again.
+- `FollowerOptions::lead`: time after the planning budget for a replan to reach the robot.
+
+### Changed
+
+- **Breaking:** `FollowStatus::Replanned` carries the new trajectory: `Replanned { at, trajectory }`.
+- **Breaking:** `FollowerOptions` gains `lead`, and `CollisionModel` gains `locked_joints`, the
+  joints locked while fitting. A model fitted with locked joints must be loaded with them locked
+  at the same values, and `relock` refuses to move them. Models saved before 0.8.0 load as before.
+
+### Fixed
+
+- `Device::evaluate` refuses configurations that are not finite, and `Robot::load` lock values
+  that are not finite.
+- GPU picks at small batches are as fast as in 0.6.1 again: IK that does not push away from
+  obstacles no longer splits each configuration's work across GPU invocations, and robots with
+  many spheres keep the split past 4,096 configurations.
+
+Earlier releases have no notes beyond their commits.
+
+[Unreleased]: https://github.com/natsuku-lab/batchplan/compare/v0.11.0...HEAD
+[0.11.0]: https://github.com/natsuku-lab/batchplan/compare/v0.10.0...v0.11.0
+[0.10.0]: https://github.com/natsuku-lab/batchplan/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/natsuku-lab/batchplan/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/natsuku-lab/batchplan/compare/v0.7.0...v0.8.0
+
+[historical-robokit]: https://github.com/natsuku-lab/batchplan/blob/9d7823a53148a3f571fd5615d0ebbd5818d8f1d4/docs/benchmarks.md#against-robokit