[occt.git] / src / math / math_FunctionSetRoot.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 FunctionSetRoot from math
    ---Purpose: The math_FunctionSetRoot class calculates the root
    -- of a set of N functions of M variables (N<M, N=M or N>M). Knowing
    -- an initial guess of the solution and using a minimization algorithm, a search
    -- is made in the Newton direction and then in the Gradient direction if there
    -- is no success in the Newton direction. This algorithm can also be
    -- used for functions minimization. Knowledge of all the partial 
    -- derivatives (the 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(F: in out FunctionSetWithDerivatives; 
           Tolerance : Vector;
    	   NbIterations: Integer = 100)
    ---Purpose: is 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.

    returns FunctionSetRoot from math;
    

    Create(F: in out FunctionSetWithDerivatives;
    	   NbIterations: Integer = 100)
    ---Purpose: is 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 after this
    --          constructor.

    returns FunctionSetRoot from math;
	   
	   
    Create(F: in out FunctionSetWithDerivatives; StartingPoint: Vector;
    	   Tolerance: Vector; NbIterations: Integer = 100)
    ---Purpose: is used to improve the root of the function F
    --          from the initial guess StartingPoint.
    --          The maximum number of iterations allowed is given by 
    --          NbIterations. 
    --          In this case, the solution is found when:
    --          abs(Xi - Xi-1)(j) <= Tolerance(j) for all unknowns.
    
    returns FunctionSetRoot from math;
    
    
    Create(F: in out FunctionSetWithDerivatives; StartingPoint: Vector;
    	   Tolerance: Vector; infBound, supBound: Vector;
	   NbIterations: Integer = 100)
       ---Purpose: is used to improve the root of the function F
       --          from the initial guess StartingPoint.
       --          The maximum number of iterations allowed is given 
       --          by NbIterations.
       --          In this case, the solution is found when:
       --          abs(Xi - Xi-1) <= Tolerance for all unknowns.

    returns FunctionSetRoot from math;


    Delete(me:out) is virtual;
    ---C++: alias "Standard_EXPORT virtual ~math_FunctionSetRoot(){Delete();}"
    
    SetTolerance(me: in out; Tolerance: Vector)
    	---Purpose: Initializes the tolerance values.

    is static;

    
    Perform(me: in out; F: in out FunctionSetWithDerivatives;
    	    StartingPoint: Vector;
    	    infBound, supBound: Vector)
       ---Purpose: Improves the root of function F from the initial guess
       -- StartingPoint. infBound and supBound may be given to constrain the solution.
       -- Warning
       -- This method is called when computation of the solution is
       -- not performed by the constructors.

    is static;
    

    IsSolutionReached(me: in out; F: in out FunctionSetWithDerivatives)
    	---Purpose: This routine is called at the end of each iteration 
    	--          to check if the solution was found. It can be redefined
    	--          in a sub-class to implement a specific test to stop the 
    	--          iterations.
    	--          In this case, the solution is found when:
    	--          abs(Xi - Xi-1) <= Tolerance for all unknowns.

    returns Boolean is virtual;


    IsDone(me)
    	---Purpose: 
    	-- Returns true if the computations are successful, otherwise returns false.
        ---C++: inline
      returns Boolean
      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;
    
    
    StateNumber(me)
    	---Purpose: returns the stateNumber (as returned by 
    	--          F.GetStateNumber()) associated to the root found.
    	---C++: inline
    returns Integer
    raises NotDone
    is static;
    
    
    Root(me)
    	---Purpose: Returns the value of the root of function F.
    	--          Exception NotDone is raised if the root was not found.
    	---C++: inline
    	---C++: return const&
    returns Vector
    raises NotDone,
    	   DimensionError
    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.

    raises NotDone from StdFail
    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 column 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.

    raises NotDone,
    	   DimensionError
    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;
Delta            : Vector is protected;
Sol              : Vector is protected;
DF               : Matrix is protected;
Kount            : Integer;
State            : Integer;
Tol              : Vector is protected;
Itermax          : Integer;

-- working tables

InfBound         : Vector;
SupBound         : Vector;

SolSave          : Vector;
GH               : Vector;
DH               : Vector;
DHSave           : Vector;
FF               : Vector;
PreviousSolution : Vector;
Save             : Vector;
Constraints      : IntegerVector;
Temp1            : Vector;
Temp2            : Vector;
Temp3            : Vector;
Temp4            : Vector;

end FunctionSetRoot;
Commit	Line	Data
b311480e	1	-- Created on: 1991-05-14
	2	-- Created by: Laurent PAINNOT
	3	-- Copyright (c) 1991-1999 Matra Datavision
	4	-- Copyright (c) 1999-2012 OPEN CASCADE SAS
	5	--
	6	-- The content of this file is subject to the Open CASCADE Technology Public
	7	-- License Version 6.5 (the "License"). You may not use the content of this file
	8	-- except in compliance with the License. Please obtain a copy of the License
	9	-- at http://www.opencascade.org and read it completely before using this file.
	10	--
	11	-- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
	12	-- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
	13	--
	14	-- The Original Code and all software distributed under the License is
	15	-- distributed on an "AS IS" basis, without warranty of any kind, and the
	16	-- Initial Developer hereby disclaims all such warranties, including without
	17	-- limitation, any warranties of merchantability, fitness for a particular
	18	-- purpose or non-infringement. Please see the License for the specific terms
	19	-- and conditions governing the rights and limitations under the License.
	20
7fd59977	21
	22
	23
	24	class FunctionSetRoot from math
	25	---Purpose: The math_FunctionSetRoot class calculates the root
	26	-- of a set of N functions of M variables (N<M, N=M or N>M). Knowing
	27	-- an initial guess of the solution and using a minimization algorithm, a search
	28	-- is made in the Newton direction and then in the Gradient direction if there
	29	-- is no success in the Newton direction. This algorithm can also be
	30	-- used for functions minimization. Knowledge of all the partial
	31	-- derivatives (the Jacobian) is required.
	32
	33
	34	uses Vector from math,
	35	Matrix from math,
	36	IntegerVector from math,
	37	FunctionSetWithDerivatives from math,
	38	OStream from Standard
	39
	40	raises NotDone from StdFail,
	41	DimensionError from Standard
	42
	43	is
	44
	45	Create(F: in out FunctionSetWithDerivatives;
	46	Tolerance : Vector;
	47	NbIterations: Integer = 100)
	48	---Purpose: is used in a sub-class to initialize correctly all the fields
	49	-- of this class.
	50	-- The range (1, F.NbVariables()) must be especially
	51	-- respected for all vectors and matrix declarations.
	52
	53	returns FunctionSetRoot from math;
	54
	55
	56
	57	Create(F: in out FunctionSetWithDerivatives;
	58	NbIterations: Integer = 100)
	59	---Purpose: is used in a sub-class to initialize correctly all the fields
	60	-- of this class.
	61	-- The range (1, F.NbVariables()) must be especially
	62	-- respected for all vectors and matrix declarations.
	63	-- The method SetTolerance must be called after this
	64	-- constructor.
	65
	66	returns FunctionSetRoot from math;
	67
	68
	69
	70	Create(F: in out FunctionSetWithDerivatives; StartingPoint: Vector;
	71	Tolerance: Vector; NbIterations: Integer = 100)
	72	---Purpose: is used to improve the root of the function F
	73	-- from the initial guess StartingPoint.
	74	-- The maximum number of iterations allowed is given by
	75	-- NbIterations.
	76	-- In this case, the solution is found when:
	77	-- abs(Xi - Xi-1)(j) <= Tolerance(j) for all unknowns.
	78
	79	returns FunctionSetRoot from math;
	80
	81
	82
	83	Create(F: in out FunctionSetWithDerivatives; StartingPoint: Vector;
	84	Tolerance: Vector; infBound, supBound: Vector;
85	NbIterations: Integer = 100)
86	---Purpose: is used to improve the root of the function F
87	-- from the initial guess StartingPoint.
88	-- The maximum number of iterations allowed is given
89	-- by NbIterations.
90	-- In this case, the solution is found when:
91	-- abs(Xi - Xi-1) <= Tolerance for all unknowns.
92
93	returns FunctionSetRoot from math;
94
95
96
97	Delete(me:out) is virtual;
98	---C++: alias "Standard_EXPORT virtual ~math_FunctionSetRoot(){Delete();}"
99
100	SetTolerance(me: in out; Tolerance: Vector)
101	---Purpose: Initializes the tolerance values.
102
103	is static;
104
105
106
107	Perform(me: in out; F: in out FunctionSetWithDerivatives;
108	StartingPoint: Vector;
109	infBound, supBound: Vector)
110	---Purpose: Improves the root of function F from the initial guess
111	-- StartingPoint. infBound and supBound may be given to constrain the solution.
112	-- Warning
113	-- This method is called when computation of the solution is
114	-- not performed by the constructors.
115
116	is static;
117
118
119	IsSolutionReached(me: in out; F: in out FunctionSetWithDerivatives)
120	---Purpose: This routine is called at the end of each iteration
121	-- to check if the solution was found. It can be redefined
122	-- in a sub-class to implement a specific test to stop the
123	-- iterations.
124	-- In this case, the solution is found when:
125	-- abs(Xi - Xi-1) <= Tolerance for all unknowns.
126
127	returns Boolean is virtual;
128
129
130	IsDone(me)
131	---Purpose:
132	-- Returns true if the computations are successful, otherwise returns false.
133	---C++: inline
134	returns Boolean
135	is static;
136
137
138	NbIterations(me)
139	---Purpose: Returns the number of iterations really done
140	-- during the computation of the root.
141	-- Exception NotDone is raised if the root was not found.
142	---C++: inline
143	returns Integer
144	raises NotDone
145	is static;
146
147
148	StateNumber(me)
149	---Purpose: returns the stateNumber (as returned by
150	-- F.GetStateNumber()) associated to the root found.
151	---C++: inline
152	returns Integer
153	raises NotDone
154	is static;
155
156
157	Root(me)
158	---Purpose: Returns the value of the root of function F.
159	-- Exception NotDone is raised if the root was not found.
160	---C++: inline
161	---C++: return const&
162	returns Vector
163	raises NotDone,
164	DimensionError
165	is static;
166
167
168	Root(me; Root: out Vector)
169	---Purpose: Outputs the root vector in Root.
170	-- Exception NotDone is raised if the root was not found.
171	-- Exception DimensionError is raised if the range of Root
172	-- is not equal to the range of the StartingPoint.
173
174	raises NotDone from StdFail
175	is static;
176
177
178	Derivative(me)
179	---Purpose: Returns the matrix value of the derivative at the root.
180	-- Exception NotDone is raised if the root was not found.
181	---C++: inline
182	---C++: return const&
183
184	returns Matrix
185	raises NotDone
186	is static;
187
188
189	Derivative(me; Der: out Matrix)
190	---Purpose: outputs the matrix value of the derivative
191	-- at the root in Der.
192	-- Exception NotDone is raised if the root was not found.
193	-- Exception DimensionError is raised if the column range
194	-- of <Der> is not equal to the range of the startingPoint.
195	---C++: inline
196
197	raises NotDone,
198	DimensionError
199	is static;
200
201
202
203	FunctionSetErrors(me)
204	---Purpose: returns the vector value of the error done
205	-- on the functions at the root.
206	-- Exception NotDone is raised if the root was not found.
207	---C++: inline
208	---C++: return const&
209
210	returns Vector
211	raises NotDone
212	is static;
213
214
215	FunctionSetErrors(me; Err: out Vector)
216	---Purpose: outputs the vector value of the error done
217	-- on the functions at the root in Err.
218	-- Exception NotDone is raised if the root was not found.
219	-- Exception DimensionError is raised if the range of Err
220	-- is not equal to the range of the StartingPoint.
221
222	raises NotDone,
223	DimensionError
224	is static;
225
226
227	Dump(me; o: in out OStream)
228	---Purpose: Prints on the stream o information on the current state
229	-- of the object.
230	-- Is used to redefine the operator <<.
231
232	is static;
233
234
235	fields
236
237	Done : Boolean;
238	Delta : Vector is protected;
239	Sol : Vector is protected;
240	DF : Matrix is protected;
241	Kount : Integer;
242	State : Integer;
243	Tol : Vector is protected;
244	Itermax : Integer;
245
246	-- working tables
247
248	InfBound : Vector;
249	SupBound : Vector;
250
251	SolSave : Vector;
252	GH : Vector;
253	DH : Vector;
254	DHSave : Vector;
255	FF : Vector;
256	PreviousSolution : Vector;
257	Save : Vector;
258	Constraints : IntegerVector;
259	Temp1 : Vector;
260	Temp2 : Vector;
261	Temp3 : Vector;
262	Temp4 : Vector;
263
264	end FunctionSetRoot;