0024044: Performance improvements: Foundation Classes (math)

[occt.git] / src / math / math_BrentMinimum.cdl

-- Created on: 1991-05-14
-- Created by: Laurent PAINNOT
-- Copyright (c) 1991-1999 Matra Datavision
-- Copyright (c) 1999-2012 OPEN CASCADE SAS
--
-- The content of this file is subject to the Open CASCADE Technology Public
-- License Version 6.5 (the "License"). You may not use the content of this file
-- except in compliance with the License. Please obtain a copy of the License
-- at http://www.opencascade.org and read it completely before using this file.
--
-- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
-- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
--
-- The Original Code and all software distributed under the License is
-- distributed on an "AS IS" basis, without warranty of any kind, and the
-- Initial Developer hereby disclaims all such warranties, including without
-- limitation, any warranties of merchantability, fitness for a particular
-- purpose or non-infringement. Please see the License for the specific terms
-- and conditions governing the rights and limitations under the License.



class BrentMinimum from math
     ---Purpose:
     -- This class implements the Brent's method to find the minimum of
     -- a function of a single variable.
     -- No knowledge of the derivative is required.

uses Matrix from math, 
     Vector from math,
     Function from math,
     OStream from Standard

raises NotDone from StdFail

is

   Create(TolX: Real; 
          NbIterations: Integer = 100; 
          ZEPS: Real = 1.0e-12)
    	---Purpose:
    	-- This constructor should be used in a sub-class to initialize
    	-- correctly all the fields of this class. 
    
   returns BrentMinimum;


   Create(TolX: Real; Fbx: Real;
          NbIterations: Integer = 100; 
          ZEPS: Real = 1.0e-12)
    	---Purpose:
    	-- This constructor should be used in a sub-class to initialize
    	-- correctly all the fields of this class. 
    	-- It has to be used if F(Bx) is known.
    
   returns BrentMinimum;



    Create(F: in out Function; Ax, Bx, Cx, TolX: Real;
      	   NbIterations: Integer = 100; ZEPS: Real=1.0e-12)
    	---Purpose:
    	-- Given a bracketing triplet of abscissae Ax, Bx, Cx 
    	-- (such as Bx is between Ax and Cx, F(Bx) is 
    	-- less than both F(Bx) and F(Cx)) the Brent minimization is done 
    	-- on the function F.
    	-- The tolerance required on F is given by Tolerance.
    	-- The solution is found when :
    	--    abs(Xi - Xi-1) <= TolX * abs(Xi) + ZEPS;
   	-- The maximum number of iterations allowed is given by NbIterations.
    
    returns BrentMinimum;
    
    
    Perform(me: in out; F: in out Function; 
            Ax, Bx, Cx: Real)
    	---Purpose: 
    	-- Brent minimization is performed on function F from a given
    	-- bracketing triplet of abscissas Ax, Bx, Cx (such that Bx is
    	-- between Ax and Cx, F(Bx) is less than both F(Bx) and F(Cx))
    	-- Warning
    	-- The initialization constructors must have been called
    	-- before the call to the Perform method.

    is static;


    IsSolutionReached(me: in out; F: in out Function)
	---Purpose:    	
    	-- This method is called at the end of each iteration to check if the
    	-- solution is found.
    	-- It can be redefined in a sub-class to implement a specific test to
    	-- stop the iterations.
    
    returns Boolean
    is virtual;
    
    
    IsDone(me)
    	---Purpose: Returns true if the computations are successful, otherwise returns false.
    	---C++: inline

    returns Boolean
    is static;
    
    
    Location(me)
        ---Purpose: returns the location value of the minimum.
        -- Exception NotDone is raised if the minimum was not found.
    	---C++: inline
    returns Real
    raises NotDone
    is static;
    
    
    Minimum(me)
    	---Purpose: returns the value of the minimum.
        -- Exception NotDone is raised if the minimum was not found.
        ---C++: inline

    returns Real
    raises NotDone
    is static;
    

    NbIterations(me)
    	---Purpose: returns the number of iterations really done during the
        -- computation of the minimum.
        -- Exception NotDone is raised if the minimum was not found.
    	---C++: inline

    returns Integer
    raises NotDone
    is static;


    Dump(me; o: in out OStream)
	---Purpose: Prints on the stream o information on the current state 
    	--          of the object.
    	--          Is used to redefine the operator <<.

    is static;



fields

Done:      Boolean;
a:         Real is protected;
b:         Real is protected;
x:         Real is protected;
fx:        Real is protected;
fv:        Real is protected;
fw:        Real is protected;
iter:      Integer;
XTol:      Real is protected;
EPSZ:      Real is protected;
Itermax:   Integer;
myF:       Boolean;

end BrentMinimum;