ANIMA  4.0
anima::NLOPTOptimizers Class Reference

Implements an ITK wrapper for the NLOPT library. More...

#include <animaNLOPTOptimizers.h>

Inheritance diagram for anima::NLOPTOptimizers:
Collaboration diagram for anima::NLOPTOptimizers:

## Public Types

typedef itk::SmartPointer< const SelfConstPointer

typedef anima::NLOPTParametersConstraintFunction ConstraintsFunctionType

typedef CostFunctionType::Pointer CostFunctionPointer

typedef itk::SingleValuedCostFunction CostFunctionType

typedef SingleValuedNonLinearOptimizer::ParametersType ParametersType

typedef itk::SmartPointer< SelfPointer

typedef NLOPTOptimizers Self

typedef SingleValuedNonLinearOptimizer Superclass

## Public Member Functions

Adds a nonlinear equality constraint of the form $$h(x) = 0$$. The parameter tol is a tolerance that is used for the purpose of stopping criteria only: a point x is considered feasible for judging whether to stop the optimization if $$|h(x)| <= tol$$. For equality constraints, a small positive tolerance is strongly advised in order to allow NLopt to converge even if the equality constraint is slightly nonzero. More...

Adds a nonlinear inequality constraint of the form $$fc(x) <= 0$$. The parameter tol is a tolerance that is used for the purpose of stopping criteria only: a point x is considered feasible for judging whether to stop the optimization if $$fc(x) <= tol$$. A tolerance of zero means that NLopt will try not to consider any x to be converged unless fc is strictly non-positive; generally, at least a small positive tolerance is advisable to reduce sensitivity to rounding errors. More...

void ClearEqualityConstraints ()
Clears all equality constraints. More...

void ClearInequalityConstraints ()
Clears all inequality constraints. More...

virtual ::itk::LightObject::Pointer CreateAnother (void) const

virtual const nlopt_algorithm & GetAlgorithm () const

virtual const MeasureType & GetCurrentCost () const

virtual const nlopt_result & GetErrorCode () const

std::string GetErrorCodeDescription () const
Gets the current error code description as a std::string. More...

virtual const double & GetFTolAbs () const

virtual const double & GetFTolRel () const

virtual const nlopt_algorithm & GetLocalOptimizer () const

virtual const ParametersTypeGetLowerBoundParameters () const

virtual const int & GetMaxEval () const

virtual const bool & GetMaximize () const

virtual const double & GetMaxTime () const

virtual const char * GetNameOfClass () const

virtual const int & GetPopulationSize () const

virtual const double & GetStopVal () const

virtual const ParametersTypeGetUpperBoundParameters () const

MeasureType GetValue () const

virtual const int & GetVectorStorageSize () const

virtual unsigned int GetVerboseLevel ()

virtual const double & GetXTolAbs () const

virtual const double & GetXTolRel () const

bool isSuccessful () const
Return true if the optimization was successful (ie the last error code was positive or equal to NLOPT_ROUNDOFF_LIMITED or NLOPT_FORCED_STOP) More...

virtual void SetAlgorithm (nlopt_algorithm _arg)

virtual void SetErrorCode (nlopt_result _arg)

virtual void SetFTolAbs (double _arg)

virtual void SetFTolRel (double _arg)

virtual void SetLocalOptimizer (nlopt_algorithm _arg)

void SetLowerBoundParameters (const ParametersType &p)
Set the lower bound parameters (not used by all algorithms) More...

virtual void SetMaxEval (int _arg)

virtual void SetMaximize (bool _arg)

virtual void SetMaxTime (double _arg)

virtual void SetPopulationSize (int _arg)

void SetStopVal (double stopval)

void SetUpperBoundParameters (const ParametersType &p)
Set the upper bound parameters (not used by all algorithms) More...

virtual void SetVectorStorageSize (int _arg)

virtual void SetVerboseLevel (unsigned int _arg)

virtual void SetXTolAbs (double _arg)

virtual void SetXTolRel (double _arg)

void StartOptimization () ITK_OVERRIDE
Starts the optimization. More...

void StopOptimization ()

## Static Public Member Functions

static Pointer New ()

