diff scripts/testfun/speed.m @ 20162:2645f9ef8c88 stable

doc: Update more docstrings to have one sentence summary as first line. Reviewed specfun, special-matrix, testfun, and time script directories. * scripts/specfun/expint.m, scripts/specfun/isprime.m, scripts/specfun/legendre.m, scripts/specfun/primes.m, scripts/specfun/reallog.m, scripts/specfun/realsqrt.m, scripts/special-matrix/gallery.m, scripts/special-matrix/hadamard.m, scripts/special-matrix/hankel.m, scripts/special-matrix/hilb.m, scripts/special-matrix/invhilb.m, scripts/special-matrix/magic.m, scripts/special-matrix/pascal.m, scripts/special-matrix/rosser.m, scripts/special-matrix/toeplitz.m, scripts/special-matrix/vander.m, scripts/special-matrix/wilkinson.m, scripts/testfun/assert.m, scripts/testfun/demo.m, scripts/testfun/example.m, scripts/testfun/fail.m, scripts/testfun/rundemos.m, scripts/testfun/runtests.m, scripts/testfun/speed.m, scripts/time/asctime.m, scripts/time/calendar.m, scripts/time/clock.m, scripts/time/ctime.m, scripts/time/datenum.m, scripts/time/datestr.m, scripts/time/datevec.m, scripts/time/etime.m, scripts/time/is_leap_year.m, scripts/time/now.m, scripts/time/weekday.m: Update more docstrings to have one sentence summary as first line.
author Rik <rik@octave.org>
date Sun, 03 May 2015 17:00:11 -0700
parents 9fc020886ae9
children
line wrap: on
line diff
--- a/scripts/testfun/speed.m	Sun May 03 15:36:23 2015 -0700
+++ b/scripts/testfun/speed.m	Sun May 03 17:00:11 2015 -0700
@@ -21,12 +21,14 @@
 ## @deftypefnx {Function File} {[@var{order}, @var{n}, @var{T_f}, @var{T_f2}] =} speed (@dots{})
 ##
 ## Determine the execution time of an expression (@var{f}) for various input
-## values (@var{n}).  The @var{n} are log-spaced from 1 to @var{max_n}.  For
-## each @var{n}, an initialization expression (@var{init}) is computed to
-## create any data needed for the test.  If a second expression (@var{f2}) is
-## given then the execution times of the two expressions are compared.  When
-## called without output arguments the results are printed to stdout and
-## displayed graphically.
+## values (@var{n}).
+##
+## The @var{n} are log-spaced from 1 to @var{max_n}.  For each @var{n}, an
+## initialization expression (@var{init}) is computed to create any data needed
+## for the test.  If a second expression (@var{f2}) is given then the
+## execution times of the two expressions are compared.  When called without
+## output arguments the results are printed to stdout and displayed
+## graphically.
 ##
 ## @table @code
 ## @item @var{f}
@@ -38,10 +40,10 @@
 ## @code{[n1, n2, @dots{}, nk]}.
 ##
 ## @item @var{init}
-## Initialization expression for function argument values.  Use @var{k}
-## for the test number and @var{n} for the size of the test.  This should
-## compute values for all variables used by @var{f}.  Note that @var{init} will
-## be evaluated first for @math{k = 0}, so things which are constant throughout
+## Initialization expression for function argument values.  Use @var{k} for
+## the test number and @var{n} for the size of the test.  This should compute
+## values for all variables used by @var{f}.  Note that @var{init} will be
+## evaluated first for @math{k = 0}, so things which are constant throughout
 ## the test series can be computed once.  The default value is
 ## @code{@var{x} = randn (@var{n}, 1)}.
 ##
@@ -56,8 +58,8 @@
 ## @code{eps}.  If @var{tol} is @code{Inf}, then no comparison will be made.
 ##
 ## @item @var{order}
