curobo.optim module

Optimizer module.

Public surface for cuRobo’s underlying optimizers. Most users should prefer the higher-level solvers (InverseKinematics, TrajectoryOptimizer, MotionPlanner, ModelPredictiveControl) which wrap these optimizers with sensible defaults.

Use this module when building custom optimization pipelines, for example to minimize a user-defined rollout with MPPI, evolution strategies, L-BFGS, PyTorch, or SciPy optimizers, or to chain them with MultiStageOptimizer.

Example

from curobo.optim import MPPI, MPPICfg

cfg = MPPICfg(...)
opt = MPPI(cfg)
result = opt.optimize(rollout, seed=x0)
class EvolutionStrategies(
config,
rollout_list,
use_cuda_graph=False,
)

Bases: object

Evolution Strategies optimizer using z-score weighting and natural gradient mean updates.

Draws action samples from a Gaussian via ParticleOptCore, computes trajectory costs through rollouts, and updates the distribution using z-score-weighted sample statistics with a configurable learning rate.

Parameters:
__init__(
config,
rollout_list,
use_cuda_graph=False,
)
Parameters:
property config
property device_cfg
property opt_dt
property use_cuda_graph
property enabled
enable()
disable()
property action_horizon
property action_dim
property opt_dim
property outer_iters
property horizon
property action_bound_lows
property action_bound_highs
property action_step_max
property action_horizon_bounds_lows
property action_horizon_bounds_highs
property solve_time
property solver_names
property rollout_fn
property mean_action
property best_traj
property cov_action
property scale_tril
property inv_cov_action
property full_scale_tril
property full_inv_cov
property sample_lib
property particles_per_problem
property sampled_particles_per_problem
property null_per_problem
property neg_per_problem
property total_num_particles
property null_act_seqs
property problem_col
property top_trajs
property gamma_seq
optimize(
seed_action,
)

Run the full optimization loop and return the best action sequence.

reinitialize(
action,
mask=None,
clear_optimizer_state=True,
reset_num_iters=False,
)

Reset optimizer state and seed with new actions before a fresh solve.

shift(shift_steps=0)
update_num_problems(
num_problems,
)

Resize internal buffers to accommodate a new number of parallel problems.

update_rollout_params(
goal,
)
update_goal_dt(goal)
get_all_rollout_instances()
compute_metrics(
action,
)

Evaluate cost and constraint metrics for the given action sequence.

reset_shape()
reset_seed()
reset_cuda_graph()
get_recorded_trace()
update_solver_params(
solver_params,
)
update_niters(
niters,
)
debug_dump(
file_path='',
)
update_seed(
init_act,
)
update_init_mean(
init_mean,
)
get_rollouts()
reset_distribution(
reset_problem_ids=None,
)
reset_mean(
reset_problem_ids=None,
)
reset_covariance(
reset_problem_ids=None,
)
initialize_samples()
update_samples()
sample_actions(
init_act,
)
generate_noise(
shape,
base_seed=None,
)
class EvolutionStrategiesCfg(
num_iters=100,
solver_type='mppi',
solver_name='mppi',
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),
store_debug=False,
debug_info=None,
num_problems=1,
num_particles=None,
sync_cuda_time=True,
use_coo_sparse=True,
step_scale=1.0,
inner_iters=1,
_num_rollout_instances=1,
gamma=1.0,
sample_mode=SampleMode.MEAN,
seed=0,
store_rollouts=False,
null_act_frac=0.0,
init_mean=None,
init_cov=0.5,
base_action=BaseActionType.REPEAT,
step_size_mean=0.9,
step_size_cov=0.1,
squash_fn=SquashType.CLAMP,
cov_type=CovType.DIAG_A,
sample_params=None,
update_cov=True,
random_mean=False,
beta=0.1,
alpha=1.0,
kappa=0.01,
sample_per_problem=True,
learning_rate=0.1,
)

Bases: curobo._src.optim.particle.mppi.MPPICfg

ES configuration. Extends MPPICfg with learning_rate.

