/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.math3.optim.nonlinear.scalar;

import org.apache.commons.math3.optim.univariate.UnivariateOptimizer;
import org.apache.commons.math3.optim.univariate.BrentOptimizer;
import org.apache.commons.math3.optim.univariate.BracketFinder;
import org.apache.commons.math3.optim.univariate.UnivariatePointValuePair;
import org.apache.commons.math3.optim.univariate.SimpleUnivariateValueChecker;
import org.apache.commons.math3.optim.univariate.SearchInterval;
import org.apache.commons.math3.optim.univariate.UnivariateObjectiveFunction;
import org.apache.commons.math3.analysis.UnivariateFunction;
import org.apache.commons.math3.optim.MaxEval;

/**
 * Class for finding the minimum of the objective function along a given
 * direction.
 *
 * @since 3.3
 * @version $Id$
 */
public class LineSearch {
    /**
     * Value that will pass the precondition check for {@link BrentOptimizer}
     * but will not pass the convergence check, so that the custom checker
     * will always decide when to stop the line search.
     */
    private static final double REL_TOL_UNUSED = 1e-15;
    /**
     * Value that will pass the precondition check for {@link BrentOptimizer}
     * but will not pass the convergence check, so that the custom checker
     * will always decide when to stop the line search.
     */
    private static final double ABS_TOL_UNUSED = Double.MIN_VALUE;
    /**
     * Optimizer used for line search.
     */
    private final UnivariateOptimizer lineOptimizer;
    /**
     * Automatic bracketing.
     */
    private final BracketFinder bracket = new BracketFinder();
    /**
     * Extent of the initial interval used to find an interval that
     * brackets the optimum.
     */
    private final double initialBracketingRange;
    /**
     * Optimizer on behalf of which the line search must be performed.
     */
    private final MultivariateOptimizer mainOptimizer;

    /**
     * The {@code BrentOptimizer} default stopping criterion uses the
     * tolerances to check the domain (point) values, not the function
     * values.
     * The {@code relativeTolerance} and {@code absoluteTolerance}
     * arguments are thus passed to a custom checker that will use
     * the function values.
     *
     * @param optimizer Optimizer on behalf of which the line search
     * be performed.
     * Its {@link MultivariateOptimizer#computeObjectiveValue(double[])
     * computeObjectiveValue} method will be called by the
     * {@link #search(double[],double[]) search} method.
     * @param relativeTolerance Search will stop when the function relative
     * difference between successive iterations is smaller than this value.
     * @param absoluteTolerance Search will stop when the function absolute
     * difference between successive iterations is smaller than this value.
     * @param initialBracketingRange Extent of the initial interval used to
     * find an interval that brackets the optimum.
     * If the optimized function varies a lot in the vicinity of the optimum,
     * it may be necessary to provide a value lower than the distance between
     * successive local minima.
     */
    public LineSearch(MultivariateOptimizer optimizer,
                      double relativeTolerance,
                      double absoluteTolerance,
                      double initialBracketingRange) {
        mainOptimizer = optimizer;
        lineOptimizer = new BrentOptimizer(REL_TOL_UNUSED,
                                           ABS_TOL_UNUSED,
                                           new SimpleUnivariateValueChecker(relativeTolerance,
                                                                            absoluteTolerance));
        this.initialBracketingRange = initialBracketingRange;
    }

    /**
     * Finds the number {@code alpha} that optimizes
     * {@code f(startPoint + alpha * direction)}.
     *
     * @param startPoint Starting point.
     * @param direction Search direction.
     * @return the optimum.
     * @throws org.apache.commons.math3.exception.TooManyEvaluationsException
     * if the number of evaluations is exceeded.
     */
    public UnivariatePointValuePair search(final double[] startPoint,
                                           final double[] direction) {
        final int n = startPoint.length;
        final UnivariateFunction f = new UnivariateFunction() {
                public double value(double alpha) {
                    final double[] x = new double[n];
                    for (int i = 0; i < n; i++) {
                        x[i] = startPoint[i] + alpha * direction[i];
                    }
                    final double obj = mainOptimizer.computeObjectiveValue(x);
                    return obj;
                }
            };

        final GoalType goal = mainOptimizer.getGoalType();
        bracket.search(f, goal, 0, initialBracketingRange);
        // Passing "MAX_VALUE" as a dummy value because it is the enclosing
        // class that counts the number of evaluations (and will eventually
        // generate the exception).
        return lineOptimizer.optimize(new MaxEval(Integer.MAX_VALUE),
                                      new UnivariateObjectiveFunction(f),
                                      goal,
                                      new SearchInterval(bracket.getLo(),
                                                         bracket.getHi(),
                                                         bracket.getMid()));
    }
}

@@ -2976,16 +2976,59 @@
 sed to a
+ %7B@link SimpleUnivariateValueChecker%0A     *
  custom 
@@ -3034,16 +3034,17 @@
  checker
+%7D
  that wi
@@ -3049,23 +3049,16 @@
 will use
-%0A     *
  the fun
@@ -3479,36 +3479,29 @@
 erations is 
-smaller than
+below
  this value.
@@ -3632,20 +3632,13 @@
  is 
-smaller than
+below
  thi

MATH-1092 Javadoc.