Dlib¶

class Dlib(*args)¶

Base class for optimization solvers from the [dlib2009] library.

Available constructors:

Dlib(algoName)

Dlib(problem, algoName)

Parameters

algoNamestr, optional: Identifier of the optimization method to use. Use GetAlgorithmNames() to list available algorithms. Default is ‘BFGS’.
problemOptimizationProblem, optional: Optimization problem to solve. Default is an empty problem.

See also

AbdoRackwitz, Cobyla, NLopt

Notes

The table below presents some properties of the available algorithms from dlib. Details on optimization methods are available on http://dlib.net/optimization.html

Algorithm	Description	Problem type support	Derivatives info	Constraint support
CG	Conjugate gradient	General	First derivative	Bounds
BFGS	BFGS	General	First derivative	Bounds
LBFGS	Limited memory BFGS	General	First derivative	Bounds
Newton	Newton	General	First and second derivatives	Bounds
Global	Global optimization	General	No derivative	Bounds needed
LSQ	Least squares (best for large residual)	Least squares	First derivative	None
LSQLM	Least squares LM (small residual)	Least squares	First derivative	None
TrustRegion	Trust region	General	No derivative	None

Derivatives are managed automatically by openturns, according to the available data (analytical formula or finite differences computation).

The global optimization algorithm requires finite fixed bounds for all input variables. In this strategy, the solver starts by refining a local extremum until no significant improvement is found. Then it tries to find better extrema in the rest of the domain defined by the user, until the maximum number of function evaluation is reached.

In least squares and trust region methods, the optimization process continues until the user criteria on absolute, relative and residual errors are satisfied, or until no significant improvement can be achieved.

Examples

Define an optimization problem to find the minimum of the Rosenbrock function:

>>> import openturns as ot
>>> rosenbrock = ot.SymbolicFunction(['x1', 'x2'], ['(1-x1)^2+100*(x2-x1^2)^2'])
>>> problem = ot.OptimizationProblem(rosenbrock)
>>> cgSolver = ot.Dlib(problem,'CG')  
>>> cgSolver.setStartingPoint([0, 0])  
>>> cgSolver.setMaximumResidualError(1.e-3)  
>>> cgSolver.setMaximumIterationNumber(100)  
>>> cgSolver.run()  
>>> result = cgSolver.getResult()  
>>> x_star = result.getOptimalPoint()  
>>> y_star = result.getOptimalValue()  

Methods

