    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    }