src/math/math_NewtonFunctionSetRoot.cdl

   1 -- Created on: 1991-05-14
   2 -- Created by: Laurent PAINNOT
   3 -- Copyright (c) 1991-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 NewtonFunctionSetRoot from math
  18         ---Purpose:
  19         -- This class computes the root of a set of N functions of N variables,
  20         -- knowing an initial guess at the solution and using the
  21         -- Newton Raphson algorithm. Knowledge of all the partial
  22         -- derivatives (Jacobian) is required.
  23
  24 uses Vector from math, Matrix from math, IntegerVector from math,
  25      FunctionSetWithDerivatives from math,
  26      OStream from Standard
  27
  28 raises NotDone from StdFail,
  29        DimensionError from Standard
  30
  31 is
  32
  33     Create(theFunction: in out FunctionSetWithDerivatives;
  34            theXTolerance: Vector; theFTolerance: Real;
  35            tehNbIterations: Integer = 100)
  36     ---Purpose:
  37     -- Initialize correctly all the fields of this class.
  38     -- The range (1, F.NbVariables()) must be especially respected for
  39     -- all vectors and matrix declarations.
  40    returns NewtonFunctionSetRoot;
  41
  42
  43     Create(theFunction: in out FunctionSetWithDerivatives;
  44            theFTolerance: Real; theNbIterations: Integer = 100)
  45     ---Purpose:
  46     -- This constructor should be used in a sub-class to initialize
  47     -- correctly all the fields of this class.
  48     -- The range (1, F.NbVariables()) must be especially respected for
  49     -- all vectors and matrix declarations.
  50     -- The method SetTolerance must be called before performing the algorithm.
  51    returns NewtonFunctionSetRoot;
  52
  53
  54     Delete(me) is static;
  55     ---Purpose: Destructor alias.
  56     ---C++: alias "  Standard_EXPORT virtual ~math_NewtonFunctionSetRoot();"
  57
  58
  59     SetTolerance(me: in out; XTol: Vector)
  60     ---Purpose: Initializes the tolerance values for the unknowns.
  61     is static;
  62
  63
  64     Perform(me: in out; theFunction: in out FunctionSetWithDerivatives; theStartingPoint: Vector)
  65     ---Purpose:
  66     -- The Newton method is done to improve the root of the function
  67     -- from the initial guess point. The solution is found when:
  68     -- abs(Xj - Xj-1)(i) <= XTol(i) and abs(Fi) <= FTol for all i;
  69     is static;
  70
  71
  72     Perform(me: in out; theFunction: in out FunctionSetWithDerivatives;
  73             theStartingPoint: Vector; theInfBound, theSupBound: Vector)
  74     ---Purpose:
  75     -- The Newton method is done to improve the root of the function
  76     -- from the initial guess point. Bounds may be given, to constrain the solution.
  77     -- The solution is found when:
  78     -- abs(Xj - Xj-1)(i) <= XTol(i) and abs(Fi) <= FTol for all i;
  79     is static;
  80
  81
  82     IsSolutionReached(me: in out; F: in out FunctionSetWithDerivatives)
  83     ---Purpose:
  84     -- This method is called at the end of each iteration to check if the
  85     -- solution is found.
  86     -- Vectors DeltaX, Fvalues and Jacobian Matrix are consistent with the
  87     -- possible solution Vector Sol and can be inspected to decide whether
  88     -- the solution is reached or not.
  89     ---C++: inline
  90     returns Boolean is virtual;
  91
  92
  93     IsDone(me)
  94         ---Purpose: Returns true if the computations are successful, otherwise returns false.
  95         ---C++: inline
  96     returns Boolean
  97     is static;
  98
  99
 100     Root(me)
 101         ---Purpose: Returns the value of the root of function F.
 102         -- Exceptions
 103         -- StdFail_NotDone if the algorithm fails (and IsDone returns false).
 104         ---C++: inline
 105         ---C++: return const&
 106     returns Vector
 107     raises NotDone
 108     is static;
 109
 110
 111     Root(me; Root: out Vector)
 112        ---Purpose: outputs the root vector in Root.
 113        -- Exception NotDone is raised if the root was not found.
 114        -- Exception DimensionError is raised if the range of Root is
 115        -- not equal to the range of the StartingPoint.
 116         ---C++: inline
 117
 118     raises NotDone,
 119            DimensionError
 120     is static;
 121
 122
 123     StateNumber(me)
 124         ---Purpose: Outputs the state number associated with the solution
 125         --          vector root.
 126         ---C++: inline
 127     returns Integer
 128     raises NotDone
 129     is static;
 130
 131
 132     Derivative(me)
 133         ---Purpose: Returns the matrix value of the derivative at the root.
 134         -- Exception NotDone is raised if the root was not found.
 135         ---C++: inline
 136         ---C++: return const&
 137     returns Matrix
 138     raises NotDone
 139     is static;
 140
 141
 142     Derivative(me; Der: out Matrix)
 143         ---Purpose: Outputs the matrix value of the derivative at the root in
 144         -- Der.
 145         -- Exception NotDone is raised if the root was not found.
 146         -- Exception DimensionError is raised if the range of Der is
 147         -- not equal to the range of the StartingPoint.
 148         ---C++: inline
 149     raises NotDone,
 150            DimensionError
 151     is static;
 152
 153
 154     FunctionSetErrors(me)
 155         ---Purpose: Returns the vector value of the error done on the
 156         -- functions at the root.
 157         -- Exception NotDone is raised if the root was not found.
 158         ---C++: inline
 159         ---C++: return const&
 160     returns Vector
 161     raises NotDone
 162     is static;
 163
 164
 165     FunctionSetErrors(me; Err: out Vector)
 166         ---Purpose: Outputs the vector value of the error done on the
 167         -- functions at the root in Err.
 168         -- Exception NotDone is raised if the root was not found.
 169         -- Exception DimensionError is raised if the range of Err is
 170         -- not equal to the range of the StartingPoint.
 171         ---C++: inline
 172     raises NotDone,
 173            DimensionError
 174     is static;
 175
 176
 177     NbIterations(me)
 178         ---Purpose: Returns the number of iterations really done
 179         -- during the computation of the Root.
 180         -- Exception NotDone is raised if the root was not found.
 181         ---C++: inline
 182     returns Integer
 183     raises NotDone
 184     is static;
 185
 186
 187     Dump(me; o: in out OStream)
 188         ---Purpose: Prints information on the current state of the object.
 189         --          Is used to redefine the operator <<.
 190
 191     is static;
 192
 193
 194 fields
 195
 196 Done:       Boolean;
 197 State:      Integer;
 198 TolX:       Vector is protected;
 199 TolF:       Real is protected;
 200 Iter:       Integer;
 201 Indx:       IntegerVector is protected;
 202 Scratch:    Vector is protected;
 203 Sol:        Vector is protected;
 204 DeltaX:     Vector is protected;
 205 FValues:    Vector is protected;
 206 Jacobian:   Matrix is protected;
 207 Itermax:    Integer;
 208
 209 end NewtonFunctionSetRoot;