Coverage Report - org.apache.commons.math.linear.BigMatrix

Classes in this File	Line Coverage	Branch Coverage	Complexity
BigMatrix	N/A	N/A	1.0;1

1		/*
2		* Copyright 2004 The Apache Software Foundation.
3		*
4		* Licensed under the Apache License, Version 2.0 (the "License");
5		* you may not use this file except in compliance with the License.
6		* You may obtain a copy of the License at
7		*
8		* http://www.apache.org/licenses/LICENSE-2.0
9		*
10		* Unless required by applicable law or agreed to in writing, software
11		* distributed under the License is distributed on an "AS IS" BASIS,
12		* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13		* See the License for the specific language governing permissions and
14		* limitations under the License.
15		*/
16
17		package org.apache.commons.math.linear;
18
19		import java.math.BigDecimal;
20
21		/**
22		* Interface defining a real-valued matrix with basic algebraic operations, using
23		* BigDecimal representations for the entries.
24		* <p>
25		* Matrix element indexing is 0-based -- e.g., <code>getEntry(0, 0)</code>
26		* returns the element in the first row, first column of the matrix.
27		*
28		* @version $Revision$ $Date: 2005-07-02 15:38:00 -0700 (Sat, 02 Jul 2005) $
29		*/
30		public interface BigMatrix {
31
32		/**
33		* Returns a (deep) copy of this.
34		*
35		* @return matrix copy
36		*/
37		BigMatrix copy();
38
39		/**
40		* Compute the sum of this and m.
41		*
42		* @param m matrix to be added
43		* @return this + m
44		* @exception IllegalArgumentException if m is not the same size as this
45		*/
46		BigMatrix add(BigMatrix m) throws IllegalArgumentException;
47
48		/**
49		* Compute this minus m.
50		*
51		* @param m matrix to be subtracted
52		* @return this + m
53		* @exception IllegalArgumentException if m is not the same size as this
54		*/
55		BigMatrix subtract(BigMatrix m) throws IllegalArgumentException;
56
57		/**
58		* Returns the result of adding d to each entry of this.
59		*
60		* @param d value to be added to each entry
61		* @return d + this
62		*/
63		BigMatrix scalarAdd(BigDecimal d);
64
65		/**
66		* Returns the result multiplying each entry of this by d.
67		*
68		* @param d value to multiply all entries by
69		* @return d * this
70		*/
71		BigMatrix scalarMultiply(BigDecimal d);
72
73		/**
74		* Returns the result of postmultiplying this by m.
75		*
76		* @param m matrix to postmultiply by
77		* @return this * m
78		* @throws IllegalArgumentException
79		* if columnDimension(this) != rowDimension(m)
80		*/
81		BigMatrix multiply(BigMatrix m) throws IllegalArgumentException;
82
83		/**
84		* Returns the result premultiplying this by <code>m</code>.
85		* @param m matrix to premultiply by
86		* @return m * this
87		* @throws IllegalArgumentException
88		* if rowDimension(this) != columnDimension(m)
89		*/
90		public BigMatrix preMultiply(BigMatrix m) throws IllegalArgumentException;
91
92		/**
93		* Returns matrix entries as a two-dimensional array.
94		*
95		* @return 2-dimensional array of entries
96		*/
97		BigDecimal[][] getData();
98
99		/**
100		* Returns matrix entries as a two-dimensional array.
101		*
102		* @return 2-dimensional array of entries
103		*/
104		double [][] getDataAsDoubleArray();
105
106		/***
107		* Gets the rounding mode
108		* @return the rounding mode
109		*/
110		int getRoundingMode();
111
112		/**
113		* Returns the <a href="http://mathworld.wolfram.com/MaximumAbsoluteRowSumNorm.html">
114		* maximum absolute row sum norm</a> of the matrix.
115		*
116		* @return norm
117		*/
118		BigDecimal getNorm();
119
120		/**
121		* Gets a submatrix. Rows and columns are indicated
122		* counting from 0 to n-1.
123		*
124		* @param startRow Initial row index
125		* @param endRow Final row index
126		* @param startColumn Initial column index
127		* @param endColumn Final column index
128		* @return The subMatrix containing the data of the
129		* specified rows and columns
130		* @exception MatrixIndexException if the indices are not valid
131		*/
132		BigMatrix getSubMatrix(int startRow, int endRow, int startColumn,
133		int endColumn) throws MatrixIndexException;
134
135		/**
136		* Gets a submatrix. Rows and columns are indicated
137		* counting from 0 to n-1.
138		*
139		* @param selectedRows Array of row indices.
140		* @param selectedColumns Array of column indices.
141		* @return The subMatrix containing the data in the
142		* specified rows and columns
143		* @exception MatrixIndexException if row or column selections are not valid
144		*/
145		BigMatrix getSubMatrix(int[] selectedRows, int[] selectedColumns)
146		throws MatrixIndexException;
147
148		/**
149		* Returns the entries in row number <code>row</code>
150		* as a row matrix. Row indices start at 0.
151		*
152		* @param row the row to be fetched
153		* @return row matrix
154		* @throws MatrixIndexException if the specified row index is invalid
155		*/
156		BigMatrix getRowMatrix(int row) throws MatrixIndexException;
157
158		/**
159		* Returns the entries in column number <code>column</code>
160		* as a column matrix. Column indices start at 0.
161		*
162		* @param column the column to be fetched
163		* @return column matrix
164		* @throws MatrixIndexException if the specified column index is invalid
165		*/
166		BigMatrix getColumnMatrix(int column) throws MatrixIndexException;
167
168		/**
169		* Returns the entries in row number <code>row</code> as an array.
170		* <p>
171		* Row indices start at 0. A <code>MatrixIndexException</code> is thrown
172		* unless <code>0 <= row < rowDimension.</code>
173		*
174		* @param row the row to be fetched
175		* @return array of entries in the row
176		* @throws MatrixIndexException if the specified row index is not valid
177		*/
178		BigDecimal[] getRow(int row) throws MatrixIndexException;
179
180		/**
181		* Returns the entries in row number <code>row</code> as an array
182		* of double values.
183		* <p>
184		* Row indices start at 0. A <code>MatrixIndexException</code> is thrown
185		* unless <code>0 <= row < rowDimension.</code>
186		*
187		* @param row the row to be fetched
188		* @return array of entries in the row
189		* @throws MatrixIndexException if the specified row index is not valid
190		*/
191		double [] getRowAsDoubleArray(int row) throws MatrixIndexException;
192
193		/**
194		* Returns the entries in column number <code>col</code> as an array.
195		* <p>
196		* Column indices start at 0. A <code>MatrixIndexException</code> is thrown
197		* unless <code>0 <= column < columnDimension.</code>
198		*
199		* @param col the column to be fetched
200		* @return array of entries in the column
201		* @throws MatrixIndexException if the specified column index is not valid
202		*/
203		BigDecimal[] getColumn(int col) throws MatrixIndexException;
204
205		/**
206		* Returns the entries in column number <code>col</code> as an array
207		* of double values.
208		* <p>
209		* Column indices start at 0. A <code>MatrixIndexException</code> is thrown
210		* unless <code>0 <= column < columnDimension.</code>
211		*
212		* @param col the column to be fetched
213		* @return array of entries in the column
214		* @throws MatrixIndexException if the specified column index is not valid
215		*/
216		double [] getColumnAsDoubleArray(int col) throws MatrixIndexException;
217
218		/**
219		* Returns the entry in the specified row and column.
220		* <p>
221		* Row and column indices start at 0 and must satisfy
222		* <ul>
223		* <li><code>0 <= row < rowDimension</code></li>
224		* <li><code> 0 <= column < columnDimension</code></li>
225		* </ul>
226		* otherwise a <code>MatrixIndexException</code> is thrown.
227		*
228		* @param row row location of entry to be fetched
229		* @param column column location of entry to be fetched
230		* @return matrix entry in row,column
231		* @throws MatrixIndexException if the row or column index is not valid
232		*/
233		BigDecimal getEntry(int row, int column) throws MatrixIndexException;
234
235		/**
236		* Returns the entry in the specified row and column as a double.
237		* <p>
238		* Row and column indices start at 0 and must satisfy
239		* <ul>
240		* <li><code>0 <= row < rowDimension</code></li>
241		* <li><code> 0 <= column < columnDimension</code></li>
242		* </ul>
243		* otherwise a <code>MatrixIndexException</code> is thrown.
244		*
245		* @param row row location of entry to be fetched
246		* @param column column location of entry to be fetched
247		* @return matrix entry in row,column
248		* @throws MatrixIndexException if the row or column index is not valid
249		*/
250		double getEntryAsDouble(int row, int column) throws MatrixIndexException;
251
252		/**
253		* Returns the transpose of this matrix.
254		*
255		* @return transpose matrix
256		*/
257		BigMatrix transpose();
258
259		/**
260		* Returns the inverse of this matrix.
261		*
262		* @return inverse matrix
263		* @throws org.apache.commons.math.linear.InvalidMatrixException if
264		* this is not invertible
265		*/
266		BigMatrix inverse() throws InvalidMatrixException;
267
268		/**
269		* Returns the determinant of this matrix.
270		*
271		* @return determinant
272		*@throws org.apache.commons.math.linear.InvalidMatrixException if
273		* matrix is not square
274		*/
275		BigDecimal getDeterminant() throws InvalidMatrixException;
276
277		/**
278		* Is this a square matrix?
279		* @return true if the matrix is square (rowDimension = columnDimension)
280		*/
281		boolean isSquare();
282
283		/**
284		* Is this a singular matrix?
285		* @return true if the matrix is singular
286		*/
287		boolean isSingular();
288
289		/**
290		* Returns the number of rows in the matrix.
291		*
292		* @return rowDimension
293		*/
294		int getRowDimension();
295
296		/**
297		* Returns the number of columns in the matrix.
298		*
299		* @return columnDimension
300		*/
301		int getColumnDimension();
302
303		/**
304		* Returns the <a href="http://mathworld.wolfram.com/MatrixTrace.html">
305		* trace</a> of the matrix (the sum of the elements on the main diagonal).
306		*
307		* @return trace
308		*/
309		BigDecimal getTrace();
310
311		/**
312		* Returns the result of multiplying this by the vector <code>v</code>.
313		*
314		* @param v the vector to operate on
315		* @return this*v
316		* @throws IllegalArgumentException if columnDimension != v.size()
317		*/
318		BigDecimal[] operate(BigDecimal[] v) throws IllegalArgumentException;
319
320		/**
321		* Returns the (row) vector result of premultiplying this by the vector <code>v</code>.
322		*
323		* @param v the row vector to premultiply by
324		* @return v*this
325		* @throws IllegalArgumentException if rowDimension != v.size()
326		*/
327		BigDecimal[] preMultiply(BigDecimal[] v) throws IllegalArgumentException;
328
329		/**
330		* Returns the solution vector for a linear system with coefficient
331		* matrix = this and constant vector = <code>b</code>.
332		*
333		* @param b constant vector
334		* @return vector of solution values to AX = b, where A is *this
335		* @throws IllegalArgumentException if this.rowDimension != b.length
336		* @throws org.apache.commons.math.linear.InvalidMatrixException if this matrix is not square or is singular
337		*/
338		BigDecimal[] solve(BigDecimal[] b) throws IllegalArgumentException, InvalidMatrixException;
339
340		/**
341		* Returns a matrix of (column) solution vectors for linear systems with
342		* coefficient matrix = this and constant vectors = columns of
343		* <code>b</code>.
344		*
345		* @param b matrix of constant vectors forming RHS of linear systems to
346		* to solve
347		* @return matrix of solution vectors
348		* @throws IllegalArgumentException if this.rowDimension != row dimension
349		* @throws org.apache.commons.math.linear.InvalidMatrixException if this matrix is not square or is singular
350		*/
351		BigMatrix solve(BigMatrix b) throws IllegalArgumentException, InvalidMatrixException;
352		}
353