occt/src/math/math_NewtonFunctionSetRoot.cdl

-- Created on: 1991-05-14
-- Created by: Laurent PAINNOT
-- Copyright (c) 1991-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 NewtonFunctionSetRoot from math
    	---Purpose:
    	-- This class computes the root of a set of N functions of N variables,
    	-- knowing an initial guess at the solution and using the
    	-- Newton Raphson algorithm. Knowledge of all the partial
    	-- derivatives (Jacobian) is required.

uses Vector from math, Matrix from math, IntegerVector from math,
     FunctionSetWithDerivatives from math,
     OStream from Standard

raises NotDone from StdFail,
       DimensionError from Standard

is

    Create(theFunction: in out FunctionSetWithDerivatives;
           theXTolerance: Vector; theFTolerance: Real;
           tehNbIterations: Integer = 100)
    ---Purpose:
    -- Initialize correctly all the fields of this class. 
    -- The range (1, F.NbVariables()) must be especially respected for
    -- all vectors and matrix declarations.
   returns NewtonFunctionSetRoot;


    Create(theFunction: in out FunctionSetWithDerivatives;
           theFTolerance: Real; theNbIterations: Integer = 100)
    ---Purpose:
    -- This constructor should be used in a sub-class to initialize
    -- correctly all the fields of this class.
    -- The range (1, F.NbVariables()) must be especially respected for
    -- all vectors and matrix declarations.
    -- The method SetTolerance must be called before performing the algorithm.
   returns NewtonFunctionSetRoot;


    Delete(me) is static;
    ---Purpose: Destructor alias.
    ---C++: alias "  Standard_EXPORT virtual ~math_NewtonFunctionSetRoot();"


    SetTolerance(me: in out; XTol: Vector)
    ---Purpose: Initializes the tolerance values for the unknowns.
    is static;


    Perform(me: in out; theFunction: in out FunctionSetWithDerivatives; theStartingPoint: Vector)
    ---Purpose:
    -- The Newton method is done to improve the root of the function 
    -- from the initial guess point. The solution is found when:
    -- abs(Xj - Xj-1)(i) <= XTol(i) and abs(Fi) <= FTol for all i;
    is static;


    Perform(me: in out; theFunction: in out FunctionSetWithDerivatives;
            theStartingPoint: Vector; theInfBound, theSupBound: Vector)
    ---Purpose:
    -- The Newton method is done to improve the root of the function 
    -- from the initial guess point. Bounds may be given, to constrain the solution.
    -- The solution is found when:
    -- abs(Xj - Xj-1)(i) <= XTol(i) and abs(Fi) <= FTol for all i;
    is static;


    IsSolutionReached(me: in out; F: in out FunctionSetWithDerivatives)
    ---Purpose:
    -- This method is called at the end of each iteration to check if the
    -- solution is found.
    -- Vectors DeltaX, Fvalues and Jacobian Matrix are consistent with the
    -- possible solution Vector Sol and can be inspected to decide whether
    -- the solution is reached or not.
    ---C++: inline
    returns Boolean is virtual;


    IsDone(me)
	---Purpose: Returns true if the computations are successful, otherwise returns false.
      	---C++: inline
    returns Boolean
    is static;


    Root(me)
    	---Purpose: Returns the value of the root of function F.
    	-- Exceptions
    	-- StdFail_NotDone if the algorithm fails (and IsDone returns false).
       	---C++: inline
    	---C++: return const&
    returns Vector
    raises NotDone
    is static;
    
    
    Root(me; Root: out Vector)
       ---Purpose: outputs the root vector in Root.
       -- Exception NotDone is raised if the root was not found.
       -- Exception DimensionError is raised if the range of Root is
       -- not equal to the range of the StartingPoint.
    	---C++: inline

    raises NotDone,
    	   DimensionError
    is static;
    
    
    StateNumber(me)
    	---Purpose: Outputs the state number associated with the solution
        --          vector root. 
    	---C++: inline
    returns Integer
    raises NotDone
    is static;
    
    
    Derivative(me)
	---Purpose: Returns the matrix value of the derivative at the root.
        -- Exception NotDone is raised if the root was not found.
    	---C++: inline
    	---C++: return const&
    returns Matrix
    raises NotDone
    is static;
    
    
    Derivative(me; Der: out Matrix)
	---Purpose: Outputs the matrix value of the derivative at the root in
        -- Der.
        -- Exception NotDone is raised if the root was not found.
        -- Exception DimensionError is raised if the range of Der is
        -- not equal to the range of the StartingPoint.
        ---C++: inline
    raises NotDone,
    	   DimensionError
    is static;
    
    
    FunctionSetErrors(me)
    	---Purpose: Returns the vector value of the error done on the 
        -- functions at the root.
        -- Exception NotDone is raised if the root was not found.
    	---C++: inline
    	---C++: return const&
    returns Vector
    raises NotDone
    is static;


    FunctionSetErrors(me; Err: out Vector)
    	---Purpose: Outputs the vector value of the error done on the 
        -- functions at the root in Err.
        -- Exception NotDone is raised if the root was not found.
        -- Exception DimensionError is raised if the range of Err is
        -- not equal to the range of the StartingPoint.
   	---C++: inline
    raises NotDone,
    	   DimensionError
    is static;
    
    
    NbIterations(me)
    	---Purpose: Returns the number of iterations really done 
        -- during the computation of the Root.
        -- Exception NotDone is raised if the root was not found.
        ---C++: inline
    returns Integer
    raises NotDone
    is static;
    

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

    is static;


fields

Done:       Boolean;
State:      Integer;
TolX:       Vector is protected;
TolF:       Real is protected;
Iter:       Integer;
Indx:       IntegerVector is protected;
Scratch:    Vector is protected;
Sol:        Vector is protected;
DeltaX:     Vector is protected;
FValues:    Vector is protected;
Jacobian:   Matrix is protected;
Itermax:    Integer;

end NewtonFunctionSetRoot;