Google

matrix Specification Sheet

Computer Algebra Kit (c) 1993,00 by Comp.Alg.Objects. All Rights Reserved.

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

Creation

Identity

Insertion

Removing

Place and Replace

Coercion

Accessing Rows and Scalars

Addition

Multiplication

Scalar Multiplication

Transposing

Gaussian Elimination

Trace Methods

Printing

Methods

diagonal:

+diagonal:cltnOfScalars
Creates a new, square matrix with the objects in cltnOfScalars on the diagonal.

circulant:

+circulant:cltnOfScalars
Creates a new n by n circulant matrix for a collection of n scalar objects.

companion:

+companion:cltnOfScalars
Creates a new n by n companion matrix for a collection of n scalar objects.

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.

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:aScalarnumRows:(int)numRowsnumColumns:(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.

scalarZero

-scalarZero
Returns the zero scalar element.

rows

-rows
Returns the collection of row vectors; the first row is the first member of this collection.

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.

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:aVectorat:(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:aCollectionat:(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 */ }
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:aScalarat:(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)jwith:aScalar
Similar to placeScalar::at: but returns 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. 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're done with 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: for indices between 0 and numRows :

id aRow,aSequence;
aSequence = [aMatrix eachRow];
while (aRow = [aSequence next]) {
    /* do something with aRow */
}

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're done with 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're done with 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 */

floatValueAt::

- (float)floatValueAt:(int)i:(int)j
Returns the floatValue of the scalar at row index i and column index j.

zero

-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.

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:

-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.

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.