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