Parameters:

  • num_iters (int)

  • solver_type (str)

  • solver_name (str)

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

  • store_debug (bool)

  • debug_info (Any)

  • num_problems (int)

  • num_particles (int | None)

  • sync_cuda_time (bool)

  • use_coo_sparse (bool)

  • step_scale (float)

  • inner_iters (int)

  • _num_rollout_instances (int)

  • gamma (float)

  • sample_mode (curobo._src.optim.components.particle_opt_core.SampleMode)

  • seed (int)

  • store_rollouts (bool)

  • null_act_frac (float)

  • init_mean (torch.Tensor | None)

  • init_cov (float)

  • base_action (curobo._src.optim.particle.mppi.BaseActionType)

  • step_size_mean (float)

  • step_size_cov (float)

  • squash_fn (curobo._src.optim.particle.particle_opt_utils.SquashType)

  • cov_type (curobo._src.optim.components.gaussian_distribution.CovType)

  • sample_params (curobo._src.optim.particle.sample_strategies.particle_sampler_cfg.ParticleSamplerCfg | None)

  • update_cov (bool)

  • random_mean (bool)

  • beta (float)

  • alpha (float)

  • kappa (float)

  • sample_per_problem (bool)

  • learning_rate (float)

learning_rate: float = 0.1

Step size for the natural gradient mean update. Controls how far the distribution mean moves along the estimated natural gradient direction each iteration.

__init__(
num_iters=100,
solver_type='mppi',
solver_name='mppi',
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),
store_debug=False,
debug_info=None,
num_problems=1,
num_particles=None,
sync_cuda_time=True,
use_coo_sparse=True,
step_scale=1.0,
inner_iters=1,
_num_rollout_instances=1,
gamma=1.0,
sample_mode=SampleMode.MEAN,
seed=0,
store_rollouts=False,
null_act_frac=0.0,
init_mean=None,
init_cov=0.5,
base_action=BaseActionType.REPEAT,
step_size_mean=0.9,
step_size_cov=0.1,
squash_fn=SquashType.CLAMP,
cov_type=CovType.DIAG_A,
sample_params=None,
update_cov=True,
random_mean=False,
beta=0.1,
alpha=1.0,
kappa=0.01,
sample_per_problem=True,
learning_rate=0.1,
)
Parameters:

  • num_iters (int)

  • solver_type (str)

  • solver_name (str)

  • device_cfg (DeviceCfg)

  • store_debug (bool)

  • debug_info (Any)

  • num_problems (int)

  • num_particles (Optional[int])

  • sync_cuda_time (bool)

  • use_coo_sparse (bool)

  • step_scale (float)

  • inner_iters (int)

  • _num_rollout_instances (int)

  • gamma (float)

  • sample_mode (SampleMode)

  • seed (int)

  • store_rollouts (bool)

  • null_act_frac (float)

  • init_mean (Optional[torch.Tensor])

  • init_cov (float)

  • base_action (BaseActionType)

  • step_size_mean (float)

  • step_size_cov (float)

  • squash_fn (SquashType)

  • cov_type (CovType)

  • sample_params (Optional[ParticleSamplerCfg])

  • update_cov (bool)

  • random_mean (bool)

  • beta (float)

  • alpha (float)

  • kappa (float)

  • sample_per_problem (bool)

  • learning_rate (float)

Return type:

None

class LBFGSOpt(
config,
rollout_list,
use_cuda_graph=False,
)

Bases: object

L-BFGS optimizer with limited-memory two-loop recursion step directions.

Uses GradientOptCore for gradient evaluation and lifecycle management, and QuasiNewtonBuffers for (s, y) history. Supports Wolfe and strong-Wolfe line search, CUDA graph wrapping, and an optional CUDA kernel fast path.

Parameters:
__init__(
config,
rollout_list,
use_cuda_graph=False,
)
Parameters:
property config
property device_cfg
property opt_dt
property use_cuda_graph
property enabled
enable()
disable()
property action_horizon
property action_dim
property opt_dim
property outer_iters
property horizon
property action_bound_lows
property action_bound_highs
property action_step_max
property action_horizon_step_max
property action_horizon_bounds_lows
property action_horizon_bounds_highs
property solve_time
property solver_names
property rollout_fn
optimize(seed_action)

Run the full optimization loop and return the best action sequence.

reinitialize(
action,
mask=None,
clear_optimizer_state=True,
reset_num_iters=False,
)

Reset optimizer state and seed with new actions before a fresh solve.

shift(shift_steps=0)
update_num_problems(
num_problems,
)

Resize internal buffers to accommodate a new number of parallel problems.

update_rollout_params(goal)
update_goal_dt(goal)
get_all_rollout_instances()
compute_metrics(action)

Evaluate cost and constraint metrics for the given action sequence.

