src/math/math_NewtonMinimum.cdl

   1 -- Created on: 1996-02-28
   2 -- Created by: Philippe MANGIN
   3 -- Copyright (c) 1996-1999 Matra Datavision
   4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
   5 --
   6 -- This file is part of Open CASCADE Technology software library.
   7 --
   8 -- This library is free software; you can redistribute it and/or modify it under
   9 -- the terms of the GNU Lesser General Public License version 2.1 as published
  10 -- by the Free Software Foundation, with special exception defined in the file
  11 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  12 -- distribution for complete text of the license and disclaimer of any warranty.
  13 --
  14 -- Alternatively, this file may be used under the terms of Open CASCADE
  15 -- commercial license or contractual agreement.
  16
  17 class NewtonMinimum from math
  18
  19         ---Purpose:
  20
  21 uses Vector from math,
  22      Matrix from math,
  23      Status from math,
  24      MultipleVarFunctionWithHessian from math,
  25      NotDone from StdFail
  26
  27 raises NotDone, DimensionError
  28
  29 is
  30
  31     Create(theFunction: in MultipleVarFunctionWithHessian;
  32            theTolerance: Real=1.0e-7;
  33            theNbIterations: Integer=40;
  34            theConvexity: Real=1.0e-6;
  35            theWithSingularity: Boolean = Standard_True)
  36     ---Purpose:
  37     -- The tolerance required on the solution is given by Tolerance.
  38     -- Iteration are  stopped if (!WithSingularity) and H(F(Xi)) is not definite
  39     -- positive (if the smaller eigenvalue of H < Convexity)
  40     -- or IsConverged() returns True for 2 successives Iterations.
  41     -- Warning: This constructor does not perform computation.
  42     returns  NewtonMinimum;
  43
  44
  45     Perform(me: in out; theFunction: in out MultipleVarFunctionWithHessian;
  46             theStartingPoint: Vector)
  47     ---Purpose: Search the solution.
  48     is static;
  49
  50
  51     Delete(me) is static;
  52     ---Purpose: Destructor alias.
  53     ---C++: inline
  54     ---C++: alias "  Standard_EXPORT virtual ~math_NewtonMinimum();"
  55
  56
  57     IsConverged(me)
  58     ---Purpose:
  59     -- This method is called at the end of each iteration to check the convergence:
  60     -- || Xi+1 - Xi || < Tolerance or || F(Xi+1) - F(Xi)|| < Tolerance * || F(Xi) ||
  61     -- It can be redefined in a sub-class to implement a specific test.
  62     ---C++: inline
  63     returns Boolean is virtual;
  64
  65
  66     IsDone(me)
  67         ---Purpose: Tests if an error has occured.
  68         ---C++: inline
  69
  70     returns Boolean
  71     is static;
  72
  73     IsConvex(me)
  74         ---Purpose: Tests if the Function is convexe during optimization.
  75         ---C++: inline
  76     returns Boolean
  77     is static;
  78
  79     Location(me)
  80         ---Purpose: returns the location vector of the minimum.
  81         -- Exception NotDone is raised if an error has occured.
  82         ---C++: inline
  83         ---C++: return const&
  84
  85     returns Vector
  86     raises NotDone
  87     is static;
  88
  89
  90     Location(me; Loc: out Vector)
  91         ---Purpose: outputs the location vector of the minimum in Loc.
  92         -- Exception NotDone is raised if an error has occured.
  93         -- Exception DimensionError is raised if the range of Loc is not
  94         -- equal to the range of the StartingPoint.
  95         ---C++: inline
  96
  97     raises DimensionError,
  98            NotDone
  99     is static;
 100
 101     SetBoundary(me: in out;
 102                 theLeftBorder : in Vector;
 103                 theRightBorder: in Vector)
 104     ---Purpose: Set boundaries.
 105     is static;
 106
 107     Minimum(me)
 108         ---Purpose: returns the value of the minimum.
 109         -- Exception NotDone is raised if the minimum was not found.
 110         ---C++: inline
 111
 112     returns Real
 113     raises NotDone
 114     is static;
 115
 116
 117     Gradient(me)
 118         ---Purpose: returns the gradient vector at the minimum.
 119         -- Exception NotDone is raised if an error has occured.the minimum was not found.
 120         ---C++: inline
 121         ---C++: return const&
 122
 123     returns Vector
 124     raises NotDone
 125     is static;
 126
 127
 128     Gradient(me; Grad: out Vector)
 129         ---Purpose: outputs the gradient vector at the minimum in Grad.
 130         -- Exception NotDone is raised if the minimum was not found.
 131         -- Exception DimensionError is raised if the range of Grad is not
 132         -- equal to the range of the StartingPoint.
 133         ---C++: inline
 134
 135     raises DimensionError,
 136            NotDone
 137     is static;
 138
 139
 140     NbIterations(me)
 141         ---Purpose: returns the number of iterations really done in the
 142         --          calculation of the minimum.
 143         -- The exception NotDone is raised if an error has occured.
 144         ---C++: inline
 145
 146     returns Integer
 147     raises NotDone
 148     is static;
 149
 150
 151     Dump(me; o: in out OStream)
 152         ---Purpose: Prints on the stream o information on the current state
 153         --          of the object.
 154         --          Is used to redefine the operator <<.
 155
 156     is static;
 157
 158
 159 fields
 160 Done:            Boolean;
 161 TheStatus:       Status  is protected;
 162 TheLocation:     Vector  is protected;
 163 TheGradient:     Vector  is protected;
 164 TheStep:         Vector  is protected;
 165 TheHessian :     Matrix  is protected;
 166 PreviousMinimum: Real    is protected;
 167 TheMinimum:      Real    is protected;
 168 MinEigenValue:   Real    is protected;
 169 XTol:            Real    is protected;
 170 CTol:            Real    is protected;
 171 nbiter:          Integer is protected;
 172 NoConvexTreatement: Boolean is protected;
 173 Convex           : Boolean is protected;
 174 myIsBoundsDefined  : Boolean is protected;
 175 myLeft             : Vector is protected;
 176 myRight            : Vector is protected;
 177 Itermax:         Integer;
 178
 179
 180 end NewtonMinimum;