klampt.math.optimize module¶
Classes to help set up and solve nonlinear, constrained optimization problems.
Supports local and global optimization. Wraps around scipy, pyOpt, or DIRECT (for now).
Works well with the klampt.math.symbolic
module.
Classes:
A holder for optimization problem data. 


A wrapper around different local optimization libraries. 

A wrapper around different global optimization libraries. 



Describes an optimization cost function or constraint. 

Defines a generalized optimization problem that can be saved/loaded from a JSON string. 
Functions:

Samples x in the range [a,b]. 

class
klampt.math.optimize.
OptimizationProblem
[source]¶ Bases:
object
A holder for optimization problem data. All attributes are optional, and some solvers can’t handle certain types of constraints and costs.
The objective function must return a float. All equality and inequality functions are required to return a list of floats.

objective
¶ an objective function f(x)
 Type
function

objectiveGrad
¶ a function df/dx(x) giving the gradient of f.
 Type
function

bounds
¶ a pair (l,u) giving lower and upper bounds on the search space.
 Type
tuple

equalities
¶ functions \(g(x)=0\) required of a feasible solution. In practice, \(g(x) \leq tol\) is required, where tol is a tolerance parameter for the solver.
 Type
list of functions

equalityGrads
¶ gradient/Jacobian functions \(\frac{\partial g}{\partial x}(x)\) of the equality functions.
 Type
list of functions

inequalities
¶ inequality functions requiring math:h(x) leq 0 for a feasible solution.
 Type
list of functions

inequalityGrads
¶ a list of gradient/Jacobian functions \(\frac{\partial h}{\partial x}(x)\) of each inequality function.
 Type
list of functions

feasibilityTests
¶ boolean blackbox predicates that must be true of the solution
 Type
list of functions
Suitable for use with the
symbolic
module. Once aContext
is created, and appropriate Variables, Functions, and Expressions are declared, thesetSymbolicObjective()
andaddSymbolicConstraint()
methods automatically determine the standard Python function forms. i.e.,context.makeFlatFunction(f,varorder)
where varorder = None for the default variable ordering.The
OptimizationProblemBuilder
class is more closely tied with the symbolic module and is more convenient to use. It performs automatic simplification and differentiation, and can be saved / loaded to disk.Methods:
setObjective
(func[, funcGrad])addEquality
(func[, funcGrad])addInequality
(func[, funcGrad])setBounds
(xmin, xmax)setFeasibilityTest
(test)addFeasibilityTest
(test)setSymbolicObjective
(func, context[, varorder])Sets an objective function from a symbolic
Function
orExpression
(seesymbolic
module).addSymbolicConstraint
(func, context[, …])Adds a constraint from a symbolic
Function
orsymbolic.Expression
(seesymbolic
module).Returns the objective function value f(x).
feasible
(x[, equalityTol])Returns true if x is a feasible point.
Returns the stacked vector g(x) where g(x)=0 is the equality constraint.
Returns the stacked vector h(x) where h(x)<=0 is the inequality constraint.
makeUnconstrained
(objective_scale[, keep_bounds])If this problem is constrained, returns a new problem in which the objective function is a scoring function that sums all of the equality / inequality errors at x plus objective_scale*objective function(x).

setSymbolicObjective
(func, context, varorder=None)[source]¶ Sets an objective function from a symbolic
Function
orExpression
(seesymbolic
module).Note
The optimization parameters will be a flattened version of each
Variable
appearing infunc
.

addSymbolicConstraint
(func, context, varorder=None, blackbox=False)[source]¶ Adds a constraint from a symbolic
Function
orsymbolic.Expression
(seesymbolic
module). This will be “smart” in thatand
Expressions will be converted to multiple constraints, inequalities will be converted to inequality constraints, and bounds will be converted to bound constraints. All other constraints will be treated as feasibility constraints.

equalityResidual
(x)[source]¶ Returns the stacked vector g(x) where g(x)=0 is the equality constraint.

inequalityResidual
(x)[source]¶ Returns the stacked vector h(x) where h(x)<=0 is the inequality constraint.

makeUnconstrained
(objective_scale, keep_bounds=True)[source]¶ If this problem is constrained, returns a new problem in which the objective function is a scoring function that sums all of the equality / inequality errors at x plus objective_scale*objective function(x). If objective_scale is small, then the scoring function is approximately minimized at a feasible minimum.
If the problem is unconstrained, this just returns self.
If keep_bounds = true, this does not add the bounds to the inequality errors.


