abs_mat.sa


Generated by gen_html_sa_files from ICSI. Contact gomes@icsi.berkeley.edu for details
 
------------------------->  GNU Sather - sourcefile  <-------------------------
-- Copyright (C) 2000 by K Hopper, University of Waikato, New Zealand        --
-- This file is part of the GNU Sather library. It is free software; you may --
-- redistribute  and/or modify it under the terms of the GNU Library General --
-- Public  License (LGPL)  as published  by the  Free  Software  Foundation; --
-- either version 2 of the license, or (at your option) any later version.   --
-- This  library  is distributed  in the  hope that it will  be  useful, but --
-- WITHOUT ANY WARRANTY without even the implied warranty of MERCHANTABILITY --
-- or FITNESS FOR A PARTICULAR PURPOSE. See Doc/LGPL for more details.       --
-- The license text is also available from:  Free Software Foundation, Inc., --
-- 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA                     --
-------------->  Please email comments to <bug-sather@gnu.org>  <--------------


abstract class $MAT{ET < $NFE{ET}, VT< $VEC{ET,VT}, MT< $MAT{ET,VT,MT}}

abstract class $MAT{ET < $NFE{ET}, VT< $VEC{ET,VT}, MT< $MAT{ET,VT,MT}} is -- This class specifies the basic mathematical matrix abstraction -- with the following class arguments :-- -- -- a. "ET" is the *element_type* which must be a $NFE (ie a Numerical -- Field Eelement. -- -- b. "VT" is its associated vector type, needed to define -- matrix-vector operations. -- -- c. "MT" ought to be the same matrix type as the concrete -- implementations that subtype from this type. -- -- This parameterization may appear to be somewhat odd, but it serves to -- give a concrete type which permits proper covariance in arguments. Just -- as a matrix/vector multiplication method needs to have a specific vector -- type to go along with the matrix type, matrix/matrix operations like -- multiplication need to be defined to accept arguments of the same matrix -- type as "self". -- -- For example, a concrete matrix class implementaion MAT_DC (double -- complex dense matrix) would need to define "plus(arg : MAT_DC)", allowing -- one to add a MATDC to another, but not allowing one to add a MAT_DC to a -- MAT_UT_F (upper triangular). -- -- The subtyping clause of MAT_DC would then read something like -- -- class MAT_DC < $MAT{CPXD,VEC_DC,MAT_DC} is ... -- -- In this way, this $MAT{ET,VT,MT} class is less useful for allowing -- run-time substitutability of many implementations than as a precise -- specification of responsibilities of its subtypes. However, both Basic -- and Fancy concrete matrices may subtype from $MAT{*,*,*}. -- -- If this mechanism is proven to be useful, more general $MAT{} -- abstract types above this one that do not have covarying features (and -- thus be useful for run-time polymorphism) may be written in the future. -- -- Routine Naming Convention -- ------------------------- -- -- The idea is that reading the routine name in order ought to generate -- the actual meaning of the operation. -- -- A := B{^T} OP {s*}C{^T} -- -- (brackets denote optional operation.) -- -- For A,B,C: if B=self, write nothing. If a matrix argument then write -- "arg". If transpose is desired append "arg" with "_trans", or just add -- "trans" if self. If an argument is a vector type then use "vec" instead -- of "arg". -- -- For OP, write "plus" for addition, "minus" for subtraction and "times" for -- multiplication. -- -- If "self" is modified, overall routine name should have "inplace_" in -- front. If there's a scalar multiplication, insert "scaled_" before the -- second argument. If the routine modifies data in some reference argument, -- then "into" denotes the argument that will be changed. -- -- Example : A := B^T - C. -- B /= self, so "arg". Transposed argument. "arg_trans". -- operation is subtraction. "arg_trans_minus". -- another argument, so "arg_trans_minus_arg(arg1,arg2:MT)" -- is the signature. -- -- Example: B := B + s*C^T -- Modifies self. "inplace_". B is self so nothing. -- "inplace_". operation is addition. "inplace_plus". -- scalar multiplication. "inplace_plus_scaled". -- matrix argument, transposed. -- "inplace_plus_scaled_arg_trans(s:ET,arg:MT)" -- is the routine signature. -- Version 1.2 Aug 97. Copyright K Hopper, U of Waikato -- Development History -- ------------------- -- Date Who By Detail -- ---- ------ ------ -- 5 May 96 mbk Original -- 18 Jul 96 ds Modifiedfor 1.1 -- 25 Aug 97 kh Modified for cardinals and portability. nr : CARD ; -- number of rows. nc : CARD ; -- number of columns. size : CARD ; -- Total number of elements (nr*nc) size1 : CARD ; -- First dimension (nr) size2 : CARD ; -- Second dimension (nc) is_same_shape( arg : MT ) : BOOL ; -- This routine returns true if and only if arg has the same dimensions -- as self. is_same_shape_trans( arg : MT ) : BOOL ; -- This routine returns true if and only if self has the same shape as -- the transposed argument. fits( arg : MT ) : BOOL ; -- This routine returns true if and only if the total number of elements -- in self is the same as the total number of elements in arg. create( nr, nc : CARD ) : MT ; -- This routine returns a new empty matrix with the given number of rows -- and columns. create( arg : MT ) : MT ; -- This creation routine returns a new matrix of the same size as the -- argument but with all elements initialised to zero.; copy : MT ; -- This routine creates a new copy of self which is then returned. contents( arg : MT ) ; -- This routine sets the contents of the array portion of self to be -- the same as the contents of arg. inplace_contents( arg : MT ) ; -- This routine is a synonym for contents. inplace_contents_from_function( function : ROUT{CARD,CARD} : ET ) ; -- This orutine sets the array portion of self to be the result of -- applying the gievn function to each element individually. The two -- arguments of the function are, respectively, row and column indices. ident : MT ; -- This routine returns the identity matrix which is the same size and -- shape as self. inplace_ident ; -- This routine sets the array portion of self to have the values of -- the identity matrix values. trans : MT ; -- This routine returns a new matrix which is the transpose of self. inplace_trans ; -- This routine sets the array portion of self to be the transpose of -- self. inplace_arg_trans( arg : MT ) ; -- This routine sets the contents of the array portion of self to be -- the transpose of the matrix argument. times_elt( elem : ET ) : MT ; -- This routine creates a new copy of self whose elements are the -- product of the given element ans the existing component of self. scaled_by( elem : ET ) : MT ; -- This routine is a synonym for times_elt. inplace_scaled_by( elem : ET ) ; -- This routine is an in-place version of the one above -- setting each -- element of self to be the result of multiplying its original value by -- self. inplace_elements( elem : ET ) ; -- This routine sets every element of the array portion of self to have -- the given element value. aget( row, col : CARD ) : ET ; -- This routine returns the value of the element at the indicated row -- and column position. aset( row, col : CARD, val : ET ) ; -- This routine sets the value of the element at the indicated row and -- column position to be val. is_eq( other : MT ) : BOOL ; -- This routine returns true if and only if the values of self and other -- are identical. plus( arg : MT ) : MT ; -- This routine returns a new matrix which is the result of adding the -- value of each element of arg to the corresponding element of self. plus_arg( arg : MT ) : MT ; -- This rotuine returns a new matrix, the elements of which have the -- value given by adding the corresponding elements of self and arg. minus( arg : MT ) : MT ; -- This routine returns a new matrix which is the result of subtracting -- the value of each ekement of arg from the corresponding element of self. minus_arg( arg : MT ) : MT ; -- This routine returns a new matrix which is the result of subtracting -- the value of each element of arg from the value of the sorresponding -- element of self. inplace_plus_arg( arg : MT ) ; -- This routine sets self to be the result of adding the value of each -- element of arg to the corresponding value of self. inplace_minus_arg( arg : MT ) ; -- This routine sets self to be the result of subtracting each element -- of arg from the corresponding element of self. plus_arg_trans( arg : MT ) : MT ; -- This routine returns the result of adding the transpose of the -- argument to self, element by element. minus_arg_trans( arg : MT ) : MT ; -- This routine returns the result of subtracting each element of self -- from the corresponding element of the tramspose of the given argument. inplace_plus_arg_trans( arg : MT ) ; -- This routine sets each element of self to be the result of adding -- the corresponding element of the transpose of the given argument. inplace_minus_arg_trans( arg : MT ) ; -- This routine sets each element of self to be the result of -- subtracting the corresponding element of the itranspose of the given -- argument from the element of self. inplace_arg_plus_arg( arg1, arg2 : MT ) ; -- This routine sets each element of self to be the sum of the -- corresponding elements of the two arguments. inplace_arg_minus_arg( arg1, arg2 : MT ) ; -- This routine sets the elements of self to be the result of -- subtracting the value of the corresponding element of arg2 from that of -- arg1. inplace_arg_plus_arg_trans( arg1, arg2 : MT ) ; -- This routine sets the elements of self to be the result of adding -- the corresponding element of the transpose of arg2 to the value of the -- corresponding element of arg1. Note that this will not work correctly -- if self and arg2 are the same matrix. inplace_arg_minus_arg_trans( arg1, arg2 : MT ) ; -- This routine sets the elements of self to be the result of -- subtracting the corresponding element of the transpose of arg2 from that -- of arg1. Note that self and arg2 must not be the same matrix. inplace_arg_trans_plus_arg_trans( arg1, arg2 : MT ) ; -- This routine sets the elements of self to be the result of adding -- the corresponding elements of the transposes of arg1 and arg2. inplace_arg_trans_minus_arg_trans( arg1, arg2 : MT ) ; -- This routine sets the elements of self to be the result of -- subtracting the corresponding element of the transpose of arg2 from that -- of the transpose of arg1. -- NOTE The two operations not needed are :-- -- -- a. Given commutative matrix elements, "inplace_arg_trans_plus_arg" -- is not needed since it is equivalent to "inplace_arg_plus_arg_trans" -- switching the order of the arguments. -- -- b. "inplace_trans_plus_arg" (i.e. self := self^T + arg) cannot -- really be implemented more efficiently than self := self^T, -- self := self + arg. plus_scaled_arg( scale : ET, arg : MT ) : MT ; -- This routine returns the new matrix which is the result of adding -- the scalar product of scale and the corresponding element of arg to self. inplace_plus_scaled_arg( scale : ET, arg : MT ) ; -- This routine sets each element of self to be the result of adding to -- it the scaled value of the corresponding element of arg. plus_scaled_arg_trans( scale : ET, arg : MT ) : MT ; -- This routine returns the new matrix which is the result of adding -- together the value of the corresponding element of self and the scaled -- value of the corresponding element of arg. inplace_plus_scaled_arg_trans( scale : ET, arg : MT ) ; -- This routine sets the value of each element of self to the result of -- adding the value of the corresponding element of self to the scaled value -- of that of arg. inplace_arg_plus_scaled_arg( arg1 : MT, scale : ET, arg2 : MT ) ; -- This routine sets the values of the elements of self to be the sum of -- the corresponding element of arg1 and the scaled element value of arg2. inplace_arg_plus_scaled_arg_trans( arg1 : MT, scale : ET, arg2 : MT ) ; -- This routine sets the value of the elements of self to be the result -- of adding the value of the corresponding element of arg1 to the scaled -- value of the corresponding element of the transpose of arg2. times( arg : MT ) : MT ; -- This routine returns the matrix product of self and arg. trans_times_arg( arg : MT ) : SAME ; -- This routine returns the result of multipkying the transpose of self -- with arg. times_arg_trans( arg : MT ) : SAME ; -- This routine returns the result of multiplying self by the transpose -- of arg. trans_times_arg_trans( arg : MT ) : SAME ; -- Thi routine returns the result of multiplying the transpose of self -- by the transpose of arg. inplace_arg_times_arg( arg1, arg2 : MT ) ; -- This routine sets self to be the result of the matrix multiplication -- of arg1 and arg2. inplace_arg_trans_times_arg( arg1, arg2 : MT ) ; -- This routine sets self to be the result of the matrix multiplication -- of arg2 by the transpose of arg1. inplace_arg_times_arg_trans( arg1, arg2 : MT ) ; -- This routine sets the value of self to be the reault of the matrix -- multiplication of arg1 by the transpose of arg2. inplace_arg_trans_times_arg_trans( arg1, arg2 : MT ) ; -- This routine sets tself to be the result of multiplying the transpose -- of arg1 by the transpose of arg2. times_vec( arg : VT ) : VT ; -- This routine returns the matrix given by performing the vector -- multiplication of self by the argument. trans_times_vec( arg : VT ) : VT ; -- This routine returns the result of the vector multiplication of the -- transpose of self by the given argument. times_vec_into_vec( arg : VT, dest : VT ) ; -- This routine sets dest to be the result of the vector product of self -- by arg. trans_times_vec_into_vec( arg : VT, dest : VT ) ; -- This routine sets dest to be the result of the vector product of the -- transpose of self and arg. times_scaled_vec_into_vec( scale : ET, arg : VT, dest : VT ) ; -- This outine sets dest to be the result of the vector multiplication -- of self by the scaled vector arg. trans_times_scaled_vec_into_vec( scale : ET, arg : VT, dest : VT ) ; -- This routine sets dest to be the result of multiplying the transpose -- of self by the scaled vector arg. inplace_plus_scaled_vec_times_vec( scale : ET, val1, val2 : VT ) ; -- This routine sets self to be the result of adding the scaled outer -- product of val1 and val2 to self. create_col_matrix( arg : VT ) : SAME ; -- This routine returns a 'column' matrix which has as a single column -- the vector arg. create_row_matrix( arg : VT ) : SAME ; -- This routine returns a single row matrix the elements of which are -- those of arg. col( index : CARD ) : VT ; -- This routine returns the vector consisting of the value in the -- indicated column of self. row( index : CARD ) : VT ; -- This routine returns the vector which is taken from the indicated -- row of self. col( index : CARD, val : VT ) ; -- This routine sets the indicated column of self to have the given -- value. row( index : CARD, val : VT ) ; -- This routine sets the indicated row of self to have the value of the -- given vector. inplace_scaled_col( scale : ET, index : CARD ) ; -- This routine scales the indicated column of self by the given factor. inplace_scaled_row( scale : ET, index : CARD ) ; -- This routine scales the indicated row of self by the given factor. inplace_col_plus_scaled_vec( index : CARD, scale : ET, val : VT ) ; -- This routine sets the indicated column of self to have the result of -- adding the scaled value to it. inplace_row( index : CARD, val : VT ) ; -- This routine is a synonym for row. inplace_row_plus_scaled_vec( index : CARD, scale : ET, val : VT ) ; -- This routine adds the scaled vector to the indicated row of self. inplace_swapped_col( index : CARD, val : VT ) ; -- This routine swaps the indicated column of self with the given vector. inplace_swapped_row( index : CARD, val : VT ) ; -- This routine swaps the indicated row of self with the given vector. submatrix( low_row, upper_row : CARD, low_column, upper_column : CARD ) : SAME ; -- This routine creates a new matrix consisting of the 'area' of self -- indicated byt the given row and column ranges which are INCLUSIVE. inplace_submatrix_to_arg( low_row, upper_row : CARD, low_column, upper_column : CARD, arg : MT ) ; -- This routine sets the indicated 'area' of self to have the values in -- arg. inplace_swapped( arg : MT ) ; -- This routine swaps the contents of self and arg, provided they are -- the same size and shape. ind1! : CARD ; -- This iter yields the values of the first matrix index (for the rows) -- in order. ind2! : CARD ; -- This iter yields the values of the second matrix index (for the -- columns) in order. diag_elt! : ET ; -- This iter yields the values along the diagonal (square in the smaller -- dimension) in order. inplace_diag_elt!( val : ET ) ; -- This iter sets the values along the diagonal (square in the smaller -- dimension) in order. inds! : TUP{CARD,CARD} ; -- This iter yields toples of the indices of self in the stirage order. elt! : ET ; -- This iter yields all elements of the matrix in storage order -- which -- is usually column-major for BLAS compatible matrices. inplace_elt!( val : ET ) ; -- This iter sets the elements of self in storage order. elt1!( once index : CARD ) : ET ; -- This iter yields the elements of the indicated row of the matrix -- in order. elt2!( once index : CARD ) : ET ; -- This iter yields the elements of the indicated column of the matrix -- in order. row_elt!( once row : CARD ) : ET ; -- This is a synonym for elt1!, yielding the elements of the indicated -- row in order. col_elt!( once col : CARD ) : ET ; -- This is a synonym for elt2!, yielding the elements of the indicated -- column in order. str : STR ; -- This routine returns a string representation of self. end ; -- $MAT{ET,VT,MT}