reset_shape()
reset_seed()
reset_cuda_graph()
get_recorded_trace()
update_solver_params(
solver_params,
)
update_niters(niters)
debug_dump(file_path='')
class LBFGSOptCfg(
num_iters=100,
solver_type='lbfgs',
solver_name='lbfgs',
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),
store_debug=False,
debug_info=None,
num_problems=1,
num_particles=None,
sync_cuda_time=True,
use_coo_sparse=True,
step_scale=1.0,
inner_iters=25,
_num_rollout_instances=2,
cost_convergence=1e-11,
cost_delta_threshold=0.0,
cost_relative_threshold=0.0,
converged_ratio=0.8,
fixed_iters=True,
convergence_iteration=0,
minimum_iters=None,
return_best_action=True,
line_search_scale=<factory>,
line_search_type=LineSearchType.APPROX_WOLFE,
use_cuda_kernel_line_search=True,
fix_terminal_action=False,
line_search_wolfe_c_1=1e-05,
line_search_wolfe_c_2=0.9,
history=7,
epsilon=0.01,
use_cuda_kernel_step_direction=True,
stable_mode=True,
use_cuda_kernel_shared_buffers=True,
initial_step_scale=0.1,
)

Bases: object

Flat configuration for L-BFGS optimizer. All fields in one place.

Parameters:

  • num_iters (int)

  • solver_type (str)

  • solver_name (str)

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

  • store_debug (bool)

  • debug_info (Any)

  • num_problems (int)

  • num_particles (int | None)

  • sync_cuda_time (bool)

  • use_coo_sparse (bool)

  • step_scale (float)

  • inner_iters (int)

  • _num_rollout_instances (int)

  • cost_convergence (float)

  • cost_delta_threshold (float)

  • cost_relative_threshold (float)

  • converged_ratio (float)

  • fixed_iters (bool)

  • convergence_iteration (int)

  • minimum_iters (int | None)

  • return_best_action (bool)

  • line_search_scale (List[float])

  • line_search_type (curobo._src.optim.gradient.line_search_strategy.LineSearchType)

  • use_cuda_kernel_line_search (bool)

  • fix_terminal_action (bool)

  • line_search_wolfe_c_1 (float)

  • line_search_wolfe_c_2 (float)

  • history (int)

  • epsilon (float)

  • use_cuda_kernel_step_direction (bool)

  • stable_mode (bool)

  • use_cuda_kernel_shared_buffers (bool)

  • initial_step_scale (float)

num_iters: int = 100
solver_type: str = 'lbfgs'
solver_name: str = 'lbfgs'
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)
store_debug: bool = False
debug_info: Any = None
num_problems: int = 1
num_particles: int | None = None
sync_cuda_time: bool = True
use_coo_sparse: bool = True
step_scale: float = 1.0
inner_iters: int = 25
cost_convergence: float = 1e-11
cost_delta_threshold: float = 0.0
cost_relative_threshold: float = 0.0
converged_ratio: float = 0.8
fixed_iters: bool = True
convergence_iteration: int = 0
minimum_iters: int | None = None
return_best_action: bool = True
line_search_scale: List[float]
line_search_type: curobo._src.optim.gradient.line_search_strategy.LineSearchType = 'approx_wolfe'
fix_terminal_action: bool = False
line_search_wolfe_c_1: float = 1e-05

Sufficient-decrease constant for the Wolfe line search (Armijo condition). The step is accepted when cost decrease exceeds c_1 * step_size * directional_derivative. Very small values (default 1e-5) make the condition easy to satisfy.

line_search_wolfe_c_2: float = 0.9

Curvature condition constant for the Wolfe line search. The step is accepted when the new directional derivative is at least c_2 * old_directional_derivative. Values close to 1.0 are typical for quasi-Newton methods like L-BFGS.

history: int = 7
epsilon: float = 0.01

Damping constant added to the denominator of the two-loop recursion to prevent division by near-zero values in the Hessian approximation. Larger values bias the step direction toward steepest descent.

use_cuda_kernel_step_direction: bool = True
stable_mode: bool = True

When True, uses a numerically stable variant of the L-BFGS two-loop recursion that guards against NaN/Inf in the (s, y) history buffers. Must be True; the unstable path is disabled.

use_cuda_kernel_shared_buffers: bool = True

