matrix(3) UNIX System V (Nov 25, 1998) matrix(3)
Matrix
Inherits from:
CAObject
Maturity Index:
Relatively mature
Class Description
A matrix consists of a number of scalars ordered in rows .
The rows are vector objects; the scalar objects can be
arbitrary Computer Algebra Kit objects, but they currently
have to be either floating-point, elements of a field (see
inField ) or elements of an integral domain (see
inIntegralDomain ).
There are methods to access, insert and remove rows and
columns . Columns are collection objects of scalars (not
vector objects). It's also possible to place or replace a
scalar directly at a position given by a row and column
index. See the documentation on eachSequence to access the
scalar at a given row and column index.
Note:
Matrix objects are meant for computational tasks. They are
no substitute for a List or Collection object, and
sometimes, e.g. for frequent random access, it's indeed
better to work with a collection of collections than with a
Matrix object.
Method types
Special Matrices
* diagonal:
* circulant:
* companion:
* hankel::
* toeplitz::
* hilbert:
Creation
* scalar:numRows:numColumns:
* copy
* deepCopy
* emptyVector
* clear
Identity
* scalarZero
* rows
* numRows
Page 1 (printed 6/28/99)
matrix(3) UNIX System V (Nov 25, 1998) matrix(3)
* numColumns
* isEqual:
* hash
* isDiagonal
* isSymmetric
* isAntiSymmetric
Insertion
* insertRow:
* insertRow:at:
* insertColumn:
* insertColumn:at:
Removing
* removeRow
* removeRowAt:
* removeColumn
* removeColumnAt:
Place and Replace
* placeScalar:at::
* replaceScalarAt::with:
Coercion
* asNumerical
* asModp:
* onCommonDenominator:
Accessing Rows and Scalars
* rowAt:
* eachRow
* eachScalar
* eachSequence
* floatValueAt::
Addition
* zero
* negate
* double
* add:
* subtract:
* addScalar:
* subtractScalar:
Multiplication
* one
* square
* multiply:
* multiplyVector:
Scalar Multiplication
* multiplyScalar:
Page 2 (printed 6/28/99)
matrix(3) UNIX System V (Nov 25, 1998) matrix(3)
* divideScalar:
Transposing
* transpose
Gaussian Elimination
* determinant
* solveVector:
* inverse
* divide:
* rank
* nullity
* kernel
* image
Trace Methods
* trace
* adjoint
Printing
* printOn:
Methods
diagonal:
+ diagonal : cltnOfScalars
Creates a new, square matrix with the objects in
cltnOfScalars on the diagonal. You remain responsible for
freeing cltnOfScalars .
circulant:
+ circulant : cltnOfScalars
Creates a new n by n circulant matrix for a collection of n
scalar objects. You remain responsible for freeing
cltnOfScalars .
companion:
+ companion : cltnOfScalars
Creates a new n by n companion matrix for a collection of n
scalar objects. You remain responsible for freeing
cltnOfScalars .
hankel::
+ hankel : rowScalars : colScalars
Creates a new rectangualr Hankel matrix, a matrix with n + 1
rows and m columns if rowScalars has m and colScalars
n members.
Page 3 (printed 6/28/99)
matrix(3) UNIX System V (Nov 25, 1998) matrix(3)
toeplitz::
+ toeplitz : rowScalars : colScalars
Creates a new rectangualr Toeplitz matrix, a matrix with n
rows and m + 1 columns if rowScalars has m and colScalars
n members.
hilbert:
+ hilbert :(int) n
Creates a new Hilbert matrix over the rational numbers. The
element at position i , j is 1 / (i+j+1) .
scalar:numRows:numColumns:
+ scalar : aScalar numRows :(int) numRows numColumns
:(int) numColumns
Creates a new numRows by numColumns matrix with zero
elements, and with copies of aScalar on the diagonal. For
example, the 5 by 5 identity matrix over the polynomials
with integer coefficients is created like this :
aPolynomial = [Polynomial new];
aMatrix = [Matrix scalar:aPolynomial numRows:5
numColumns:5];
See also:
- one
copy
- copy
Returns a new copy of the original; the rows are also copies
of the original rows, not just new references.
deepCopy
- deepCopy
Makes a fully independent copy of the matrix.
emptyVector
- emptyVector
Returns a new empty vector.
clear
- clear
Frees the rows in the matrix.
Page 4 (printed 6/28/99)
matrix(3) UNIX System V (Nov 25, 1998) matrix(3)
scalarZero
- scalarZero
Returns the zero scalar element. You may not free or modify
the object returned by this method.
rows
- rows
Returns the collection of row vectors; the first row is the
first member of this collection. You may not modify or free
the object returned by this method.
numRows
- ( int ) numRows
Returns the number of rows in the matrix, or zero if there
are no rows in the matrix. If numRows is equal to zero,
numColumns is zero too, but not vice-versa.
numColumns
- ( int ) numColumns
Returns the number of columns in the matrix, or zero if
there are no columns in the matrix. Note that if numColumns
is equal to zero, it's still possible that numRows is not
equal to zero; in other words, if there are no columns in
the matrix, there can be empty vectors as rows.
isEqual:
- ( BOOL ) isEqual : aMatrix
Returns YES if the matrices have the same number of rows and
columns and if the scalars are equal.
hash
- ( unsigned ) hash
Returns a small integer that is the same for matrices that
are equal (in the sense of isEqual: ).
isDiagonal
- ( BOOL ) isDiagonal
Returns YES if all scalars that are not on the diagonal of
the matrix, are zero.
isSymmetric
- ( BOOL ) isSymmetric
Returns YES if the scalar at position i , j is equal to the
scalar at j , i .
Page 5 (printed 6/28/99)
matrix(3) UNIX System V (Nov 25, 1998) matrix(3)
isAntiSymmetric
- ( BOOL ) isAntiSymmetric
Returns YES if the scalar at position i , j is the opposite
of the scalar at j , i .
insertRow:
- insertRow : aVector
Inserts aVector as last row in the collection of rows and
returns self . The vector belongs after insertion to the
matrix, and is not necessarily copied. If there were
already rows in the matrix, the vector must contain the same
number of scalars. To insert rows, the reference count of
the matrix should be equal to one.
insertRow:at:
- insertRow : aVector at :(int) i
Similar to insertRow: but inserts at position i . If i is
equal to the number of rows, this method is identical to
insertRow: . If i is equal to zero, this method inserts
the vector as first row in the matrix.
insertColumn:
- insertColumn : aCollection
Inserts aCollection in the matrix as first column and
returns self . The collection and its members belong after
insertion to the matrix, and are not necessarily copied.
The number of rows of the matrix should be equal to the
number of scalars in the collection, and the reference count
of the matrix should be equal to one.
insertColumn:at:
- insertColumn : aCollection at :(int) i
Similar to insertColumn: but inserts at position i . If i
is equal to zero, this method is identical to insertColumn:
. If i is equal to the number of columns, this method
inserts the collection as last column in the matrix.
removeRow
- removeRow
Removes (and returns) the last row of the matrix. Returns
nil if there are no rows in the matrix. This can be used in
the following way :
while (row = [matrix removeRow]) { /* do something with
row */ }
Page 6 (printed 6/28/99)
matrix(3) UNIX System V (Nov 25, 1998) matrix(3)
To remove a row, the reference count of the matrix must be
equal to one.
removeRowAt:
- removeRowAt :(int) i
Similar to removeRow , but removes the i -th row. If i is
equal the number of rows minus one, this method is identical
to removeRow . If i is equal to zero, then the method
removes the first row of the matrix. It's an error to use
an illegal index i or to attempt to remove a row from a
matrix whose reference count is not equal to one.
removeColumn
- removeColumn
Removes (and returns) the first column of the matrix. The
column is a collection of scalars, not a vector object.
Returns nil if there are no columns in the matrix. This can
be used in the following way :
while (column = [matrix removeColumn]) { /* do something
with column */ }
The reference count of the matrix must be equal to one.
removeColumnAt:
- removeColumnAt :(int) i
Similar to removeColumn , but removes the i -th column. If
i is equal to zero, this method is identical to removeColumn
. If i is equal to the number of columns minus one, then
the method removes the last column in the matrix. It's an
error to use an illegal index i or to attempt to remove a
column from a matrix whose reference count is not equal to
one.
placeScalar:at::
- placeScalar : aScalar at :(int) i :(int) j
Frees the scalar at position i , j and replaces it by the
scalar object aScalar . Returns self .
The scalar aScalar belongs, after placing, to the receiving
matrix object; it is not necessarily copied. It is an error
to use illegal indices i and j or to attempt to place a
scalar in a matrix whose reference count is not equal to
one.
replaceScalarAt::with:
- replaceScalarAt :(int) i :(int) j with : aScalar
Page 7 (printed 6/28/99)
matrix(3) UNIX System V (Nov 25, 1998) matrix(3)
Similar to placeScalar::at: but returns, rather than frees,
the scalar at position i , j after replacing it by aScalar .
asNumerical
- asNumerical
Returns a new matrix, whose scalars are the numerical value
of the scalars of the original matrix. For a matrix with
integer scalars, this method returns a matrix with
floating-point scalars.
asModp:
- asModp :(unsigned short) p
Returns a new matrix, whose scalars are the value of the
scalars of the original matrix mod p . For a matrix with
integer scalars, this method returns a matrix with
IntegerModp scalars.
onCommonDenominator:
- onCommonDenominator :(id *) denominator
Puts a matrix with fractional scalars on a common
denominator. Returns a new matrix with integral scalars,
and, by reference, the common denominator of the scalars in
the matrix (the least common multiple of the denominators of
the fractions in the matrix).
rowAt:
- rowAt :(int) i
Returns the i -th row of the matrix. You may not modify or
free the object returned by this method. The following
example is equivalent to using eachRow and sequencing over
the rows :
int i;
for(i=0;i<[aMatrix numRows];i++) {
id aRow = [aMatrix rowAt:i];
/* do something with aRow */
}
eachRow
- eachRow
Returns a new sequence of the rows of the matrix. You
cannot add or remove rows, or alter in any other way the
matrix, until you have freed the sequence object (the
sequence contains a reference to the rows of the matrix).
The i -th member in this sequence is the i -th row of the
matrix. The following example is equivalent to using rowAt:
Page 8 (printed 6/28/99)
matrix(3) UNIX System V (Nov 25, 1998) matrix(3)
for indices between 0 and numRows :
id aRow,aSequence;
aSequence = [aMatrix eachRow];
while (aRow = [aSequence next]) {
/* do something with aRow */
}
aSequence = [aSequence free];
eachScalar
- eachScalar
Returns a new sequence of scalars, obtained by concatenating
the sequences of scalars of all row vectors of the matrix.
If the matrix contains m rows and n columns, then the
sequence contains m times n members. You cannot add or
remove scalars, or alter in any other way the matrix, until
you have freed the sequence object (the sequence contains a
reference to the matrix).
Note:
The sequence returned by this method cannot be accessed
through an index. It doesn't implement the at: and
toElementAt: methods.
eachSequence
- eachSequence
Returns a new sequence of sequences of scalars. You cannot
add or remove scalars, or alter in any other way the matrix,
until you have freed the sequence object (the sequence
contains a reference to the matrix). The following example
shows how to access the i -th sequence of scalars, and in
that sequence, the j -th scalar object :
aSequence = [aMatrix eachSequence];
aScalar = [[aSequence at:i] at:j];
/* do something here with aScalar */
aSequence = [aSequence free];
floatValueAt::
- ( float ) floatValueAt :(int) i :(int) j
Returns the floatValue of the scalar at row index i and
column index j .
zero
Page 9 (printed 6/28/99)
matrix(3) UNIX System V (Nov 25, 1998) matrix(3)
- zero
Returns a zero matrix of the same dimensions as the matrix
that receives the message.
negate
- negate
Negates the matrix row by row.
double
- double
Returns a new matrix equal to the matrix multiplied by two.
Multiplies the matrix row by row by two.
add:
- add : b
Returns a new matrix equal to the sum of the two matrices.
Adds the matrices row by row together.
subtract:
- subtract : b
Returns a new matrix equal to the difference of the two
matrices. Subtracts the matrices row by row from each
other.
addScalar:
- addScalar : s
Adds the scalar s to the diagonal of the matrix. Returns a
new object.
subtractScalar:
- subtractScalar : s
Subtracts the scalar s from the diagonal of the matrix.
Returns a new object.
one
- one
Returns the (right) unity matrix of the same dimensions as
the matrix that receives the message.
square
- square
Multiplies the (square) matrix by itself.
Page 10 (printed 6/28/99)
matrix(3) UNIX System V (Nov 25, 1998) matrix(3)
multiply:
- multiply : b
Returns the product self b . The number of columns of self
must match the number of rows of b .
multiplyVector:
- multiplyVector : aColumn
Returns a new vector, the product of the matrix by a column
vector object. The number of rows of the matrix must match
the number of scalars in the vector.
multiplyScalar:
- multiplyScalar : b
Returns the matrix multiplied (to the right) by the scalar b
.
divideScalar:
- divideScalar : b
Returns the matrix divided by the scalar b . Returns nil if
the division was not exact for some scalar in the matrix.
transpose
- transpose
Returns the transposed of the matrix (a new matrix object).
If the matrix has m rows and n columns, the transposed
matrix has n rows and m columns.
determinant
- determinant
Computes the determinant of the square matrix. Returns a
new scalar object.
For fields of fractions, the method will extract a common
denominator for the scalars, and compute the determinant
over the associated integral domain. For fields that are
not fields of fractions, the method computes the determinant
by Gaussian elimination taking inverses of leading non-zero
elements. For matrices over an integral domain, the
determinant is computed by the Bareiss method.
Note:
You can't compute a determinant over the floating-point
numbers yet.
solveVector:
Page 11 (printed 6/28/99)
matrix(3) UNIX System V (Nov 25, 1998) matrix(3)
- solveVector : y
Returns a vector x that is the solution of the linear
equation A x = y with A the (non-singular) matrix and y a
column vector object.
The method works over fields and integral domains, but in
the latter case, the method looks for an integral (and
primitive i.e., common gcd divided out) solution only. It
will give an error message if the solution requires the
construction of the field of fractions.
inverse
- inverse
Returns the inverse of the matrix (a new matrix object).
The matrix must be square; if it is singular (determinant
equal to zero), the method returns nil . Implemented as a
special case of divide: , which computes A B^-1 .
divide:
- divide : b
Returns a new matrix, equal to the matrix multiplied to the
right by the inverse of the matrix b .
Note:
Currently matrix inversion only works over a field (by
Gaussian elimination).
rank
- ( int ) rank
Returns the dimension of the image of the matrix, without
computing the image vectors themselves. Works currently
only over a field.
nullity
- ( int ) nullity
Returns the dimension of the kernel (nullspace) of the
matrix, without computing the kernel itself. By the
dimension theorem, the nullity of the matrix is the number
of columns minus the rank of the matrix.
kernel
- kernel
Returns the kernel (or nullspace) of the matrix as a
collection of columns; each column is a vector object.
Works currently only over a field.
Page 12 (printed 6/28/99)
matrix(3) UNIX System V (Nov 25, 1998) matrix(3)
image
- image
Returns the image of the matrix as a collection of columns;
each column is a vector object. Works currently only over a
field.
trace
- trace
Returns a new scalar object, the trace of the square matrix,
ie. the sum of the scalars on the diagonal of the matrix.
adjoint
- adjoint
Returns a new matrix, the adjoint of the matrix computed
through repeated trace computations (ie. the Faddeev-
Leverrier method). If the characteristic of the scalars is
non-zero, it must be larger than the number of rows in the
matrix.
printOn:
- printOn :(IOD) aFile
Prints, between braces, a comma separated list of the rows.
Sends printOn: messages to the scalars in the matrix.
Page 13 (printed 6/28/99)
