curobo.batch_motion_planner module

Batch motion planning module.

This module provides batch motion planning for solving multiple independent planning problems in parallel with a single IK + trajectory optimization pass.

Example

```python from curobo import BatchMotionPlanner, MotionPlannerCfg

config = MotionPlannerCfg.create(

robot=”franka.yml”, max_batch_size=16,

) planner = BatchMotionPlanner(config) result = planner.plan_pose(goal_tool_poses, current_states) ```

class BatchMotionPlanner(config)

Bases: object

Batch motion planner: solves batch_size problems in parallel.

Single IK → (optional graph seed) → TrajOpt pass with no retries. When multi_env=False, the PRM graph planner provides trajectory seeds. When multi_env=True, graph seeding is unavailable.

Parameters:

config (MotionPlannerCfg) – Planner configuration. max_batch_size and multi_env are read from config.ik_solver_config.

__init__(config)
Parameters:

config (curobo._src.motion.motion_planner_cfg.MotionPlannerCfg)

destroy()

Release all CUDA graph resources.

Call before dropping the last reference to avoid cudaMallocAsync warnings about captured allocations freed outside graph replay.

property attachment_manager

Attachment manager for attaching/detaching obstacles to robot links.

property batch_size: int
warmup(
enable_graph=True,
num_warmup_iterations=5,
)

JIT-warmup the solvers and (optionally) the graph planner.

Parameters:

  • enable_graph (bool) – Warmup graph planner if available (multi_env=False).

  • num_warmup_iterations (int) – Number of dummy solves.

Return type:

bool

plan_pose(
goal_tool_poses,
current_state,
use_implicit_goal=True,
max_attempts=1,
success_ratio=1.0,
enable_graph_attempt=0,
)

Plan trajectories for a batch of pose targets.

Runs up to max_attempts IK -> TrajOpt passes. On each attempt the full batch is re-solved; per-problem results are locked in on first success (first-success-wins). The loop exits early when the fraction of solved problems reaches success_ratio.

Parameters:

  • goal_tool_poses (GoalToolPose) – Target poses as GoalToolPose [B, H, L, G, 3/4].

  • current_state (JointState) – Initial joint states (batch_size, dof).

  • use_implicit_goal (bool) – Use IK solution as implicit trajectory goal.

  • max_attempts (int) – Maximum number of IK + TrajOpt passes.

  • success_ratio (float) – Exit early when this fraction of the batch has succeeded (0.0-1.0). Default 1.0 means wait for all.

  • enable_graph_attempt (int) – Attempt index at which to start graph seeding (when graph planner is available).

Return type:

Optional[TrajOptSolverResult]

Returns:

TrajOptSolverResult with per-problem success, or None if IK never found any solution across all attempts.

plan_cspace(
goal_states,
current_state,
max_attempts=1,
success_ratio=1.0,
enable_graph_attempt=0,
)

Plan trajectories for a batch of joint-space targets.

Same retry / first-success-wins logic as plan_pose.

Parameters:

  • goal_states (JointState) – Target joint configurations (batch_size, dof).

  • current_state (JointState) – Initial joint states (batch_size, dof).

  • max_attempts (int) – Maximum number of TrajOpt passes.

  • success_ratio (float) – Exit early when this fraction of the batch has succeeded.

  • enable_graph_attempt (int) – Attempt index to start graph seeding.

Return type:

Optional[TrajOptSolverResult]

Returns:

TrajOptSolverResult with per-problem success.

plan_grasp(
grasp_poses,
current_state,
grasp_approach_axis='z',
grasp_approach_offset=-0.15,
grasp_approach_in_tool_frame=True,
grasp_lift_axis='z',
grasp_lift_offset=-0.15,
grasp_lift_in_tool_frame=True,
plan_approach_to_grasp=True,
plan_grasp_to_lift=True,
disable_collision_links=None,
)

Plan grasp motions for a batch: goalset -> approach -> grasp -> lift.

All B problems are planned at every stage (CUDA graph stability). Problems that fail a stage get their current state substituted as the goal for subsequent stages so the optimizer doesn’t diverge.

Return type:

GraspPlanResult

Parameters:
property joint_names: List[str]
property action_dim: int
property tool_frames: List[str]
property default_joint_state: curobo._src.state.state_joint.JointState
property kinematics: curobo._src.robot.kinematics.kinematics.Kinematics
compute_kinematics(
state,
)
Return type:

KinematicsState

Parameters:

state (curobo._src.state.state_joint.JointState)

update_world(
scene_cfg,
)
Parameters:

scene_cfg (curobo._src.geom.types.SceneCfg)

clear_scene_cache()
reset_seed()
Parameters:

enable_collision_links (List[str])

