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.numerical.LockedException;
19 import com.irurueta.numerical.NotAvailableException;
20 import com.irurueta.numerical.SingleDimensionFunctionEvaluatorListener;
21
22 /**
23 * Abstract class to find roots of single dimension functions.
24 * A root is the locus of points (set of points) where the value of a given
25 * function equals to zero.
26 * A single dimension function is one containing a single parameter and
27 * returning a single value (i.e. f(x)).
28 * Usually root estimators will only find a single root around an initial
29 * coarsely estimated solution.
30 */
31 public abstract class SingleRootEstimator extends RootEstimator {
32
33 /**
34 * Listener that evaluates a single dimension function in order to find its
35 * root.
36 */
37 protected SingleDimensionFunctionEvaluatorListener listener;
38
39 /**
40 * Boolean indicating that a root has been computed and is available to be
41 * retrieved.
42 */
43 protected boolean rootAvailable;
44
45 /**
46 * Root that has been found.
47 */
48 protected double root;
49
50 /**
51 * Empty constructor.
52 */
53 protected SingleRootEstimator() {
54 super();
55 listener = null;
56 rootAvailable = false;
57 root = 0.0;
58 }
59
60 /**
61 * Constructor.
62 *
63 * @param listener Listener that evaluates a single dimension function in
64 * order to find its root.
65 */
66 protected SingleRootEstimator(final SingleDimensionFunctionEvaluatorListener listener) {
67 super();
68 this.listener = listener;
69 rootAvailable = false;
70 root = 0.0;
71 }
72
73 /**
74 * Returns listener that evaluates a single dimension function in order to
75 * find its root.
76 *
77 * @return Listener that evaluates a single dimension function.
78 * @throws NotAvailableException Raised if listener has not yet been
79 * provided.
80 */
81 public SingleDimensionFunctionEvaluatorListener getListener() throws NotAvailableException {
82 if (!isListenerAvailable()) {
83 throw new NotAvailableException();
84 }
85 return listener;
86 }
87
88 /**
89 * Sets listener that evaluates a single dimension function in order to find
90 * its root.
91 *
92 * @param listener Listener that evaluates a single dimension function.
93 * @throws LockedException Raised if this instance is already locked.
94 */
95 public void setListener(final SingleDimensionFunctionEvaluatorListener listener) throws LockedException {
96 if (isLocked()) {
97 throw new LockedException();
98 }
99 this.listener = listener;
100 }
101
102 /**
103 * Returns boolean indicating whether a listener has been provided.
104 *
105 * @return True if listener is available, false otherwise.
106 */
107 public boolean isListenerAvailable() {
108 return listener != null;
109 }
110
111 /**
112 * Returns boolean indicating whether enough parameters have been provided
113 * in order to start the estimation of the roots of a function.
114 *
115 * @return True if this instance is ready to start the root estimation,
116 * false otherwise.
117 */
118 @Override
119 public boolean isReady() {
120 return isListenerAvailable();
121 }
122
123 /**
124 * Returns boolean indicating whether a root has been estimated and is
125 * available for retrieval.
126 *
127 * @return True if root is available, false otherwise.
128 */
129 public boolean isRootAvailable() {
130 return rootAvailable;
131 }
132
133 /**
134 * Returns estimated root for a single dimension function inside a given
135 * bracket of values.
136 *
137 * @return Estimated root.
138 * @throws NotAvailableException Raised if root has not yet been estimated.
139 */
140 public double getRoot() throws NotAvailableException {
141 if (!isRootAvailable()) {
142 throw new NotAvailableException();
143 }
144 return root;
145 }
146 }