symforce.opt.optimizer module¶
- class Optimizer(factors, optimized_keys=None, params=None, debug_stats=False, include_jacobians=False)[source]¶
Bases:
object
A nonlinear least-squares optimizer
Typical usage is to construct an Optimizer from a set of factors and keys to optimize, and then call optimize repeatedly with a Values.
Example creation with a single Factor:
- factor = Factor(
[my_key_0, my_key_1, my_key_2], my_residual_function
) optimizer = Optimizer(
factors=[factor], optimized_keys=[my_key_0, my_key_1],
)
And usage:
initial_guess = Values(…) result = optimizer.optimize(initial_guess) print(result.optimized_values)
Example creation with an OptimizationProblem using make_numeric_factors(). The linearization functions are generated in make_numeric_factors() and are linearized with respect to problem.optimized_keys().
problem = OptimizationProblem(subproblems=[…], residual_blocks=…) factors = problem.make_numeric_factors(“my_problem”) optimizer = Optimizer(factors)
Example creation with an OptimizationProblem using make_symbolic_factors(). The symbolic factors are converted into numeric factors when the optimizer is created, and are linearized with respect to the “optimized keys” passed to the optimizer. The linearization functions are generated when converting to numeric factors when the optimizer is created.
problem = OptimizationProblem(subproblems=[…], residual_blocks=…) factors = problem.make_symbolic_factors(“my_problem”) optimizer = Optimizer(factors, problem.optimized_keys())
Wraps the C++ sym::Optimizer class in opt/optimizer.h, so the API is mostly the same and optimization results will be identical.
- Parameters:
factors (
Iterable
[Union
[Factor
,NumericFactor
]]) – A sequence of either Factor or NumericFactor objects representing the residuals in the problem. If (symbolic) Factors are passed, they are convered to NumericFactors by generating linearization functions of the residual with respect to the keys in optimized_keys.optimized_keys (
Optional
[Sequence
[str
]]) – A set of the keys to be optimized. Only required if symbolic factors are passed to the optimizer.params (
Optional
[Params
]) – Params for the optimizerdebug_stats (
bool
) – Whether the optimizer should record debugging stats such as the optimized values, residual, jacobian, etc. computed at each iteration of the optimization.include_jacobians (
bool
) – Whether the optimizer should compute jacobians (required for linear error)
- class Params(verbose=True, initial_lambda=1.0, lambda_up_factor=4.0, lambda_down_factor=0.25, lambda_lower_bound=0.0, lambda_upper_bound=1000000.0, use_diagonal_damping=False, use_unit_damping=True, keep_max_diagonal_damping=False, diagonal_damping_min=1e-06, iterations=50, early_exit_min_reduction=1e-06, enable_bold_updates=False)[source]¶
Bases:
object
Parameters for the Python Optimizer
Mirrors the optimizer_params_t LCM type, see documentation there for information on each parameter
Note: For the Python optimizer, verbose defaults to True
- Parameters:
verbose (
bool
) –initial_lambda (
float
) –lambda_up_factor (
float
) –lambda_down_factor (
float
) –lambda_lower_bound (
float
) –lambda_upper_bound (
float
) –use_diagonal_damping (
bool
) –use_unit_damping (
bool
) –keep_max_diagonal_damping (
bool
) –diagonal_damping_min (
float
) –iterations (
int
) –early_exit_min_reduction (
float
) –enable_bold_updates (
bool
) –
- verbose: bool = True¶
- initial_lambda: float = 1.0¶
- lambda_up_factor: float = 4.0¶
- lambda_down_factor: float = 0.25¶
- lambda_lower_bound: float = 0.0¶
- lambda_upper_bound: float = 1000000.0¶
- use_diagonal_damping: bool = False¶
- use_unit_damping: bool = True¶
- keep_max_diagonal_damping: bool = False¶
- diagonal_damping_min: float = 1e-06¶
- iterations: int = 50¶
- early_exit_min_reduction: float = 1e-06¶
- enable_bold_updates: bool = False¶
- __init__(verbose=True, initial_lambda=1.0, lambda_up_factor=4.0, lambda_down_factor=0.25, lambda_lower_bound=0.0, lambda_upper_bound=1000000.0, use_diagonal_damping=False, use_unit_damping=True, keep_max_diagonal_damping=False, diagonal_damping_min=1e-06, iterations=50, early_exit_min_reduction=1e-06, enable_bold_updates=False)¶
- Parameters:
verbose (
bool
) –initial_lambda (
float
) –lambda_up_factor (
float
) –lambda_down_factor (
float
) –lambda_lower_bound (
float
) –lambda_upper_bound (
float
) –use_diagonal_damping (
bool
) –use_unit_damping (
bool
) –keep_max_diagonal_damping (
bool
) –diagonal_damping_min (
float
) –iterations (
int
) –early_exit_min_reduction (
float
) –enable_bold_updates (
bool
) –
- Status¶
alias of
optimization_status_t
- FailureReason¶
alias of
levenberg_marquardt_solver_failure_reason_t
- class Result(initial_values, optimized_values, _stats)[source]¶
Bases:
object
The result of an optimization, with additional stats and debug information
- initial_values:
The initial guess used for this optimization
- optimized_values:
The best Values achieved during the optimization (Values with the smallest error)
- iterations:
Per-iteration stats, if requested, like the error per iteration. If debug stats are turned on, also the Values and linearization per iteration.
- best_index:
The index into iterations for the iteration that produced the smallest error. I.e. result.iterations[best_index].values == optimized_values. This is not guaranteed to be the last iteration, if the optimizer tried additional steps which did not reduce the error
- status:
What was the result of the optimization? (did it converge, fail, etc.)
- failure_reason:
If status == FAILED, why?
- best_linearization:
The linearization at best_index (at optimized_values), filled out if populate_best_linearization=True
- jacobian_sparsity:
The sparsity pattern of the jacobian, filled out if debug_stats=True
- linear_solver_ordering:
The ordering used for the linear solver, filled out if debug_stats=True
- cholesky_factor_sparsity:
The sparsity pattern of the cholesky factor L, filled out if debug_stats=True
- Parameters:
initial_values (
Values
) –optimized_values (
Values
) –_stats (
OptimizationStats
) –
- property iterations: List[optimization_iteration_t]¶
- property best_index: int¶
- property status: optimization_status_t¶
- property failure_reason: levenberg_marquardt_solver_failure_reason_t¶
- property best_linearization: Linearization | None¶
- property jacobian_sparsity: sparse_matrix_structure_t¶
- property linear_solver_ordering: ndarray¶
- property cholesky_factor_sparsity: sparse_matrix_structure_t¶
- property iteration_stats: Sequence[optimization_iteration_t]¶
- error()[source]¶
The lowest error achieved by the optimization (the error at optimized_values)
- Return type:
float
- __init__(initial_values, optimized_values, _stats)¶
- Parameters:
initial_values (
Values
) –optimized_values (
Values
) –_stats (
OptimizationStats
) –
- __init__(factors, optimized_keys=None, params=None, debug_stats=False, include_jacobians=False)[source]¶
- Parameters:
factors (
Iterable
[Union
[Factor
,NumericFactor
]]) –optimized_keys (
Optional
[Sequence
[str
]]) –params (
Optional
[Params
]) –debug_stats (
bool
) –include_jacobians (
bool
) –
- compute_all_covariances(optimized_value)[source]¶
Compute the covariance matrix (J^T@J)^-1 for all optimized keys about a given linearization point
- Parameters:
optimized_value (
Values
) – A value containing the linearization point to compute the covariance matrix about- Returns:
numerical covariance matrix}
- Return type:
A dict of {optimized_key
- optimize(initial_guess, **kwargs)[source]¶
Optimize from the given initial guess, and return the optimized Values and stats
- Parameters:
initial_guess (
Values
) – A Values containing the initial guess, should contain at least all the keys required by the factors passed to the constructornum_iterations – If < 0 (the default), uses the number of iterations specified by the params at construction
populate_best_linearization – If true, the linearization at the best values will be filled out in the stats
kwargs (
Any
) –
- Return type:
- Returns:
The optimization results, with additional stats and debug information. See the Optimizer.Result documentation for more information
- linearize(values)[source]¶
Compute and return the linearization at the given Values
- Parameters:
values (
Values
) –- Return type:
- load_iteration_values(values_msg)[source]¶
Load a values_t message into a Python Values by first creating a C++ Values, then converting back to the python key names.
- Parameters:
values_msg (
values_t
) –- Return type:
- linearization_index()[source]¶
Get the index mapping keys to their positions in the linearized state vector. Useful for extracting blocks from the problem jacobian, hessian, or RHS
Returns: The index for the Optimizer’s problem linearization
- Return type:
Dict
[str
,index_entry_t
]
- linearization_index_entry(key)[source]¶
Get the index entry for a given key in the linearized state vector. Useful for extracting blocks from the problem jacobian, hessian, or RHS
- Parameters:
key (
str
) – The string key for a variable in the Python Values
Returns: The index entry for the variable in the Optimizer’s problem linearization
- Return type:
index_entry_t