class
klampt.math.optimize.
LocalOptimizer
(method='auto')[source]¶ Bases:
object
A wrapper around different local optimization libraries. Only minimization is supported, and only scipy and pyOpt are supported.
The method is specified using the method string, which can be:
‘auto’: picks between scipy and pyOpt, whatever is available.
‘scipy’: uses scipy.optimize.minimize with default settings.
‘scipy.[METHOD]’: uses scipy.optimize.minimize with the argument method=[METHOD].
‘pyOpt’: uses pyOpt with SLSQP.
‘pyOpt.[METHOD]’: uses pyOpt with the given method.
Methods:
Returns a list of methods that are available on this system
methodsAppropriate
(problem)Returns a list of available methods that are appropriate to use for the given problem
setSeed
(x)solve
(problem[, numIters, tol])Returns a tuple (success,result)

klampt.math.optimize.
sample_range
(a, b)[source]¶ Samples x in the range [a,b].
If the range is bounded, the uniform distribution x~U(a,b) is used.
If the range is unbounded, then this uses the log transform to sample a distribution.
Specifically, if a=inf and b is finite, then \(x \sim b + \log(y)\) where \(y \sim U(0,1)\). A similar formula holds for a finite and \(b=\infty\).
If a=inf and b=inf, then \(x \sim s*\log(y)\), where \(y \sim U(0,1)\) and the sign
s
takes on either of {1,1} each with probability 0.5.

class
klampt.math.optimize.
GlobalOptimizer
(method='auto')[source]¶ Bases:
object
A wrapper around different global optimization libraries. Only minimization is supported, and only DIRECT, scipy, and pyOpt are supported.
The optimization technique is specified using the method string, which can be:
‘auto’: picks between DIRECT and randomrestart
‘randomrestart.METHOD’: random restarts using the local optimizer METHOD.
‘DIRECT’: the DIRECT global optimizer
‘scipy’: uses scipy.optimize.minimize with default settings.
‘scipy.METHOD’: uses scipy.optimize.minimize with the argument method=METHOD.
‘pyOpt’: uses pyOpt with SLSQP.
‘pyOpt.METHOD’: uses pyOpt with the given method.
The method attribute can also be a list, which does a cascading solver in which the previous solution point is used as a seed for the next solver.
Examples:
‘DIRECT’: Run the DIRECT method
‘scipy.differential_evolution’: Runs the scipy differential evolution technique
‘randomrestart.scipy’: Runs random restarts using scipy’s default local optimizer
‘randomrestart.pyOpt.SLSQP’: Runs random restarts using pyOpt as a local optimizer
[‘DIRECT’,’auto’]: Run the DIRECT method then clean it up with the default local optimizer
Random restarts picks each component x of the seed state randomly using sample_range(a,b) where [a,b] is the range of x given by problem.bounds.
DIRECT and scipy.differential_evolution require a bounded state space.
Methods:
setSeed
(x)solve
(problem[, numIters, tol])Returns a pair (solved,x) where solved is True if the solver found a valid solution, and x is the solution vector.

class
klampt.math.optimize.
OptimizerParams
(numIters=50, tol=0.001, startRandom=False, numRestarts=1, timeout=10, globalMethod=None, localMethod=None)[source]¶ Bases:
object
Methods:
toJson
()fromJson
(obj)solve
(optProblem[, seed])Globally or locally solves an
OptimizationProblem
instance with the given parameters.
solve
(optProblem, seed=None)[source]¶ Globally or locally solves an
OptimizationProblem
instance with the given parameters. Optionally takes a seed as well.Basically, this is a thin wrapper around
GlobalOptimizer
that converts theOptimizerParams
to the appropriate format. Returns
(success,x) where success is True or False and x is the solution.
 Return type
tuple


class
klampt.math.optimize.
OptimizationObjective
(expr, type, weight=None)[source]¶ Bases:
object
Describes an optimization cost function or constraint.

expr
¶ object f(x)
 Type

type
¶ string describing what the objective does:
‘cost’: added to the cost. Must be scalar.
‘eq’: an equality f(x)=0 that must be met exactly (up to a given equality tolerance)
‘ineq’: an inequality constraint f(x)<=0
‘feas’: a blackbox boolean feasibility test f(x) = True
 Type
str

soft
¶ if true, this is penalized as part of the cost function. Specifically \(w \f(x)\^2\) is the penalty for ‘eq’ types, and \(w I[f(x)\neq \text{True}]\) for ‘feas’ types.
 Type
bool

weight
¶ a weight, used only for cost or soft objectives
 Type
float, optional

name
¶ a name for this objective.
 Type
str, optional


class
klampt.math.optimize.
OptimizationProblemBuilder
(context=None)[source]¶ Bases:
object
Defines a generalized optimization problem that can be saved/loaded from a JSON string. Allows custom lists of objectives, feasibility tests, and cost functions. Multiple variables can be optimized at once.

context
¶ a context that stores the optimization variables and any user data.
 Type

objectives
¶ all objectives or constraints used in the optimization.
 Type
