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 org.apache.commons.math4.legacy.core.RealFieldElement; 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(RealFieldElement) 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. 31 * 32 * <pre> 33 * private static class LocalException extends RuntimeException { 34 * // The x value that caused the problem. 35 * private final SomeFieldType x; 36 * 37 * LocalException(SomeFieldType x) { 38 * this.x = x; 39 * } 40 * 41 * SomeFieldType getX() { 42 * return x; 43 * } 44 * } 45 * 46 * private static class MyFunction implements FieldUnivariateFunction<SomeFieldType> { 47 * 48 * // ... function set-up 49 * 50 * public SomeFieldType value(SomeFieldType x) { 51 * SomeFieldType y = hugeFormula(x); 52 * if (somethingBadHappens) { 53 * throw new LocalException(x); 54 * } 55 * return y; 56 * } 57 * } 58 * 59 * public void compute() { 60 * try { 61 * solver.solve(maxEval, new MyFunction(a, b, c), min, max); 62 * } catch (LocalException le) { 63 * // Retrieve the x value. 64 * } 65 * } 66 * </pre> 67 *<p> 68 * As shown, the exception is local to the user's code and it is guaranteed 69 * that Apache Commons Math will not catch it.</p> 70 * 71 * @param <T> the type of the field elements 72 * @since 3.6 73 * @see UnivariateFunction 74 */ 75 public interface RealFieldUnivariateFunction<T extends RealFieldElement<T>> { 76 /** 77 * Compute the value of the function. 78 * 79 * @param x Point at which the function value should be computed. 80 * @return the value of the function. 81 * @throws IllegalArgumentException when the activated method itself can 82 * ascertain that a precondition, specified in the API expressed at the 83 * level of the activated method, has been violated. 84 * When Commons Math throws an {@code IllegalArgumentException}, it is 85 * usually the consequence of checking the actual parameters passed to 86 * the method. 87 */ 88 T value(T x); 89 }