When True, the CUDA kernel for the two-loop recursion uses shared memory for intermediate buffers, giving a significant speed-up on small-to-medium opt_dim. Automatically disabled when the shared memory requirement exceeds the hardware limit.

initial_step_scale: float = 0.1
property num_rollout_instances
property outer_iters
classmethod create_data_dict(
data_dict,
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),
child_dict=None,
)

Create config dict, filtering to only valid fields.

update_niters(niters)
Parameters:

niters (int)

__init__(
num_iters=100,
solver_type='lbfgs',
solver_name='lbfgs',
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),
store_debug=False,
debug_info=None,
num_problems=1,
num_particles=None,
sync_cuda_time=True,
use_coo_sparse=True,
step_scale=1.0,
inner_iters=25,
_num_rollout_instances=2,
cost_convergence=1e-11,
cost_delta_threshold=0.0,
cost_relative_threshold=0.0,
converged_ratio=0.8,
fixed_iters=True,
convergence_iteration=0,
minimum_iters=None,
return_best_action=True,
line_search_scale=<factory>,
line_search_type=LineSearchType.APPROX_WOLFE,
use_cuda_kernel_line_search=True,
fix_terminal_action=False,
line_search_wolfe_c_1=1e-05,
line_search_wolfe_c_2=0.9,
history=7,
epsilon=0.01,
use_cuda_kernel_step_direction=True,
stable_mode=True,
use_cuda_kernel_shared_buffers=True,
initial_step_scale=0.1,
)
Parameters:

  • num_iters (int)

  • solver_type (str)

  • solver_name (str)

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

  • store_debug (bool)

  • debug_info (Any)

  • num_problems (int)

  • num_particles (int | None)

  • sync_cuda_time (bool)

  • use_coo_sparse (bool)

  • step_scale (float)

  • inner_iters (int)

  • _num_rollout_instances (int)

  • cost_convergence (float)

  • cost_delta_threshold (float)

  • cost_relative_threshold (float)

  • converged_ratio (float)

  • fixed_iters (bool)

  • convergence_iteration (int)

  • minimum_iters (int | None)

  • return_best_action (bool)

  • line_search_scale (List[float])

  • line_search_type (curobo._src.optim.gradient.line_search_strategy.LineSearchType)

  • use_cuda_kernel_line_search (bool)

  • fix_terminal_action (bool)

  • line_search_wolfe_c_1 (float)

  • line_search_wolfe_c_2 (float)

  • history (int)

  • epsilon (float)

  • use_cuda_kernel_step_direction (bool)

  • stable_mode (bool)

  • use_cuda_kernel_shared_buffers (bool)

  • initial_step_scale (float)

Return type:

None

class MPPI(
config,
rollout_list,
use_cuda_graph=False,
)

Bases: object

MPPI optimizer using softmax-weighted sample statistics to update the distribution.

Draws action samples from a Gaussian via ParticleOptCore, computes trajectory costs through rollouts, and updates mean and covariance using softmax weights over the cost-ranked samples.

Parameters:

  • config (MPPICfg)

  • rollout_list (List[Rollout])

  • use_cuda_graph (bool)

__init__(
config,
rollout_list,
use_cuda_graph=False,
)
Parameters:
property config
property device_cfg
property opt_dt
property use_cuda_graph
property enabled
enable()
disable()
property action_horizon
property action_dim
property opt_dim
property outer_iters
property horizon
property action_bound_lows
property action_bound_highs
property action_step_max
property action_horizon_bounds_lows
property action_horizon_bounds_highs
property solve_time
property solver_names
property rollout_fn
property mean_action
property best_traj
property cov_action
property scale_tril
property inv_cov_action
property full_scale_tril
property full_inv_cov
property sample_lib
property entropy
property squashed_mean
property particles_per_problem
property sampled_particles_per_problem
property null_per_problem
property neg_per_problem
property total_num_particles
property null_act_seqs
property problem_col
property top_trajs
property gamma_seq
optimize(seed_action)

Run the full optimization loop and return the best action sequence.

reinitialize(
action,
mask=None,
clear_optimizer_state=True,
reset_num_iters=False,
)

Reset optimizer state and seed with new actions before a fresh solve.

shift(shift_steps=0)
update_num_problems(num_problems)

Resize internal buffers to accommodate a new number of parallel problems.

update_rollout_params(goal)
update_goal_dt(goal)
get_all_rollout_instances()
compute_metrics(action)

Evaluate cost and constraint metrics for the given action sequence.

