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}