Parameters:

disable_collision_links (List[str])

update_tool_pose_criteria(
tool_pose_criteria,
)
Parameters:

tool_pose_criteria (Dict[str, curobo._src.cost.tool_pose_criteria.ToolPoseCriteria])

Return type:

None

Parameters:
Return type:

None

Parameters:

link_properties (dict[str, dict[str, float | torch.Tensor]])

class MotionPlannerCfg(
ik_solver_config,
trajopt_solver_config,
graph_planner_config=None,
scene_collision_cfg=None,
device_cfg=DeviceCfg(device=device(type='cuda', index=0), dtype=torch.float32, collision_geometry_dtype=torch.float32, collision_gradient_dtype=torch.float32, collision_distance_dtype=torch.float32),
)

Bases: object

Configuration for the motion planner.

Parameters:

  • ik_solver_config (curobo._src.solver.solver_ik_cfg.IKSolverCfg)

  • trajopt_solver_config (curobo._src.solver.solver_trajopt_cfg.TrajOptSolverCfg)

  • graph_planner_config (curobo._src.graph_planner.graph_planner_prm_cfg.PRMGraphPlannerCfg)

  • scene_collision_cfg (curobo._src.geom.collision.collision_scene.SceneCollisionCfg | None)

  • device_cfg (curobo._src.types.device_cfg.DeviceCfg)

ik_solver_config: curobo._src.solver.solver_ik_cfg.IKSolverCfg
trajopt_solver_config: curobo._src.solver.solver_trajopt_cfg.TrajOptSolverCfg
graph_planner_config: curobo._src.graph_planner.graph_planner_prm_cfg.PRMGraphPlannerCfg = None
scene_collision_cfg: curobo._src.geom.collision.collision_scene.SceneCollisionCfg | None = None
device_cfg: curobo._src.types.device_cfg.DeviceCfg = DeviceCfg(device=device(type='cuda', index=0), dtype=torch.float32, collision_geometry_dtype=torch.float32, collision_gradient_dtype=torch.float32, collision_distance_dtype=torch.float32)
static create(robot, ik_optimizer_configs=['ik/lbfgs_ik.yml'], ik_transition_model='ik/transition_ik.yml', metrics_rollout='metrics_base.yml', trajopt_optimizer_configs=['trajopt/lbfgs_bspline_trajopt.yml'], trajopt_transition_model='trajopt/transition_bspline_trajopt.yml', graph_planner_config='graph_planner/exact_graph_planner.yml', graph_planner_rollout='metrics_base.yml', graph_planner_transition_model='graph_planner/transition_graph_planner.yml', scene_model=None, collision_cache=None, self_collision_check=True, device_cfg=DeviceCfg(device=device(type='cuda', index=0), dtype=torch.float32, collision_geometry_dtype=torch.float32, collision_gradient_dtype=torch.float32, collision_distance_dtype=torch.float32), num_ik_seeds=32, num_trajopt_seeds=4, position_tolerance=0.005, orientation_tolerance=0.05, use_cuda_graph=True, random_seed=123, optimizer_collision_activation_distance=0.01, store_debug=False, transition_model_config_instance_type=<class 'curobo._src.transition.robot_state_transition_cfg.RobotStateTransitionCfg'>, cost_manager_config_instance_type=<class 'curobo._src.rollout.cost_manager.cost_manager_robot_cfg.RobotCostManagerCfg'>, max_batch_size=1, multi_env=False, max_goalset=1)

Create a MotionPlannerCfg from robot, task, and scene configs.

This factory builds the three components used by MotionPlanner: IK, trajectory optimization, and PRM graph planning. Most integration code should pass a robot, optional scene/collision cache, sizing bounds, and leave the task YAMLs at their defaults.

Config path arguments may be relative YAML names under cuRobo’s content folders, absolute YAML paths, parsed dictionaries, or typed config objects where supported.

