
matrix Specification SheetComputer Algebra Kit (c) 1993,00 by Comp.Alg.Objects. All Rights Reserved.
MatrixInherits from: CAObjectMaturity Index: Relatively mature
Class DescriptionA 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 floatingpoint, 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 typesSpecial MatricesCreationIdentityInsertionRemovingPlace and ReplaceCoercionAccessing Rows and ScalarsAdditionMultiplicationScalar MultiplicationTransposingGaussian EliminationTrace MethodsPrintingMethodsdiagonal:+diagonal:cltnOfScalarsCreates a new, square matrix with the objects in cltnOfScalars on the diagonal.
circulant:+circulant:cltnOfScalarsCreates a new n by n circulant matrix for a collection of n scalar objects.
companion:+companion:cltnOfScalarsCreates a new n by n companion matrix for a collection of n scalar objects.
hankel::+hankel:rowScalars:colScalarsCreates 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:colScalarsCreates 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)nCreates 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)numColumnsCreates 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 :
See also:  oneaPolynomial = [Polynomial new]; aMatrix = [Matrix scalar:aPolynomial numRows:5 numColumns:5];
copycopyReturns a new copy of the original; the rows are also copies of the original rows, not just new references.
deepCopydeepCopyMakes a fully independent copy of the matrix.
emptyVectoremptyVectorReturns a new empty vector.
scalarZeroscalarZeroReturns the zero scalar element.
rowsrowsReturns the collection of row vectors; the first row is the first member of this collection.
numRows (int)numRowsReturns 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 viceversa.
numColumns (int)numColumnsReturns 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:aMatrixReturns YES if the matrices have the same number of rows and columns and if the scalars are equal.
hash (unsigned)hashReturns a small integer that is the same for matrices that are equal (in the sense of isEqual:).
isDiagonal (BOOL)isDiagonalReturns YES if all scalars that are not on the diagonal of the matrix, are zero.
isSymmetric (BOOL)isSymmetricReturns YES if the scalar at position i,j is equal to the scalar at j,i.
isAntiSymmetric (BOOL)isAntiSymmetricReturns YES if the scalar at position i,j is the opposite of the scalar at j,i.
insertRow:insertRow:aVectorInserts 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)iSimilar 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:aCollectionInserts 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)iSimilar 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.
removeRowremoveRowRemoves (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 :
To remove a row, the reference count of the matrix must be equal to one.while (row = [matrix removeRow]) { /* do something with row */ }
removeRowAt:removeRowAt:(int)iSimilar to removeRow, but removes the ith 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.
removeColumnremoveColumnRemoves (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 :
The reference count of the matrix must be equal to one.while (column = [matrix removeColumn]) { /* do something with column */ }
removeColumnAt:removeColumnAt:(int)iSimilar to removeColumn, but removes the ith 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)jFrees 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:aScalarSimilar to placeScalar::at: but returns the scalar at position i,j after replacing it by aScalar.
asNumericalasNumericalReturns 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 floatingpoint scalars.
asModp:asModp:(unsigned short)pReturns 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 *)denominatorPuts 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)iReturns the ith 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 */ } eachRoweachRowReturns 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 ith member in this sequence is the ith 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 */ } eachScalareachScalarReturns 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.
eachSequenceeachSequenceReturns 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 ith sequence of scalars, and in that sequence, the jth scalar object :
aSequence = [aMatrix eachSequence]; aScalar = [[aSequence at:i] at:j]; /* do something here with aScalar */ floatValueAt:: (float)floatValueAt:(int)i:(int)jReturns the floatValue of the scalar at row index i and column index j.
zerozeroReturns a zero matrix of the same dimensions as the matrix that receives the message.
negatenegateNegates the matrix row by row.
doubledoubleReturns a new matrix equal to the matrix multiplied by two. Multiplies the matrix row by row by two.
add:add:bReturns a new matrix equal to the sum of the two matrices. Adds the matrices row by row together.
subtract:subtract:bReturns a new matrix equal to the difference of the two matrices. Subtracts the matrices row by row from each other.
addScalar:addScalar:sAdds the scalar s to the diagonal of the matrix. Returns a new object.
subtractScalar:subtractScalar:sSubtracts the scalar s from the diagonal of the matrix. Returns a new object.
oneoneReturns the (right) unity matrix of the same dimensions as the matrix that receives the message.
squaresquareMultiplies the (square) matrix by itself.
multiply:multiply:bReturns the product self b. The number of columns of self must match the number of rows of b.
multiplyVector:multiplyVector:aColumnReturns 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:bReturns the matrix multiplied (to the right) by the scalar b.
divideScalar:divideScalar:bReturns the matrix divided by the scalar b. Returns nil if the division was not exact for some scalar in the matrix.
transposetransposeReturns 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.
determinantdeterminantComputes 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 nonzero elements. For matrices over an integral domain, the determinant is computed by the Bareiss method. Note: You can't compute a determinant over the floatingpoint numbers yet.
solveVector:solveVector:yReturns a vector x that is the solution of the linear equation A x = y with A the (nonsingular) 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.
inverseinverseReturns 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:bReturns 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)rankReturns the dimension of the image of the matrix, without computing the image vectors themselves. Works currently only over a field.
nullity (int)nullityReturns 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.
kernelkernelReturns the kernel (or nullspace) of the matrix as a collection of columns; each column is a vector object. Works currently only over a field.
imageimageReturns the image of the matrix as a collection of columns; each column is a vector object. Works currently only over a field.
tracetraceReturns a new scalar object, the trace of the square matrix, ie. the sum of the scalars on the diagonal of the matrix.
adjointadjointReturns a new matrix, the adjoint of the matrix computed through repeated trace computations (ie. the FaddeevLeverrier method). If the characteristic of the scalars is nonzero, it must be larger than the number of rows in the matrix.
printOn:printOn:(IOD)aFilePrints, between braces, a comma separated list of the rows. Sends printOn: messages to the scalars in the matrix.
