1 /*=========================================================================
2 Program: vv http://www.creatis.insa-lyon.fr/rio/vv
5 - University of LYON http://www.universite-lyon.fr/
6 - Léon Bérard cancer center http://www.centreleonberard.fr
7 - CREATIS CNRS laboratory http://www.creatis.insa-lyon.fr
9 This software is distributed WITHOUT ANY WARRANTY; without even
10 the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
11 PURPOSE. See the copyright notices for more information.
13 It is distributed under dual licence
15 - BSD See included LICENSE.txt file
16 - CeCILL-B http://www.cecill.info/licences/Licence_CeCILL-B_V1-en.html
17 ===========================================================================**/
18 #ifndef __clitkLBFGSBOptimizer_h
19 #define __clitkLBFGSBOptimizer_h
20 #include "itkSingleValuedNonLinearVnlOptimizer.h"
22 #include "clitkCommon.h"
27 /** \class LBFGSBOptimizerHelper
28 * \brief Wrapper helper around vnl_lbfgsb.
30 * This class is used to translate iteration events, etc, from
31 * vnl_lbfgsb into iteration events in ITK.
33 class ITK_EXPORT LBFGSBOptimizerHelper;
36 /** \class LBFGSBOptimizer
37 * \brief Limited memory Broyden Fletcher Goldfarb Shannon minimization with simple bounds.
39 * This class is a wrapper for converted fortan code for performing limited
40 * memory Broyden Fletcher Goldfarb Shannon minimization with simple bounds.
41 * The algorithm miminizes a nonlinear function f(x) of n variables subject to
42 * simple bound constraints of l <= x <= u.
44 * See also the documentation in Numerics/lbfgsb.c
48 * [1] R. H. Byrd, P. Lu and J. Nocedal.
49 * A Limited Memory Algorithm for Bound Constrained Optimization, (1995),
50 * SIAM Journal on Scientific and Statistical Computing ,
51 * 16, 5, pp. 1190-1208.
53 * [2] C. Zhu, R. H. Byrd and J. Nocedal.
54 * L-BFGS-B: Algorithm 778: L-BFGS-B, FORTRAN routines for large scale
55 * bound constrained optimization (1997),
56 * ACM Transactions on Mathematical Software,
57 * Vol 23, Num. 4, pp. 550 - 560.
59 * \ingroup Numerics Optimizers
61 class ITK_EXPORT LBFGSBOptimizer :
62 public itk::SingleValuedNonLinearVnlOptimizer
65 /** Standard "Self" typedef. */
66 typedef LBFGSBOptimizer Self;
67 typedef itk::SingleValuedNonLinearVnlOptimizer Superclass;
68 typedef itk::SmartPointer<Self> Pointer;
69 typedef itk::SmartPointer<const Self> ConstPointer;
71 /** Method for creation through the object factory. */
74 /** Run-time type information (and related methods). */
75 itkTypeMacro( LBFGSBOptimizer, SingleValuedNonLinearVnlOptimizer );
78 * Use for defining the lower and upper bounds on the variables.
80 typedef itk::Array<double> BoundValueType;
82 /** BoundSelection type
83 * Use for defining the boundary condition for each variables.
85 typedef itk::Array<long> BoundSelectionType;
87 /** Internal boundary value storage type */
88 typedef vnl_vector<double> InternalBoundValueType;
90 /** Internal boundary selection storage type */
91 typedef vnl_vector<long> InternalBoundSelectionType;
93 /** The vnl optimizer */
94 typedef LBFGSBOptimizerHelper InternalOptimizerType;
97 /** Start optimization with an initial value. */
98 virtual void StartOptimization( void ) ITK_OVERRIDE;
100 /** Plug in a Cost Function into the optimizer */
101 virtual void SetCostFunction( itk::SingleValuedCostFunction * costFunction ) ITK_OVERRIDE;
103 /** Set the lower bound value for each variable. */
104 virtual void SetLowerBound( const BoundValueType & value );
105 virtual const BoundValueType & GetLowerBound();
107 /** Set the upper bound value for each variable. */
108 virtual void SetUpperBound( const BoundValueType & value );
109 virtual const BoundValueType & GetUpperBound();
111 /** Set the boundary condition for each variable, where
112 * select[i] = 0 if x[i] is unbounded,
113 * = 1 if x[i] has only a lower bound,
114 * = 2 if x[i] has both lower and upper bounds, and
115 * = 3 if x[1] has only an upper bound
117 virtual void SetBoundSelection( const BoundSelectionType & select );
118 virtual const BoundSelectionType & GetBoundSelection();
120 /** Set/Get the CostFunctionConvergenceFactor. Algorithm terminates
121 * when the reduction in cost function is less than factor * epsmcj
122 * where epsmch is the machine precision.
123 * Typical values for factor: 1e+12 for low accuracy;
124 * 1e+7 for moderate accuracy and 1e+1 for extremely high accuracy.
126 virtual void SetCostFunctionConvergenceFactor( double );
127 itkGetMacro( CostFunctionConvergenceFactor, double );
129 /** Set/Get the ProjectedGradientTolerance. Algorithm terminates
130 * when the project gradient is below the tolerance. Default value
133 virtual void SetProjectedGradientTolerance( double );
134 itkGetMacro( ProjectedGradientTolerance, double );
136 /** Set/Get the MaximumNumberOfIterations. Default is 500 */
137 virtual void SetMaximumNumberOfIterations( unsigned int );
138 itkGetMacro( MaximumNumberOfIterations, unsigned int );
140 /** Set/Get the MaximumNumberOfEvaluations. Default is 500 */
141 virtual void SetMaximumNumberOfEvaluations( unsigned int );
142 itkGetMacro( MaximumNumberOfEvaluations, unsigned int );
144 /** Set/Get the MaximumNumberOfCorrections. Default is 5 */
145 virtual void SetMaximumNumberOfCorrections( unsigned int );
146 itkGetMacro( MaximumNumberOfCorrections, unsigned int );
148 /** This optimizer does not support scaling of the derivatives. */
149 void SetScales( const ScalesType & )
151 itkExceptionMacro( << "This optimizer does not support scales." );
154 /** Get the current iteration number. */
155 itkGetConstReferenceMacro( CurrentIteration, unsigned int );
157 /** Get the current cost function value. */
158 itkGetConstReferenceMacro( Value, MeasureType );
160 /** Get the current infinity norm of the project gradient of the cost
162 itkGetConstReferenceMacro( InfinityNormOfProjectedGradient, double );
164 /** Get the reason for termination */
165 virtual const std::string GetStopConditionDescription() const ITK_OVERRIDE;
169 virtual ~LBFGSBOptimizer();
170 void PrintSelf(std::ostream& os, itk::Indent indent) const ITK_OVERRIDE;
172 typedef Superclass::CostFunctionAdaptorType CostFunctionAdaptorType;
175 LBFGSBOptimizer(const Self&); //purposely not implemented
176 void operator=(const Self&); //purposely not implemented
178 // give the helper access to member variables, to update iteration
180 friend class LBFGSBOptimizerHelper;
182 bool m_OptimizerInitialized;
183 InternalOptimizerType * m_VnlOptimizer;
184 mutable std::ostringstream m_StopConditionDescription;
185 BoundValueType m_LowerBound;
186 BoundValueType m_UpperBound;
187 BoundSelectionType m_BoundSelection;
189 double m_CostFunctionConvergenceFactor;
190 double m_ProjectedGradientTolerance;
191 unsigned int m_MaximumNumberOfIterations;
192 unsigned int m_MaximumNumberOfEvaluations;
193 unsigned int m_MaximumNumberOfCorrections;
195 unsigned int m_CurrentIteration;
197 double m_InfinityNormOfProjectedGradient;
201 } // end namespace clitk