reset_shape()
reset_seed()
reset_cuda_graph()
get_recorded_trace()
update_solver_params(solver_params)
update_niters(niters)
debug_dump(file_path='')
update_seed(init_act)
update_init_mean(init_mean)
get_rollouts()
reset_distribution(
reset_problem_ids=None,
)
reset_mean(reset_problem_ids=None)
reset_covariance(
reset_problem_ids=None,
)
initialize_samples()
update_samples()
sample_actions(init_act)
generate_noise(
shape,
base_seed=None,
)
class MPPICfg(
num_iters=100,
solver_type='mppi',
solver_name='mppi',
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),
store_debug=False,
debug_info=None,
num_problems=1,
num_particles=None,
sync_cuda_time=True,
use_coo_sparse=True,
step_scale=1.0,
inner_iters=1,
_num_rollout_instances=1,
gamma=1.0,
sample_mode=SampleMode.MEAN,
seed=0,
store_rollouts=False,
null_act_frac=0.0,
init_mean=None,
init_cov=0.5,
base_action=BaseActionType.REPEAT,
step_size_mean=0.9,
step_size_cov=0.1,
squash_fn=SquashType.CLAMP,
cov_type=CovType.DIAG_A,
sample_params=None,
update_cov=True,
random_mean=False,
beta=0.1,
alpha=1.0,
kappa=0.01,
sample_per_problem=True,
)

Bases: object

Flat configuration for MPPI optimizer. All fields in one place.

Parameters:

  • num_iters (int)

  • solver_type (str)

  • solver_name (str)

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

  • store_debug (bool)

  • debug_info (Any)

  • num_problems (int)

  • num_particles (int | None)

  • sync_cuda_time (bool)

  • use_coo_sparse (bool)

  • step_scale (float)

  • inner_iters (int)

  • _num_rollout_instances (int)

  • gamma (float)

  • sample_mode (curobo._src.optim.components.particle_opt_core.SampleMode)

  • seed (int)

  • store_rollouts (bool)

  • null_act_frac (float)

  • init_mean (torch.Tensor | None)

  • init_cov (float)

  • base_action (curobo._src.optim.particle.mppi.BaseActionType)

  • step_size_mean (float)

  • step_size_cov (float)

  • squash_fn (curobo._src.optim.particle.particle_opt_utils.SquashType)

  • cov_type (curobo._src.optim.components.gaussian_distribution.CovType)

  • sample_params (curobo._src.optim.particle.sample_strategies.particle_sampler_cfg.ParticleSamplerCfg | None)

  • update_cov (bool)

  • random_mean (bool)

  • beta (float)

  • alpha (float)

  • kappa (float)

  • sample_per_problem (bool)

num_iters: int = 100
solver_type: str = 'mppi'
solver_name: str = 'mppi'
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)
store_debug: bool = False
debug_info: Any = None
num_problems: int = 1
num_particles: int | None = None
sync_cuda_time: bool = True
use_coo_sparse: bool = True
step_scale: float = 1.0
inner_iters: int = 1
gamma: float = 1.0
sample_mode: curobo._src.optim.components.particle_opt_core.SampleMode = 'MEAN'
seed: int = 0
store_rollouts: bool = False
null_act_frac: float = 0.0

Fraction of particles that use the null (zero) action sequence. Ensures at least some samples explore the “do nothing” trajectory, which improves stability in MPC settings. Range [0, 1]; 0 disables null samples.

init_mean: torch.Tensor | None = None
init_cov: float = 0.5
base_action: curobo._src.optim.particle.mppi.BaseActionType = 'REPEAT'
step_size_mean: float = 0.9

Exponential moving average blending factor for the distribution mean update. At each iteration the new mean is (1 - step_size_mean) * old_mean + step_size_mean * weighted_mean. Higher values make the mean track the current sample statistics faster.

step_size_cov: float = 0.1

Exponential moving average blending factor for the covariance update, analogous to step_size_mean. Lower values keep the covariance closer to the previous iteration, reducing exploration noise.

squash_fn: curobo._src.optim.particle.particle_opt_utils.SquashType = 0
cov_type: curobo._src.optim.components.gaussian_distribution.CovType = 'DIAG_A'
sample_params: curobo._src.optim.particle.sample_strategies.particle_sampler_cfg.ParticleSamplerCfg | None = None
update_cov: bool = True
random_mean: bool = False

