1/*2* Licensed to the Apache Software Foundation (ASF) under one or more3* contributor license agreements. See the NOTICE file distributed with4* this work for additional information regarding copyright ownership.5* The ASF licenses this file to You under the Apache License, Version 2.06* (the "License"); you may not use this file except in compliance with7* the License. You may obtain a copy of the License at8*9* http://www.apache.org/licenses/LICENSE-2.010*11* Unless required by applicable law or agreed to in writing, software12* 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 and15* limitations under the License.16*/17 18packageorg.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 specific24* matrices from which they can solve A × X = B in least squares sense: they find X25* such that ||A × X - B|| is minimal.26* <p>27* Some solvers like {@link LUDecomposition} can only find the solution for28* square matrices and when the solution is an exact linear solution, i.e. when29* ||A × X - B|| is exactly 0. Other solvers can also find solutions30* with non-square matrix A and with non-null minimal norm. If an exact linear31* solution exists it is also the minimal norm solution.32*33* @since 2.034*/35publicinterfaceDecompositionSolver { 36 37/**38* Solve the linear equation A × X = B for matrices A.39* <p>40* The A matrix is implicit, it is provided by the underlying41* decomposition algorithm.42*43* @param b right-hand side of the equation A × X = B44* @return a vector X that minimizes the two norm of A × X - B45* @throws org.apache.commons.math3.exception.DimensionMismatchException46* if the matrices dimensions do not match.47* @throws SingularMatrixException if the decomposed matrix is singular.48*/49 RealVector solve(finalRealVector b)throwsSingularMatrixException; 50 51/**52* Solve the linear equation A × X = B for matrices A.53* <p>54* The A matrix is implicit, it is provided by the underlying55* decomposition algorithm.56*57* @param b right-hand side of the equation A × X = B58* @return a matrix X that minimizes the two norm of A × X - B59* @throws org.apache.commons.math3.exception.DimensionMismatchException60* if the matrices dimensions do not match.61* @throws SingularMatrixException if the decomposed matrix is singular.62*/63 RealMatrix solve(finalRealMatrix b)throwsSingularMatrixException; 64 65/**66* Check if the decomposed matrix is non-singular.67* @return true if the decomposed matrix is non-singular.68*/69booleanisNonSingular(); 70 71/**72* Get the <a href="http://en.wikipedia.org/wiki/Moore%E2%80%93Penrose_pseudoinverse">pseudo-inverse</a>73* of the decomposed matrix.74* <p>75* <em>This is equal to the inverse of the decomposed matrix, if such an inverse exists.</em>76* <p>77* If no such inverse exists, then the result has properties that resemble that of an inverse.78* <p>79* In particular, in this case, if the decomposed matrix is A, then the system of equations80* \( A x = b \) may have no solutions, or many. If it has no solutions, then the pseudo-inverse81* \( A^+ \) gives the "closest" solution \( z = A^+ b \), meaning \( \left \| A z - b \right \|_2 \)82* is minimized. If there are many solutions, then \( z = A^+ b \) is the smallest solution,83* meaning \( \left \| z \right \|_2 \) is minimized.84* <p>85* Note however that some decompositions cannot compute a pseudo-inverse for all matrices.86* For example, the {@link LUDecomposition} is not defined for non-square matrices to begin87* with. The {@link QRDecomposition} can operate on non-square matrices, but will throw88* {@link SingularMatrixException} if the decomposed matrix is singular. Refer to the javadoc89* of specific decomposition implementations for more details.90*91* @return pseudo-inverse matrix (which is the inverse, if it exists),92* if the decomposition can pseudo-invert the decomposed matrix93* @throws SingularMatrixException if the decomposed matrix is singular and the decomposition94* can not compute a pseudo-inverse95*/96 RealMatrix getInverse()throwsSingularMatrixException; 97 }