1 /*
2 * Copyright (C) 2012 Alberto Irurueta Carro (alberto@irurueta.com)
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package com.irurueta.numerical.roots;
17
18 import com.irurueta.algebra.Complex;
19 import com.irurueta.numerical.LockedException;
20 import com.irurueta.numerical.NotAvailableException;
21
22 /**
23 * Abstract class to estimate the roots of a polynomial.
24 */
25 public abstract class PolynomialRootsEstimator extends RootEstimator {
26
27 /**
28 * Array containing parameters of a polynomial, taking into account that
29 * a polynomial of degree n is defined as:
30 * p(x) = a0 * x^n + a1 * x^(n - 1) + ... a(n-1) * x + an
31 * then the array of parameters is [a0, a1, ... a(n - 1), an]
32 */
33 protected Complex[] polyParams;
34
35 /**
36 * Array containing estimated roots.
37 */
38 protected Complex[] roots;
39
40 /**
41 * Empty constructor.
42 */
43 protected PolynomialRootsEstimator() {
44 super();
45 polyParams = roots = null;
46 }
47
48 /**
49 * Returns array containing polynomial parameters.
50 *
51 * @return Array of polynomial parameters.
52 * @throws NotAvailableException Raised if polynomial parameters have not
53 * been provided and are not available for retrieval.
54 */
55 public Complex[] getPolynomialParameters() throws NotAvailableException {
56 if (!arePolynomialParametersAvailable()) {
57 throw new NotAvailableException();
58 }
59 return polyParams;
60 }
61
62 /**
63 * Sets parameters of a polynomial, taking into account
64 * that a polynomial of degree n is defined as:
65 * p(x) = a0 * x^n + a1 * x^(n - 1) + ... a(n-1) * x + an
66 * then the array of parameters is [a0, a1, ... a(n - 1), an]
67 *
68 * @param polyParams Polynomial parameters.
69 * @throws LockedException Raised if this instance is locked.
70 * @throws IllegalArgumentException Raised if the length of the array is not
71 * valid depending on the subclass implementation.
72 */
73 public void setPolynomialParameters(final Complex[] polyParams) throws LockedException {
74 if (isLocked()) {
75 throw new LockedException();
76 }
77 internalSetPolynomialParameters(polyParams);
78 }
79
80 /**
81 * Returns boolean indicating whether polynomial parameters have been
82 * provided and are available for retrieval.
83 *
84 * @return True if available, false otherwise.
85 */
86 public boolean arePolynomialParametersAvailable() {
87 return polyParams != null;
88 }
89
90 /**
91 * Returns boolean indicating whether this instance is ready to start the
92 * estimation of the polynomial roots.
93 * This instance is considered to be ready once polynomial parameters are
94 * provided.
95 *
96 * @return True if ready, false otherwise.
97 */
98 @Override
99 public boolean isReady() {
100 return arePolynomialParametersAvailable();
101 }
102
103 /**
104 * Returns array of estimated polynomial roots.
105 * The array will have a length equal to the polynomial degree.
106 * If a polynomial has multiple roots, then such roots will be repeated.
107 *
108 * @return Array of estimated polynomial roots
109 * @throws NotAvailableException Raised if roots have not yet been estimated
110 * and are not available for retrieval
111 */
112 public Complex[] getRoots() throws NotAvailableException {
113 if (!areRootsAvailable()) {
114 throw new NotAvailableException();
115 }
116 return roots;
117 }
118
119 /**
120 * Returns boolean indicating whether roots have been estimated and are
121 * available for retrieval.
122 *
123 * @return True if available, false otherwise.
124 */
125 public boolean areRootsAvailable() {
126 return roots != null;
127 }
128
129 /**
130 * Internal method to set parameters of a polynomial, taking into account
131 * that a polynomial of degree n is defined as:
132 * p(x) = a0 * x^n + a1 * x^(n - 1) + ... a(n-1) * x + an
133 * then the array of parameters is [a0, a1, ... a(n - 1), an]
134 * This method does not check if this class is locked.
135 *
136 * @param polyParams Polynomial parameters.
137 * @throws IllegalArgumentException Raised if the length of the array is not
138 * valid depending on the subclass implementation.
139 */
140 protected abstract void internalSetPolynomialParameters(Complex[] polyParams);
141 }