View Javadoc

    1   /*
    2    * Copyright 2003-2004 The Apache Software Foundation.
    3    *
    4    * Licensed under the Apache License, Version 2.0 (the "License");
    5    * you may not use this file except in compliance with the License.
    6    * You may obtain a copy of the License at
    7    *
    8    *      http://www.apache.org/licenses/LICENSE-2.0
    9    *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.
    15   */
    16  package org.apache.commons.math.analysis;
    17
    18  import org.apache.commons.math.ConvergenceException;
    19  import org.apache.commons.math.FunctionEvaluationException;
    20
    21
    22  /***
    23   * Interface for (univariate real) rootfinding algorithms.
    24   * <p>
    25   * Implementations will search for only one zero in the given interval.
    26   *
    27   * @version $Revision: 1.14 $ $Date: 2004/07/17 21:19:39 $
    28   */
    29  public interface UnivariateRealSolver {
    30
    31      /***
    32       * Set the upper limit for the number of iterations.
    33       * <p>
    34       * Usually a high iteration count indicates convergence problems. However,
    35       * the "reasonable value" varies widely for different solvers.  Users are
    36       * advised to use the default value supplied by the solver.
    37       * <p>
    38       * A <code>ConvergenceException</code> will be thrown if this number
    39       * is exceeded.
    40       *
    41       * @param count maximum number of iterations
    42       */
    43      void setMaximalIterationCount(int count);
    44
    45      /***
    46       * Get the upper limit for the number of iterations.
    47       *
    48       * @return the actual upper limit
    49       */
    50      int getMaximalIterationCount();
    51
    52      /***
    53       * Reset the upper limit for the number of iterations to the default.
    54       * <p>
    55       * The default value is supplied by the solver implementation.
    56       *
    57       * @see #setMaximalIterationCount(int)
    58       */
    59      void resetMaximalIterationCount();
    60
    61      /***
    62       * Set the absolute accuracy.
    63       * <p>
    64       * The default is usually choosen so that roots in the interval
    65       * -10..-0.1 and +0.1..+10 can be found with a reasonable accuracy. If the
    66       * expected absolute value of your roots is of much smaller magnitude, set
    67       * this to a smaller value.
    68       * <p>
    69       * Solvers are advised to do a plausibility check with the relative
    70       * accuracy, but clients should not rely on this.
    71       *
    72       * @param accuracy the accuracy.
    73       * @throws IllegalArgumentException if the accuracy can't be achieved by
    74       * the solver or is otherwise deemed unreasonable.
    75       */
    76      void setAbsoluteAccuracy(double accuracy);
    77
    78      /***
    79       * Get the actual absolute accuracy.
    80       *
    81       * @return the accuracy
    82       */
    83      double getAbsoluteAccuracy();
    84
    85      /***
    86       * Reset the absolute accuracy to the default.
    87       * <p>
    88       * The default value is provided by the solver implementation.
    89       */
    90      void resetAbsoluteAccuracy();
    91
    92      /***
    93       * Set the relative accuracy.
    94       * <p>
    95       * This is used to stop iterations if the absolute accuracy can't be
    96       * achieved due to large values or short mantissa length.
    97       * <p>
    98       * If this should be the primary criterion for convergence rather then a
    99       * safety measure, set the absolute accuracy to a ridiculously small value,
    100      * like 1E-1000.
    101      *
    102      * @param accuracy the relative accuracy.
    103      * @throws IllegalArgumentException if the accuracy can't be achieved by
    104      *  the solver or is otherwise deemed unreasonable.
    105      */
    106     void setRelativeAccuracy(double accuracy);
    107
    108     /***
    109      * Get the actual relative accuracy.
    110      * @return the accuracy
    111      */
    112     double getRelativeAccuracy();
    113
    114     /***
    115      * Reset the relative accuracy to the default.
    116      * The default value is provided by the solver implementation.
    117      */
    118     void resetRelativeAccuracy();
    119
    120     /***
    121      * Set the function value accuracy.
    122      * <p>
    123      * This is used to determine whan an evaluated function value or some other
    124      * value which is used as divisor is zero.
    125      * <p>
    126      * This is a safety guard and it shouldn't be necesary to change this in
    127      * general.
    128      *
    129      * @param accuracy the accuracy.
    130      * @throws IllegalArgumentException if the accuracy can't be achieved by
    131      * the solver or is otherwise deemed unreasonable.
    132      */
    133     void setFunctionValueAccuracy(double accuracy);
    134
    135     /***
    136      * Get the actual function value accuracy.
    137      * @return the accuracy
    138      */
    139     double getFunctionValueAccuracy();
    140
    141     /***
    142      * Reset the actual function accuracy to the default.
    143      * The default value is provided by the solver implementation.
    144      */
    145     void resetFunctionValueAccuracy();
    146
    147     /***
    148      * Solve for a zero root in the given interval.
    149      * A solver may require that the interval brackets a single zero root.
    150      *
    151      * @param min the lower bound for the interval.
    152      * @param max the upper bound for the interval.
    153      * @return a value where the function is zero
    154      * @throws ConvergenceException if the maximum iteration count is exceeded
    155      * or the solver detects convergence problems otherwise.
    156      * @throws FunctionEvaluationException if an error occurs evaluating the
    157      * function
    158      * @throws IllegalArgumentException if min > max or the endpoints do not
    159      * satisfy the requirements specified by the solver
    160      */
    161     double solve(double min, double max) throws ConvergenceException,
    162         FunctionEvaluationException;
    163
    164     /***
    165      * Solve for a zero in the given interval, start at startValue.
    166      * A solver may require that the interval brackets a single zero root.
    167      *
    168      * @param min the lower bound for the interval.
    169      * @param max the upper bound for the interval.
    170      * @param startValue the start value to use
    171      * @return a value where the function is zero
    172      * @throws ConvergenceException if the maximum iteration count is exceeded
    173      * or the solver detects convergence problems otherwise.
    174      * @throws FunctionEvaluationException if an error occurs evaluating the
    175      * function
    176      * @throws IllegalArgumentException if min > max or the arguments do not
    177      * satisfy the requirements specified by the solver
    178      */
    179     double solve(double min, double max, double startValue)
    180         throws ConvergenceException, FunctionEvaluationException;
    181
    182     /***
    183      * Get the result of the last run of the solver.
    184      *
    185      * @return the last result.
    186      * @throws IllegalStateException if there is no result available, either
    187      * because no result was yet computed or the last attempt failed.
    188      */
    189     double getResult();
    190
    191     /***
    192      * Get the number of iterations in the last run of the solver.
    193      * <p>
    194      * This is mainly meant for testing purposes. It may occasionally
    195      * help track down performance problems: if the iteration count
    196      * is notoriously high, check whether the function is evaluated
    197      * properly, and whether another solver is more amenable to the
    198      * problem.
    199      *
    200      * @return the last iteration count.
    201      * @throws IllegalStateException if there is no result available, either
    202      * because no result was yet computed or the last attempt failed.
    203      */
    204     int getIterationCount();
    205 }