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.math4.legacy.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 × X = B in least squares sense: they find X
25 * such that ||A × 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 × 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 * @since 2.0
34 */
35 public interface DecompositionSolver {
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 underlying
41 * decomposition algorithm.
42 *
43 * @param b right-hand side of the equation A × X = B
44 * @return a vector X that minimizes the two norm of A × X - B
45 * @throws org.apache.commons.math4.legacy.exception.DimensionMismatchException
46 * if the matrices dimensions do not match.
47 * @throws SingularMatrixException if the decomposed matrix is singular.
48 */
49 RealVector solve(RealVector b) throws SingularMatrixException;
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 underlying
55 * decomposition algorithm.
56 *
57 * @param b right-hand side of the equation A × X = B
58 * @return a matrix X that minimizes the two norm of A × X - B
59 * @throws org.apache.commons.math4.legacy.exception.DimensionMismatchException
60 * if the matrices dimensions do not match.
61 * @throws SingularMatrixException if the decomposed matrix is singular.
62 */
63 RealMatrix solve(RealMatrix b) throws SingularMatrixException;
64
65 /**
66 * Check if the decomposed matrix is non-singular.
67 * @return true if the decomposed matrix is non-singular.
68 */
69 boolean isNonSingular();
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 equations
80 * \( A x = b \) may have no solutions, or many. If it has no solutions, then the pseudo-inverse
81 * \( 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 begin
87 * with. The {@link QRDecomposition} can operate on non-square matrices, but will throw
88 * {@link SingularMatrixException} if the decomposed matrix is singular. Refer to the javadoc
89 * 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 matrix
93 * @throws SingularMatrixException if the decomposed matrix is singular and the decomposition
94 * can not compute a pseudo-inverse
95 */
96 RealMatrix getInverse() throws SingularMatrixException;
97 }