batches 0.11.0b1__tar.gz

batches-0.11.0b1/AGENTS.md

@@ -0,0 +1,130 @@
+# 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` or `ToolPath`, 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. 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)).
+- **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 `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) |
+| Motions run without stopping between them | `join` | [joins](docs/planning.md#joining-motions) |
+| 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 it 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.
+- 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 (starts and goals must be within them), 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; 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. `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: worlds where a held object may touch something are uploaded to the device of the robot holding it.
+- `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.
+- `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)).

batches-0.11.0b1/CHANGELOG.md

@@ -0,0 +1,253 @@
+# 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]
+
+### Added
+
+- **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
+
+- 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
+  ([Benchmarks](docs/benchmarks.md#against-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).
+- IK on a GPU takes 10-28% less time: the kernels are built without the counter naga adds to
+  every loop to rule out infinite ones, which theirs cannot be (the crate's one `unsafe`). One
+  target's 64 seeds of 30 steps take 1.01 ms where they took 1.27 on an M4 Pro for a Panda
+  without collision spheres (2.83 ms where 3.33 with them), and 0.53 ms where 0.74 on an RTX
+  4090 (about 1.2 ms where 1.33). A GPU's results round differently for it, as they do from
+  driver to driver ([Benchmarks](docs/benchmarks.md#how-the-speed-came)).
+- 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 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.10.0...HEAD
+[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

batches-0.11.0b1/CONTRIBUTING.md

@@ -0,0 +1,121 @@
+# Contributing
+
+Thanks for helping. Issues and pull requests are welcome at
+[natsuku-lab/batchplan](https://github.com/natsuku-lab/batchplan).
+
+## Building and testing
+
+```bash
+cargo build --release --all-targets --features lerobot,usd
+BATCHPLAN_REQUIRE_GPU=1 cargo test --release --features lerobot,usd   # fails rather than skips the GPU tests without an adapter
+cargo test --release --no-default-features                            # the CPU-only build
+cargo clippy --release --all-targets --features lerobot,usd           # zero warnings; CI denies them
+cargo doc --no-deps --features lerobot,usd                            # zero warnings
+(cd demos && cargo clippy --release --all-targets)                    # the Rerun demos, a crate of their own
+(cd python && BATCHPLAN_REQUIRE_GPU=1 uv run pytest)                  # the Python bindings, built and tested through the package
+scripts/check.sh                                                      # every lint CI runs, on every crate: run it before pushing
+```
+
+CI runs the same on Linux, with the GPU kernels on Mesa's llvmpipe, and builds on macOS, Windows
+and aarch64 Linux. [Verification](docs/verification.md) says what each test pins down.
+
+## Style
+
+The code follows [Google's Rust style guide](https://google.github.io/styleguide/rustguide.html).
+Format with stable rustfmt, then check the guide's options that only nightly rustfmt has:
+
+```bash
+cargo fmt
+rustup toolchain install nightly --profile minimal -c rustfmt
+cargo +nightly fmt --check -- --config imports_granularity=Module,hex_literal_case=Lower,format_macro_matchers=true
+```
+
+Clippy checks what it can of the guide (`[lints]` in `Cargo.toml`, and `src/lib.rs` for the
+library). Where the guide leaves a choice to the codebase:
+
+- **Imports.** No glob imports, except `use super::*` in test modules and the rayon and
+  fearless_simd preludes. Call free functions through their module (`world::box_distance`,
+  `datagen::handover`, `batchplan::plan`), and import types by name, unless the name would clash
+  or comes from wgpu or rerun.
+- **Modules.** A module with children only declares and re-exports them.
+- **API.** Document every public item; mark pure functions `#[must_use]`; name a constructor that
+  returns a `Result` `try_new`; return named fields rather than tuples; spell names out (the
+  field's own terms, such as `dof` and `q`, excepted). Results and enums that may grow are
+  `#[non_exhaustive]`; options and problems keep struct literals, so struct update syntax works.
+- **Implementation.** `expect` says why it cannot fail, `for` loops replace sequential
+  `for_each`, iterator chains are named before a `for` loop, and assertions say why they hold.
+
+## Changes
+
+- **A new test must fail on the unfixed code.** Plant the bug and watch the test fail.
+- **The CPU and the GPU implement the same math.** A change to one (`src/cpu.rs`, the kernels in
+  `src/*.wgsl` and `gpu.rs`) lands in the other in the same change; the parity tests catch drift.
+- **Performance claims need an A/B comparison on one machine.** Build the previous commit in a
+  `git worktree` with its own `CARGO_TARGET_DIR`, and alternate runs with yours after checking the
+  machine is idle. One run proves nothing.
+- **Numbers in the docs come from runs you can name.** [Benchmarks](docs/benchmarks.md) says how
+  each was measured; rerun what a change moves and update every page that quotes it.
+
+## Review
+
+Before pushing, run `scripts/check.sh`, then have the reviewer agent read the change. In
+[Claude Code](https://claude.com/claude-code), ask for the `reviewer` agent on your branch
+([`.claude/agents/reviewer.md`](.claude/agents/reviewer.md)). It checks the change against the
+rules in [CLAUDE.md](CLAUDE.md): correctness, the CPU/GPU twin and the other invariants,
+deep-module design, the style guide, tests that fail on the unfixed code, measured performance and
+docs that match the code. It reports each defect with the input that shows it. Fix what it finds,
+or say in the pull request why a finding does not apply.
+
+[CLAUDE.md](CLAUDE.md) holds the design rules, invariants and working rules, for people and coding
+agents alike; [architecture.md](docs/architecture.md) says how the code fits together.
+
+## Releases
+
+Merging is not releasing. Changes collect on `main` and ship together, so a version stands for a
+batch of changes rather than for each one.
+
+- **The changelog.** A change a user would notice adds a line to `## [Unreleased]` in
+  [CHANGELOG.md](CHANGELOG.md), under Keep a Changelog's headings (Added, Changed, Removed,
+  Fixed). Mark with **Breaking:** whatever
+  breaks code written against the last release.
+- **Before a release.** A project that needs a merged change before it ships pins its commit,
+  `batchplan = { git = "https://github.com/natsuku-lab/batchplan", rev = "<commit>" }`, and goes
+  back to a version when the release is out. crates.io takes no crate with a git dependency, so
+  this is for applications and unpublished crates. To try the changes from crates.io, cut a
+  pre-release: `0.10.0-beta.1`, then `0.10.0-beta.2`. Cargo picks a pre-release only for a
+  requirement that names one, so users of `0.9` never get it. One beta may break the last, and a
+  requirement of one takes the next, so a project trying a beta pins it exactly
+  (`batchplan = "=0.10.0-beta.1"`).
+- **Patch or minor.** `cargo semver-checks --release-type minor`
+  (`cargo install cargo-semver-checks --locked`) fails on a change to the interface that breaks
+  the latest release on crates.io. It calls such a change major, which before 1.0 means the next
+  minor version. A call that now behaves differently can break callers too, which only a reader
+  sees. A batch that breaks nothing is a patch, even one that adds to the interface. Breaking
+  changes wait on `main` for the next minor version.
+- **When.** A patch whenever a fix should reach crates.io users. A minor release at most every
+  two weeks, once a beta of it has run in the projects that use batchplan,
+  [batchplan-ros](https://github.com/natsuku-lab/batchplan-ros) among them. A patch for a release
+  that `main` has moved past with breaking changes goes on a branch from that release's last tag
+  (`0.9.x` from `v0.9.0`). Changes reach the branch by pull request, so CI runs on them, and their
+  changelog lines go to `main` too.
+- **Cutting one.**
+  1. Set `version` in `Cargo.toml` and `python/Cargo.toml` (the Python package's). The next build
+     of each crate updates `Cargo.lock`, `demos/Cargo.lock` and `python/Cargo.lock`, and
+     `scripts/check.sh` builds all three.
+  2. For a release, not a beta, move the lines under `## [Unreleased]` to a new
+     `## [0.10.0] - date`, and point the compare links at the end of the file at it.
+  3. Commit it as `batchplan 0.10.0`, to `main` or by pull request to a release's branch, and
+     wait for CI.
+  4. `git tag -a v0.10.0 -m "batchplan 0.10.0" && git push origin v0.10.0`. The release workflow
+     checks that the tag names the version and that `cargo semver-checks` passes, then publishes to
+     crates.io.
+  5. After a release, move batchplan-ros to it.
+- **1.0** waits for an interface we mean to keep. Two-digit minor versions until then are usual
+  for Rust crates: nalgebra, glam and rapier are past 0.30. One decision comes first: how options
+  and problems grow. Today a new field breaks callers' struct literals, and after 1.0 each one would
+  take a major version.
+
+## License
+
+Contributions are dual-licensed under MIT or Apache-2.0, as the project is, unless you say
+otherwise.