View Javadoc
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.math3.linear;
19  
20  /**
21   * Interface handling decomposition algorithms that can solve A × X = B.
22   * <p>
23   * Decomposition algorithms decompose an A matrix has a product of several specific
24   * matrices from which they can solve A &times; X = B in least squares sense: they find X
25   * such that ||A &times; X - B|| is minimal.
26   * <p>
27   * Some solvers like {@link LUDecomposition} can only find the solution for
28   * square matrices and when the solution is an exact linear solution, i.e. when
29   * ||A &times; X - B|| is exactly 0. Other solvers can also find solutions
30   * with non-square matrix A and with non-null minimal norm. If an exact linear
31   * solution exists it is also the minimal norm solution.
32   *
33   * @version $Id: DecompositionSolver.java 1566017 2014-02-08 14:13:34Z tn $
34   * @since 2.0
35   */
36  public interface DecompositionSolver {
37  
38      /**
39       * Solve the linear equation A &times; X = B for matrices A.
40       * <p>
41       * The A matrix is implicit, it is provided by the underlying
42       * decomposition algorithm.
43       *
44       * @param b right-hand side of the equation A &times; X = B
45       * @return a vector X that minimizes the two norm of A &times; X - B
46       * @throws org.apache.commons.math3.exception.DimensionMismatchException
47       * if the matrices dimensions do not match.
48       * @throws SingularMatrixException if the decomposed matrix is singular.
49       */
50      RealVector solve(final RealVector b) throws SingularMatrixException;
51  
52      /**
53       * Solve the linear equation A &times; X = B for matrices A.
54       * <p>
55       * The A matrix is implicit, it is provided by the underlying
56       * decomposition algorithm.
57       *
58       * @param b right-hand side of the equation A &times; X = B
59       * @return a matrix X that minimizes the two norm of A &times; X - B
60       * @throws org.apache.commons.math3.exception.DimensionMismatchException
61       * if the matrices dimensions do not match.
62       * @throws SingularMatrixException if the decomposed matrix is singular.
63       */
64      RealMatrix solve(final RealMatrix b) throws SingularMatrixException;
65  
66      /**
67       * Check if the decomposed matrix is non-singular.
68       * @return true if the decomposed matrix is non-singular.
69       */
70      boolean isNonSingular();
71  
72      /**
73       * Get the <a href="http://en.wikipedia.org/wiki/Moore%E2%80%93Penrose_pseudoinverse">pseudo-inverse</a>
74       * of the decomposed matrix.
75       * <p>
76       * <em>This is equal to the inverse  of the decomposed matrix, if such an inverse exists.</em>
77       * <p>
78       * If no such inverse exists, then the result has properties that resemble that of an inverse.
79       * <p>
80       * In particular, in this case, if the decomposed matrix is A, then the system of equations
81       * \( A x = b \) may have no solutions, or many. If it has no solutions, then the pseudo-inverse
82       * \( A^+ \) gives the "closest" solution \( z = A^+ b \), meaning \( \left \| A z - b \right \|_2 \)
83       * is minimized. If there are many solutions, then \( z = A^+ b \) is the smallest solution,
84       * meaning \( \left \| z \right \|_2 \) is minimized.
85       * <p>
86       * Note however that some decompositions cannot compute a pseudo-inverse for all matrices.
87       * For example, the {@link LUDecomposition} is not defined for non-square matrices to begin
88       * with. The {@link QRDecomposition} can operate on non-square matrices, but will throw
89       * {@link SingularMatrixException} if the decomposed matrix is singular. Refer to the javadoc
90       * of specific decomposition implementations for more details.
91       *
92       * @return pseudo-inverse matrix (which is the inverse, if it exists),
93       * if the decomposition can pseudo-invert the decomposed matrix
94       * @throws SingularMatrixException if the decomposed matrix is singular and the decomposition
95       * can not compute a pseudo-inverse
96       */
97      RealMatrix getInverse() throws SingularMatrixException;
98  }