occt/src/math/math_NewtonMinimum.cdl

-- Created on: 1996-02-28
-- Created by: Philippe MANGIN
-- Copyright (c) 1996-1999 Matra Datavision
-- Copyright (c) 1999-2014 OPEN CASCADE SAS
--
-- This file is part of Open CASCADE Technology software library.
--
-- This library is free software; you can redistribute it and/or modify it under
-- the terms of the GNU Lesser General Public License version 2.1 as published
-- by the Free Software Foundation, with special exception defined in the file
-- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
-- distribution for complete text of the license and disclaimer of any warranty.
--
-- Alternatively, this file may be used under the terms of Open CASCADE
-- commercial license or contractual agreement.

class NewtonMinimum from math 

	---Purpose: 

uses Vector from math,
     Matrix from math,
     Status from math,
     MultipleVarFunctionWithHessian from math,
     NotDone from StdFail

raises NotDone, DimensionError

is
 
    Create(F: in out MultipleVarFunctionWithHessian;
    	   StartingPoint: Vector; 
           Tolerance: Real=1.0e-7;
	   NbIterations: Integer=40; 
           Convexity: Real=1.0e-6; 
           WithSingularity  :  Boolean = Standard_True)
    ---Purpose: -- Given the  starting   point  StartingPoint,
    --            The tolerance  required on  the  solution is given  by
    --            Tolerance.  
    --             Iteration are  stopped if  
    --             (!WithSingularity)  and H(F(Xi)) is not definite
    --             positive  (if the smaller eigenvalue of H < Convexity)
    --            or IsConverged() returns True for 2 successives Iterations.
    --  Warning: Obsolete Constructor (because IsConverged can not be redefined
    --           with this. )
    returns  NewtonMinimum;

    Create(F: in out MultipleVarFunctionWithHessian;
           Tolerance: Real=1.0e-7;
	   NbIterations: Integer=40; 
           Convexity: Real=1.0e-6; 
           WithSingularity  :  Boolean = Standard_True)
    ---Purpose:
    --            The tolerance  required on  the  solution is given  by
    --            Tolerance.  
    --             Iteration are  stopped if  
    --             (!WithSingularity)  and H(F(Xi)) is not definite
    --             positive  (if the smaller eigenvalue of H < Convexity)
    --            or IsConverged() returns True for 2 successives Iterations.
    --  Warning: This constructor do not computation 
    returns  NewtonMinimum;
    
    ---C++: alias "  Standard_EXPORT virtual ~math_NewtonMinimum();"
    
    Perform(me: in out; F: in out MultipleVarFunctionWithHessian;
    	    StartingPoint: Vector)
	 ---Purpose: Search the solution.
    is static;

    
    IsConverged(me)
    	---Purpose:  This method is  called    at the end  of   each
    	--            iteration to  check the convergence :
    	--            || Xi+1 - Xi || < Tolerance 
    	--            or || F(Xi+1) - F(Xi)|| < Tolerance * || F(Xi) ||
    	--            It can be  redefined in a sub-class to implement a specific  test.
    
    returns Boolean
    is virtual;
    
    
    IsDone(me)
    	---Purpose: Tests if an error has occured.
    	---C++: inline
    
    returns Boolean
    is static;
    
    IsConvex(me)
    	---Purpose: Tests if the Function is convexe during optimization.
    	---C++: inline    
    returns Boolean
    is static;    
    
    Location(me)
    	---Purpose: returns the location vector of the minimum.
        -- Exception NotDone is raised if an error has occured.
    	---C++: inline
    	---C++: return const&
    
    returns Vector
    raises NotDone
    is static;
    
    
    Location(me; Loc: out Vector)
    	---Purpose: outputs the location vector of the minimum in Loc.
        -- Exception NotDone is raised if an error has occured.
        -- Exception DimensionError is raised if the range of Loc is not
        -- equal to the range of the StartingPoint.
    	---C++: inline
	    
    raises DimensionError,
    	   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;
    
    
    Gradient(me)
    	---Purpose: returns the gradient vector at the minimum.
        -- Exception NotDone is raised if an error has occured.the minimum was not found.
    	---C++: inline
    	---C++: return const&
    
    returns Vector
    raises NotDone
    is static;
    
    
    Gradient(me; Grad: out Vector)
    	---Purpose: outputs the gradient vector at the minimum in Grad.
        -- Exception NotDone is raised if the minimum was not found.
        -- Exception DimensionError is raised if the range of Grad is not
        -- equal to the range of the StartingPoint.
    	---C++: inline

    raises DimensionError,
    	   NotDone
    is static;


    NbIterations(me)
    	---Purpose: returns the number of iterations really done in the 
    	--          calculation of the minimum.
    	-- The exception NotDone is raised if an error has occured.
    	---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;
TheStatus:       Status  is protected;
TheLocation:     Vector  is protected;
TheGradient:     Vector  is protected;
TheStep:         Vector  is protected;
TheHessian :     Matrix  is protected;
PreviousMinimum: Real    is protected;
TheMinimum:      Real    is protected;
MinEigenValue:   Real    is protected;
XTol:            Real    is protected;
CTol:            Real    is protected;
nbiter:          Integer is protected;
NoConvexTreatement: Boolean is protected;
Convex           : Boolean is protected;
Itermax:         Integer;


end NewtonMinimum;