## Protected Member Functions

NLOPTOptimizers ()
Default constructor. More...

NLOPTOptimizers (const NLOPTOptimizers &)

void PrintSelf (std::ostream &os, itk::Indent indent) const ITK_OVERRIDE

virtual void SetCurrentCost (double _arg)

virtual ~NLOPTOptimizers ()
Destructor. More...

## Static Protected Member Functions

static double NloptFunctionWrapper (unsigned n, const double *x, double *grad, void *data)
NloptFunctionWrapper is called by nlopt to evaluate the function f to minimize. NloptFunctionWrapper converts the nlopt parameters to the SingleValuedCostFunction parameters, and call the SingleValuedCostFunction to actually compute the value of f. More...

## Detailed Description

Implements an ITK wrapper for the NLOPT library.

# Wrapper for the NLOPT library

Version 1.0.0
This code was graciously provided to us by the CRL at Boston.

Copyright (c) 2010-2011 Children's Hospital Boston.
Benoit Scherrer, CRL (Computational Radiology Laboratory), Harvard Medical School

# Example

The wrapper is very easy to use. Here is an example of how to minimimze a function with MyCostFunction being a regular itk::SingleValuedCostFunction

// Create the cost function
itk::MyCostFunction::Pointer costFun = itk::MyCostFunction::New();
// Create the optimizer
itk::NLOPTOptimizers::Pointer optimizer = itk::NLOPTOptimizers::New();
optimizer->SetCostFunction(costFun);
// Set the parameters
optimizer->SetMaxEval(500);
optimizer->SetAlgorithm(itk::NLOPTOptimizers::NLOPT_LN_BOBYQA);
// Set the initial position
itk::NLOPTOptimizers::ParametersType pinit(2);
pinit[0]=pinit[1] = 4;
optimizer->SetInitialPosition(pinit);
optimizer->StartOptimization();
std::cout<<"Return code "<<(int)optimizer->GetErrorCode();
std::cout<<" = "<<optimizer->GetErrorCodeDescription()<<endl;
std::cout<<"Position = "<<optimizer->GetCurrentPosition()<<endl;
std::cout<<"Value = "<<optimizer->GetCurrentCost()<<endl;

http://ab-initio.mit.edu/wiki/index.php/NLopt

This software is licensed by the copyright holder under the terms of the Open Software License version 3.0.

# Notice.

This research was carried out in the Computational Radiology Laboratory of Children's Hospital, Boston and Harvard Medical School.
http://www.crl.med.harvard.edu

This research work was made possible by Grant Number R01 RR021885 (Principal Investigator: Simon K. Warfield, Ph.D.) to Children's Hospital, Boston from the National Center for Research Resources (NCRR), a component of the National Institutes of Health (NIH).

        NLopt is a free/open-source library for nonlinear optimization, providing a common
interface for a number of different free optimization routines available online as
well as original implementations of various other algorithms.

WEBSITE: http://ab-initio.mit.edu/wiki/index.php/NLopt \n
AUTHOR: Steven G. Johnson

This ITK wrapper was created by:\n Benoit Scherrer, CRL, Harvard Medical School. \n
Copyright (c) 2010-2011 Children's Hospital Boston

Date
July 2010

Definition at line 94 of file animaNLOPTOptimizers.h.

## ◆ ConstPointer

 typedef itk::SmartPointer anima::NLOPTOptimizers::ConstPointer

Standard ITK "ConstPointer" typedef.

Definition at line 102 of file animaNLOPTOptimizers.h.

## ◆ ConstraintsFunctionType

Base constraints (for inequality and equality)

Definition at line 105 of file animaNLOPTOptimizers.h.

## ◆ CostFunctionPointer

 typedef CostFunctionType::Pointer anima::NLOPTOptimizers::CostFunctionPointer

Definition at line 115 of file animaNLOPTOptimizers.h.

## ◆ CostFunctionType

 typedef itk::SingleValuedCostFunction anima::NLOPTOptimizers::CostFunctionType

Type of the Cost Function

Definition at line 114 of file animaNLOPTOptimizers.h.

