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.math3.analysis;
18
19 /**
20 * An interface representing a univariate real function.
21 * <br/>
22 * When a <em>user-defined</em> function encounters an error during
23 * evaluation, the {@link #value(double) value} method should throw a
24 * <em>user-defined</em> unchecked exception.
25 * <br/>
26 * The following code excerpt shows the recommended way to do that using
27 * a root solver as an example, but the same construct is applicable to
28 * ODE integrators or optimizers.
29 *
30 * <pre>
31 * private static class LocalException extends RuntimeException {
32 * // The x value that caused the problem.
33 * private final double x;
34 *
35 * public LocalException(double x) {
36 * this.x = x;
37 * }
38 *
39 * public double getX() {
40 * return x;
41 * }
42 * }
43 *
44 * private static class MyFunction implements UnivariateFunction {
45 * public double value(double x) {
46 * double y = hugeFormula(x);
47 * if (somethingBadHappens) {
48 * throw new LocalException(x);
49 * }
50 * return y;
51 * }
52 * }
53 *
54 * public void compute() {
55 * try {
56 * solver.solve(maxEval, new MyFunction(a, b, c), min, max);
57 * } catch (LocalException le) {
58 * // Retrieve the x value.
59 * }
60 * }
61 * </pre>
62 *
63 * As shown, the exception is local to the user's code and it is guaranteed
64 * that Apache Commons Math will not catch it.
65 *
66 * @version $Id: UnivariateFunction.java 1364387 2012-07-22 18:14:11Z tn $
67 */
68 public interface UnivariateFunction {
69 /**
70 * Compute the value of the function.
71 *
72 * @param x Point at which the function value should be computed.
73 * @return the value of the function.
74 * @throws IllegalArgumentException when the activated method itself can
75 * ascertain that a precondition, specified in the API expressed at the
76 * level of the activated method, has been violated.
77 * When Commons Math throws an {@code IllegalArgumentException}, it is
78 * usually the consequence of checking the actual parameters passed to
79 * the method.
80 */
81 double value(double x);
82 }