`GetAlgorithmNames`()	List of dlib available optimization algorithms.
`IsAvailable`()	Check if dlib functions are available for use in openturns.
`computeLagrangeMultipliers`(self, x)	Compute the Lagrange multipliers of a problem at a given point.
`getClassName`(self)	Accessor to the object’s name.
`getId`(self)	Accessor to the object’s id.
`getInitialTrustRegionRadius`(self)	Accessor to initialTrustRegionRadius parameter.
`getMaxLineSearchIterations`(self)	Accessor to maxLineSearchIterations parameter.
`getMaxSize`(self)	Accessor to maxSize parameter.
`getMaximumAbsoluteError`(self)	Accessor to maximum allowed absolute error.
`getMaximumConstraintError`(self)	Accessor to maximum allowed constraint error.
`getMaximumEvaluationNumber`(self)	Accessor to maximum allowed number of evaluations.
`getMaximumIterationNumber`(self)	Accessor to maximum allowed number of iterations.
`getMaximumRelativeError`(self)	Accessor to maximum allowed relative error.
`getMaximumResidualError`(self)	Accessor to maximum allowed residual error.
`getName`(self)	Accessor to the object’s name.
`getProblem`(self)	Accessor to optimization problem.
`getResult`(self)	Accessor to optimization result.
`getShadowedId`(self)	Accessor to the object’s shadowed id.
`getStartingPoint`(self)	Accessor to starting point.
`getVerbose`(self)	Accessor to the verbosity flag.
`getVisibility`(self)	Accessor to the object’s visibility state.
`getWolfeRho`(self)	Accessor to wolfeRho parameter.
`getWolfeSigma`(self)	Accessor to wolfeSigma parameter.
`hasName`(self)	Test if the object is named.
`hasVisibleName`(self)	Test if the object has a distinguishable name.
`run`(self)	Performs the actual optimization process.
`setInitialTrustRegionRadius`(self, radius)	Accessor to initialTrustRegionRadius parameter, sets the value to use during optimization process.
`setMaxLineSearchIterations`(self, …)	Accessor to maxLineSearchIterations parameter, sets the value to use during line search process.
`setMaxSize`(self, maxSize)	Accessor to maxSize parameter, sets the value to use during optimization process.
`setMaximumAbsoluteError`(self, …)	Accessor to maximum allowed absolute error.
`setMaximumConstraintError`(self, …)	Accessor to maximum allowed constraint error.
`setMaximumEvaluationNumber`(self, …)	Accessor to maximum allowed number of evaluations.
`setMaximumIterationNumber`(self, …)	Accessor to maximum allowed number of iterations.
`setMaximumRelativeError`(self, …)	Accessor to maximum allowed relative error.
`setMaximumResidualError`(self, …)	Accessor to maximum allowed residual error.
`setName`(self, name)	Accessor to the object’s name.
`setProblem`(self, problem)	Accessor to optimization problem.
`setProgressCallback`(self, \*args)	Set up a progress callback.
`setResult`(self, result)	Accessor to optimization result.
`setShadowedId`(self, id)	Accessor to the object’s shadowed id.
`setStartingPoint`(self, startingPoint)	Accessor to starting point.
`setStopCallback`(self, \*args)	Set up a stop callback.
`setVerbose`(self, verbose)	Accessor to the verbosity flag.
`setVisibility`(self, visible)	Accessor to the object’s visibility state.
`setWolfeRho`(self, wolfeRho)	Accessor to wolfeRho parameter, sets the value to use during line search process.
`setWolfeSigma`(self, wolfeSigma)	Accessor to wolfeSigma parameter, sets the value to use during line search process.

getAlgorithmName
setAlgorithmName

__init__(self, \*args)¶: Initialize self. See help(type(self)) for accurate signature.

static GetAlgorithmNames()¶

List of dlib available optimization algorithms.

Returns

algorithmNamesDescription: List of the names of available dlib search strategies.

static IsAvailable()¶

Check if dlib functions are available for use in openturns.

Returns

isAvailablebool: Whether dlib algorithms can be used or not.

computeLagrangeMultipliers(self, x)¶

Compute the Lagrange multipliers of a problem at a given point.

Parameters

xsequence of float: Point at which the Lagrange multipliers are computed.

Returns

lagrangeMultipliersequence of float: Lagrange multipliers of the problem at the given point.

Notes

The Lagrange multipliers $\vect{\lambda}$ are associated with the following Lagrangian formulation of the optimization problem:

$\cL(\vect{x}, \vect{\lambda}_{eq}, \vect{\lambda}_{\ell}, \vect{\lambda}_{u}, \vect{\lambda}_{ineq}) = J(\vect{x}) + \Tr{\vect{\lambda}}_{eq} g(\vect{x}) + \Tr{\vect{\lambda}}_{\ell} (\vect{x}-\vect{\ell})^{+} + \Tr{\vect{\lambda}}_{u} (\vect{u}-\vect{x})^{+} + \Tr{\vect{\lambda}}_{ineq} h^{+}(\vect{x})$

where $\vect{\alpha}^{+}=(\max(0,\alpha_1),\hdots,\max(0,\alpha_n))$ .

The Lagrange multipliers are stored as $(\vect{\lambda}_{eq}, \vect{\lambda}_{\ell}, \vect{\lambda}_{u}, \vect{\lambda}_{ineq})$ , where:

$\vect{\lambda}_{eq}$ is of dimension 0 if there is no equality constraint, else of dimension the dimension of $g(\vect{x})$ ie the number of scalar equality constraints
$\vect{\lambda}_{\ell}$ and $\vect{\lambda}_{u}$ are of dimension 0 if there is no bound constraint, else of dimension of $\vect{x}$
$\vect{\lambda}_{eq}$ is of dimension 0 if there is no inequality constraint, else of dimension the dimension of $h(\vect{x})$ ie the number of scalar inequality constraints

The vector $\vect{\lambda}$ is solution of the following linear system:

$\Tr{\vect{\lambda}}_{eq}\left[\dfrac{\partial g}{\partial\vect{x}}(\vect{x})\right]+ \Tr{\vect{\lambda}}_{\ell}\left[\dfrac{\partial (\vect{x}-\vect{\ell})^{+}}{\partial\vect{x}}(\vect{x})\right]+ \Tr{\vect{\lambda}}_{u}\left[\dfrac{\partial (\vect{u}-\vect{x})^{+}}{\partial\vect{x}}(\vect{x})\right]+ \Tr{\vect{\lambda}}_{ineq}\left[\dfrac{\partial h}{\partial\vect{x}}(\vect{x})\right]=-\dfrac{\partial J}{\partial\vect{x}}(\vect{x})$

If there is no constraint of any kind, $\vect{\lambda}$ is of dimension 0, as well as if no constraint is active.

getClassName(self)¶

Accessor to the object’s name.

Returns

class_namestr: The object class name (object.__class__.__name__).

getId(self)¶

Accessor to the object’s id.

Returns

idint: Internal unique identifier.

getInitialTrustRegionRadius(self)¶

Accessor to initialTrustRegionRadius parameter. Relevant for trust region, least squares and least squares LM algorithms only.

Returns

initialTrustRegionRadiusfloat: The radius of the initial trust region used in optimization algorithms.

getMaxLineSearchIterations(self)¶

Accessor to maxLineSearchIterations parameter. Relevant for algorithms CG, BFGS/LBFGS and Newton only.

Returns

maxLineSearchIterationsint: The maximum number of line search iterations to perform at each iteration of the optimization process. Relevant for algorithms CG, BFGS/LBFGS and Newton only.

getMaxSize(self)¶

Accessor to maxSize parameter. Relevant for LBFGS algorithm only.

Returns

maxSizeint: The maximum amount of memory used during optimization process. 10 is a typical value for maxSize. Relevant for LBFGS algorithm only.

getMaximumAbsoluteError(self)¶

Accessor to maximum allowed absolute error.

Returns

maximumAbsoluteErrorfloat: Maximum allowed absolute error, where the absolute error is defined by $\epsilon^a_n=\|\vect{x}_{n+1}-\vect{x}_n\|_{\infty}$ where $\vect{x}_{n+1}$ and $\vect{x}_n$ are two consecutive approximations of the optimum.

getMaximumConstraintError(self)¶

Accessor to maximum allowed constraint error.

Returns

maximumConstraintErrorfloat: Maximum allowed constraint error, where the constraint error is defined by $\gamma_n=\|g(\vect{x}_n)\|_{\infty}$ where $\vect{x}_n$ is the current approximation of the optimum and $g$ is the function that gathers all the equality and inequality constraints (violated values only)

getMaximumEvaluationNumber(self)¶

Accessor to maximum allowed number of evaluations.

Returns

Nint: Maximum allowed number of evaluations.

getMaximumIterationNumber(self)¶

Accessor to maximum allowed number of iterations.

Returns

Nint: Maximum allowed number of iterations.

getMaximumRelativeError(self)¶

Accessor to maximum allowed relative error.

Returns

maximumRelativeErrorfloat: Maximum allowed relative error, where the relative error is defined by $\epsilon^r_n=\epsilon^a_n/\|\vect{x}_{n+1}\|_{\infty}$ if $\|\vect{x}_{n+1}\|_{\infty}\neq 0$ , else $\epsilon^r_n=-1$ .

getMaximumResidualError(self)¶

Accessor to maximum allowed residual error.

Returns