## ◆ ParametersType

 typedef SingleValuedNonLinearOptimizer::ParametersType anima::NLOPTOptimizers::ParametersType

Parameter type

Definition at line 104 of file animaNLOPTOptimizers.h.

## ◆ Pointer

 typedef itk::SmartPointer anima::NLOPTOptimizers::Pointer

Standard ITK "Pointer" typedef.

Definition at line 101 of file animaNLOPTOptimizers.h.

## ◆ Self

Standard ITK "Self" typedef.

Definition at line 99 of file animaNLOPTOptimizers.h.

## ◆ Superclass

 typedef SingleValuedNonLinearOptimizer anima::NLOPTOptimizers::Superclass

Standard ITK "Superclass" typedef.

Definition at line 100 of file animaNLOPTOptimizers.h.

## ◆ NLOPTOptimizers() [1/2]

 anima::NLOPTOptimizers::NLOPTOptimizers ( )
protected

Default constructor.

Date
July 2010

Definition at line 45 of file animaNLOPTOptimizers.cxx.

## ◆ NLOPTOptimizers() [2/2]

 anima::NLOPTOptimizers::NLOPTOptimizers ( const NLOPTOptimizers & )
protected

## ◆ ~NLOPTOptimizers()

 anima::NLOPTOptimizers::~NLOPTOptimizers ( )
protectedvirtual

Destructor.

Date
July 2010

Definition at line 74 of file animaNLOPTOptimizers.cxx.

## Member Function Documentation

 void anima::NLOPTOptimizers::AddEqualityConstraint ( ConstraintsFunctionType * constraint )

Adds a nonlinear equality constraint of the form $$h(x) = 0$$. The parameter tol is a tolerance that is used for the purpose of stopping criteria only: a point x is considered feasible for judging whether to stop the optimization if $$|h(x)| <= tol$$. For equality constraints, a small positive tolerance is strongly advised in order to allow NLopt to converge even if the equality constraint is slightly nonzero.

(For any algorithm listed as "derivative-free" below, the grad argument to fc or h will always be NULL and need never be computed.)

Date
July 2010
Parameters
 constraint The constraint function containing all details

Definition at line 381 of file animaNLOPTOptimizers.cxx.

 void anima::NLOPTOptimizers::AddInequalityConstraint ( ConstraintsFunctionType * constraint )

Adds a nonlinear inequality constraint of the form $$fc(x) <= 0$$. The parameter tol is a tolerance that is used for the purpose of stopping criteria only: a point x is considered feasible for judging whether to stop the optimization if $$fc(x) <= tol$$. A tolerance of zero means that NLopt will try not to consider any x to be converged unless fc is strictly non-positive; generally, at least a small positive tolerance is advisable to reduce sensitivity to rounding errors.

Date
July 2010
Parameters
 constraint The constraint function containing all details

Definition at line 346 of file animaNLOPTOptimizers.cxx.

## ◆ ClearEqualityConstraints()

 void anima::NLOPTOptimizers::ClearEqualityConstraints ( )

Clears all equality constraints.

Date
July 2010

Definition at line 394 of file animaNLOPTOptimizers.cxx.

## ◆ ClearInequalityConstraints()

 void anima::NLOPTOptimizers::ClearInequalityConstraints ( )

Clears all inequality constraints.

Date
July 2010

Definition at line 359 of file animaNLOPTOptimizers.cxx.

## ◆ CreateAnother()

 virtual::itk::LightObject::Pointer anima::NLOPTOptimizers::CreateAnother ( void ) const

## ◆ GetAlgorithm()

 virtual const nlopt_algorithm& anima::NLOPTOptimizers::GetAlgorithm ( ) const
virtual

## ◆ GetCurrentCost()

 virtual const MeasureType& anima::NLOPTOptimizers::GetCurrentCost ( ) const
virtual

Returns the current value

## ◆ GetErrorCode()

 virtual const nlopt_result& anima::NLOPTOptimizers::GetErrorCode ( ) const
virtual

## ◆ GetErrorCodeDescription()

 std::string anima::NLOPTOptimizers::GetErrorCodeDescription ( ) const

Gets the current error code description as a std::string.

Date
July 2010
Returns
The error code description.

