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 }