When True, the distribution mean is re-sampled randomly each iteration instead of being updated from the weighted sample statistics. Useful for highly multi-modal landscapes but generally hurts convergence.

beta: float = 0.1

MPPI temperature parameter (inverse). Controls the sharpness of the softmax weighting over trajectory costs: smaller values concentrate weight on the lowest-cost samples (greedy), larger values spread weight more uniformly (exploratory). This is the single most important tuning knob for MPPI convergence behavior.

alpha: float = 1.0

Trade-off between control cost and state cost in the MPPI objective. alpha = 1.0 uses only state cost; values below 1.0 blend in a control-effort penalty proportional to (1 - alpha).

kappa: float = 0.01

Minimum covariance floor added after each covariance update to prevent the distribution from collapsing to a point. Keeps exploration alive across iterations.

sample_per_problem: bool = True
property num_rollout_instances
property outer_iters
classmethod create_data_dict(
data_dict,
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),
child_dict=None,
)
update_niters(niters)
Parameters:

niters (int)

__init__(
num_iters=100,
solver_type='mppi',
solver_name='mppi',
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),
store_debug=False,
debug_info=None,
num_problems=1,
num_particles=None,
sync_cuda_time=True,
use_coo_sparse=True,
step_scale=1.0,
inner_iters=1,
_num_rollout_instances=1,
gamma=1.0,
sample_mode=SampleMode.MEAN,
seed=0,
store_rollouts=False,
null_act_frac=0.0,
init_mean=None,
init_cov=0.5,
base_action=BaseActionType.REPEAT,
step_size_mean=0.9,
step_size_cov=0.1,
squash_fn=SquashType.CLAMP,
cov_type=CovType.DIAG_A,
sample_params=None,
update_cov=True,
random_mean=False,
beta=0.1,
alpha=1.0,
kappa=0.01,
sample_per_problem=True,
)
Parameters:

  • num_iters (int)

  • solver_type (str)

  • solver_name (str)

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

  • store_debug (bool)

  • debug_info (Any)

  • num_problems (int)

  • num_particles (int | None)

  • sync_cuda_time (bool)

  • use_coo_sparse (bool)

  • step_scale (float)

  • inner_iters (int)

  • _num_rollout_instances (int)

  • gamma (float)

  • sample_mode (curobo._src.optim.components.particle_opt_core.SampleMode)

  • seed (int)

  • store_rollouts (bool)

  • null_act_frac (float)

  • init_mean (torch.Tensor | None)

  • init_cov (float)

  • base_action (curobo._src.optim.particle.mppi.BaseActionType)

  • step_size_mean (float)

  • step_size_cov (float)

  • squash_fn (curobo._src.optim.particle.particle_opt_utils.SquashType)

  • cov_type (curobo._src.optim.components.gaussian_distribution.CovType)

  • sample_params (curobo._src.optim.particle.sample_strategies.particle_sampler_cfg.ParticleSamplerCfg | None)

  • update_cov (bool)

  • random_mean (bool)

  • beta (float)

  • alpha (float)

  • kappa (float)

  • sample_per_problem (bool)

Return type:

None

class MultiStageOptimizer(
optimizers,
rollout_list=None,
)

Bases: object

Chains multiple optimizers in sequence, seeding each stage from the previous result.

Delegates lifecycle operations (reinitialize, shift, update_num_problems, etc.) to all contained optimizers, and exposes the final stage’s configuration and action shape as its own.

Initialize the multi-stage optimizer with an ordered list of stages.

The final optimizer in the list determines the exposed config, action_horizon, and action_dim. When rollout_list is not provided, it falls back to optimizers[-1]._rollout_list so the multi-stage wrapper can be constructed without explicitly duplicating rollout references.

Parameters:

  • optimizers (List) – Ordered list of optimizer instances. Each must implement the Optimizer protocol (optimize, reinitialize, shift, update_num_problems, etc.).

  • rollout_list (Optional[List[Rollout]]) – Optional explicit rollout list. If None, uses optimizers[-1]._rollout_list as the fallback.

__init__(
optimizers,
rollout_list=None,
)

Initialize the multi-stage optimizer with an ordered list of stages.

The final optimizer in the list determines the exposed config, action_horizon, and action_dim. When rollout_list is not provided, it falls back to optimizers[-1]._rollout_list so the multi-stage wrapper can be constructed without explicitly duplicating rollout references.

