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.InvalidBracketRangeException;
19 import com.irurueta.numerical.LockedException;
20 import com.irurueta.numerical.NotAvailableException;
21 import com.irurueta.numerical.SingleDimensionFunctionEvaluatorListener;
22
23 /**
24 * Abstract class to find function roots of a single dimension function using
25 * also its derivative information.
26 * This class is meant to be extended by final implementations.
27 */
28 public abstract class DerivativeSingleRootEstimator extends BracketedSingleRootEstimator {
29
30 /**
31 * Listener to evaluate a function's derivative. If the function's
32 * derivative is not known (e.g. a closed expression is not available), then
33 * a DerivativeEstimator can be used inside the derivative listener
34 * implementation.
35 */
36 protected SingleDimensionFunctionEvaluatorListener derivativeListener;
37
38 /**
39 * Empty constructor.
40 */
41 protected DerivativeSingleRootEstimator() {
42 super();
43 derivativeListener = null;
44 }
45
46 /**
47 * Constructor.
48 *
49 * @param listener Listener to evaluate a single dimension function f(x)
50 * to find its roots.
51 * @param minEvalPoint Smallest value inside the bracket of values where the
52 * root will be searched.
53 * @param maxEvalPoint Largest value inside the bracket of values where the
54 * root will be searched.
55 * @throws InvalidBracketRangeException Raised if minEvalPoint <
56 * maxEvalPoint.
57 */
58 protected DerivativeSingleRootEstimator(
59 final SingleDimensionFunctionEvaluatorListener listener, final double minEvalPoint,
60 final double maxEvalPoint) throws InvalidBracketRangeException {
61 super(listener, minEvalPoint, maxEvalPoint);
62 derivativeListener = null;
63 }
64
65 /**
66 * Constructor
67 *
68 * @param listener Listener to evaluate a single dimension function f(x)
69 * to find its roots.
70 * @param derivativeListener Listener to evaluate the function's derivative
71 * @param minEvalPoint Smallest value inside the bracket of values where the
72 * root will be searched.
73 * @param maxEvalPoint Largest value inside the bracket of values where the
74 * root will be searched.
75 * @throws InvalidBracketRangeException Raised if minEvalPoint <
76 * maxEvalPoint.
77 */
78 protected DerivativeSingleRootEstimator(
79 final SingleDimensionFunctionEvaluatorListener listener,
80 final SingleDimensionFunctionEvaluatorListener derivativeListener, final double minEvalPoint,
81 final double maxEvalPoint) throws InvalidBracketRangeException {
82 super(listener, minEvalPoint, maxEvalPoint);
83 this.derivativeListener = derivativeListener;
84 }
85
86 /**
87 * Returns derivative listener to evaluate a function's derivative.
88 * If the function's derivative is not known (e.g. a closed expression is
89 * not available), then a DerivativeEstimator can be used inside the
90 * derivative listener implementation.
91 *
92 * @return Derivative listener.
93 * @throws NotAvailableException if listener is not available for retrieval.
94 */
95 public SingleDimensionFunctionEvaluatorListener getDerivativeListener() throws NotAvailableException {
96 if (!isDerivativeListenerAvailable()) {
97 throw new NotAvailableException();
98 }
99 return derivativeListener;
100 }
101
102 /**
103 * Sets derivative listener to evaluate a function's derivative.
104 * If the function's derivative is not known (e.g. a closed expression is
105 * not available), then a DerivativeEstimator can be used inside the
106 * derivative listener implementation.
107 *
108 * @param derivativeListener Derivative listener to be set.
109 * @throws LockedException Raised if this instance is locked.
110 */
111 public void setDerivativeListener(final SingleDimensionFunctionEvaluatorListener derivativeListener)
112 throws LockedException {
113 if (isLocked()) {
114 throw new LockedException();
115 }
116 this.derivativeListener = derivativeListener;
117 }
118
119 /**
120 * Returns boolean indicating whether the derivative listener has been
121 * provided and is available for retrieval.
122 *
123 * @return true if derivative listener is available, false otherwise
124 */
125 public boolean isDerivativeListenerAvailable() {
126 return derivativeListener != null;
127 }
128
129 /**
130 * Returns boolean indicating whether enough parameters have been provided
131 * in order to start the estimation of the roots of a function.
132 * An instance of this class is assumed to be ready when a listener, a
133 * derivative listener and a bracket have been provided or computed.
134 *
135 * @return True if this instance is ready to start the root estimation,
136 * false otherwise.
137 */
138 @Override
139 public boolean isReady() {
140 return isListenerAvailable() && isBracketAvailable() && isDerivativeListenerAvailable();
141 }
142 }