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     */
017    package org.apache.commons.math3.analysis;
018    
019    /**
020     * An interface representing a univariate real function.
021     * <br/>
022     * When a <em>user-defined</em> function encounters an error during
023     * evaluation, the {@link #value(double) value} method should throw a
024     * <em>user-defined</em> unchecked exception.
025     * <br/>
026     * The following code excerpt shows the recommended way to do that using
027     * a root solver as an example, but the same construct is applicable to
028     * ODE integrators or optimizers.
029     *
030     * <pre>
031     * private static class LocalException extends RuntimeException {
032     *     // The x value that caused the problem.
033     *     private final double x;
034     *
035     *     public LocalException(double x) {
036     *         this.x = x;
037     *     }
038     *
039     *     public double getX() {
040     *         return x;
041     *     }
042     * }
043     *
044     * private static class MyFunction implements UnivariateFunction {
045     *     public double value(double x) {
046     *         double y = hugeFormula(x);
047     *         if (somethingBadHappens) {
048     *           throw new LocalException(x);
049     *         }
050     *         return y;
051     *     }
052     * }
053     *
054     * public void compute() {
055     *     try {
056     *         solver.solve(maxEval, new MyFunction(a, b, c), min, max);
057     *     } catch (LocalException le) {
058     *         // Retrieve the x value.
059     *     }
060     * }
061     * </pre>
062     *
063     * As shown, the exception is local to the user's code and it is guaranteed
064     * that Apache Commons Math will not catch it.
065     *
066     * @version $Id: UnivariateFunction.java 1364387 2012-07-22 18:14:11Z tn $
067     */
068    public interface UnivariateFunction {
069        /**
070         * Compute the value of the function.
071         *
072         * @param x Point at which the function value should be computed.
073         * @return the value of the function.
074         * @throws IllegalArgumentException when the activated method itself can
075         * ascertain that a precondition, specified in the API expressed at the
076         * level of the activated method, has been violated.
077         * When Commons Math throws an {@code IllegalArgumentException}, it is
078         * usually the consequence of checking the actual parameters passed to
079         * the method.
080         */
081        double value(double x);
082    }