Parameters:

  • optimizers (List) – Ordered list of optimizer instances. Each must implement the Optimizer protocol (optimize, reinitialize, shift, update_num_problems, etc.).

  • rollout_list (Optional[List[Rollout]]) – Optional explicit rollout list. If None, uses optimizers[-1]._rollout_list as the fallback.

property enabled: bool
enable()
disable()
property action_horizon: int
property action_dim: int
property opt_dim: int
property outer_iters
property solver_names
property solve_time: float
optimize(
seed_action,
)

Run all optimizer stages in sequence and return the final result.

Each stage receives the best action from the previous stage as its seed. Disabled optimizers are skipped. Wall-clock time is recorded via a CUDA event timer.

Parameters:

seed_action (Tensor) – Initial action tensor of shape (num_problems, action_horizon, action_dim) or a flat view (num_problems, action_horizon * action_dim).

Return type:

Tensor

Returns:

Tensor of shape (num_problems, action_horizon, action_dim) containing the best action from the final stage.

reinitialize(
action,
mask=None,
clear_optimizer_state=True,
reset_num_iters=False,
)
Parameters:
shift(shift_steps=0)
Return type:

bool

Parameters:

shift_steps (int)

update_num_problems(
num_problems,
)
Parameters:

num_problems (int)

update_rollout_params(
goal,
)
update_goal_dt(goal)
get_all_rollout_instances()
Return type:

List[Rollout]

compute_metrics(
action,
)

Compute rollout metrics for an action sequence (always raises).

Multi-stage optimizers do not support compute_metrics because the intermediate stages may use different rollout configurations and it is ambiguous which stage’s rollout should evaluate the action. Callers should invoke compute_metrics directly on the desired single-stage optimizer instead.

Raises:

RuntimeError – Always, via log_and_raise.

Parameters:

action (torch.Tensor)

reset_shape()
reset_seed()
reset_cuda_graph()
get_recorded_trace()
Return type:

Dict[str, Any]

update_solver_params(
solver_params,
)
Return type:

bool

Parameters:

solver_params (Dict[str, Dict[str, Any]])

update_niters(
niters,
)
Parameters:

niters (int)

debug_dump(
file_path='',
)
Parameters:

file_path (str)

class ScipyOpt(
config,
rollout_list,
use_cuda_graph=False,
)

Bases: object

SciPy optimizer that computes costs and gradients on GPU via cuRobo rollouts.

Evaluates the objective, constraints, and gradients on GPU, copies them to CPU for scipy.optimize.minimize. When use_cuda_graph=True, GPU evaluations are wrapped in CUDA graph executors for faster repeated evaluation.

Parameters:
__init__(
config,
rollout_list,
use_cuda_graph=False,
)
Parameters:
property enabled
enable()
disable()
property action_horizon
property action_dim
property opt_dim
property outer_iters
property horizon
property action_bound_lows
property action_bound_highs
property action_horizon_bounds_lows
property action_horizon_bounds_highs
property solve_time
property solver_names
optimize(seed_action)
Return type:

Tensor

Parameters:

seed_action (torch.Tensor)

reinitialize(
action,
mask=None,
clear_optimizer_state=True,
reset_num_iters=False,
)
shift(shift_steps=0)
update_num_problems(
num_problems,
)
update_rollout_params(goal)
update_goal_dt(goal)
get_all_rollout_instances()
compute_metrics(action)
reset_shape()
reset_seed()
reset_cuda_graph()
get_recorded_trace()
update_solver_params(
solver_params,
)
update_niters(niters)
debug_dump(file_path='')
class ScipyOptCfg(
num_iters=100,
solver_type='scipy',
solver_name='scipy',
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),
store_debug=False,
debug_info=None,
num_problems=1,
num_particles=None,
sync_cuda_time=True,
use_coo_sparse=True,
step_scale=1.0,
inner_iters=1,
_num_rollout_instances=1,
scipy_minimize_method='SLSQP',
scipy_minimize_kwargs=<factory>,
use_float64_on_cpu=False,
)

Bases: object

Flat configuration for scipy optimizer.

Parameters:
num_iters: int = 100
solver_type: str = 'scipy'
solver_name: str = 'scipy'
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)
store_debug: bool = False
debug_info: Any = None
num_problems: int = 1
num_particles: int | None = None
sync_cuda_time: bool = True
use_coo_sparse: bool = True
step_scale: float = 1.0
inner_iters: int = 1
scipy_minimize_method: str = 'SLSQP'

