From: Jean-Paul Pelteret Date: Tue, 18 Sep 2018 08:31:51 +0000 (+0200) Subject: Further clean up documentation for line minimization algorithms. X-Git-Tag: v9.1.0-rc1~696^2~1 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c033c03dff61611988b62e7baadc51442ee9809d;p=dealii.git Further clean up documentation for line minimization algorithms. --- diff --git a/include/deal.II/optimization/line_minimization.h b/include/deal.II/optimization/line_minimization.h index 6cbef42b64..f89f51a3d0 100644 --- a/include/deal.II/optimization/line_minimization.h +++ b/include/deal.II/optimization/line_minimization.h @@ -62,8 +62,8 @@ namespace LineMinimization * Given $x\_low$ and $x\_hi$ together with values of function * $f(x\_low)$ and $f(x\_hi)$) and its gradients ($g(x\_low)*g(x\_hi) < 0$) at * those points, return the local minimizer of the cubic interpolation - * function. That is the location where the cubic interpolation function - * attains its minimum. + * function (that is, the location where the cubic interpolation function + * attains its minimum value). * * The return type is optional as the real-valued solution might not exist. */ @@ -94,12 +94,15 @@ namespace LineMinimization const NumberType f_rec); /** - * Return the minimizer of a polynomial using function values @p f_low @p f_hi @p f_rec[0] at three points - * @p x_low @p x_hi @p x_rec[0] and derivatives at two points @p g_low and @p g_hi. The returned point - * should be within the bounds @p bounds . + * Return the minimizer of a polynomial using function values @p f_low , + * @p f_hi , and @p f_rec[0] at three points @p x_low , @p x_hi , and + * @p x_rec[0] as well as the derivatives at two points @p g_low and @p g_hi. + * The returned point should be within the bounds @p bounds . * - * This function will first try the cubic_fit(). If it's unsuccessful or not, within the provided @p bounds, - * the quadratic_fit() will be performed. The function will fallback to bisection if quadratic_fit() fails. + * This function will first try to perform a cubic_fit(). If its unsuccessful, + * or if the minimum is not within the provided @p bounds, a quadratic_fit() + * will be performed. The function will fallback to a bisection method if + * quadratic_fit() fails as well. */ template NumberType @@ -115,7 +118,7 @@ namespace LineMinimization const std::pair bounds); /** - * Same as above but doing cubic fit with three points (see + * Same as poly_fit(), but performing a cubic fit with three points (see * cubic_fit_three_points() ). */ template @@ -138,20 +141,38 @@ namespace LineMinimization * f(\alpha) \le f(0) + \alpha \mu f'(0) \\ * |f'(\alpha)| \le \eta |f'(0)| * \f] - * using one dimensional - * functions @p func and a function @p interpolate to choose a new point - * from the interval based on the function values and derivatives at its ends. - * @p a1 is a trial estimate of the first step. - * Interpolation can be done using poly_fit or poly_fit_three_points . + * using the one dimensional function @p func in conjunction with a function @p interpolate + * to choose a new point from the interval based on the function values and + * derivatives at its ends. + * The parameter @p a1 is a trial estimate of the first step. + * Interpolation can be done using either poly_fit() or + * poly_fit_three_points(), or any other function that has a similar + * signature. * - * The function implements Algorithms - * 2.6.2 and 2.6.4 on pages 34-35 in Fletcher, 2013, Practical methods of - * optimization. these are minor variations of the Algorithm 3.5 and 3.6 on - * pages 60-61 in Nocedal and Wright, Numerical optimization. + * The function implements Algorithms 2.6.2 and 2.6.4 on pages 34-35 in + * @code{.bib} + * @book{Fletcher2013, + * title = {Practical methods of optimization}, + * publisher = {John Wiley \& Sons}, + * year = {2013}, + * author = {Fletcher, Roger}, + * isbn = {978-0-471-49463-8}, + * doi = {10.1002/9781118723203}, + * } + * @endcode + * These are minor variations of Algorithms 3.5 and 3.6 on pages 60-61 in + * @code{.bib} + * @book{Nocedal2006, + * title = {Numerical Optimization}, + * publisher = {Springer New York}, + * year = {2006}, + * author = {Jorge Nocedal and S. Wright}, + * address = {233 Spring Street, New York, NY 10013, USA}, + * doi = {10.1007/978-0-387-40065-5}, + * } + * @endcode * It consists of a bracketing phase and a zoom phase, where @p interpolate is used. * - * The function returns the step size and the number of times function @p func was called. - * * @param func A one dimensional function which returns value and derivative * at the given point. * @param f0 The function value at the origin. @@ -168,6 +189,8 @@ namespace LineMinimization * @param max_evaluations The maximum allowed number of function evaluations. * @param debug_output A flag to output extra debug information into the * deallog static object. + * @return The function returns the step size and the number of times function + * @p func was called. */ template std::pair @@ -194,9 +217,13 @@ namespace LineMinimization const unsigned int max_evaluations = 20, const bool debug_output = false); + // ------------------- inline and template functions ---------------- + + #ifndef DOXYGEN + template boost::optional quadratic_fit(const NumberType x1, @@ -213,6 +240,8 @@ namespace LineMinimization return (g1 * (x2 * x2 - x1 * x1) + 2. * (f1 - f2) * x1) / denom; } + + template boost::optional cubic_fit(const NumberType x1, @@ -283,6 +312,7 @@ namespace LineMinimization } + template NumberType poly_fit(const NumberType x1, @@ -357,6 +387,7 @@ namespace LineMinimization } + template std::pair line_search( @@ -609,7 +640,7 @@ namespace LineMinimization return std::make_pair(std::numeric_limits::signaling_NaN(), i); } -#endif +#endif // DOXYGEN } // namespace LineMinimization