0023830: BRepExtrema_DistShapeShape does not find intersection of face with edge
[occt.git] / src / math / math_FunctionSetRoot.cdl
CommitLineData
b311480e 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
7fd59977 21
22
23
24class FunctionSetRoot from math
25 ---Purpose: The math_FunctionSetRoot class calculates the root
26 -- of a set of N functions of M variables (N<M, N=M or N>M). Knowing
27 -- an initial guess of the solution and using a minimization algorithm, a search
28 -- is made in the Newton direction and then in the Gradient direction if there
29 -- is no success in the Newton direction. This algorithm can also be
30 -- used for functions minimization. Knowledge of all the partial
31 -- derivatives (the Jacobian) is required.
32
33
34uses Vector from math,
35 Matrix from math,
36 IntegerVector from math,
37 FunctionSetWithDerivatives from math,
38 OStream from Standard
39
40raises NotDone from StdFail,
41 DimensionError from Standard
42
43is
44
45 Create(F: in out FunctionSetWithDerivatives;
46 Tolerance : Vector;
47 NbIterations: Integer = 100)
48 ---Purpose: is used in a sub-class to initialize correctly all the fields
49 -- of this class.
50 -- The range (1, F.NbVariables()) must be especially
51 -- respected for all vectors and matrix declarations.
52
53 returns FunctionSetRoot from math;
54
55
56
57 Create(F: in out FunctionSetWithDerivatives;
58 NbIterations: Integer = 100)
59 ---Purpose: is used in a sub-class to initialize correctly all the fields
60 -- of this class.
61 -- The range (1, F.NbVariables()) must be especially
62 -- respected for all vectors and matrix declarations.
63 -- The method SetTolerance must be called after this
64 -- constructor.
65
66 returns FunctionSetRoot from math;
67
68
69
70 Create(F: in out FunctionSetWithDerivatives; StartingPoint: Vector;
71 Tolerance: Vector; NbIterations: Integer = 100)
72 ---Purpose: is used to improve the root of the function F
73 -- from the initial guess StartingPoint.
74 -- The maximum number of iterations allowed is given by
75 -- NbIterations.
76 -- In this case, the solution is found when:
77 -- abs(Xi - Xi-1)(j) <= Tolerance(j) for all unknowns.
78
79 returns FunctionSetRoot from math;
80
81
82
83 Create(F: in out FunctionSetWithDerivatives; StartingPoint: Vector;
84 Tolerance: Vector; infBound, supBound: Vector;
b659a6dc 85 NbIterations: Integer = 100; theStopOnDivergent : Boolean from Standard = Standard_False)
7fd59977 86 ---Purpose: is used to improve the root of the function F
87 -- from the initial guess StartingPoint.
88 -- The maximum number of iterations allowed is given
89 -- by NbIterations.
90 -- In this case, the solution is found when:
91 -- abs(Xi - Xi-1) <= Tolerance for all unknowns.
92
93 returns FunctionSetRoot from math;
94
95
96
97 Delete(me:out) is virtual;
98 ---C++: alias "Standard_EXPORT virtual ~math_FunctionSetRoot(){Delete();}"
99
100 SetTolerance(me: in out; Tolerance: Vector)
101 ---Purpose: Initializes the tolerance values.
102
103 is static;
104
105
106
107 Perform(me: in out; F: in out FunctionSetWithDerivatives;
b659a6dc 108 StartingPoint: Vector;
109 infBound, supBound: Vector; theStopOnDivergent : Boolean from Standard = Standard_False)
7fd59977 110 ---Purpose: Improves the root of function F from the initial guess
111 -- StartingPoint. infBound and supBound may be given to constrain the solution.
112 -- Warning
113 -- This method is called when computation of the solution is
114 -- not performed by the constructors.
115
116 is static;
117
118
119 IsSolutionReached(me: in out; F: in out FunctionSetWithDerivatives)
120 ---Purpose: This routine is called at the end of each iteration
121 -- to check if the solution was found. It can be redefined
122 -- in a sub-class to implement a specific test to stop the
123 -- iterations.
124 -- In this case, the solution is found when:
125 -- abs(Xi - Xi-1) <= Tolerance for all unknowns.
126
127 returns Boolean is virtual;
128
129
130 IsDone(me)
131 ---Purpose:
132 -- Returns true if the computations are successful, otherwise returns false.
133 ---C++: inline
134 returns Boolean
135 is static;
136
137
138 NbIterations(me)
139 ---Purpose: Returns the number of iterations really done
140 -- during the computation of the root.
141 -- Exception NotDone is raised if the root was not found.
142 ---C++: inline
143 returns Integer
144 raises NotDone
145 is static;
146
147
148 StateNumber(me)
149 ---Purpose: returns the stateNumber (as returned by
150 -- F.GetStateNumber()) associated to the root found.
151 ---C++: inline
152 returns Integer
153 raises NotDone
154 is static;
155
156
157 Root(me)
158 ---Purpose: Returns the value of the root of function F.
159 -- Exception NotDone is raised if the root was not found.
160 ---C++: inline
161 ---C++: return const&
162 returns Vector
163 raises NotDone,
164 DimensionError
165 is static;
166
167
168 Root(me; Root: out Vector)
169 ---Purpose: Outputs the root vector in Root.
170 -- Exception NotDone is raised if the root was not found.
171 -- Exception DimensionError is raised if the range of Root
172 -- is not equal to the range of the StartingPoint.
173
174 raises NotDone from StdFail
175 is static;
176
177
178 Derivative(me)
179 ---Purpose: Returns the matrix value of the derivative at the root.
180 -- Exception NotDone is raised if the root was not found.
181 ---C++: inline
182 ---C++: return const&
183
184 returns Matrix
185 raises NotDone
186 is static;
187
188
189 Derivative(me; Der: out Matrix)
190 ---Purpose: outputs the matrix value of the derivative
191 -- at the root in Der.
192 -- Exception NotDone is raised if the root was not found.
193 -- Exception DimensionError is raised if the column range
194 -- of <Der> is not equal to the range of the startingPoint.
195 ---C++: inline
196
197 raises NotDone,
198 DimensionError
199 is static;
200
201
202
203 FunctionSetErrors(me)
204 ---Purpose: returns the vector value of the error done
205 -- on the functions at the root.
206 -- Exception NotDone is raised if the root was not found.
207 ---C++: inline
208 ---C++: return const&
209
210 returns Vector
211 raises NotDone
212 is static;
213
214
215 FunctionSetErrors(me; Err: out Vector)
216 ---Purpose: outputs the vector value of the error done
217 -- on the functions at the root in Err.
218 -- Exception NotDone is raised if the root was not found.
219 -- Exception DimensionError is raised if the range of Err
220 -- is not equal to the range of the StartingPoint.
221
222 raises NotDone,
223 DimensionError
224 is static;
225
226
227 Dump(me; o: in out OStream)
228 ---Purpose: Prints on the stream o information on the current state
229 -- of the object.
230 -- Is used to redefine the operator <<.
231
232 is static;
233
b659a6dc 234 IsDivergent(me)
235 returns Boolean
236 is static;
237
7fd59977 238
239fields
240
241Done : Boolean;
242Delta : Vector is protected;
243Sol : Vector is protected;
244DF : Matrix is protected;
245Kount : Integer;
246State : Integer;
247Tol : Vector is protected;
248Itermax : Integer;
249
250-- working tables
251
252InfBound : Vector;
253SupBound : Vector;
254
255SolSave : Vector;
256GH : Vector;
257DH : Vector;
258DHSave : Vector;
259FF : Vector;
260PreviousSolution : Vector;
261Save : Vector;
262Constraints : IntegerVector;
263Temp1 : Vector;
264Temp2 : Vector;
265Temp3 : Vector;
266Temp4 : Vector;
b659a6dc 267myIsDivergent : Boolean from Standard;
7fd59977 268
269end FunctionSetRoot;