src/math/math_BFGS.cdl

   1 -- Created on: 1991-05-14
   2 -- Created by: Laurent PAINNOT
   3 -- Copyright (c) 1991-1999 Matra Datavision
   4 -- Copyright (c) 1999-2012 OPEN CASCADE SAS
   5 --
   6 -- The content of this file is subject to the Open CASCADE Technology Public
   7 -- License Version 6.5 (the "License"). You may not use the content of this file
   8 -- except in compliance with the License. Please obtain a copy of the License
   9 -- at http://www.opencascade.org and read it completely before using this file.
  10 --
  11 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
  12 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
  13 --
  14 -- The Original Code and all software distributed under the License is
  15 -- distributed on an "AS IS" basis, without warranty of any kind, and the
  16 -- Initial Developer hereby disclaims all such warranties, including without
  17 -- limitation, any warranties of merchantability, fitness for a particular
  18 -- purpose or non-infringement. Please see the License for the specific terms
  19 -- and conditions governing the rights and limitations under the License.
  20
  21
  22
  23
  24 class BFGS from math
  25         ---Purpose:
  26         -- This class implements the Broyden-Fletcher-Goldfarb-Shanno variant of
  27         -- Davidson-Fletcher-Powell minimization algorithm of a function of
  28         -- multiple variables.Knowledge of the function's gradient is required.
  29
  30 uses Vector from math, Matrix from math,
  31      MultipleVarFunctionWithGradient from math,
  32      Status from math,
  33      OStream from Standard
  34
  35 raises NotDone from StdFail,
  36        DimensionError from Standard
  37
  38 is
  39
  40
  41     Create(F: in out MultipleVarFunctionWithGradient;
  42            StartingPoint: Vector; Tolerance: Real=1.0e-8;
  43            NbIterations: Integer=200; ZEPS: Real=1.0e-12)
  44         ---Purpose:
  45         -- Given the starting point StartingPoint,
  46         -- the Broyden-Fletcher-Goldfarb-Shanno variant of Davidson-Fletcher-Powell
  47         -- minimization is done on the function F.
  48         -- The tolerance required on F is given by Tolerance.
  49         -- The solution F = Fi is found when :
  50         --   2.0 * abs(Fi - Fi-1) <= Tolerance * (abs(Fi) + abs(Fi-1) + ZEPS).
  51         -- The maximum number of iterations allowed is given by NbIterations.
  52
  53     returns BFGS;
  54
  55     Create(F: in out MultipleVarFunctionWithGradient;
  56            Tolerance: Real = 1.0e-8;
  57            NbIterations: Integer = 200;
  58            ZEPS: Real = 1.0e-12)
  59         ---Purpose: Initializes the computation of the minimum of F.
  60         -- Warning
  61         -- A call to the Perform method must be made after this
  62         -- initialization to effectively compute the minimum of the
  63         -- function F.
  64     returns BFGS;
  65
  66
  67     Delete(me:out) is virtual;
  68         ---C++: alias "Standard_EXPORT virtual ~math_BFGS(){Delete() ; }"
  69
  70     Perform(me: in out; F: in out MultipleVarFunctionWithGradient;
  71             StartingPoint: Vector)
  72          ---Purpose: Is used internally by the constructors.
  73
  74     is static;
  75
  76
  77     IsSolutionReached(me; F: in out MultipleVarFunctionWithGradient)
  78         ---Purpose:
  79         -- This method is called at the end of each iteration to check if the
  80         -- solution is found.
  81         -- It can be redefined in a sub-class to implement a specific test to
  82         -- stop the iterations.
  83
  84     returns Boolean
  85     is virtual;
  86
  87
  88     IsDone(me)
  89         ---Purpose: Returns true if the computations are successful, otherwise returns false.
  90         ---C++: inline
  91
  92     returns Boolean
  93     is static;
  94
  95
  96     Location(me)
  97         ---Purpose: returns the location vector of the minimum.
  98         -- Exception NotDone is raised if the minimum was not found.
  99         ---C++: inline
 100         ---C++: return const&
 101     returns Vector
 102     raises NotDone
 103     is static;
 104
 105
 106     Location(me; Loc: out Vector)
 107         ---Purpose: outputs the location vector of the minimum in Loc.
 108         -- Exception NotDone is raised if the minimum was not found.
 109         -- Exception DimensionError is raised if the range of Loc is not
 110         -- equal to the range of the StartingPoint.
 111         ---C++: inline
 112
 113     raises DimensionError,
 114            NotDone
 115     is static;
 116
 117
 118     Minimum(me)
 119         ---Purpose: returns the value of the minimum.
 120         -- Exception NotDone is raised if the minimum was not found.
 121         ---C++: inline
 122
 123     returns Real
 124     raises NotDone
 125     is static;
 126
 127
 128     Gradient(me)
 129         ---Purpose: Returns the gradient vector at the minimum.
 130         -- Exception NotDone is raised if the minimum was not found.
 131         ---C++: inline
 132         ---C++: return const&
 133     returns Vector
 134     raises NotDone
 135     is static;
 136
 137
 138     Gradient(me; Grad: out Vector)
 139         ---Purpose: Returns the value of the gradient vector at the minimum in Grad.
 140         -- Exception NotDone is raised if the minimum was not found.
 141         -- Exception DimensionError is raised if the range of Grad is not
 142         -- equal to the range of the StartingPoint.
 143         ---C++: inline
 144     raises DimensionError,
 145            NotDone
 146     is static;
 147
 148
 149     NbIterations(me)
 150         ---Purpose: Returns the number of iterations really done in the
 151         --          calculation of the minimum.
 152         -- The exception NotDone is raised if the minimum was not found.
 153         ---C++: inline
 154     returns Integer
 155     raises NotDone
 156     is static;
 157
 158
 159     Dump(me; o: in out OStream)
 160         ---Purpose: Prints on the stream o information on the current state
 161         --          of the object.
 162         --          Is used to redefine the operator <<.
 163
 164     is static;
 165
 166
 167 fields
 168
 169 Done:            Boolean;
 170 TheStatus:       Status  is protected;
 171 TheLocation:     Vector  is protected;
 172 TheGradient:     Vector  is protected;
 173 PreviousMinimum: Real    is protected;
 174 TheMinimum:      Real    is protected;
 175 XTol:            Real    is protected;
 176 EPSZ:            Real    is protected;
 177 nbiter:          Integer is protected;
 178 Itermax:         Integer;
 179
 180 end BFGS;