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://oncora1.lyon.fnclcc.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 ======================================================================-====*/
19 /*=========================================================================
21 Program: Insight Segmentation & Registration Toolkit
22 Module: $RCSfile: clitkLBFGSBOptimizer.h,v $
24 Date: $Date: 2010/06/14 17:32:07 $
25 Version: $Revision: 1.1 $
27 Copyright (c) Insight Software Consortium. All rights reserved.
28 See ITKCopyright.txt or http://www.itk.org/HTML/Copyright.htm for details.
30 This software is distributed WITHOUT ANY WARRANTY; without even
31 the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
32 PURPOSE. See the above copyright notices for more information.
34 =========================================================================*/
35 #ifndef __clitkLBFGSBOptimizer_h
36 #define __clitkLBFGSBOptimizer_h
38 #include "itkSingleValuedNonLinearVnlOptimizer.h"
43 /** \class LBFGSBOptimizerHelper
44 * \brief Wrapper helper around vnl_lbfgsb.
46 * This class is used to translate iteration events, etc, from
47 * vnl_lbfgsb into iteration events in ITK.
49 class ITK_EXPORT LBFGSBOptimizerHelper;
52 /** \class LBFGSBOptimizer
53 * \brief Limited memory Broyden Fletcher Goldfarb Shannon minimization with simple bounds.
55 * This class is a wrapper for converted fortan code for performing limited
56 * memory Broyden Fletcher Goldfarb Shannon minimization with simple bounds.
57 * The algorithm miminizes a nonlinear function f(x) of n variables subject to
58 * simple bound constraints of l <= x <= u.
60 * See also the documentation in Numerics/lbfgsb.c
64 * [1] R. H. Byrd, P. Lu and J. Nocedal.
65 * A Limited Memory Algorithm for Bound Constrained Optimization, (1995),
66 * SIAM Journal on Scientific and Statistical Computing ,
67 * 16, 5, pp. 1190-1208.
69 * [2] C. Zhu, R. H. Byrd and J. Nocedal.
70 * L-BFGS-B: Algorithm 778: L-BFGS-B, FORTRAN routines for large scale
71 * bound constrained optimization (1997),
72 * ACM Transactions on Mathematical Software,
73 * Vol 23, Num. 4, pp. 550 - 560.
75 * \ingroup Numerics Optimizers
77 class ITK_EXPORT LBFGSBOptimizer :
78 public itk::SingleValuedNonLinearVnlOptimizer
81 /** Standard "Self" typedef. */
82 typedef LBFGSBOptimizer Self;
83 typedef itk::SingleValuedNonLinearVnlOptimizer Superclass;
84 typedef itk::SmartPointer<Self> Pointer;
85 typedef itk::SmartPointer<const Self> ConstPointer;
87 /** Method for creation through the object factory. */
90 /** Run-time type information (and related methods). */
91 itkTypeMacro( LBFGSBOptimizer, SingleValuedNonLinearVnlOptimizer );
94 * Use for defining the lower and upper bounds on the variables.
96 typedef itk::Array<double> BoundValueType;
98 /** BoundSelection type
99 * Use for defining the boundary condition for each variables.
101 typedef itk::Array<long> BoundSelectionType;
103 /** Internal boundary value storage type */
104 typedef vnl_vector<double> InternalBoundValueType;
106 /** Internal boundary selection storage type */
107 typedef vnl_vector<long> InternalBoundSelectionType;
109 /** The vnl optimizer */
110 typedef LBFGSBOptimizerHelper InternalOptimizerType;
113 /** Start optimization with an initial value. */
114 void StartOptimization( void );
116 /** Plug in a Cost Function into the optimizer */
117 virtual void SetCostFunction( itk::SingleValuedCostFunction * costFunction );
119 /** Set the lower bound value for each variable. */
120 virtual void SetLowerBound( const BoundValueType & value );
121 virtual const BoundValueType & GetLowerBound();
123 /** Set the upper bound value for each variable. */
124 virtual void SetUpperBound( const BoundValueType & value );
125 virtual const BoundValueType & GetUpperBound();
127 /** Set the boundary condition for each variable, where
128 * select[i] = 0 if x[i] is unbounded,
129 * = 1 if x[i] has only a lower bound,
130 * = 2 if x[i] has both lower and upper bounds, and
131 * = 3 if x[1] has only an upper bound
133 virtual void SetBoundSelection( const BoundSelectionType & select );
134 virtual const BoundSelectionType & GetBoundSelection();
136 /** Set/Get the CostFunctionConvergenceFactor. Algorithm terminates
137 * when the reduction in cost function is less than factor * epsmcj
138 * where epsmch is the machine precision.
139 * Typical values for factor: 1e+12 for low accuracy;
140 * 1e+7 for moderate accuracy and 1e+1 for extremely high accuracy.
142 virtual void SetCostFunctionConvergenceFactor( double );
143 itkGetMacro( CostFunctionConvergenceFactor, double );
145 /** Set/Get the ProjectedGradientTolerance. Algorithm terminates
146 * when the project gradient is below the tolerance. Default value
149 virtual void SetProjectedGradientTolerance( double );
150 itkGetMacro( ProjectedGradientTolerance, double );
152 /** Set/Get the MaximumNumberOfIterations. Default is 500 */
153 virtual void SetMaximumNumberOfIterations( unsigned int );
154 itkGetMacro( MaximumNumberOfIterations, unsigned int );
156 /** Set/Get the MaximumNumberOfEvaluations. Default is 500 */
157 virtual void SetMaximumNumberOfEvaluations( unsigned int );
158 itkGetMacro( MaximumNumberOfEvaluations, unsigned int );
160 /** Set/Get the MaximumNumberOfCorrections. Default is 5 */
161 virtual void SetMaximumNumberOfCorrections( unsigned int );
162 itkGetMacro( MaximumNumberOfCorrections, unsigned int );
164 /** This optimizer does not support scaling of the derivatives. */
165 void SetScales( const ScalesType & ) {
166 itkExceptionMacro( << "This optimizer does not support scales." );
169 /** Get the current iteration number. */
170 itkGetConstReferenceMacro( CurrentIteration, unsigned int );
172 /** Get the current cost function value. */
173 itkGetConstReferenceMacro( Value, MeasureType );
175 /** Get the current infinity norm of the project gradient of the cost
177 itkGetConstReferenceMacro( InfinityNormOfProjectedGradient, double );
181 virtual ~LBFGSBOptimizer();
182 void PrintSelf(std::ostream& os, itk::Indent indent) const;
184 typedef Superclass::CostFunctionAdaptorType CostFunctionAdaptorType;
187 LBFGSBOptimizer(const Self&); //purposely not implemented
188 void operator=(const Self&); //purposely not implemented
190 // give the helper access to member variables, to update iteration
192 friend class LBFGSBOptimizerHelper;
194 bool m_OptimizerInitialized;
195 InternalOptimizerType * m_VnlOptimizer;
197 BoundValueType m_LowerBound;
198 BoundValueType m_UpperBound;
199 BoundSelectionType m_BoundSelection;
201 double m_CostFunctionConvergenceFactor;
202 double m_ProjectedGradientTolerance;
203 unsigned int m_MaximumNumberOfIterations;
204 unsigned int m_MaximumNumberOfEvaluations;
205 unsigned int m_MaximumNumberOfCorrections;
207 unsigned int m_CurrentIteration;
209 double m_InfinityNormOfProjectedGradient;
213 } // end namespace clitk