maximumResidualErrorfloat: Maximum allowed residual error, where the residual error is defined by $\epsilon^r_n=\frac{\|f(\vect{x}_{n+1})-f(\vect{x}_{n})\|}{\|f(\vect{x}_{n+1})\|}$ if $\|f(\vect{x}_{n+1})\|\neq 0$ , else $\epsilon^r_n=-1$ .

getName(self)¶

Accessor to the object’s name.

Returns

namestr: The name of the object.

getProblem(self)¶

Accessor to optimization problem.

Returns

problemOptimizationProblem: Optimization problem.

getResult(self)¶

Accessor to optimization result.

Returns

resultOptimizationResult: Result class.

getShadowedId(self)¶

Accessor to the object’s shadowed id.

Returns

idint: Internal unique identifier.

getStartingPoint(self)¶

Accessor to starting point.

Returns

startingPointPoint: Starting point.

getVerbose(self)¶

Accessor to the verbosity flag.

Returns

verbosebool: Verbosity flag state.

getVisibility(self)¶

Accessor to the object’s visibility state.

Returns

visiblebool: Visibility flag.

getWolfeRho(self)¶

Accessor to wolfeRho parameter. Relevant for algorithms CG, BFGS/LBFGS and Newton only.

Returns

wolfeRhofloat: The value of the wolfeRho parameter used in the optimization process.

getWolfeSigma(self)¶

Accessor to wolfeSigma parameter. Relevant for algorithms CG, BFGS/LBFGS and Newton only.

Returns

wolfeSigmafloat: The value of the wolfeSigma parameter used in the optimization process.

hasName(self)¶

Test if the object is named.

Returns

hasNamebool: True if the name is not empty.

hasVisibleName(self)¶

Test if the object has a distinguishable name.

Returns

hasVisibleNamebool: True if the name is not empty and not the default one.

run(self)¶: Performs the actual optimization process. Results are stored in the OptimizationResult parameter of the Dlib object.

setInitialTrustRegionRadius(self, radius)¶

Accessor to initialTrustRegionRadius parameter, sets the value to use during optimization process. Relevant for trust region, least squares and least squares LM algorithms only.

Parameters

initialTrustRegionRadiusfloat: The radius of the initial trust region to use in the optimization process.

setMaxLineSearchIterations(self, maxLineSearchIterations)¶

Accessor to maxLineSearchIterations parameter, sets the value to use during line search process. Relevant for algorithms CG, BFGS/LBFGS and Newton only.

Parameters

maxLineSearchIterationsint: The value of the maxLineSearchIterations parameter to use in the optimization process.

setMaxSize(self, maxSize)¶

Accessor to maxSize parameter, sets the value to use during optimization process. Relevant for LBFGS algorithm only.

Parameters

maxSizeint: The maximum amount of memory to use during optimization process. 10 is a typical value for maxSize. Relevant for LBFGS algorithm only.

setMaximumAbsoluteError(self, maximumAbsoluteError)¶

Accessor to maximum allowed absolute error.

Parameters

maximumAbsoluteErrorfloat: Maximum allowed absolute error, where the absolute error is defined by $\epsilon^a_n=\|\vect{x}_{n+1}-\vect{x}_n\|_{\infty}$ where $\vect{x}_{n+1}$ and $\vect{x}_n$ are two consecutive approximations of the optimum.

setMaximumConstraintError(self, maximumConstraintError)¶

Accessor to maximum allowed constraint error.

Parameters

maximumConstraintErrorfloat: Maximum allowed constraint error, where the constraint error is defined by $\gamma_n=\|g(\vect{x}_n)\|_{\infty}$ where $\vect{x}_n$ is the current approximation of the optimum and $g$ is the function that gathers all the equality and inequality constraints (violated values only)

setMaximumEvaluationNumber(self, maximumEvaluationNumber)¶

Accessor to maximum allowed number of evaluations.

Parameters

Nint: Maximum allowed number of evaluations.

setMaximumIterationNumber(self, maximumIterationNumber)¶

Accessor to maximum allowed number of iterations.

Parameters

Nint: Maximum allowed number of iterations.

setMaximumRelativeError(self, maximumRelativeError)¶

