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.NotReadyException;
20
21 /**
22 * Abstract class to find roots of functions.
23 * A root is the locus of points (set of points) where the value of a given
24 * function equals to zero.
25 * Usually root estimators will only find a single root around an initial
26 * coarsely estimated solution.
27 */
28 public abstract class RootEstimator {
29
30 /**
31 * Boolean indicating that this instance is locked because it is doing
32 * computations.
33 * Attempting to change any parameters while being locked will raise a
34 * LockedException.
35 */
36 protected boolean locked;
37
38 /**
39 * Constructor.
40 */
41 protected RootEstimator() {
42 locked = false;
43 }
44
45 /**
46 * Returns boolean indicating whether this instance is locked.
47 * An instance is locked while it is doing computations. Attempting to
48 * change any parameters while being locked will raise a LockedException.
49 *
50 * @return Boolean indicating whether this instance is locked.
51 */
52 public boolean isLocked() {
53 return locked;
54 }
55
56 /**
57 * Estimates the root or roots for a given function.
58 *
59 * @throws LockedException Exception raised if this instance is already
60 * locked.
61 * @throws NotReadyException Exception raised if not enough parameters have
62 * been provided in order to start the estimation.
63 * @throws RootEstimationException Raised if the root estimation failed for
64 * some other reason (usually inability to evaluate the function,
65 * numerical instability or convergence problems, or no roots are found).
66 */
67 public void estimate() throws LockedException, NotReadyException, RootEstimationException {
68 }
69
70 /**
71 * Returns boolean indicating whether enough parameters have been provided
72 * in order to start the estimation of the roots of a function.
73 *
74 * @return True if this instance is ready to start the root estimation,
75 * false otherwise.
76 */
77 public boolean isReady() {
78 return false;
79 }
80 }