1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.math.linear;
19
20
21 /**
22 * An interface to classes that implement an algorithm to calculate the
23 * eigen decomposition of a real matrix.
24 * <p>The eigen decomposition of matrix A is a set of two matrices:
25 * V and D such that A = V × D × V<sup>T</sup>.
26 * A, V and D are all m × m matrices.</p>
27 * <p>This interface is similar in spirit to the <code>EigenvalueDecomposition</code>
28 * class from the now defunct <a href="http://math.nist.gov/javanumerics/jama/">JAMA</a>
29 * library, with the following changes:</p>
30 * <ul>
31 * <li>a {@link #getVT() getVt} method has been added,</li>
32 * <li>two {@link #getRealEigenvalue(int) getRealEigenvalue} and {@link #getImagEigenvalue(int)
33 * getImagEigenvalue} methods to pick up a single eigenvalue have been added,</li>
34 * <li>a {@link #getEigenvector(int) getEigenvector} method to pick up a single
35 * eigenvector has been added,</li>
36 * <li>a {@link #getDeterminant() getDeterminant} method has been added.</li>
37 * <li>a {@link #getSolver() getSolver} method has been added.</li>
38 * </ul>
39 * @see <a href="http://mathworld.wolfram.com/EigenDecomposition.html">MathWorld</a>
40 * @see <a href="http://en.wikipedia.org/wiki/Eigendecomposition_of_a_matrix">Wikipedia</a>
41 * @version $Revision: 799857 $ $Date: 2009-08-01 09:07:12 -0400 (Sat, 01 Aug 2009) $
42 * @since 2.0
43 */
44 public interface EigenDecomposition {
45
46 /**
47 * Returns the matrix V of the decomposition.
48 * <p>V is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
49 * <p>The columns of V are the eigenvectors of the original matrix.</p>
50 * @return the V matrix
51 */
52 RealMatrix getV();
53
54 /**
55 * Returns the block diagonal matrix D of the decomposition.
56 * <p>D is a block diagonal matrix.</p>
57 * <p>Real eigenvalues are on the diagonal while complex values are on
58 * 2x2 blocks { {real +imaginary}, {-imaginary, real} }.</p>
59 * @return the D matrix
60 * @see #getRealEigenvalues()
61 * @see #getImagEigenvalues()
62 */
63 RealMatrix getD();
64
65 /**
66 * Returns the transpose of the matrix V of the decomposition.
67 * <p>V is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
68 * <p>The columns of V are the eigenvectors of the original matrix.</p>
69 * @return the transpose of the V matrix
70 */
71 RealMatrix getVT();
72
73 /**
74 * Returns a copy of the real parts of the eigenvalues of the original matrix.
75 * @return a copy of the real parts of the eigenvalues of the original matrix
76 * @see #getD()
77 * @see #getRealEigenvalue(int)
78 * @see #getImagEigenvalues()
79 */
80 double[] getRealEigenvalues();
81
82 /**
83 * Returns the real part of the i<sup>th</sup> eigenvalue of the original matrix.
84 * @param i index of the eigenvalue (counting from 0)
85 * @return real part of the i<sup>th</sup> eigenvalue of the original matrix
86 * @see #getD()
87 * @see #getRealEigenvalues()
88 * @see #getImagEigenvalue(int)
89 */
90 double getRealEigenvalue(int i);
91
92 /**
93 * Returns a copy of the imaginary parts of the eigenvalues of the original matrix.
94 * @return a copy of the imaginary parts of the eigenvalues of the original matrix
95 * @see #getD()
96 * @see #getImagEigenvalue(int)
97 * @see #getRealEigenvalues()
98 */
99 double[] getImagEigenvalues();
100
101 /**
102 * Returns the imaginary part of the i<sup>th</sup> eigenvalue of the original matrix.
103 * @param i index of the eigenvalue (counting from 0)
104 * @return imaginary part of the i<sup>th</sup> eigenvalue of the original matrix
105 * @see #getD()
106 * @see #getImagEigenvalues()
107 * @see #getRealEigenvalue(int)
108 */
109 double getImagEigenvalue(int i);
110
111 /**
112 * Returns a copy of the i<sup>th</sup> eigenvector of the original matrix.
113 * @param i index of the eigenvector (counting from 0)
114 * @return copy of the i<sup>th</sup> eigenvector of the original matrix
115 * @see #getD()
116 */
117 RealVector getEigenvector(int i);
118
119 /**
120 * Return the determinant of the matrix
121 * @return determinant of the matrix
122 */
123 double getDeterminant();
124
125 /**
126 * Get a solver for finding the A × X = B solution in exact linear sense.
127 * @return a solver
128 */
129 DecompositionSolver getSolver();
130
131 }