0027067: Avoid use of virtual methods for implementation of destructors in legacy...
[occt.git] / src / math / math_FunctionSetRoot.hxx
CommitLineData
42cf5bc1 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#ifndef _math_FunctionSetRoot_HeaderFile
18#define _math_FunctionSetRoot_HeaderFile
19
20#include <Standard.hxx>
21#include <Standard_DefineAlloc.hxx>
22#include <Standard_Handle.hxx>
23
24#include <Standard_Boolean.hxx>
25#include <math_Vector.hxx>
26#include <math_Matrix.hxx>
27#include <Standard_Integer.hxx>
28#include <math_IntegerVector.hxx>
29#include <Standard_OStream.hxx>
30class StdFail_NotDone;
31class Standard_DimensionError;
32class math_FunctionSetWithDerivatives;
33class math_Matrix;
34
35
36//! The math_FunctionSetRoot class calculates the root
37//! of a set of N functions of M variables (N<M, N=M or N>M). Knowing
38//! an initial guess of the solution and using a minimization algorithm, a search
39//! is made in the Newton direction and then in the Gradient direction if there
40//! is no success in the Newton direction. This algorithm can also be
41//! used for functions minimization. Knowledge of all the partial
42//! derivatives (the Jacobian) is required.
43class math_FunctionSetRoot
44{
45public:
46
47 DEFINE_STANDARD_ALLOC
48
49
50 //! is used in a sub-class to initialize correctly all the fields
51 //! of this class.
52 //! The range (1, F.NbVariables()) must be especially
53 //! respected for all vectors and matrix declarations.
54 Standard_EXPORT math_FunctionSetRoot(math_FunctionSetWithDerivatives& F, const math_Vector& Tolerance, const Standard_Integer NbIterations = 100);
55
56 //! is used in a sub-class to initialize correctly all the fields
57 //! of this class.
58 //! The range (1, F.NbVariables()) must be especially
59 //! respected for all vectors and matrix declarations.
60 //! The method SetTolerance must be called after this
61 //! constructor.
62 Standard_EXPORT math_FunctionSetRoot(math_FunctionSetWithDerivatives& F, const Standard_Integer NbIterations = 100);
63
e6f550da 64 //! Destructor
42cf5bc1 65 Standard_EXPORT virtual ~math_FunctionSetRoot();
66
67 //! Initializes the tolerance values.
68 Standard_EXPORT void SetTolerance (const math_Vector& Tolerance);
69
70 //! This routine is called at the end of each iteration
71 //! to check if the solution was found. It can be redefined
72 //! in a sub-class to implement a specific test to stop the iterations.
73 //! In this case, the solution is found when: abs(Xi - Xi-1) <= Tolerance
74 //! for all unknowns.
75 virtual Standard_Boolean IsSolutionReached (math_FunctionSetWithDerivatives& F);
76
77
78 //! Improves the root of function from the initial guess point.
79 //! The infinum and supremum may be given to constrain the solution.
80 //! In this case, the solution is found when: abs(Xi - Xi-1)(j) <= Tolerance(j)
81 //! for all unknowns.
82 Standard_EXPORT void Perform (math_FunctionSetWithDerivatives& theFunction, const math_Vector& theStartingPoint, const Standard_Boolean theStopOnDivergent = Standard_False);
83
84
85 //! Improves the root of function from the initial guess point.
86 //! The infinum and supremum may be given to constrain the solution.
87 //! In this case, the solution is found when: abs(Xi - Xi-1) <= Tolerance
88 //! for all unknowns.
89 Standard_EXPORT void Perform (math_FunctionSetWithDerivatives& theFunction, const math_Vector& theStartingPoint, const math_Vector& theInfBound, const math_Vector& theSupBound, const Standard_Boolean theStopOnDivergent = Standard_False);
90
91
92 //! Returns true if the computations are successful, otherwise returns false.
93 Standard_Boolean IsDone() const;
94
95 //! Returns the number of iterations really done
96 //! during the computation of the root.
97 //! Exception NotDone is raised if the root was not found.
98 Standard_Integer NbIterations() const;
99
100 //! returns the stateNumber (as returned by
101 //! F.GetStateNumber()) associated to the root found.
102 Standard_Integer StateNumber() const;
103
104 //! Returns the value of the root of function F.
105 //! Exception NotDone is raised if the root was not found.
106 const math_Vector& Root() const;
107
108 //! Outputs the root vector in Root.
109 //! Exception NotDone is raised if the root was not found.
110 //! Exception DimensionError is raised if the range of Root
111 //! is not equal to the range of the StartingPoint.
112 Standard_EXPORT void Root (math_Vector& Root) const;
113
114 //! Returns the matrix value of the derivative at the root.
115 //! Exception NotDone is raised if the root was not found.
116 const math_Matrix& Derivative() const;
117
118 //! outputs the matrix value of the derivative
119 //! at the root in Der.
120 //! Exception NotDone is raised if the root was not found.
121 //! Exception DimensionError is raised if the column range
122 //! of <Der> is not equal to the range of the startingPoint.
123 void Derivative (math_Matrix& Der) const;
124
125 //! returns the vector value of the error done
126 //! on the functions at the root.
127 //! Exception NotDone is raised if the root was not found.
128 const math_Vector& FunctionSetErrors() const;
129
130 //! outputs the vector value of the error done
131 //! on the functions at the root in Err.
132 //! Exception NotDone is raised if the root was not found.
133 //! Exception DimensionError is raised if the range of Err
134 //! is not equal to the range of the StartingPoint.
135 Standard_EXPORT void FunctionSetErrors (math_Vector& Err) const;
136
137 //! Prints on the stream o information on the current state
138 //! of the object.
139 //! Is used to redefine the operator <<.
140 Standard_EXPORT void Dump (Standard_OStream& o) const;
141
142 Standard_EXPORT Standard_Boolean IsDivergent() const;
143
144
145
146
147protected:
148
149
150
151 math_Vector Delta;
152 math_Vector Sol;
153 math_Matrix DF;
154 math_Vector Tol;
155
156
157private:
158
159
160
161 Standard_Boolean Done;
162 Standard_Integer Kount;
163 Standard_Integer State;
164 Standard_Integer Itermax;
165 math_Vector InfBound;
166 math_Vector SupBound;
167 math_Vector SolSave;
168 math_Vector GH;
169 math_Vector DH;
170 math_Vector DHSave;
171 math_Vector FF;
172 math_Vector PreviousSolution;
173 math_Vector Save;
174 math_IntegerVector Constraints;
175 math_Vector Temp1;
176 math_Vector Temp2;
177 math_Vector Temp3;
178 math_Vector Temp4;
179 Standard_Boolean myIsDivergent;
180
181
182};
183
184
185#include <math_FunctionSetRoot.lxx>
186
187
188
189
190
191#endif // _math_FunctionSetRoot_HeaderFile