list of OptimizationObjective

optimizationVariables
¶ A list of Variables used for optimization. If not set, this will try to find the variable ‘x’. If not found, this will use all unbound variables in the objectives.
 Type
list of Variable
Note that objectives must be created from
symbolic.Function
objects, so that they are savable/loadable. See the documentation of thesymbolic
module for more detail.Methods:
addEquality
(f[, weight])If f is a symbolic.Function it’s a function f(x) that evaluates to 0 for a feasible solution.
addInequality
(f[, weight])Adds an inequality f(x) <= 0.
addCost
(f[, weight])Adds a cost function f(q).
addFeasibilityTest
(f[, weight])Adds an additional feasibility test.
setBounds
(var[, xmin, xmax])Bounds the optimization variable var
bind
(**kwargs)Binds the variables specified by the keyword arguments
unbind
(**kwargs)Unbinds the variables specified by the keyword arguments
bindVars
(*args)Saves the bindings for optimization variables in the current context into a list.
setVarValues
(s)Converts a state into bindings for the optimization variables in the current context.
Flattens the bindings for optimization variables in the current context into a vector x.
setVarVector
(x)Turns a vector x into bindings for the optimization variables in the current context.
Samples values for all optimization variables, sampling uniformly according to their bounds
cost
()Evaluates the cost function with the variables already bound.
equalityResidual
([soft])Evaluates the equality + ik functions at the currently bound state x, stacking the results into a single vector.
satisfiesEqualities
([tol])Returns True if every entry of the (hard) equality + IK residual equals 0 (to the tolerance tol).
inequalityResidual
([soft])Evaluates the inequality functions at the currently bound state x, stacking the results into a single vector.
satisfiesInequalities
([margin])Returns True if the for currently bound state x, every entry of the (hard) inequality residuals is <= margin (default 0).
feasibilityTestsPass
([soft])Returns True if the currently bound state passes all blackbox feasibility tests.
inBounds
()Returns True if all bounded variables are within their ranges at the currently bound state x
isFeasible
([eqTol])Returns True if the currently bound state passes all equality, inequality, joint limit, and blackbox feasibility tests.
Returns a symbolic.Expression, over variables in self.context, that evaluates to the cost
equalityResidualSymbolic
([soft])Returns a symbolic.Expression, over variables in self.context, that evaluates to the equality residual
inequalityResidualSymbolic
([soft])Returns a symbolic.Expression, over variables in self.context, that evaluates to the inequality residual
equalitySatisfiedSymbolic
([tol, soft])Returns a symbolic.Expression, over variables in self.context, that evaluates to True if the equality constraint is met with tolerance tol
inequalitySatisfiedSymbolic
([soft])Returns a symbolic.Expression, over variables in self.context, that evaluates to True if the inequality constraint is met
feasibilityTestsPassSymbolic
([soft])Returns a symbolic.Expression, over variables in self.context, that evaluates to True if the blackbox feasibility constraints are met
Returns a symbolic.Expression, over variables in self.context, that evaluates to True the configuration meets bound constraints
isFeasibleSymbolic
([eqTol])Returns a symbolic.Expression, over $q and other user data variables, that evaluates to True if the configuration meets all feasibility tests
score
([eqWeight, ineqWeight, infeasWeight])Returns an error score that is equal to the optimum at a feasible solution.
pprint
([indent])toJson
([saveContextFunctions, prettyPrintExprs])Returns a JSON object representing this optimization problem.
fromJson
(object[, context])Sets this IK problem to a JSON object representing it.
preprocess
([steps])Preprocesses the problem to make solving more efficient
Returns optimization varable bounds as a list of (xmin,xmax) pairs.
Returns an OptimizationProblem instance over the optimization variables.
solve
([params, preprocess, cache])Solves the optimization problem.

addEquality
(f, weight=None)[source]¶ If f is a symbolic.Function it’s a function f(x) that evaluates to 0 for a feasible solution. If it is a symbolic.Expression it’s an expresion over the optimization variables
If weight = None then this is an equality constraint, Otherwise it gets added to the objective weight*f(x)^2.

getVarValues
()[source]¶ Saves the bindings for optimization variables in the current context into a list.

setVarValues
(s)[source]¶ Converts a state into bindings for the optimization variables in the current context.

getVarVector
()[source]¶ Flattens the bindings for optimization variables in the current context into a vector x.

setVarVector
(x)[source]¶ Turns a vector x into bindings for the optimization variables in the current context.

randomVarBinding
()[source]¶ Samples values for all optimization variables, sampling uniformly according to their bounds

equalityResidual
(soft=True)[source]¶ Evaluates the equality + ik functions at the currently bound state x, stacking the results into a single vector. The residual should equal 0 (to a small tolerance) at a feasible solution.
If soft=True, also stacks the soft equalities.

