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(F: in out FunctionSetWithDerivatives;
  34            XTol: Vector; FTol: Real;
  35            NbIterations: Integer = 100)
  36         ---Purpose:
  37         -- This constructor should be used in a sub-class to initialize
  38         -- correctly all the fields of this class.
  39         -- The range (1, F.NbVariables()) must be especially respected for
  40         -- all vectors and matrix declarations.
  41
  42    returns NewtonFunctionSetRoot;
  43
  44
  45     Create(F: in out FunctionSetWithDerivatives;
  46            FTol: Real; NbIterations: Integer = 100)
  47         ---Purpose:
  48         -- This constructor should be used in a sub-class to initialize
  49         -- correctly all the fields of this class.
  50         -- The range (1, F.NbVariables()) must be especially respected for
  51         -- all vectors and matrix declarations.
  52         -- The method SetTolerance must be called before performing the
  53         -- algorithm.
  54
  55    returns NewtonFunctionSetRoot;
  56
  57
  58
  59    Create(F: in out FunctionSetWithDerivatives;
  60           StartingPoint: Vector;
  61           XTol: Vector; FTol: Real;
  62           NbIterations: Integer = 100)
  63         ---Purpose:
  64         -- The Newton method is done to improve the root of the function F
  65         -- from the initial guess StartingPoint.
  66         -- The tolerance required on the root is given by Tolerance.
  67         -- The solution is found when :
  68         --    abs(Xj - Xj-1)(i) <= XTol(i) and abs(Fi) <= FTol for all i;
  69         -- The maximum number of iterations allowed is given by NbIterations.
  70
  71     returns NewtonFunctionSetRoot;
  72
  73
  74
  75    Create(F: in out FunctionSetWithDerivatives;
  76           StartingPoint: Vector;
  77           InfBound, SupBound: Vector;
  78           XTol: Vector; FTol: Real;
  79           NbIterations: Integer = 100)
  80         ---Purpose:
  81         -- The Newton method is done to improve the root of the function F
  82         -- from the initial guess StartingPoint.
  83         -- The tolerance required on the root is given by Tolerance.
  84         -- The solution is found when :
  85         --    abs(Xj - Xj-1)(i) <= XTol(i) and abs(Fi) <= FTol for all i;
  86         -- The maximum number of iterations allowed is given by NbIterations.
  87
  88     returns NewtonFunctionSetRoot;
  89
  90
  91     Delete(me:out) is virtual;
  92         ---C++: alias "Standard_EXPORT virtual ~math_NewtonFunctionSetRoot(){Delete();}"
  93
  94     SetTolerance(me: in out; XTol: Vector)
  95         ---Purpose: Initializes the tolerance values for the unknowns.
  96
  97     is static;
  98
  99
 100     Perform(me: in out; F:in  out FunctionSetWithDerivatives;
 101             StartingPoint: Vector;
 102             InfBound, SupBound: Vector)
 103         ---Purpose: Improves the root of function F from the initial guess
 104         -- StartingPoint. infBound and supBound may be given, to constrain the solution.
 105         -- Warning
 106         -- This method must be called when the solution is not computed by the constructors.
 107
 108     is static;
 109
 110
 111
 112     IsSolutionReached(me: in out; F: in out FunctionSetWithDerivatives)
 113         ---Purpose:
 114         -- This method is called at the end of each iteration to check if the
 115         -- solution is found.
 116         -- Vectors DeltaX, Fvalues and Jacobian Matrix are consistent with the
 117         -- possible solution Vector Sol and can be inspected to decide whether
 118         -- the solution is reached or not.
 119
 120     returns Boolean
 121     is virtual;
 122
 123
 124     IsDone(me)
 125         ---Purpose: Returns true if the computations are successful, otherwise returns false.
 126         ---C++: inline
 127     returns Boolean
 128     is static;
 129
 130
 131     Root(me)
 132         ---Purpose: Returns the value of the root of function F.
 133         -- Exceptions
 134         -- StdFail_NotDone if the algorithm fails (and IsDone returns false).
 135         ---C++: inline
 136         ---C++: return const&
 137     returns Vector
 138     raises NotDone
 139     is static;
 140
 141
 142     Root(me; Root: out Vector)
 143        ---Purpose: outputs the root vector in Root.
 144        -- Exception NotDone is raised if the root was not found.
 145        -- Exception DimensionError is raised if the range of Root is
 146        -- not equal to the range of the StartingPoint.
 147         ---C++: inline
 148
 149     raises NotDone,
 150            DimensionError
 151     is static;
 152
 153
 154     StateNumber(me)
 155         ---Purpose: Outputs the state number associated with the solution
 156         --          vector root.
 157         ---C++: inline
 158     returns Integer
 159     raises NotDone
 160     is static;
 161
 162
 163     Derivative(me)
 164         ---Purpose: Returns the matrix value of the derivative at the root.
 165         -- Exception NotDone is raised if the root was not found.
 166         ---C++: inline
 167         ---C++: return const&
 168     returns Matrix
 169     raises NotDone
 170     is static;
 171
 172
 173     Derivative(me; Der: out Matrix)
 174         ---Purpose: Outputs the matrix value of the derivative at the root in
 175         -- Der.
 176         -- Exception NotDone is raised if the root was not found.
 177         -- Exception DimensionError is raised if the range of Der is
 178         -- not equal to the range of the StartingPoint.
 179         ---C++: inline
 180     raises NotDone,
 181            DimensionError
 182     is static;
 183
 184
 185     FunctionSetErrors(me)
 186         ---Purpose: Returns the vector value of the error done on the
 187         -- functions at the root.
 188         -- Exception NotDone is raised if the root was not found.
 189         ---C++: inline
 190         ---C++: return const&
 191     returns Vector
 192     raises NotDone
 193     is static;
 194
 195
 196     FunctionSetErrors(me; Err: out Vector)
 197         ---Purpose: Outputs the vector value of the error done on the
 198         -- functions at the root in Err.
 199         -- Exception NotDone is raised if the root was not found.
 200         -- Exception DimensionError is raised if the range of Err is
 201         -- not equal to the range of the StartingPoint.
 202         ---C++: inline
 203     raises NotDone,
 204            DimensionError
 205     is static;
 206
 207
 208     NbIterations(me)
 209         ---Purpose: Returns the number of iterations really done
 210         -- during the computation of the Root.
 211         -- Exception NotDone is raised if the root was not found.
 212         ---C++: inline
 213     returns Integer
 214     raises NotDone
 215     is static;
 216
 217
 218     Dump(me; o: in out OStream)
 219         ---Purpose: Prints information on the current state of the object.
 220         --          Is used to redefine the operator <<.
 221
 222     is static;
 223
 224
 225 fields
 226
 227 Done:       Boolean;
 228 State:      Integer;
 229 TolX:       Vector is protected;
 230 TolF:       Real is protected;
 231 Iter:       Integer;
 232 Indx:       IntegerVector is protected;
 233 Scratch:    Vector is protected;
 234 Sol:        Vector is protected;
 235 DeltaX:     Vector is protected;
 236 FValues:    Vector is protected;
 237 Jacobian:   Matrix is protected;
 238 Itermax:    Integer;
 239
 240 end NewtonFunctionSetRoot;