Accessor to maximum allowed relative error.

Parameters

maximumRelativeErrorfloat: Maximum allowed relative error, where the relative error is defined by $\epsilon^r_n=\epsilon^a_n/\|\vect{x}_{n+1}\|_{\infty}$ if $\|\vect{x}_{n+1}\|_{\infty}\neq 0$ , else $\epsilon^r_n=-1$ .

setMaximumResidualError(self, maximumResidualError)¶

Accessor to maximum allowed residual error.

Parameters

Maximum allowed residual error, where the residual error is defined by: $\epsilon^r_n=\frac{\|f(\vect{x}_{n+1})-f(\vect{x}_{n})\|}{\|f(\vect{x}_{n+1})\|}$ if $\|f(\vect{x}_{n+1})\|\neq 0$ , else $\epsilon^r_n=-1$ .

setName(self, name)¶

Accessor to the object’s name.

Parameters

namestr: The name of the object.

setProblem(self, problem)¶

Accessor to optimization problem.

Parameters

problemOptimizationProblem: Optimization problem.

setProgressCallback(self, \*args)¶

Set up a progress callback.

Can be used to programmatically report the progress of an optimization.

Parameters

callbackcallable: Takes a float as argument as percentage of progress.

Examples

>>> import sys
>>> import openturns as ot
>>> rosenbrock = ot.SymbolicFunction(['x1', 'x2'], ['(1-x1)^2+100*(x2-x1^2)^2'])
>>> problem = ot.OptimizationProblem(rosenbrock)
>>> solver = ot.OptimizationAlgorithm(problem)
>>> solver.setStartingPoint([0, 0])
>>> solver.setMaximumResidualError(1.e-3)
>>> solver.setMaximumIterationNumber(100)
>>> def report_progress(progress):
...     sys.stderr.write('-- progress=' + str(progress) + '%\n')
>>> solver.setProgressCallback(report_progress)
>>> solver.run()

setResult(self, result)¶

Accessor to optimization result.

Parameters

resultOptimizationResult: Result class.

setShadowedId(self, id)¶

Accessor to the object’s shadowed id.

Parameters

idint: Internal unique identifier.

setStartingPoint(self, startingPoint)¶

Accessor to starting point.

Parameters

startingPointPoint: Starting point.

setStopCallback(self, \*args)¶

Set up a stop callback.

Can be used to programmatically stop an optimization.

Parameters

callbackcallable: Returns an int deciding whether to stop or continue.

Examples

>>> import openturns as ot
>>> rosenbrock = ot.SymbolicFunction(['x1', 'x2'], ['(1-x1)^2+100*(x2-x1^2)^2'])
>>> problem = ot.OptimizationProblem(rosenbrock)
>>> solver = ot.OptimizationAlgorithm(problem)
>>> solver.setStartingPoint([0, 0])
>>> solver.setMaximumResidualError(1.e-3)
>>> solver.setMaximumIterationNumber(100)
>>> def ask_stop():
...     return True
>>> solver.setStopCallback(ask_stop)
>>> solver.run()

setVerbose(self, verbose)¶

Accessor to the verbosity flag.

Parameters

verbosebool: Verbosity flag state.

setVisibility(self, visible)¶

Accessor to the object’s visibility state.

Parameters

visiblebool: Visibility flag.

setWolfeRho(self, wolfeRho)¶

Accessor to wolfeRho parameter, sets the value to use during line search process. Relevant for algorithms CG, BFGS/LBFGS and Newton only.

Parameters

wolfeRhofloat: The value of the wolfeRho parameter to use in the optimization process.

setWolfeSigma(self, wolfeSigma)¶

Accessor to wolfeSigma parameter, sets the value to use during line search process. Relevant for algorithms CG, BFGS/LBFGS and Newton only.

Parameters

wolfeSigmafloat: The value of the wolfeSigma parameter to use in the optimization process.

OpenTURNS

An Open source initiative for the Treatment of Uncertainties, Risks'N Statistics

Previous topic

Next topic

This Page

Dlib¶