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

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

1		/*
2		* Copyright 2003-2005 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		/**
20		* Interface defining a real-valued matrix with basic algebraic operations.
21		* <p>
22		* Matrix element indexing is 0-based -- e.g., <code>getEntry(0, 0)</code>
23		* returns the element in the first row, first column of the matrix.
24		*
25		* @version $Revision$ $Date: 2005-07-02 15:38:00 -0700 (Sat, 02 Jul 2005) $
26		*/
27		public interface RealMatrix {
28		/**
29		* Returns a (deep) copy of this.
30		*
31		* @return matrix copy
32		*/
33		RealMatrix copy();
34
35		/**
36		* Compute the sum of this and m.
37		*
38		* @param m matrix to be added
39		* @return this + m
40		* @throws IllegalArgumentException if m is not the same size as this
41		*/
42		RealMatrix add(RealMatrix m) throws IllegalArgumentException;
43
44		/**
45		* Compute this minus m.
46		*
47		* @param m matrix to be subtracted
48		* @return this + m
49		* @throws IllegalArgumentException if m is not the same size as this
50		*/
51		RealMatrix subtract(RealMatrix m) throws IllegalArgumentException;
52
53		/**
54		* Returns the result of adding d to each entry of this.
55		*
56		* @param d value to be added to each entry
57		* @return d + this
58		*/
59		RealMatrix scalarAdd(double d);
60
61		/**
62		* Returns the result multiplying each entry of this by d.
63		*
64		* @param d value to multiply all entries by
65		* @return d * this
66		*/
67		RealMatrix scalarMultiply(double d);
68
69		/**
70		* Returns the result of postmultiplying this by m.
71		*
72		* @param m matrix to postmultiply by
73		* @return this * m
74		* @throws IllegalArgumentException
75		* if columnDimension(this) != rowDimension(m)
76		*/
77		RealMatrix multiply(RealMatrix m) throws IllegalArgumentException;
78
79		/**
80		* Returns the result premultiplying this by <code>m</code>.
81		* @param m matrix to premultiply by
82		* @return m * this
83		* @throws IllegalArgumentException
84		* if rowDimension(this) != columnDimension(m)
85		*/
86		public RealMatrix preMultiply(RealMatrix m) throws IllegalArgumentException;
87
88		/**
89		* Returns matrix entries as a two-dimensional array.
90		*
91		* @return 2-dimensional array of entries
92		*/
93		double[][] getData();
94
95		/**
96		* Returns the <a href="http://mathworld.wolfram.com/MaximumAbsoluteRowSumNorm.html">
97		* maximum absolute row sum norm</a> of the matrix.
98		*
99		* @return norm
100		*/
101		double getNorm();
102
103		/**
104		* Gets a submatrix. Rows and columns are indicated
105		* counting from 0 to n-1.
106		*
107		* @param startRow Initial row index
108		* @param endRow Final row index
109		* @param startColumn Initial column index
110		* @param endColumn Final column index
111		* @return The subMatrix containing the data of the
112		* specified rows and columns
113		* @exception MatrixIndexException if the indices are not valid
114		*/
115		RealMatrix getSubMatrix(int startRow, int endRow, int startColumn,
116		int endColumn) throws MatrixIndexException;
117
118		/**
119		* Gets a submatrix. Rows and columns are indicated
120		* counting from 0 to n-1.
121		*
122		* @param selectedRows Array of row indices.
123		* @param selectedColumns Array of column indices.
124		* @return The subMatrix containing the data in the
125		* specified rows and columns
126		* @exception MatrixIndexException if row or column selections are not valid
127		*/
128		RealMatrix getSubMatrix(int[] selectedRows, int[] selectedColumns)
129		throws MatrixIndexException;
130
131		/**
132		* Returns the entries in row number <code>row</code>
133		* as a row matrix. Row indices start at 0.
134		*
135		* @param row the row to be fetched
136		* @return row matrix
137		* @throws MatrixIndexException if the specified row index is invalid
138		*/
139		RealMatrix getRowMatrix(int row) throws MatrixIndexException;
140
141		/**
142		* Returns the entries in column number <code>column</code>
143		* as a column matrix. Column indices start at 0.
144		*
145		* @param column the column to be fetched
146		* @return column matrix
147		* @throws MatrixIndexException if the specified column index is invalid
148		*/
149		RealMatrix getColumnMatrix(int column) throws MatrixIndexException;
150
151		/**
152		* Returns the entries in row number <code>row</code> as an array.
153		* <p>
154		* Row indices start at 0. A <code>MatrixIndexException</code> is thrown
155		* unless <code>0 <= row < rowDimension.</code>
156		*
157		* @param row the row to be fetched
158		* @return array of entries in the row
159		* @throws MatrixIndexException if the specified row index is not valid
160		*/
161		double[] getRow(int row) throws MatrixIndexException;
162
163		/**
164		* Returns the entries in column number <code>col</code> as an array.
165		* <p>
166		* Column indices start at 0. A <code>MatrixIndexException</code> is thrown
167		* unless <code>0 <= column < columnDimension.</code>
168		*
169		* @param col the column to be fetched
170		* @return array of entries in the column
171		* @throws MatrixIndexException if the specified column index is not valid
172		*/
173		double[] getColumn(int col) throws MatrixIndexException;
174
175		/**
176		* Returns the entry in the specified row and column.
177		* <p>
178		* Row and column indices start at 0 and must satisfy
179		* <ul>
180		* <li><code>0 <= row < rowDimension</code></li>
181		* <li><code> 0 <= column < columnDimension</code></li>
182		* </ul>
183		* otherwise a <code>MatrixIndexException</code> is thrown.
184		*
185		* @param row row location of entry to be fetched
186		* @param column column location of entry to be fetched
187		* @return matrix entry in row,column
188		* @throws MatrixIndexException if the row or column index is not valid
189		*/
190		double getEntry(int row, int column) throws MatrixIndexException;
191
192		/**
193		* Returns the transpose of this matrix.
194		*
195		* @return transpose matrix
196		*/
197		RealMatrix transpose();
198
199		/**
200		* Returns the inverse of this matrix.
201		*
202		* @return inverse matrix
203		* @throws InvalidMatrixException if this is not invertible
204		*/
205		RealMatrix inverse() throws InvalidMatrixException;
206
207		/**
208		* Returns the determinant of this matrix.
209		*
210		* @return determinant
211		*/
212		double getDeterminant();
213
214		/**
215		* Is this a square matrix?
216		* @return true if the matrix is square (rowDimension = columnDimension)
217		*/
218		boolean isSquare();
219
220		/**
221		* Is this a singular matrix?
222		* @return true if the matrix is singular
223		*/
224		boolean isSingular();
225
226		/**
227		* Returns the number of rows in the matrix.
228		*
229		* @return rowDimension
230		*/
231		int getRowDimension();
232
233		/**
234		* Returns the number of columns in the matrix.
235		*
236		* @return columnDimension
237		*/
238		int getColumnDimension();
239
240		/**
241		* Returns the <a href="http://mathworld.wolfram.com/MatrixTrace.html">
242		* trace</a> of the matrix (the sum of the elements on the main diagonal).
243		*
244		* @return trace
245		*/
246		double getTrace();
247
248		/**
249		* Returns the result of multiplying this by the vector <code>v</code>.
250		*
251		* @param v the vector to operate on
252		* @return this*v
253		* @throws IllegalArgumentException if columnDimension != v.size()
254		*/
255		double[] operate(double[] v) throws IllegalArgumentException;
256
257		/**
258		* Returns the (row) vector result of premultiplying this by the vector <code>v</code>.
259		*
260		* @param v the row vector to premultiply by
261		* @return v*this
262		* @throws IllegalArgumentException if rowDimension != v.size()
263		*/
264		double[] preMultiply(double[] v) throws IllegalArgumentException;
265
266		/**
267		* Returns the solution vector for a linear system with coefficient
268		* matrix = this and constant vector = <code>b</code>.
269		*
270		* @param b constant vector
271		* @return vector of solution values to AX = b, where A is *this
272		* @throws IllegalArgumentException if this.rowDimension != b.length
273		* @throws InvalidMatrixException if this matrix is not square or is singular
274		*/
275		double[] solve(double[] b) throws IllegalArgumentException, InvalidMatrixException;
276
277		/**
278		* Returns a matrix of (column) solution vectors for linear systems with
279		* coefficient matrix = this and constant vectors = columns of
280		* <code>b</code>.
281		*
282		* @param b matrix of constant vectors forming RHS of linear systems to
283		* to solve
284		* @return matrix of solution vectors
285		* @throws IllegalArgumentException if this.rowDimension != row dimension
286		* @throws InvalidMatrixException if this matrix is not square or is singular
287		*/
288		RealMatrix solve(RealMatrix b) throws IllegalArgumentException, InvalidMatrixException;
289		}
290