Definition at line 295 of file animaNLOPTOptimizers.cxx.

## ◆ GetFTolAbs()

 virtual const double& anima::NLOPTOptimizers::GetFTolAbs ( ) const
virtual

## ◆ GetFTolRel()

 virtual const double& anima::NLOPTOptimizers::GetFTolRel ( ) const
virtual

## ◆ GetLocalOptimizer()

 virtual const nlopt_algorithm& anima::NLOPTOptimizers::GetLocalOptimizer ( ) const
virtual

## ◆ GetLowerBoundParameters()

 virtual const ParametersType& anima::NLOPTOptimizers::GetLowerBoundParameters ( ) const
virtual

## ◆ GetMaxEval()

 virtual const int& anima::NLOPTOptimizers::GetMaxEval ( ) const
virtual

## ◆ GetMaximize()

 virtual const bool& anima::NLOPTOptimizers::GetMaximize ( ) const
virtual

## ◆ GetMaxTime()

 virtual const double& anima::NLOPTOptimizers::GetMaxTime ( ) const
virtual

## ◆ GetNameOfClass()

 virtual const char* anima::NLOPTOptimizers::GetNameOfClass ( ) const
virtual

Run-time type information (and related methods).

## ◆ GetPopulationSize()

 virtual const int& anima::NLOPTOptimizers::GetPopulationSize ( ) const
virtual

## ◆ GetStopVal()

 virtual const double& anima::NLOPTOptimizers::GetStopVal ( ) const
virtual

## ◆ GetUpperBoundParameters()

 virtual const ParametersType& anima::NLOPTOptimizers::GetUpperBoundParameters ( ) const
virtual

## ◆ GetValue()

 MeasureType anima::NLOPTOptimizers::GetValue ( ) const
inline

Returns the current value

Definition at line 133 of file animaNLOPTOptimizers.h.

Referenced by NloptFunctionWrapper().

## ◆ GetVectorStorageSize()

 virtual const int& anima::NLOPTOptimizers::GetVectorStorageSize ( ) const
virtual

## ◆ GetVerboseLevel()

 virtual unsigned int anima::NLOPTOptimizers::GetVerboseLevel ( )
virtual

## ◆ GetXTolAbs()

 virtual const double& anima::NLOPTOptimizers::GetXTolAbs ( ) const
virtual

## ◆ GetXTolRel()

 virtual const double& anima::NLOPTOptimizers::GetXTolRel ( ) const
virtual

## ◆ isSuccessful()

 bool anima::NLOPTOptimizers::isSuccessful ( ) const

Return true if the optimization was successful (ie the last error code was positive or equal to NLOPT_ROUNDOFF_LIMITED or NLOPT_FORCED_STOP)

Date
July 2010
Returns
true if successful, false if not.

Definition at line 275 of file animaNLOPTOptimizers.cxx.

## ◆ New()

 static Pointer anima::NLOPTOptimizers::New ( )
static

Method for creation through the object factory.

## ◆ NloptFunctionWrapper()

 double anima::NLOPTOptimizers::NloptFunctionWrapper ( unsigned n, const double * x, double * grad, void * data )
staticprotected

NloptFunctionWrapper is called by nlopt to evaluate the function f to minimize. NloptFunctionWrapper converts the nlopt parameters to the SingleValuedCostFunction parameters, and call the SingleValuedCostFunction to actually compute the value of f.

Date
July 2010
Parameters
 n The. x The x coordinate. [in,out] grad If non-null, the graduated. [in,out] data If non-null, the data.
Returns
.

Definition at line 95 of file animaNLOPTOptimizers.cxx.

References GetValue().

## ◆ PrintSelf()

 void anima::NLOPTOptimizers::PrintSelf ( std::ostream & os, itk::Indent indent ) const
protected

Definition at line 436 of file animaNLOPTOptimizers.cxx.

## ◆ SetAlgorithm()

 virtual void anima::NLOPTOptimizers::SetAlgorithm ( nlopt_algorithm _arg )
virtual

NLOPT Algorithm to use

## ◆ SetCurrentCost()

 virtual void anima::NLOPTOptimizers::SetCurrentCost ( double _arg )
