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 package org.apache.commons.math4.legacy.linear;
18
19 import org.apache.commons.math4.legacy.exception.DimensionMismatchException;
20 import org.apache.commons.math4.legacy.exception.MaxCountExceededException;
21 import org.apache.commons.math4.legacy.exception.NullArgumentException;
22
23 /**
24 * This abstract class defines an iterative solver for the linear system A
25 * · x = b. In what follows, the <em>residual</em> r is defined as r = b
26 * - A · x, where A is the linear operator of the linear system, b is the
27 * right-hand side vector, and x the current estimate of the solution.
28 *
29 * @since 3.0
30 */
31 public abstract class IterativeLinearSolver {
32
33 /** The object in charge of managing the iterations. */
34 private final IterationManager manager;
35
36 /**
37 * Creates a new instance of this class, with default iteration manager.
38 *
39 * @param maxIterations the maximum number of iterations
40 */
41 public IterativeLinearSolver(final int maxIterations) {
42 this.manager = new IterationManager(maxIterations);
43 }
44
45 /**
46 * Creates a new instance of this class, with custom iteration manager.
47 *
48 * @param manager the custom iteration manager
49 * @throws NullArgumentException if {@code manager} is {@code null}
50 */
51 public IterativeLinearSolver(final IterationManager manager)
52 throws NullArgumentException {
53 NullArgumentException.check(manager);
54 this.manager = manager;
55 }
56
57 /**
58 * Performs all dimension checks on the parameters of
59 * {@link #solve(RealLinearOperator, RealVector, RealVector) solve} and
60 * {@link #solveInPlace(RealLinearOperator, RealVector, RealVector) solveInPlace},
61 * and throws an exception if one of the checks fails.
62 *
63 * @param a the linear operator A of the system
64 * @param b the right-hand side vector
65 * @param x0 the initial guess of the solution
66 * @throws NullArgumentException if one of the parameters is {@code null}
67 * @throws NonSquareOperatorException if {@code a} is not square
68 * @throws DimensionMismatchException if {@code b} or {@code x0} have
69 * dimensions inconsistent with {@code a}
70 */
71 protected static void checkParameters(final RealLinearOperator a,
72 final RealVector b, final RealVector x0) throws
73 NullArgumentException, NonSquareOperatorException,
74 DimensionMismatchException {
75 NullArgumentException.check(a);
76 NullArgumentException.check(b);
77 NullArgumentException.check(x0);
78 if (a.getRowDimension() != a.getColumnDimension()) {
79 throw new NonSquareOperatorException(a.getRowDimension(),
80 a.getColumnDimension());
81 }
82 if (b.getDimension() != a.getRowDimension()) {
83 throw new DimensionMismatchException(b.getDimension(),
84 a.getRowDimension());
85 }
86 if (x0.getDimension() != a.getColumnDimension()) {
87 throw new DimensionMismatchException(x0.getDimension(),
88 a.getColumnDimension());
89 }
90 }
91
92 /**
93 * Returns the iteration manager attached to this solver.
94 *
95 * @return the manager
96 */
97 public IterationManager getIterationManager() {
98 return manager;
99 }
100
101 /**
102 * Returns an estimate of the solution to the linear system A · x =
103 * b.
104 *
105 * @param a the linear operator A of the system
106 * @param b the right-hand side vector
107 * @return a new vector containing the solution
108 * @throws NullArgumentException if one of the parameters is {@code null}
109 * @throws NonSquareOperatorException if {@code a} is not square
110 * @throws DimensionMismatchException if {@code b} has dimensions
111 * inconsistent with {@code a}
112 * @throws MaxCountExceededException at exhaustion of the iteration count,
113 * unless a custom
114 * {@link org.apache.commons.math4.legacy.core.IntegerSequence.Incrementor.MaxCountExceededCallback callback}
115 * has been set at construction of the {@link IterationManager}
116 */
117 public RealVector solve(final RealLinearOperator a, final RealVector b)
118 throws NullArgumentException, NonSquareOperatorException,
119 DimensionMismatchException, MaxCountExceededException {
120 NullArgumentException.check(a);
121 final RealVector x = new ArrayRealVector(a.getColumnDimension());
122 x.set(0.);
123 return solveInPlace(a, b, x);
124 }
125
126 /**
127 * Returns an estimate of the solution to the linear system A · x =
128 * b.
129 *
130 * @param a the linear operator A of the system
131 * @param b the right-hand side vector
132 * @param x0 the initial guess of the solution
133 * @return a new vector containing the solution
134 * @throws NullArgumentException if one of the parameters is {@code null}
135 * @throws NonSquareOperatorException if {@code a} is not square
136 * @throws DimensionMismatchException if {@code b} or {@code x0} have
137 * dimensions inconsistent with {@code a}
138 * @throws MaxCountExceededException at exhaustion of the iteration count,
139 * unless a custom
140 * {@link org.apache.commons.math4.legacy.core.IntegerSequence.Incrementor.MaxCountExceededCallback callback}
141 * has been set at construction of the {@link IterationManager}
142 */
143 public RealVector solve(RealLinearOperator a, RealVector b, RealVector x0)
144 throws NullArgumentException, NonSquareOperatorException,
145 DimensionMismatchException, MaxCountExceededException {
146 NullArgumentException.check(x0);
147 return solveInPlace(a, b, x0.copy());
148 }
149
150 /**
151 * Returns an estimate of the solution to the linear system A · x =
152 * b. The solution is computed in-place (initial guess is modified).
153 *
154 * @param a the linear operator A of the system
155 * @param b the right-hand side vector
156 * @param x0 initial guess of the solution
157 * @return a reference to {@code x0} (shallow copy) updated with the
158 * solution
159 * @throws NullArgumentException if one of the parameters is {@code null}
160 * @throws NonSquareOperatorException if {@code a} is not square
161 * @throws DimensionMismatchException if {@code b} or {@code x0} have
162 * dimensions inconsistent with {@code a}
163 * @throws MaxCountExceededException at exhaustion of the iteration count,
164 * unless a custom
165 * {@link org.apache.commons.math4.legacy.core.IntegerSequence.Incrementor.MaxCountExceededCallback callback}
166 * has been set at construction of the {@link IterationManager}
167 */
168 public abstract RealVector solveInPlace(RealLinearOperator a, RealVector b,
169 RealVector x0) throws NullArgumentException, NonSquareOperatorException,
170 DimensionMismatchException, MaxCountExceededException;
171 }