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 * https://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 /*
19 * This is not the original file distributed by the Apache Software Foundation
20 * It has been modified by the Hipparchus project
21 */
22
23 package org.hipparchus.linear;
24
25 import org.hipparchus.exception.MathIllegalArgumentException;
26
27 /**
28 * Interface handling decomposition algorithms that can solve A × X = B.
29 * <p>
30 * Decomposition algorithms decompose an A matrix as a product of several specific
31 * matrices from which they can solve A × X = B in least squares sense: they find X
32 * such that ||A × X - B|| is minimal.
33 * <p>
34 * Some solvers like {@link LUDecomposition} can only find the solution for
35 * square matrices and when the solution is an exact linear solution, i.e. when
36 * ||A × X - B|| is exactly 0. Other solvers can also find solutions
37 * with non-square matrix A and with non-null minimal norm. If an exact linear
38 * solution exists it is also the minimal norm solution.
39 *
40 */
41 public interface DecompositionSolver {
42
43 /**
44 * Solve the linear equation A × X = B for matrices A.
45 * <p>
46 * The A matrix is implicit, it is provided by the underlying
47 * decomposition algorithm.
48 *
49 * @param b right-hand side of the equation A × X = B
50 * @return a vector X that minimizes the two norm of A × X - B
51 * @throws org.hipparchus.exception.MathIllegalArgumentException
52 * if the matrices dimensions do not match.
53 * @throws MathIllegalArgumentException if the decomposed matrix is singular.
54 */
55 RealVector solve(RealVector b) throws MathIllegalArgumentException;
56
57 /**
58 * Solve the linear equation A × X = B for matrices A.
59 * <p>
60 * The A matrix is implicit, it is provided by the underlying
61 * decomposition algorithm.
62 *
63 * @param b right-hand side of the equation A × X = B
64 * @return a matrix X that minimizes the two norm of A × X - B
65 * @throws org.hipparchus.exception.MathIllegalArgumentException
66 * if the matrices dimensions do not match.
67 * @throws MathIllegalArgumentException if the decomposed matrix is singular.
68 */
69 RealMatrix solve(RealMatrix b) throws MathIllegalArgumentException;
70
71 /**
72 * Check if the decomposed matrix is non-singular.
73 * @return true if the decomposed matrix is non-singular.
74 */
75 boolean isNonSingular();
76
77 /**
78 * Get the <a href="http://en.wikipedia.org/wiki/Moore%E2%80%93Penrose_pseudoinverse">pseudo-inverse</a>
79 * of the decomposed matrix.
80 * <p>
81 * <em>This is equal to the inverse of the decomposed matrix, if such an inverse exists.</em>
82 * <p>
83 * If no such inverse exists, then the result has properties that resemble that of an inverse.
84 * <p>
85 * In particular, in this case, if the decomposed matrix is A, then the system of equations
86 * \( A x = b \) may have no solutions, or many. If it has no solutions, then the pseudo-inverse
87 * \( A^+ \) gives the "closest" solution \( z = A^+ b \), meaning \( \left \| A z - b \right \|_2 \)
88 * is minimized. If there are many solutions, then \( z = A^+ b \) is the smallest solution,
89 * meaning \( \left \| z \right \|_2 \) is minimized.
90 * <p>
91 * Note however that some decompositions cannot compute a pseudo-inverse for all matrices.
92 * For example, the {@link LUDecomposition} is not defined for non-square matrices to begin
93 * with. The {@link QRDecomposition} can operate on non-square matrices, but will throw
94 * {@link MathIllegalArgumentException} if the decomposed matrix is singular. Refer to the javadoc
95 * of specific decomposition implementations for more details.
96 *
97 * @return pseudo-inverse matrix (which is the inverse, if it exists),
98 * if the decomposition can pseudo-invert the decomposed matrix
99 * @throws MathIllegalArgumentException if the decomposed matrix is singular and the decomposition
100 * can not compute a pseudo-inverse
101 */
102 RealMatrix getInverse() throws MathIllegalArgumentException;
103
104 /**
105 * Returns the number of rows in the matrix.
106 *
107 * @return rowDimension
108 * @since 2.0
109 */
110 int getRowDimension();
111
112 /**
113 * Returns the number of columns in the matrix.
114 *
115 * @return columnDimension
116 * @since 2.0
117 */
118 int getColumnDimension();
119
120 }