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
 102     Minimum(me)
 103         ---Purpose: returns the value of the minimum.
 104         -- Exception NotDone is raised if the minimum was not found.
 105         ---C++: inline
 106
 107     returns Real
 108     raises NotDone
 109     is static;
 110
 111
 112     Gradient(me)
 113         ---Purpose: returns the gradient vector at the minimum.
 114         -- Exception NotDone is raised if an error has occured.the minimum was not found.
 115         ---C++: inline
 116         ---C++: return const&
 117
 118     returns Vector
 119     raises NotDone
 120     is static;
 121
 122
 123     Gradient(me; Grad: out Vector)
 124         ---Purpose: outputs the gradient vector at the minimum in Grad.
 125         -- Exception NotDone is raised if the minimum was not found.
 126         -- Exception DimensionError is raised if the range of Grad is not
 127         -- equal to the range of the StartingPoint.
 128         ---C++: inline
 129
 130     raises DimensionError,
 131            NotDone
 132     is static;
 133
 134
 135     NbIterations(me)
 136         ---Purpose: returns the number of iterations really done in the
 137         --          calculation of the minimum.
 138         -- The exception NotDone is raised if an error has occured.
 139         ---C++: inline
 140
 141     returns Integer
 142     raises NotDone
 143     is static;
 144
 145
 146     Dump(me; o: in out OStream)
 147         ---Purpose: Prints on the stream o information on the current state
 148         --          of the object.
 149         --          Is used to redefine the operator <<.
 150
 151     is static;
 152
 153
 154 fields
 155 Done:            Boolean;
 156 TheStatus:       Status  is protected;
 157 TheLocation:     Vector  is protected;
 158 TheGradient:     Vector  is protected;
 159 TheStep:         Vector  is protected;
 160 TheHessian :     Matrix  is protected;
 161 PreviousMinimum: Real    is protected;
 162 TheMinimum:      Real    is protected;
 163 MinEigenValue:   Real    is protected;
 164 XTol:            Real    is protected;
 165 CTol:            Real    is protected;
 166 nbiter:          Integer is protected;
 167 NoConvexTreatement: Boolean is protected;
 168 Convex           : Boolean is protected;
 169 Itermax:         Integer;
 170
 171
 172 end NewtonMinimum;