satisfiesEqualities
(tol=0.001)[source]¶ Returns True if every entry of the (hard) equality + IK residual equals 0 (to the tolerance tol).

inequalityResidual
(soft=False)[source]¶ Evaluates the inequality functions at the currently bound state x, stacking the results into a single vector. The residual should be <= 0 at a feasible solution.
If soft=True then this includes the soft inequality residuals.

satisfiesInequalities
(margin=0)[source]¶ Returns True if the for currently bound state x, every entry of the (hard) inequality residuals is <= margin (default 0).

feasibilityTestsPass
(soft=False)[source]¶ Returns True if the currently bound state passes all blackbox feasibility tests.

inBounds
()[source]¶ Returns True if all bounded variables are within their ranges at the currently bound state x

isFeasible
(eqTol=0.001)[source]¶ Returns True if the currently bound state passes all equality, inequality, joint limit, and blackbox feasibility tests. Equality and IK constraints mut be met with equality tolerance eqTol.

costSymbolic
()[source]¶ Returns a symbolic.Expression, over variables in self.context, that evaluates to the cost

equalityResidualSymbolic
(soft=False)[source]¶ Returns a symbolic.Expression, over variables in self.context, that evaluates to the equality residual

inequalityResidualSymbolic
(soft=False)[source]¶ Returns a symbolic.Expression, over variables in self.context, that evaluates to the inequality residual

equalitySatisfiedSymbolic
(tol=0.001, soft=False)[source]¶ Returns a symbolic.Expression, over variables in self.context, that evaluates to True if the equality constraint is met with tolerance tol

inequalitySatisfiedSymbolic
(soft=False)[source]¶ Returns a symbolic.Expression, over variables in self.context, that evaluates to True if the inequality constraint is met

feasibilityTestsPassSymbolic
(soft=False)[source]¶ Returns a symbolic.Expression, over variables in self.context, that evaluates to True if the blackbox feasibility constraints are met

inBoundsSymbolic
()[source]¶ Returns a symbolic.Expression, over variables in self.context, that evaluates to True the configuration meets bound constraints

isFeasibleSymbolic
(eqTol=0.001)[source]¶ Returns a symbolic.Expression, over $q and other user data variables, that evaluates to True if the configuration meets all feasibility tests

score
(eqWeight=1.0, ineqWeight=1.0, infeasWeight=1.0)[source]¶ Returns an error score that is equal to the optimum at a feasible solution. Evaluated at the currently bound state x.

toJson
(saveContextFunctions=False, prettyPrintExprs=False)[source]¶ Returns a JSON object representing this optimization problem.
 Parameters
saveContextFunctions (bool, optional) – if True, saves all custom functions in self.context. If they are saved, then the current context is required to be the same context in which the problem is loaded.
prettyPrintExprs (bool, optional) – if True, prints expressions more nicely as more humanreadable strings rather than JSON objects. These strings are parsed on load, which is a little slower than pure JSON.

fromJson
(object, context=None)[source]¶ Sets this IK problem to a JSON object representing it. A ValueError is raised if it is not the correct type.

preprocess
(steps='all')[source]¶ Preprocesses the problem to make solving more efficient
 Returns
(opt,optToSelf,selfToOpt) giving:
opt: a simplified version of this optimization problem. If no simplfication can be performed, opt = self
optToSelf: a map of opt’s variables to self’s variables. If no simplification can be performed, optToSelf = None
selfToOpt: a map of self’s variables to opts’s variables. If no simplification can be performed, selfToOpt = None
 Return type
tuple
Specific steps include:
delete any objectives with 0 weight
delete any optimization variables not appearing in expressions
fixedbound (x in [a,b], with a=b) variables are replaced with fixed values.
simplify objectives
TODO: replace equalities of the form var = expr by matching var to expr?
If optToSelf is not None, then it is a list of Expressions that, when eval’ed, produce the values of the corresponding optimizationVariables in the original optimization problem. selfToOpt performs the converse mapping. In other words, if opt has bound values to all of its optimizationVariables, the code:
for var,expr in zip(self.optimizationVariables,optToSelf): var.bind(expr.eval(opt.context))
binds all optimization variables in self appropriately.

getBounds
()[source]¶ Returns optimization varable bounds as a list of (xmin,xmax) pairs. None is returned if the problem is unconstrained

solve
(params=<klampt.math.optimize.OptimizerParams object>, preprocess=True, cache=False)[source]¶ Solves the optimization problem. The result is stored in the bound optimizationVariables.
If you will be solving the problem several times without modification (except for user data and initial values of optimizationVariables), you may set cache=True to eliminate some overhead. Note that caching does not work properly if you change constraints or nonoptimization variables.