protectedvirtual

## ◆ SetErrorCode()

 virtual void anima::NLOPTOptimizers::SetErrorCode ( nlopt_result _arg )
virtual

Returns the last error code of NLOPT

## ◆ SetFTolAbs()

 virtual void anima::NLOPTOptimizers::SetFTolAbs ( double _arg )
virtual

Stopping criteria: Set absolute tolerance on function value: stop when an optimization step (or an estimate of the optimum) changes the function value by less than tol. Criterion is disabled if tol is non-positive.

Note
Multiple stopping criteria for the optimization are supported. The optimization halts whenever any one of these criteria is satisfied. In some cases, the precise interpretation of the stopping criterion depends on the optimization algorithm above (although NLopt try to make them as consistent as reasonably possible), and some algorithms do not support all of the stopping criteria.
You do not need to use all of the stopping criteria! In most cases, you only need one or two, and can omit the remainder (all criteria are disabled by default).

## ◆ SetFTolRel()

 virtual void anima::NLOPTOptimizers::SetFTolRel ( double _arg )
virtual

Stopping criteria: Set relative tolerance on function value: stop when an optimization step (or an estimate of the optimum) changes the objective function value by less than tol multiplied by the absolute value of the function value. (If there is any chance that your optimum function value is close to zero, you might want to set an absolute tolerance with nlopt_set_ftol_abs as well.) Criterion is disabled if tol is non-positive.

Note
Multiple stopping criteria for the optimization are supported. The optimization halts whenever any one of these criteria is satisfied. In some cases, the precise interpretation of the stopping criterion depends on the optimization algorithm above (although NLopt try to make them as consistent as reasonably possible), and some algorithms do not support all of the stopping criteria.
You do not need to use all of the stopping criteria! In most cases, you only need one or two, and can omit the remainder (all criteria are disabled by default).

## ◆ SetLocalOptimizer()

 virtual void anima::NLOPTOptimizers::SetLocalOptimizer ( nlopt_algorithm _arg )
virtual

Set local optimizer for AUGLAG and MLSL algos

## ◆ SetLowerBoundParameters()

 void anima::NLOPTOptimizers::SetLowerBoundParameters ( const ParametersType & p )

Set the lower bound parameters (not used by all algorithms)

Date
July 2010
Parameters
 p The lower bound parameters.

Definition at line 409 of file animaNLOPTOptimizers.cxx.

## ◆ SetMaxEval()

 virtual void anima::NLOPTOptimizers::SetMaxEval ( int _arg )
virtual

Stopping criteria: Stop when the number of function evaluations exceeds maxeval. (This is not a strict maximum: the number of function evaluations may exceed maxeval slightly, depending upon the algorithm.) Criterion is disabled if maxeval is non-positive.

Note
Multiple stopping criteria for the optimization are supported. The optimization halts whenever any one of these criteria is satisfied. In some cases, the precise interpretation of the stopping criterion depends on the optimization algorithm above (although NLopt try to make them as consistent as reasonably possible), and some algorithms do not support all of the stopping criteria.
You do not need to use all of the stopping criteria! In most cases, you only need one or two, and can omit the remainder (all criteria are disabled by default).

## ◆ SetMaximize()

 virtual void anima::NLOPTOptimizers::SetMaximize ( bool _arg )
virtual

Set if the Optimizer should Maximize the metric

## ◆ SetMaxTime()

 virtual void anima::NLOPTOptimizers::SetMaxTime ( double _arg )
virtual

Stopping criteria: Stop when the optimization time (in seconds) exceeds maxtime. (This is not a strict maximum: the time may exceed maxtime slightly, depending upon the algorithm and on how slow your function evaluation is.) Criterion is disabled if maxtime is non-positive

Note
Multiple stopping criteria for the optimization are supported. The optimization halts whenever any one of these criteria is satisfied. In some cases, the precise interpretation of the stopping criterion depends on the optimization algorithm above (although NLopt try to make them as consistent as reasonably possible), and some algorithms do not support all of the stopping criteria.
You do not need to use all of the stopping criteria! In most cases, you only need one or two, and can omit the remainder (all criteria are disabled by default).

