curobo.motion_planner module

Motion planning module.

This module provides high-level motion planning combining trajectory optimization and graph planning.

Example

```python from curobo import MotionPlanner, MotionPlannerCfg

config = MotionPlannerCfg.create(robot=”franka.yml”) planner = MotionPlanner(config) result = planner.plan_pose(goal_tool_poses, current_state) ```

class MotionPlanner(config)

Bases: object

Single-problem motion planner with retry logic and graph-planner seeding.

Solves one planning problem at a time (batch_size=1). For batched planning see BatchMotionPlanner.

Parameters:

config (MotionPlannerCfg)

__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.

Does not synchronize, the gc.collect() + synchronize() fence in GraphExecutor._initialize_cuda_graph ensures stale cuGraphExecDestroy calls complete before any new capture begins.

property attachment_manager

Attachment manager for attaching/detaching obstacles to robot links.

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)

warmup(
enable_graph=True,
warmup_joint_index=0,
warmup_joint_delta=0.2,
num_warmup_iterations=10,
)
Return type:

bool

Parameters:

  • enable_graph (bool)

  • warmup_joint_index (int)

  • warmup_joint_delta (float)

  • num_warmup_iterations (int)

plan_pose(
goal_tool_poses,
current_state,
use_implicit_goal=True,
max_attempts=5,
enable_graph_attempt=1,
)

Plan a trajectory to reach target tool poses.

Goalset is auto-detected from goal_tool_poses.num_goalset. When num_goalset > 1 the planner uses a simpler IK+TrajOpt loop without graph seeding.

Return type:

Optional[TrajOptSolverResult]

Parameters:
plan_cspace(
goal_state,
current_state,
max_attempts=5,
enable_graph_attempt=1,
)

Plan a collision-free trajectory to a joint configuration.

Parameters:

  • goal_state (JointState) – Target joint configuration.

  • current_state (JointState) – Initial joint state.

  • max_attempts (int) – Maximum planning attempts.

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

Return type:

Optional[TrajOptSolverResult]

Returns:

TrajOptSolverResult, or None if planning failed.

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 a grasp motion: goalset -> approach -> grasp -> lift.

Parameters:

  • grasp_poses (GoalToolPose) – Candidate grasp poses with num_goalset entries per link. Construct via GoalToolPose with the desired goalset size.

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

  • grasp_approach_axis (str)

  • grasp_approach_offset (float)

  • grasp_approach_in_tool_frame (bool)

  • grasp_lift_axis (str)

  • grasp_lift_offset (float)

  • grasp_lift_in_tool_frame (bool)

  • plan_approach_to_grasp (bool)

  • plan_grasp_to_lift (bool)

  • disable_collision_links (List[str])

Return type:

GraspPlanResult

Parameters:

enable_collision_links (List[str])

Parameters:

disable_collision_links (List[str])

update_world(scene_cfg)
Parameters:

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

clear_scene_cache()
reset_seed()
Return type:

None

Parameters:
Return type:

None

Parameters:

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

update_tool_pose_criteria(
tool_pose_criteria,
)
Parameters:

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

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

class GraspPlanResult(
success=None,
approach_success=None,
grasp_success=None,
lift_success=None,
approach_trajectory=None,
approach_trajectory_dt=None,
approach_interpolated_trajectory=None,
grasp_trajectory=None,
grasp_trajectory_dt=None,
grasp_interpolated_trajectory=None,
lift_trajectory=None,
lift_trajectory_dt=None,
lift_interpolated_trajectory=None,
approach_interpolated_last_tstep=None,
grasp_interpolated_last_tstep=None,
lift_interpolated_last_tstep=None,
status=None,
planning_time=0.0,
goalset_index=None,
)

Bases: object

Result of a grasp planning operation.

Parameters:
success: torch.Tensor | None = None
approach_success: torch.Tensor | None = None
grasp_success: torch.Tensor | None = None
lift_success: torch.Tensor | None = None
approach_trajectory: curobo._src.state.state_joint.JointState | None = None
approach_trajectory_dt: torch.Tensor | None = None
approach_interpolated_trajectory: curobo._src.state.state_joint.JointState | None = None
grasp_trajectory: curobo._src.state.state_joint.JointState | None = None
grasp_trajectory_dt: torch.Tensor | None = None
grasp_interpolated_trajectory: curobo._src.state.state_joint.JointState | None = None
lift_trajectory: curobo._src.state.state_joint.JointState | None = None
lift_trajectory_dt: torch.Tensor | None = None
lift_interpolated_trajectory: curobo._src.state.state_joint.JointState | None = None
approach_interpolated_last_tstep: torch.Tensor | None = None
grasp_interpolated_last_tstep: torch.Tensor | None = None
lift_interpolated_last_tstep: torch.Tensor | None = None
status: str | None = None
planning_time: float = 0.0
goalset_index: torch.Tensor | None = None
__init__(
success=None,
approach_success=None,
grasp_success=None,
lift_success=None,
approach_trajectory=None,
approach_trajectory_dt=None,
approach_interpolated_trajectory=None,
grasp_trajectory=None,
grasp_trajectory_dt=None,
grasp_interpolated_trajectory=None,
lift_trajectory=None,
lift_trajectory_dt=None,
lift_interpolated_trajectory=None,
approach_interpolated_last_tstep=None,
grasp_interpolated_last_tstep=None,
lift_interpolated_last_tstep=None,
status=None,
planning_time=0.0,
goalset_index=None,
)
Parameters:
Return type:

None