0025720: Incorrect code of math classes can lead to unpredicted behavior of algorithms
[occt.git] / src / math / math_BissecNewton.cdl
1 -- Created on: 1991-03-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 BissecNewton from math
18         ---Purpose:
19         -- This class implements a combination of Newton-Raphson and bissection 
20         --  methods to find the root of the function between two bounds.
21         -- Knowledge of the derivative is required.
22
23 uses Vector from math, 
24      Matrix from math, 
25      FunctionWithDerivative from math,
26      Status from math,
27      OStream from Standard
28
29 raises NotDone from StdFail
30
31 is
32
33     Create(theXTolerance: in Real) returns BissecNewton;
34     ---Purpose: Constructor.
35     -- @param theXTolerance - algorithm tolerance.
36
37     Perform(me: in out; F: out FunctionWithDerivative;
38             Bound1, Bound2: Real;
39             NbIterations: Integer = 100)
40     ---Purpose:
41     -- A combination of Newton-Raphson and bissection methods is done to find
42     -- the root of the function F between the bounds Bound1 and Bound2 
43     -- on the function F.
44     -- The tolerance required on the root is given by TolX.
45     -- The solution is found when:
46     --    abs(Xi - Xi-1) <= TolX and F(Xi) * F(Xi-1) <= 0
47     -- The maximum number of iterations allowed is given by NbIterations.
48     is static;
49
50
51     IsSolutionReached(me: in out; theFunction: out FunctionWithDerivative)
52     ---Purpose:
53     -- This method is called at the end of each iteration to check if the
54     -- solution has been found.
55     -- It can be redefined in a sub-class to implement a specific test to
56     -- stop the iterations.
57     ---C++: inline
58     returns Boolean is virtual;
59
60
61     IsDone(me)
62         ---Purpose: Tests is the root has been successfully found.
63         ---C++: inline
64     returns Boolean
65     is static;
66     
67     
68     Root(me)
69        ---Purpose: returns the value of the root.
70        -- Exception NotDone is raised if the minimum was not found.
71        ---C++: inline
72     returns Real
73     raises NotDone
74     is static;
75
76     Derivative(me)
77         ---Purpose: returns the value of the derivative at the root.
78         -- Exception NotDone is raised if the minimum was not found.
79         ---C++: inline
80
81     returns Real
82     raises NotDone
83     is static;
84     
85
86     Value(me)
87         ---Purpose: returns the value of the function at the root.
88         -- Exception NotDone is raised if the minimum was not found.
89         ---C++: inline
90
91     returns Real
92     raises NotDone
93     is static;
94
95
96     Dump(me; o: in out OStream)
97         ---Purpose: Prints on the stream o information on the current state 
98         --          of the object.
99         --          Is used to redifine the operator <<.
100
101     is static;
102
103
104     Delete(me) is static;
105     ---Purpose: Destructor alias.
106     ---C++: inline
107     ---C++: alias "  Standard_EXPORT virtual ~math_BissecNewton();"
108
109
110 fields
111
112 Done:         Boolean;
113 TheStatus:    Status is protected;
114 XTol:         Real is protected;
115 x:            Real is protected;
116 dx:           Real is protected;
117 f:            Real is protected;
118 df:           Real is protected;
119
120 end BissecNewton;