.TH "matrix" 3 "Oct 12, 2003" .SH Matrix .PP .B Inherits from: CAObject .PP .B Maturity Index: Relatively mature .SH Class Description .PP A matrix consists of a number of .I scalars ordered in .I 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 .B inField ) or elements of an integral domain (see .B inIntegralDomain )\&. .PP There are methods to access, insert and remove rows and .I 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 .B eachSequence to access the scalar at a given row and column index\&. .PP .B 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\&. .SH Method types .PP .B Special Matrices .RS 3 .br * diagonal: .br * circulant: .br * companion: .br * hankel:: .br * toeplitz:: .br * hilbert: .RE .PP .B Creation .RS 3 .br * scalar:numRows:numColumns: .br * copy .br * deepCopy .br * emptyVector .RE .PP .B Identity .RS 3 .br * scalarZero .br * rows .br * numRows .br * numColumns .br * isEqual: .br * hash .br * isDiagonal .br * isSymmetric .br * isAntiSymmetric .RE .PP .B Insertion .RS 3 .br * insertRow: .br * insertRow:at: .br * insertColumn: .br * insertColumn:at: .RE .PP .B Removing .RS 3 .br * removeRow .br * removeRowAt: .br * removeColumn .br * removeColumnAt: .RE .PP .B Place and Replace .RS 3 .br * placeScalar:at:: .br * replaceScalarAt::with: .RE .PP .B Coercion .RS 3 .br * asNumerical .br * asModp: .br * onCommonDenominator: .RE .PP .B Accessing Rows and Scalars .RS 3 .br * rowAt: .br * eachRow .br * eachScalar .br * eachSequence .br * floatValueAt:: .RE .PP .B Addition .RS 3 .br * zero .br * negate .br * double .br * add: .br * subtract: .br * addScalar: .br * subtractScalar: .RE .PP .B Multiplication .RS 3 .br * one .br * square .br * multiply: .br * multiplyVector: .RE .PP .B Scalar Multiplication .RS 3 .br * multiplyScalar: .br * divideScalar: .RE .PP .B Transposing .RS 3 .br * transpose .RE .PP .B Gaussian Elimination .RS 3 .br * determinant .br * solveVector: .br * inverse .br * divide: .br * rank .br * nullity .br * kernel .br * image .RE .PP .B Trace Methods .RS 3 .br * trace .br * adjoint .RE .PP .B Printing .RS 3 .br * printOn: .RE .SH Methods .PP diagonal: .RS 1 + .B diagonal : .I cltnOfScalars .RE .PP Creates a new, square matrix with the objects in .I cltnOfScalars on the diagonal\&. .PP circulant: .RS 1 + .B circulant : .I cltnOfScalars .RE .PP Creates a new .I n by .I n circulant matrix for a collection of .I n scalar objects\&. .PP companion: .RS 1 + .B companion : .I cltnOfScalars .RE .PP Creates a new .I n by .I n companion matrix for a collection of .I n scalar objects\&. .PP hankel:: .RS 1 + .B hankel : .I rowScalars : .I colScalars .RE .PP Creates a new rectangualr Hankel matrix, a matrix with .I n + 1 rows and .I m columns if .I rowScalars has .I m and .I colScalars .I n members\&. .PP toeplitz:: .RS 1 + .B toeplitz : .I rowScalars : .I colScalars .RE .PP Creates a new rectangualr Toeplitz matrix, a matrix with .I n rows and .I m + 1 columns if .I rowScalars has .I m and .I colScalars .I n members\&. .PP hilbert: .RS 1 + .B hilbert :(int) .I n .RE .PP Creates a new Hilbert matrix over the rational numbers\&. The element at position .I i , .I j is .I 1 / (i+j+1) \&. .PP scalar:numRows:numColumns: .RS 1 + .B scalar : .I aScalar .B numRows :(int) .I numRows .B numColumns :(int) .I numColumns .RE .PP Creates a new .I numRows by .I numColumns matrix with zero elements, and with copies of .I aScalar on the diagonal\&. For example, the 5 by 5 identity matrix over the polynomials with integer coefficients is created like this : .RS 3 aPolynomial = [Polynomial new]; .br aMatrix = [Matrix scalar:aPolynomial numRows:5 numColumns:5]; .br .RE .PP .B See also: - one .PP copy .RS 1 - .B copy .RE .PP Returns a new copy of the original; the rows are also copies of the original rows, not just new references\&. .PP deepCopy .RS 1 - .B deepCopy .RE .PP Makes a fully independent copy of the matrix\&. .PP emptyVector .RS 1 - .B emptyVector .RE .PP Returns a new empty vector\&. .PP scalarZero .RS 1 - .B scalarZero .RE .PP Returns the zero scalar element\&. .PP rows .RS 1 - .B rows .RE .PP Returns the collection of row vectors; the first row is the first member of this collection\&. .PP numRows .RS 1 - ( int ) .B numRows .RE .PP Returns the number of rows in the matrix, or zero if there are no rows in the matrix\&. If .B numRows is equal to zero, .B numColumns is zero too, but not vice-versa\&. .PP numColumns .RS 1 - ( int ) .B numColumns .RE .PP Returns the number of columns in the matrix, or zero if there are no columns in the matrix\&. Note that if .B numColumns is equal to zero, it\&'s still possible that .B numRows is .I not equal to zero; in other words, if there are no columns in the matrix, there can be empty vectors as rows\&. .PP isEqual: .RS 1 - ( BOOL ) .B isEqual : .I aMatrix .RE .PP Returns YES if the matrices have the same number of rows and columns and if the scalars are equal\&. .PP hash .RS 1 - ( unsigned ) .B hash .RE .PP Returns a small integer that is the same for matrices that are equal (in the sense of .B isEqual: )\&. .PP isDiagonal .RS 1 - ( BOOL ) .B isDiagonal .RE .PP Returns YES if all scalars that are not on the diagonal of the matrix, are zero\&. .PP isSymmetric .RS 1 - ( BOOL ) .B isSymmetric .RE .PP Returns YES if the scalar at position .I i , .I j is equal to the scalar at .I j , .I i \&. .PP isAntiSymmetric .RS 1 - ( BOOL ) .B isAntiSymmetric .RE .PP Returns YES if the scalar at position .I i , .I j is the opposite of the scalar at .I j , .I i \&. .PP insertRow: .RS 1 - .B insertRow : .I aVector .RE .PP Inserts .I aVector as last row in the collection of rows and returns .B 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\&. .PP insertRow:at: .RS 1 - .B insertRow : .I aVector .B at :(int) .I i .RE .PP Similar to .B insertRow: but inserts at position .I i \&. If .I i is equal to the number of rows, this method is identical to .B insertRow: \&. If .I i is equal to zero, this method inserts the vector as first row in the matrix\&. .PP insertColumn: .RS 1 - .B insertColumn : .I aCollection .RE .PP Inserts .I aCollection in the matrix as first column and returns .B 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\&. .PP insertColumn:at: .RS 1 - .B insertColumn : .I aCollection .B at :(int) .I i .RE .PP Similar to .B insertColumn: but inserts at position .I i \&. If .I i is equal to zero, this method is identical to .B insertColumn: \&. If .I i is equal to the number of columns, this method inserts the collection as last column in the matrix\&. .PP removeRow .RS 1 - .B removeRow .RE .PP Removes (and returns) the last row of the matrix\&. Returns .B nil if there are no rows in the matrix\&. This can be used in the following way : .RS 3 while (row = [matrix removeRow]) { /* do something with row */ } .br .RE .PP To remove a row, the reference count of the matrix must be equal to one\&. .PP removeRowAt: .RS 1 - .B removeRowAt :(int) .I i .RE .PP Similar to .B removeRow , but removes the .I i -th row\&. If .I i is equal the number of rows minus one, this method is identical to .B removeRow \&. If .I 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 i or to attempt to remove a row from a matrix whose reference count is not equal to one\&. .PP removeColumn .RS 1 - .B removeColumn .RE .PP Removes (and returns) the first column of the matrix\&. The column is a collection of scalars, not a vector object\&. Returns .B nil if there are no columns in the matrix\&. This can be used in the following way : .RS 3 while (column = [matrix removeColumn]) { /* do something with column */ } .br .RE .PP The reference count of the matrix must be equal to one\&. .PP removeColumnAt: .RS 1 - .B removeColumnAt :(int) .I i .RE .PP Similar to .B removeColumn , but removes the .I i -th column\&. If .I i is equal to zero, this method is identical to .B removeColumn \&. If .I 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 i or to attempt to remove a column from a matrix whose reference count is not equal to one\&. .PP placeScalar:at:: .RS 1 - .B placeScalar : .I aScalar .B at :(int) .I i :(int) .I j .RE .PP Frees the scalar at position .I i , .I j and replaces it by the scalar object .I aScalar \&. Returns .B self \&. .PP The scalar .I aScalar belongs, after placing, to the receiving matrix object; it is not necessarily copied\&. It is an error to use illegal indices .I i and .I j or to attempt to place a scalar in a matrix whose reference count is not equal to one\&. .PP replaceScalarAt::with: .RS 1 - .B replaceScalarAt :(int) .I i :(int) .I j .B with : .I aScalar .RE .PP Similar to .B placeScalar::at: but returns the scalar at position .I i , .I j after replacing it by .I aScalar \&. .PP asNumerical .RS 1 - .B asNumerical .RE .PP 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\&. .PP asModp: .RS 1 - .B asModp :(unsigned short) .I p .RE .PP Returns a new matrix, whose scalars are the value of the scalars of the original matrix mod .I p \&. For a matrix with integer scalars, this method returns a matrix with IntegerModp scalars\&. .PP onCommonDenominator: .RS 1 - .B onCommonDenominator :(id *) .I denominator .RE .PP 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)\&. .PP rowAt: .RS 1 - .B rowAt :(int) .I i .RE .PP Returns the .I i -th row of the matrix\&. The following example is equivalent to using .B eachRow and sequencing over the rows : .RS 3 int i; .br for(i=0;i<[aMatrix numRows];i++) { .br id aRow = [aMatrix rowAt:i]; .br /* do something with aRow */ .br } .br .RE .PP eachRow .RS 1 - .B eachRow .RE .PP 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 i -th member in this sequence is the .I i -th row of the matrix\&. The following example is equivalent to using .B rowAt: for indices between 0 and .B numRows : .RS 3 id aRow,aSequence; .br aSequence = [aMatrix eachRow]; .br while (aRow = [aSequence next]) { .br /* do something with aRow */ .br } .br .RE .PP eachScalar .RS 1 - .B eachScalar .RE .PP Returns a new sequence of scalars, obtained by concatenating the sequences of scalars of all row vectors of the matrix\&. If the matrix contains .I m rows and .I n columns, then the sequence contains .I m times .I 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)\&. .PP .B Note: The sequence returned by this method cannot be accessed through an index\&. It doesn\&'t implement the .B at: and .B toElementAt: methods\&. .PP eachSequence .RS 1 - .B eachSequence .RE .PP 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 i -th sequence of scalars, and in that sequence, the .I j -th scalar object : .RS 3 aSequence = [aMatrix eachSequence]; .br aScalar = [[aSequence at:i] at:j]; .br .br /* do something here with aScalar */ .br .br .RE .PP floatValueAt:: .RS 1 - ( float ) .B floatValueAt :(int) .I i :(int) .I j .RE .PP Returns the .B floatValue of the scalar at row index .I i and column index .I j \&. .PP zero .RS 1 - .B zero .RE .PP Returns a zero matrix of the same dimensions as the matrix that receives the message\&. .PP negate .RS 1 - .B negate .RE .PP Negates the matrix row by row\&. .PP double .RS 1 - .B double .RE .PP Returns a new matrix equal to the matrix multiplied by two\&. Multiplies the matrix row by row by two\&. .PP add: .RS 1 - .B add : .I b .RE .PP Returns a new matrix equal to the sum of the two matrices\&. Adds the matrices row by row together\&. .PP subtract: .RS 1 - .B subtract : .I b .RE .PP Returns a new matrix equal to the difference of the two matrices\&. Subtracts the matrices row by row from each other\&. .PP addScalar: .RS 1 - .B addScalar : .I s .RE .PP Adds the scalar .I s to the diagonal of the matrix\&. Returns a new object\&. .PP subtractScalar: .RS 1 - .B subtractScalar : .I s .RE .PP Subtracts the scalar .I s from the diagonal of the matrix\&. Returns a new object\&. .PP one .RS 1 - .B one .RE .PP Returns the (right) unity matrix of the same dimensions as the matrix that receives the message\&. .PP square .RS 1 - .B square .RE .PP Multiplies the (square) matrix by itself\&. .PP multiply: .RS 1 - .B multiply : .I b .RE .PP Returns the product .I self b \&. The number of columns of .I self must match the number of rows of .I b \&. .PP multiplyVector: .RS 1 - .B multiplyVector : .I aColumn .RE .PP 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\&. .PP multiplyScalar: .RS 1 - .B multiplyScalar : .I b .RE .PP Returns the matrix multiplied (to the right) by the scalar .I b \&. .PP divideScalar: .RS 1 - .B divideScalar : .I b .RE .PP Returns the matrix divided by the scalar .I b \&. Returns .B nil if the division was not exact for some scalar in the matrix\&. .PP transpose .RS 1 - .B transpose .RE .PP Returns the transposed of the matrix (a new matrix object)\&. If the matrix has .I m rows and .I n columns, the transposed matrix has .I n rows and .I m columns\&. .PP determinant .RS 1 - .B determinant .RE .PP Computes the determinant of the square matrix\&. Returns a new scalar object\&. .PP 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\&. .PP .B Note: You can\&'t compute a determinant over the floating-point numbers yet\&. .PP solveVector: .RS 1 - .B solveVector : .I y .RE .PP Returns a vector .I x that is the solution of the linear equation .I A x = y with .I A the (non-singular) matrix and .I y a column vector object\&. .PP 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\&. .PP inverse .RS 1 - .B inverse .RE .PP 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 .B nil \&. Implemented as a special case of .B divide: , which computes .I A B^-1 \&. .PP divide: .RS 1 - .B divide : .I b .RE .PP Returns a new matrix, equal to the matrix multiplied to the right by the inverse of the matrix .I b \&. .PP .B Note: Currently matrix inversion only works over a field (by Gaussian elimination)\&. .PP rank .RS 1 - ( int ) .B rank .RE .PP Returns the dimension of the image of the matrix, without computing the image vectors themselves\&. Works currently only over a field\&. .PP nullity .RS 1 - ( int ) .B nullity .RE .PP 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\&. .PP kernel .RS 1 - .B kernel .RE .PP 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\&. .PP image .RS 1 - .B image .RE .PP Returns the image of the matrix as a collection of columns; each column is a vector object\&. Works currently only over a field\&. .PP trace .RS 1 - .B trace .RE .PP Returns a new scalar object, the trace of the square matrix, ie\&. the sum of the scalars on the diagonal of the matrix\&. .PP adjoint .RS 1 - .B adjoint .RE .PP 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\&. .PP printOn: .RS 1 - .B printOn :(IOD) .I aFile .RE .PP Prints, between braces, a comma separated list of the rows\&. Sends .B printOn: messages to the scalars in the matrix\&.