001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.math4.legacy.analysis;
018
019import org.apache.commons.math4.legacy.core.RealFieldElement;
020
021/**
022 * An interface representing a univariate real function.
023 * <p>
024 * When a <em>user-defined</em> function encounters an error during
025 * evaluation, the {@link #value(RealFieldElement) value} method should throw a
026 * <em>user-defined</em> unchecked exception.</p>
027 * <p>
028 * The following code excerpt shows the recommended way to do that using
029 * a root solver as an example, but the same construct is applicable to
030 * ODE integrators or optimizers.
031 *
032 * <pre>
033 * private static class LocalException extends RuntimeException {
034 *     // The x value that caused the problem.
035 *     private final SomeFieldType x;
036 *
037 *     LocalException(SomeFieldType x) {
038 *         this.x = x;
039 *     }
040 *
041 *     SomeFieldType getX() {
042 *         return x;
043 *     }
044 * }
045 *
046 * private static class MyFunction implements FieldUnivariateFunction&lt;SomeFieldType&gt; {
047 *
048 *     // ... function set-up
049 *
050 *     public SomeFieldType value(SomeFieldType x) {
051 *         SomeFieldType y = hugeFormula(x);
052 *         if (somethingBadHappens) {
053 *           throw new LocalException(x);
054 *         }
055 *         return y;
056 *     }
057 * }
058 *
059 * public void compute() {
060 *     try {
061 *         solver.solve(maxEval, new MyFunction(a, b, c), min, max);
062 *     } catch (LocalException le) {
063 *         // Retrieve the x value.
064 *     }
065 * }
066 * </pre>
067 *<p>
068 * As shown, the exception is local to the user's code and it is guaranteed
069 * that Apache Commons Math will not catch it.</p>
070 *
071 * @param <T> the type of the field elements
072 * @since 3.6
073 * @see UnivariateFunction
074 */
075public interface RealFieldUnivariateFunction<T extends RealFieldElement<T>> {
076    /**
077     * Compute the value of the function.
078     *
079     * @param x Point at which the function value should be computed.
080     * @return the value of the function.
081     * @throws IllegalArgumentException when the activated method itself can
082     * ascertain that a precondition, specified in the API expressed at the
083     * level of the activated method, has been violated.
084     * When Commons Math throws an {@code IllegalArgumentException}, it is
085     * usually the consequence of checking the actual parameters passed to
086     * the method.
087     */
088    T value(T x);
089}