-## The time complexity of the expression @math{O(a*n^p)}.  This
-## is a structure with fields @code{a} and @code{p}.
+## The time complexity of the expression @math{O(a*n^p)}.  This is a
+## structure with fields @code{a} and @code{p}.
 ##
 ## @item @var{n}
 ## The values @var{n} for which the expression was calculated @strong{AND}
@@ -72,17 +74,15 @@
 ##
 ## @end table
 ##
-## The slope of the execution time graph shows the approximate
-## power of the asymptotic running time @math{O(n^p)}.  This
-## power is plotted for the region over which it is approximated
-## (the latter half of the graph).  The estimated power is not
-## very accurate, but should be sufficient to determine the
-## general order of an algorithm.  It should indicate if, for
-## example, the implementation is unexpectedly @math{O(n^2)}
-## rather than @math{O(n)} because it extends a vector each
-## time through the loop rather than pre-allocating storage.
-## In the current version of Octave, the following is not the
-## expected @math{O(n)}.
+## The slope of the execution time graph shows the approximate power of the
+## asymptotic running time @math{O(n^p)}.  This power is plotted for the
+## region over which it is approximated (the latter half of the graph).  The
+## estimated power is not very accurate, but should be sufficient to
+## determine the general order of an algorithm.  It should indicate if, for
+## example, the implementation is unexpectedly @math{O(n^2)} rather than
+## @math{O(n)} because it extends a vector each time through the loop rather
+## than pre-allocating storage.  In the current version of Octave, the
+## following is not the expected @math{O(n)}.
 ##
 ## @example
 ## speed ("for i = 1:n, y@{i@} = x(i); endfor", "", [1000, 10000])
@@ -98,21 +98,19 @@
 ## @end group
 ## @end example
 ##
-## An attempt is made to approximate the cost of individual
-## operations, but it is wildly inaccurate.  You can improve the
-## stability somewhat by doing more work for each @code{n}.  For
-## example:
+## An attempt is made to approximate the cost of individual operations, but
+## it is wildly inaccurate.  You can improve the stability somewhat by doing
+## more work for each @code{n}.  For example:
 ##
 ## @example
 ## speed ("airy(x)", "x = rand (n, 10)", [10000, 100000])
 ## @end example
 ##
-## When comparing two different expressions (@var{f}, @var{f2}), the slope
-## of the line on the speedup ratio graph should be larger than 1 if the new
+## When comparing two different expressions (@var{f}, @var{f2}), the slope of
+## the line on the speedup ratio graph should be larger than 1 if the new
 ## expression is faster.  Better algorithms have a shallow slope.  Generally,
-## vectorizing an algorithm will not change the slope of the execution
-## time graph, but will shift it relative to the original.  For
-## example:
+## vectorizing an algorithm will not change the slope of the execution time
+## graph, but will shift it relative to the original.  For example:
 ##
 ## @example
 ## @group
@@ -135,12 +133,12 @@
 ## @end group
 ## @end example
 ##
-## Assuming one of the two versions is in xcorr_orig, this
-## would compare their speed and their output values.  Note that the
-## FFT version is not exact, so one must specify an acceptable tolerance on
-## the comparison @code{100*eps}.  In this case, the comparison should be
-## computed relatively, as @code{abs ((@var{x} - @var{y}) ./ @var{y})} rather
-## than absolutely as @code{abs (@var{x} - @var{y})}.
+## Assuming one of the two versions is in xcorr_orig, this would compare their
+## speed and their output values.  Note that the FFT version is not exact, so
+## one must specify an acceptable tolerance on the comparison @code{100*eps}.
+## In this case, the comparison should be computed relatively, as
+## @code{abs ((@var{x} - @var{y}) ./ @var{y})} rather than absolutely as
+## @code{abs (@var{x} - @var{y})}.
 ##
 ## Type @kbd{example ("speed")} to see some real examples or
 ## @kbd{demo ("speed")} to run them.