Grasp Optimization
Batched Warp grasp optimizer: samples init grasps per scene, then runs GraspOptimConfig.optimizer_backend.
Optimize grasps for each scene; returns (n_scene, num_samples_per_scene, dof) grasp variables.
Per-term 0.5·Σr² cost of (n_scene, n, dof) grasps, with contacts re-picked nearest the object.
Grasp optimizer algorithm and runtime parameters, with hand-independent defaults.
The config of the optimize_grasps stage (ExperimentConfig.grasp_optim); every field is a CLI flag, e.g. --grasp_optim.num_iters 2000. The annealing fields drive warp_gd only and the lm_* fields warp_lm only. The init-sampler fields feed stages/grasp_optim/sampler.py; the runtime fields feed optimize_pipeline.py, not a bare optimize() call.
Annealing iterations (warp_gd). Each replays one CUDA graph; fewer trade grasp quality for speed, and 2000 suits smoke tests.
Active contact points per grasp, drawn from the robot's contact candidates; they parameterize the distance and force-closure terms. 4-5 fits most five-finger hands.
Per-grasp probability, each iteration, of re-drawing the whole contact set; the Metropolis test accepts or rejects it together with the pose step.
RMSprop weight on the current squared gradient, ema = mu * g^2 + (1 - mu) * ema. Near 1 the step approaches the gradient's sign times step_size.
Base RMSprop step; the effective step is step_size * temperature_decay^(t // stepsize_period).
Iterations between step-size decays.
Initial Metropolis temperature T: a proposal that worsens the energy by d is still accepted with probability exp(-d / T).
Iterations per temperature decay, T = starting_temperature * temperature_decay^(t // annealing_period).
Decay factor shared by the temperature and step-size schedules; closer to 1 cools slower and explores more.
Self-collision margin (m) between sphere/capsule pairs; 2 cm pinned the middle finger of most hands off the object.
Self-collision geometry for warp_gd: per-link capsules or the collision spheres. warp_lm always uses capsules.
Force-closure weight: the active contact normals must balance external wrenches. A zero weight disables any term.
Weight pulling each active contact point onto the target surface.
Weight of the fingertip term (warp_gd only; requires fingertip links set): each fingertip link's closest collision sphere is drawn onto the object. 0 disables; a hand should touch without it, this is a last resort.
warp_gd scene-penetration weight: hand collision spheres against the target and table, with a fixed 5 mm margin. warp_lm uses lm_w_pen.
Self-penetration weight between robot links; zero skips building the term.
warp_gd joint-limit weight; q is also clamped to its limits every iteration. warp_lm uses lm_w_joints.
Weight of the hand-orientation prior (HandUpAngleTask, both backends).
Minimum angle between the hand-up axis and world +z; tabletop configs use it to forbid underhand grasps.
Hand-axis cone filter on init samples: which hand_coord_spec axis to check, after IK for fixed-base samplers. None disables it. The cone on optimized grasps lives on GraspTrajBuilderConfig.
Direction hand_axis should point, in the robot base frame (world for floating hands).
Hand-axis cone half-angle in degrees.
warp_gd: simulated-annealing gradient descent for floating or fixed-base robots. warp_lm: multi-seed Levenberg-Marquardt, floating base only, typically 2-3x faster and needs fingertip links; to target an arm, set enable_ik_scoring and let GraspTrajBuilder IK-convert.
sdf_volume: a cached SDF of the target mesh plus analytic table boxes; fast, accuracy bounded by voxel size, and the target must be the scene's only mesh. mesh: per-scene BVHs, exact but slower.
SDF bake padding, in mesh units (robokit bakes the unscaled mesh and applies scales at query time).
Voxel grid resolution along the longest axis when sdf_voxel_size is None.
Voxel size in mesh units (before scales). None = derive voxel size from sdf_resolution.
Sphere-level broad-phase skip on the warp scene-collision task. Only for scene_geom_backend="sdf_volume".
warp_lm counterpart of w_pen: scene-collision term weight (LM raw-residual scale).
warp_lm counterpart of w_joints: position-limit term weight (LM raw-residual scale).
warp_lm counterpart of w_fingertip_dis: fingertip-distance term weight (LM raw-residual scale).
warp_lm scene-collision margin (meters).
warp_lm residual epsilon for distance / position-limit / self-penetration terms.
warp_lm floating-base step relative to the joint step; keeps base updates from overshooting.
warp_lm per-seed joint half-range: the 24 seeds are the init qpos plus Roberts offsets in [-range, range], clamped to limits.
warp_lm per-seed base-translation sampling half-range (floating base only).
warp_lm floating base only: oversample inits 16x, keep those an arm IK can reach, and rank solutions by energy plus reachability. Use when GraspTrajBuilder will IK-convert onto an arm.
In-loop simulation filter: each optimized batch is rolled out (e.g. with perturbation or a heavy object) and only survivors are saved. None gates on motion-plan success only.
fixed_base: look-at poses solved to collision-free arm IK. wbc: world-rooted arms, any azimuth, never from below the table. floating_base: no IK, emits [xyz, euler_rxyz, hand_qpos]; floating optimizers force it.
Lower bound (m) of the hand-to-surface standoff, sampled uniformly. Tight bounds are the usual cause of starved init sampling.
Upper bound (m) of the hand-to-surface standoff.
Lower bound of the roll jitter about the look-at approach axis.
Upper bound of the roll jitter about the look-at approach axis.
Lower bound of the tilt jitter about the two axes perpendicular to the approach.
Upper bound of the tilt jitter about the two axes perpendicular to the approach.
Std of the per-joint Gaussian jitter added to hand_qpos_mu.
Mean hand qpos for init sampling, typically half-open; None uses the robot config's init qpos.
Position tolerance (m) for the init-time arm IK solve (FixedBaseSampler / WBCSampler).
Orientation tolerance (rad) for that solve.
That solve keeps the solution nearest the rest pose; False keeps its best-scoring random seed.
Reject init IK solutions whose arm-qpos L2 distance from the rest pose exceeds this.
IK candidates per requested sample before collision/rest filtering (this × num_samples_per_scene).
Empty-space points sampled per requested sample when seeding approach directions.
Chunk size of the IK + collision sweep over candidates (memory only).
Grasps optimized per scene per attempt.
Scenes batched into one solve: num_scenes_per_batch * num_samples_per_scene grasps on the GPU.
A scene is done once its output holds this many grasps; scenes below it are re-attempted.
Top-up passes over unfinished scenes; attempt i runs with seed + i.
If set, caps scenes processed per attempt (after sort/shuffle/rank slicing). Useful for quick testing.
Save all candidates and their filter/plan/simulation verdicts to <grasp_output_dir>.labels/.
Robot equipped with the grasp-pipeline torch facade and contact-point candidates.
Build (and cache) a GraspRobot from RobotConfig; pruned to ee_link_names, prune=False for the full robot.
Load representation-specific pairs against this robot's pruned link names.
Torch FK. Two cases:
- floating base: variables packs free qpos (xyz + rxyz or xyz + 6d) then actuated qpos (root_poses must not be provided).
- fixed base: variables is just qpos (root_poses optional).
Actuated joints that are neither arm nor hand (complement of arm ∪ hand indices).
Link-local collision spheres from collision_spheres_path: (num_spheres,4) centers+radius, link indices.
Canonical contact candidates: (N,3) link-local centers, (N,) link indices in the chain robot's link order.