0025720: Incorrect code of math classes can lead to unpredicted behavior of algorithms
[occt.git] / src / math / math_BrentMinimum.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 BrentMinimum from math
18      ---Purpose:
19      -- This class implements the Brent's method to find the minimum of
20      -- a function of a single variable.
21      -- No knowledge of the derivative is required.
22
23 uses Matrix from math, 
24      Vector from math,
25      Function from math,
26      OStream from Standard
27
28 raises NotDone from StdFail
29
30 is
31
32    Create(TolX: Real; 
33           NbIterations: Integer = 100; 
34           ZEPS: Real = 1.0e-12)
35        ---Purpose:
36        -- This constructor should be used in a sub-class to initialize
37        -- correctly all the fields of this class. 
38    returns BrentMinimum;
39
40
41    Create(TolX: Real; Fbx: Real;
42           NbIterations: Integer = 100; 
43           ZEPS: Real = 1.0e-12)
44        ---Purpose:
45        -- This constructor should be used in a sub-class to initialize
46        -- correctly all the fields of this class. 
47        -- It has to be used if F(Bx) is known.
48    returns BrentMinimum;
49
50
51    Delete(me) is static;
52     ---Purpose: Destructor alias.
53     ---C++: inline
54     ---C++: alias "  Standard_EXPORT virtual ~math_BrentMinimum();"
55
56
57     Perform(me: in out; F: in out Function;
58             Ax, Bx, Cx: Real)
59         ---Purpose:
60         -- Brent minimization is performed on function F from a given
61         -- bracketing triplet of abscissas Ax, Bx, Cx (such that Bx is
62         -- between Ax and Cx, F(Bx) is less than both F(Bx) and F(Cx))
63         -- The solution is found when: abs(Xi - Xi-1) <= TolX * abs(Xi) + ZEPS;
64     is static;
65
66
67     IsSolutionReached(me: in out; theFunction: in out Function)
68         ---Purpose:
69         -- This method is called at the end of each iteration to check if the
70         -- solution is found.
71         -- It can be redefined in a sub-class to implement a specific test to
72         -- stop the iterations.
73     ---C++:inline
74     returns Boolean is virtual;
75
76
77     IsDone(me)
78         ---Purpose: Returns true if the computations are successful, otherwise returns false.
79         ---C++: inline
80
81     returns Boolean
82     is static;
83     
84     
85     Location(me)
86         ---Purpose: returns the location value of the minimum.
87         -- Exception NotDone is raised if the minimum was not found.
88         ---C++: inline
89     returns Real
90     raises NotDone
91     is static;
92     
93     
94     Minimum(me)
95         ---Purpose: returns the value of the minimum.
96         -- Exception NotDone is raised if the minimum was not found.
97         ---C++: inline
98
99     returns Real
100     raises NotDone
101     is static;
102     
103
104     NbIterations(me)
105         ---Purpose: returns the number of iterations really done during the
106         -- computation of the minimum.
107         -- Exception NotDone is raised if the minimum was not found.
108         ---C++: inline
109
110     returns Integer
111     raises NotDone
112     is static;
113
114
115     Dump(me; o: in out OStream)
116         ---Purpose: Prints on the stream o information on the current state 
117         --          of the object.
118         --          Is used to redefine the operator <<.
119
120     is static;
121
122
123 fields
124
125 Done:      Boolean;
126 a:         Real is protected;
127 b:         Real is protected;
128 x:         Real is protected;
129 fx:        Real is protected;
130 fv:        Real is protected;
131 fw:        Real is protected;
132 iter:      Integer;
133 XTol:      Real is protected;
134 EPSZ:      Real is protected;
135 Itermax:   Integer;
136 myF:       Boolean;
137
138 end BrentMinimum;