Parameters:

  • robot (Union[str, Dict[str, Any], RobotCfg]) – Robot config. String paths are resolved relative to cuRobo robot configs unless absolute. Dicts and RobotCfg objects are accepted.

  • ik_optimizer_configs (List[Union[str, Dict[str, Any]]]) – IK optimizer task configs. Defaults to ["ik/lbfgs_ik.yml"]. Add "ik/particle_ik.yml" when broader IK search is needed.

  • ik_transition_model (Union[str, Dict[str, Any]]) – IK transition model task config.

  • metrics_rollout (Union[str, Dict[str, Any]]) – Metrics rollout task config shared by IK, TrajOpt, and graph planner validation.

  • trajopt_optimizer_configs (List[Union[str, Dict[str, Any]]]) – Trajectory optimization task configs.

  • trajopt_transition_model (Union[str, Dict[str, Any]]) – Trajectory optimization transition model config.

  • graph_planner_config (Union[str, Dict[str, Any]]) – PRM graph planner config. The default enables graph seeding for single-environment planning. This factory currently expects a graph planner config.

  • graph_planner_rollout (Union[str, Dict[str, Any]]) – Rollout config used by the graph planner for collision/feasibility checks.

  • graph_planner_transition_model (Union[str, Dict[str, Any]]) – Transition model used by graph planner rollout validation.

  • scene_model (Union[str, Dict[str, Any], None]) – Optional scene config. String paths are resolved relative to cuRobo scene configs. When None, no world obstacles are loaded initially.

  • collision_cache (Optional[Dict[str, int]]) – Optional obstacle cache sizes, for example {"mesh": 2, "cuboid": 8}. When scene_model is None, this still preallocates a scene collision checker for later update_world calls.

  • self_collision_check (bool) – Enable robot self-collision costs/checks in IK, TrajOpt, and graph planner validation.

  • device_cfg (DeviceCfg) – Tensor device and dtype configuration.

  • num_ik_seeds (int) – Number of IK seeds evaluated per problem. A value of 16 is good for most single-tool planning problems; increase to 32 when more IK diversity is needed. Increasing beyond 32 usually does not help unless solving multi-tool IK/planning problems.

  • num_trajopt_seeds (int) – Number of trajectory optimization seeds. MotionPlanner asks IK to return this many solutions to seed TrajOpt. The default of 4 is recommended; using more than 4 typically does not improve solution quality and can significantly increase planning time.

  • position_tolerance (float) – Cartesian position tolerance in meters used for IK and TrajOpt success.

  • orientation_tolerance (float) – Cartesian orientation tolerance in radians used for IK and TrajOpt success.

  • use_cuda_graph (bool) – Enable CUDA graph capture for solver rollouts and optimizers. Defaults to True and should be left enabled for normal integration/runtime code. The value is forwarded to IK, TrajOpt, and graph-planner rollout components. cuRobo manages graph caches internally and pads smaller batches/ goalsets up to max_batch_size and max_goalset. Set to False only for debugging graph-capture issues; steady-state solve calls can be about 5x slower without CUDA graph replay. Also disabled automatically when store_debug=True.

  • random_seed (int) – Random seed forwarded to IK and TrajOpt seed generation. Graph planner path finding uses its own seed in PRMGraphPlannerCfg.

  • optimizer_collision_activation_distance (float) – Collision-cost activation distance forwarded to IK and TrajOpt optimizer rollouts. The default is 0.01 m (10 mm). Increasing this distance makes the optimizer react to obstacles earlier and keep more clearance, but can make narrow passages harder or infeasible. Decreasing it allows closer motion near obstacles, but can reduce clearance margin and make collision avoidance less robust.

  • store_debug (bool) – Whether to store debug information. When True, CUDA graphs are disabled automatically.

  • transition_model_config_instance_type (Type[RobotStateTransitionCfg]) – Advanced extension hook for custom transition model config classes.

  • cost_manager_config_instance_type (Type[RobotCostManagerCfg]) – Advanced extension hook for custom cost manager config classes.

  • max_batch_size (int) – Maximum batch size captured/allocated by IK and TrajOpt. Single MotionPlanner calls use one problem; BatchMotionPlanner uses up to this value. Smaller batches are padded internally.

  • multi_env (bool) – Use one collision environment per batch item. This is for BatchMotionPlanner with per-problem worlds; graph seeding is skipped in this mode.

  • max_goalset (int) – Maximum number of alternative goal poses per problem. Smaller goalsets are padded internally.

Return type:

MotionPlannerCfg

Returns:

MotionPlannerCfg containing IK, TrajOpt, graph planner, and optional scene collision configuration.

__init__(
ik_solver_config,
trajopt_solver_config,
graph_planner_config=None,
scene_collision_cfg=None,
device_cfg=DeviceCfg(device=device(type='cuda', index=0), dtype=torch.float32, collision_geometry_dtype=torch.float32, collision_gradient_dtype=torch.float32, collision_distance_dtype=torch.float32),
)
Parameters:

  • ik_solver_config (curobo._src.solver.solver_ik_cfg.IKSolverCfg)

  • trajopt_solver_config (curobo._src.solver.solver_trajopt_cfg.TrajOptSolverCfg)

  • graph_planner_config (curobo._src.graph_planner.graph_planner_prm_cfg.PRMGraphPlannerCfg)

  • scene_collision_cfg (curobo._src.geom.collision.collision_scene.SceneCollisionCfg | None)

  • device_cfg (curobo._src.types.device_cfg.DeviceCfg)

Return type:

None