Method name passed to scipy.optimize.minimize (e.g. "SLSQP", "L-BFGS-B", "COBYLA"). Constraint-aware methods like SLSQP receive cuRobo constraints as inequality constraints.

scipy_minimize_kwargs: dict
use_float64_on_cpu: bool = False

When True, action vectors are converted to float64 before sending to SciPy on CPU. Required for SLSQP (automatically enabled). Reduces numerical issues in SciPy’s Fortran routines at the cost of an extra dtype conversion round-trip.

property num_rollout_instances
property outer_iters
classmethod create_data_dict(
data_dict,
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),
child_dict=None,
)
update_niters(niters)
Parameters:

niters (int)

__init__(
num_iters=100,
solver_type='scipy',
solver_name='scipy',
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),
store_debug=False,
debug_info=None,
num_problems=1,
num_particles=None,
sync_cuda_time=True,
use_coo_sparse=True,
step_scale=1.0,
inner_iters=1,
_num_rollout_instances=1,
scipy_minimize_method='SLSQP',
scipy_minimize_kwargs=<factory>,
use_float64_on_cpu=False,
)
Parameters:
Return type:

None

class TorchOpt(
config,
rollout_list,
use_cuda_graph=False,
)

Bases: object

Adapts any torch.optim optimizer (Adam, SGD, LBFGS, etc.) for cuRobo rollouts.

Evaluates the cost function via cuRobo rollouts, backpropagates through the computation graph, and delegates the parameter update to the wrapped PyTorch optimizer.

Parameters:
__init__(
config,
rollout_list,
use_cuda_graph=False,
)
Parameters:
property enabled
enable()
disable()
property action_horizon
property action_dim
property opt_dim
property outer_iters
property horizon
property action_bound_lows
property action_bound_highs
property solve_time
property solver_names
optimize(seed_action)
Return type:

Tensor

Parameters:

seed_action (torch.Tensor)

reinitialize(
action,
mask=None,
clear_optimizer_state=True,
reset_num_iters=False,
)
shift(shift_steps=0)
update_num_problems(
num_problems,
)
update_rollout_params(goal)
update_goal_dt(goal)
get_all_rollout_instances()
compute_metrics(action)
reset_shape()
reset_seed()
reset_cuda_graph()
get_recorded_trace()
update_solver_params(
solver_params,
)
update_niters(niters)
debug_dump(file_path='')
class TorchOptCfg(
num_iters=100,
solver_type='torch',
solver_name='torch',
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),
store_debug=False,
debug_info=None,
num_problems=1,
num_particles=None,
sync_cuda_time=True,
use_coo_sparse=True,
step_scale=1.0,
inner_iters=1,
_num_rollout_instances=1,
torch_optim_name='Adam',
torch_optim_kwargs=<factory>,
torch_optim_class=None,
)

Bases: object

Flat configuration for torch optimizer wrapper.

Parameters:
num_iters: int = 100
solver_type: str = 'torch'
solver_name: str = 'torch'
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)
store_debug: bool = False
debug_info: Any = None
num_problems: int = 1
num_particles: int | None = None
sync_cuda_time: bool = True
use_coo_sparse: bool = True
step_scale: float = 1.0
inner_iters: int = 1
torch_optim_name: str = 'Adam'

Name of a torch.optim optimizer class (e.g. "Adam", "SGD", "LBFGS"). Used to look up the class via getattr(torch.optim, torch_optim_name) when torch_optim_class is None.

torch_optim_kwargs: dict
torch_optim_class: Any | None = None

Explicit optimizer class to use instead of looking up by name. When set, torch_optim_name is ignored for class resolution. This allows using custom optimizer classes not in torch.optim.

property num_rollout_instances
property outer_iters
classmethod create_data_dict(
data_dict,
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),
child_dict=None,
)
update_niters(niters)
Parameters:

niters (int)

__init__(
num_iters=100,
solver_type='torch',
solver_name='torch',
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),
store_debug=False,
debug_info=None,
num_problems=1,
num_particles=None,
sync_cuda_time=True,
use_coo_sparse=True,
step_scale=1.0,
inner_iters=1,
_num_rollout_instances=1,
torch_optim_name='Adam',
torch_optim_kwargs=<factory>,
torch_optim_class=None,
)
Parameters:
Return type:

None