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.math.linear;
19  
20  import org.apache.commons.math.FieldElement;
21  
22  
23  /**
24   * Interface handling decomposition algorithms that can solve A × X = B.
25   * <p>Decomposition algorithms decompose an A matrix has a product of several specific
26   * matrices from which they can solve A &times; X = B in least squares sense: they find X
27   * such that ||A &times; X - B|| is minimal.</p>
28   * <p>Some solvers like {@link LUDecomposition} can only find the solution for
29   * square matrices and when the solution is an exact linear solution, i.e. when
30   * ||A &times; X - B|| is exactly 0. Other solvers can also find solutions
31   * with non-square matrix A and with non-null minimal norm. If an exact linear
32   * solution exists it is also the minimal norm solution.</p>
33   *
34   * @param <T> the type of the field elements
35   * @version $Revision: 781122 $ $Date: 2009-06-02 14:53:23 -0400 (Tue, 02 Jun 2009) $
36   * @since 2.0
37   */
38  public interface FieldDecompositionSolver<T extends FieldElement<T>> {
39  
40      /** Solve the linear equation A &times; X = B for matrices A.
41       * <p>The A matrix is implicit, it is provided by the underlying
42       * decomposition algorithm.</p>
43       * @param b right-hand side of the equation A &times; X = B
44       * @return a vector X that minimizes the two norm of A &times; X - B
45       * @exception IllegalArgumentException if matrices dimensions don't match
46       * @exception InvalidMatrixException if decomposed matrix is singular
47       */
48      T[] solve(final T[] b)
49          throws IllegalArgumentException, InvalidMatrixException;
50  
51      /** Solve the linear equation A &times; X = B for matrices A.
52       * <p>The A matrix is implicit, it is provided by the underlying
53       * decomposition algorithm.</p>
54       * @param b right-hand side of the equation A &times; X = B
55       * @return a vector X that minimizes the two norm of A &times; X - B
56       * @exception IllegalArgumentException if matrices dimensions don't match
57       * @exception InvalidMatrixException if decomposed matrix is singular
58       */
59      FieldVector<T> solve(final FieldVector<T> b)
60          throws IllegalArgumentException, InvalidMatrixException;
61  
62      /** Solve the linear equation A &times; X = B for matrices A.
63       * <p>The A matrix is implicit, it is provided by the underlying
64       * decomposition algorithm.</p>
65       * @param b right-hand side of the equation A &times; X = B
66       * @return a matrix X that minimizes the two norm of A &times; X - B
67       * @exception IllegalArgumentException if matrices dimensions don't match
68       * @exception InvalidMatrixException if decomposed matrix is singular
69       */
70      FieldMatrix<T> solve(final FieldMatrix<T> b)
71          throws IllegalArgumentException, InvalidMatrixException;
72  
73      /**
74       * Check if the decomposed matrix is non-singular.
75       * @return true if the decomposed matrix is non-singular
76       */
77      boolean isNonSingular();
78  
79      /** Get the inverse (or pseudo-inverse) of the decomposed matrix.
80       * @return inverse matrix
81       * @throws InvalidMatrixException if decomposed matrix is singular
82       */
83      FieldMatrix<T> getInverse()
84          throws InvalidMatrixException;
85  
86  }