## ◆ SetPopulationSize()

 virtual void anima::NLOPTOptimizers::SetPopulationSize ( int _arg )
virtual

Stochastic population size: This is for random global optimization. It sets the number of random particles to propagate from.

## ◆ SetStopVal()

 void anima::NLOPTOptimizers::SetStopVal ( double stopval )
inline

Stopping criteria: Stop when an objective value of at least stopval is found: stop minimizing when an objective value <= stopval is found, or stop maximizing a value >= stopval is found. (Setting stopval to -HUGE_VAL for minimizing or +HUGE_VAL for maximizing disables this stopping criterion.)

Note
Multiple stopping criteria for the optimization are supported. The optimization halts whenever any one of these criteria is satisfied. In some cases, the precise interpretation of the stopping criterion depends on the optimization algorithm above (although NLopt try to make them as consistent as reasonably possible), and some algorithms do not support all of the stopping criteria.
You do not need to use all of the stopping criteria! In most cases, you only need one or two, and can omit the remainder (all criteria are disabled by default).

Definition at line 161 of file animaNLOPTOptimizers.h.

## ◆ SetUpperBoundParameters()

 void anima::NLOPTOptimizers::SetUpperBoundParameters ( const ParametersType & p )

Set the upper bound parameters (not used by all algorithms)

Date
July 2010
Parameters
 p The upper bound parameters.

Definition at line 426 of file animaNLOPTOptimizers.cxx.

## ◆ SetVectorStorageSize()

 virtual void anima::NLOPTOptimizers::SetVectorStorageSize ( int _arg )
virtual

Vector storage size: number of gradients to "remember" from previous optimization steps: increasing it increases the memory requirements but speeds convergence.

## ◆ SetVerboseLevel()

 virtual void anima::NLOPTOptimizers::SetVerboseLevel ( unsigned int _arg )
virtual

## ◆ SetXTolAbs()

 virtual void anima::NLOPTOptimizers::SetXTolAbs ( double _arg )
virtual

Stopping criteria: Set the absolute tolerance on optimization parameters.

Todo:
Set the absolute tolerances for each parameter separately by using nlopt_set_xtol_abs(nlopt_opt opt, const double* tol)
Note
Multiple stopping criteria for the optimization are supported. The optimization halts whenever any one of these criteria is satisfied. In some cases, the precise interpretation of the stopping criterion depends on the optimization algorithm above (although NLopt try to make them as consistent as reasonably possible), and some algorithms do not support all of the stopping criteria.
You do not need to use all of the stopping criteria! In most cases, you only need one or two, and can omit the remainder (all criteria are disabled by default).

## ◆ SetXTolRel()

 virtual void anima::NLOPTOptimizers::SetXTolRel ( double _arg )
virtual

Stopping criteria: Set relative tolerance on optimization parameters: stop when an optimization step (or an estimate of the optimum) changes every parameter by less than tol multiplied by the absolute value of the parameter. (If there is any chance that an optimal parameter is close to zero, you might want to set an absolute tolerance with nlopt_set_xtol_abs as well.) Criterion is disabled if tol is non-positive.

Note
Multiple stopping criteria for the optimization are supported. The optimization halts whenever any one of these criteria is satisfied. In some cases, the precise interpretation of the stopping criterion depends on the optimization algorithm above (although NLopt try to make them as consistent as reasonably possible), and some algorithms do not support all of the stopping criteria.
You do not need to use all of the stopping criteria! In most cases, you only need one or two, and can omit the remainder (all criteria are disabled by default).

## ◆ StartOptimization()

 void anima::NLOPTOptimizers::StartOptimization ( )

Starts the optimization.

Date
July 2010
Exceptions
 itk::ExceptionObject Thrown when exception.

Definition at line 134 of file animaNLOPTOptimizers.cxx.

## ◆ StopOptimization()

 void anima::NLOPTOptimizers::StopOptimization ( )
inline

Tells Nlopt to stop the optimization at the next iteration and to returns the best point found so far.

Definition at line 298 of file animaNLOPTOptimizers.h.

The documentation for this class was generated from the following files: