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