Mercurial > octave-antonio

comparison scripts/general/quadgk.m @ 20158:7503499a252b stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: Update docstrings to have one sentence summary as first line. Update scripts in audio, elfun, general, geometry, and image directories. * scripts/audio/@audioplayer/__get_properties__.m, scripts/audio/@audioplayer/audioplayer.m, scripts/audio/@audioplayer/get.m, scripts/audio/@audioplayer/isplaying.m, scripts/audio/@audioplayer/play.m, scripts/audio/@audioplayer/playblocking.m, scripts/audio/@audioplayer/set.m, scripts/audio/@audioplayer/subsasgn.m, scripts/audio/@audioplayer/subsref.m, scripts/audio/@audiorecorder/audiorecorder.m, scripts/audio/@audiorecorder/get.m, scripts/audio/@audiorecorder/getaudiodata.m, scripts/audio/@audiorecorder/getplayer.m, scripts/audio/@audiorecorder/isrecording.m, scripts/audio/@audiorecorder/play.m, scripts/audio/@audiorecorder/record.m, scripts/audio/@audiorecorder/recordblocking.m, scripts/audio/@audiorecorder/set.m, scripts/audio/@audiorecorder/stop.m, scripts/audio/@audiorecorder/subsasgn.m, scripts/audio/@audiorecorder/subsref.m, scripts/audio/lin2mu.m, scripts/audio/mu2lin.m, scripts/audio/record.m, scripts/audio/sound.m, scripts/audio/soundsc.m, scripts/audio/wavread.m, scripts/audio/wavwrite.m, scripts/elfun/cosd.m, scripts/elfun/sind.m, scripts/elfun/tand.m, scripts/general/accumarray.m, scripts/general/accumdim.m, scripts/general/bitcmp.m, scripts/general/bitget.m, scripts/general/bitset.m, scripts/general/blkdiag.m, scripts/general/cart2pol.m, scripts/general/cart2sph.m, scripts/general/cell2mat.m, scripts/general/celldisp.m, scripts/general/chop.m, scripts/general/circshift.m, scripts/general/common_size.m, scripts/general/cplxpair.m, scripts/general/cumtrapz.m, scripts/general/dblquad.m, scripts/general/deal.m, scripts/general/del2.m, scripts/general/display.m, scripts/general/divergence.m, scripts/general/fieldnames.m, scripts/general/flip.m, scripts/general/flipdim.m, scripts/general/fliplr.m, scripts/general/flipud.m, scripts/general/gradient.m, scripts/general/interp3.m, scripts/general/interpft.m, scripts/general/interpn.m, scripts/general/loadobj.m, scripts/general/logspace.m, scripts/general/methods.m, scripts/general/nargchk.m, scripts/general/narginchk.m, scripts/general/nargoutchk.m, scripts/general/nextpow2.m, scripts/general/nthargout.m, scripts/general/num2str.m, scripts/general/pol2cart.m, scripts/general/polyarea.m, scripts/general/postpad.m, scripts/general/prepad.m, scripts/general/profile.m, scripts/general/quadgk.m, scripts/general/quadl.m, scripts/general/quadv.m, scripts/general/randi.m, scripts/general/rat.m, scripts/general/repmat.m, scripts/general/rot90.m, scripts/general/rotdim.m, scripts/general/saveobj.m, scripts/general/shift.m, scripts/general/shiftdim.m, scripts/general/sortrows.m, scripts/general/sph2cart.m, scripts/general/structfun.m, scripts/general/subsindex.m, scripts/general/trapz.m, scripts/general/triplequad.m, scripts/geometry/delaunayn.m, scripts/geometry/dsearch.m, scripts/geometry/dsearchn.m, scripts/geometry/griddata.m, scripts/geometry/griddata3.m, scripts/geometry/griddatan.m, scripts/geometry/inpolygon.m, scripts/geometry/rectint.m, scripts/geometry/tsearchn.m, scripts/geometry/voronoi.m, scripts/geometry/voronoin.m, scripts/help/__unimplemented__.m, scripts/help/doc.m, scripts/help/doc_cache_create.m, scripts/help/get_first_help_sentence.m, scripts/help/help.m, scripts/help/lookfor.m, scripts/help/print_usage.m, scripts/help/type.m, scripts/help/which.m, scripts/image/autumn.m, scripts/image/bone.m, scripts/image/brighten.m, scripts/image/cmpermute.m, scripts/image/colorcube.m, scripts/image/contrast.m, scripts/image/cool.m, scripts/image/copper.m, scripts/image/cubehelix.m, scripts/image/flag.m, scripts/image/gmap40.m, scripts/image/gray.m, scripts/image/gray2ind.m, scripts/image/hot.m, scripts/image/hsv.m, scripts/image/image.m, scripts/image/imagesc.m, scripts/image/imfinfo.m, scripts/image/imformats.m, scripts/image/imread.m, scripts/image/imshow.m, scripts/image/imwrite.m, scripts/image/iscolormap.m, scripts/image/jet.m, scripts/image/lines.m, scripts/image/ntsc2rgb.m, scripts/image/ocean.m, scripts/image/pink.m, scripts/image/prism.m, scripts/image/rainbow.m, scripts/image/rgb2ntsc.m, scripts/image/spinmap.m, scripts/image/spring.m, scripts/image/summer.m, scripts/image/white.m, scripts/image/winter.m: Update docstrings to have one sentence summary as first line. Re-structure to have line lengths <= 80 chars.
author Rik <rik@octave.org>
date Sun, 03 May 2015 09:36:20 -0700
parents 9fc020886ae9
children
comparison
equal deleted inserted replaced
20153:3b3579ad7e46 20158:7503499a252b
23 ## @deftypefnx {Function File} {@var{q} =} quadgk (@var{f}, @var{a}, @var{b}, @var{prop}, @var{val}, @dots{}) 23 ## @deftypefnx {Function File} {@var{q} =} quadgk (@var{f}, @var{a}, @var{b}, @var{prop}, @var{val}, @dots{})
24 ## @deftypefnx {Function File} {[@var{q}, @var{err}] =} quadgk (@dots{}) 24 ## @deftypefnx {Function File} {[@var{q}, @var{err}] =} quadgk (@dots{})
25 ## 25 ##
26 ## Numerically evaluate the integral of @var{f} from @var{a} to @var{b} 26 ## Numerically evaluate the integral of @var{f} from @var{a} to @var{b}
27 ## using adaptive Gauss-Konrod quadrature. 27 ## using adaptive Gauss-Konrod quadrature.
28 ## @var{f} is a function handle, inline function, or string 28 ##
29 ## containing the name of the function to evaluate. 29 ## @var{f} is a function handle, inline function, or string containing the name
30 ## The formulation is based on a proposal by @nospell{L.F. Shampine}, 30 ## of the function to evaluate. The function @var{f} must be vectorized and
31 ## @cite{"Vectorized adaptive quadrature in @sc{matlab}", Journal of 31 ## return a vector of output values when given a vector of input values.
32 ## Computational and Applied Mathematics, pp131-140, Vol 211, Issue 2,
33 ## Feb 2008} where all function evaluations at an iteration are
34 ## calculated with a single call to @var{f}. Therefore, the function
35 ## @var{f} must be vectorized and must accept a vector of input values @var{x}
36 ## and return an output vector representing the function evaluations at the
37 ## given values of @var{x}.
38 ## 32 ##
39 ## @var{a} and @var{b} are the lower and upper limits of integration. Either 33 ## @var{a} and @var{b} are the lower and upper limits of integration. Either
40 ## or both limits may be infinite or contain weak end singularities. 34 ## or both limits may be infinite or contain weak end singularities. Variable
41 ## Variable transformation will be used to treat any infinite intervals and 35 ## transformation will be used to treat any infinite intervals and weaken the
42 ## weaken the singularities. For example: 36 ## singularities. For example:
43 ## 37 ##
44 ## @example 38 ## @example
45 ## quadgk (@@(x) 1 ./ (sqrt (x) .* (x + 1)), 0, Inf) 39 ## quadgk (@@(x) 1 ./ (sqrt (x) .* (x + 1)), 0, Inf)
46 ## @end example 40 ## @end example
47 ## 41 ##
48 ## @noindent 42 ## @noindent
49 ## Note that the formulation of the integrand uses the 43 ## Note that the formulation of the integrand uses the element-by-element
50 ## element-by-element operator @code{./} and all user functions to 44 ## operator @code{./} and all user functions to @code{quadgk} should do the
51 ## @code{quadgk} should do the same. 45 ## same.
52 ## 46 ##
53 ## The optional argument @var{tol} defines the absolute tolerance used to stop 47 ## The optional argument @var{tol} defines the absolute tolerance used to stop
54 ## the integration procedure. The default value is @math{1e^{-10}}. 48 ## the integration procedure. The default value is 1e-10.
55 ## 49 ##
56 ## The algorithm used by @code{quadgk} involves subdividing the 50 ## The algorithm used by @code{quadgk} involves subdividing the integration
57 ## integration interval and evaluating each subinterval. 51 ## interval and evaluating each subinterval. If @var{trace} is true then after
58 ## If @var{trace} is true then after computing each of these partial 52 ## computing each of these partial integrals display: (1) the number of
59 ## integrals display: (1) the number of subintervals at this step, 53 ## subintervals at this step, (2) the current estimate of the error @var{err},
60 ## (2) the current estimate of the error @var{err}, (3) the current estimate 54 ## (3) the current estimate for the integral @var{q}.
61 ## for the integral @var{q}.
62 ## 55 ##
63 ## Alternatively, properties of @code{quadgk} can be passed to the function as 56 ## Alternatively, properties of @code{quadgk} can be passed to the function as
64 ## pairs @qcode{"@var{prop}", @var{val}}. Valid properties are 57 ## pairs @qcode{"@var{prop}", @var{val}}. Valid properties are
65 ## 58 ##
66 ## @table @code 59 ## @table @code
71 ## @item RelTol 64 ## @item RelTol
72 ## Define the relative error tolerance for the quadrature. The default 65 ## Define the relative error tolerance for the quadrature. The default
73 ## relative tolerance is 1e-5. 66 ## relative tolerance is 1e-5.
74 ## 67 ##
75 ## @item MaxIntervalCount 68 ## @item MaxIntervalCount
76 ## @code{quadgk} initially subdivides the interval on which to perform 69 ## @code{quadgk} initially subdivides the interval on which to perform the
77 ## the quadrature into 10 intervals. Subintervals that have an 70 ## quadrature into 10 intervals. Subintervals that have an unacceptable error
78 ## unacceptable error are subdivided and re-evaluated. If the number of 71 ## are subdivided and re-evaluated. If the number of subintervals exceeds 650
79 ## subintervals exceeds 650 subintervals at any point then a poor 72 ## subintervals at any point then a poor convergence is signaled and the
80 ## convergence is signaled and the current estimate of the integral is 73 ## current estimate of the integral is returned. The property
81 ## returned. The property @qcode{"MaxIntervalCount"} can be used to alter the 74 ## @qcode{"MaxIntervalCount"} can be used to alter the number of subintervals
82 ## number of subintervals that can exist before exiting. 75 ## that can exist before exiting.
83 ## 76 ##
84 ## @item WayPoints 77 ## @item WayPoints
85 ## Discontinuities in the first derivative of the function to integrate can be 78 ## Discontinuities in the first derivative of the function to integrate can be
86 ## flagged with the @qcode{"WayPoints"} property. This forces the ends of 79 ## flagged with the @qcode{"WayPoints"} property. This forces the ends of a
87 ## a subinterval to fall on the breakpoints of the function and can result in 80 ## subinterval to fall on the breakpoints of the function and can result in
88 ## significantly improved estimation of the error in the integral, faster 81 ## significantly improved estimation of the error in the integral, faster
89 ## computation, or both. For example, 82 ## computation, or both. For example,
90 ## 83 ##
91 ## @example 84 ## @example
92 ## quadgk (@@(x) abs (1 - x.^2), 0, 2, "Waypoints", 1) 85 ## quadgk (@@(x) abs (1 - x.^2), 0, 2, "Waypoints", 1)
94 ## 87 ##
95 ## @noindent 88 ## @noindent
96 ## signals the breakpoint in the integrand at @code{@var{x} = 1}. 89 ## signals the breakpoint in the integrand at @code{@var{x} = 1}.
97 ## 90 ##
98 ## @item Trace 91 ## @item Trace
99 ## If logically true @code{quadgk} prints information on the 92 ## If logically true @code{quadgk} prints information on the convergence of the
100 ## convergence of the quadrature at each iteration. 93 ## quadrature at each iteration.
101 ## @end table 94 ## @end table
102 ## 95 ##
103 ## If any of @var{a}, @var{b}, or @var{waypoints} is complex then the 96 ## If any of @var{a}, @var{b}, or @var{waypoints} is complex then the
104 ## quadrature is treated as a contour integral along a piecewise 97 ## quadrature is treated as a contour integral along a piecewise continuous
105 ## continuous path defined by the above. In this case the integral is 98 ## path defined by the above. In this case the integral is assumed to have no
106 ## assumed to have no edge singularities. For example, 99 ## edge singularities. For example,
107 ## 100 ##
108 ## @example 101 ## @example
109 ## @group 102 ## @group
110 ## quadgk (@@(z) log (z), 1+1i, 1+1i, "WayPoints", 103 ## quadgk (@@(z) log (z), 1+1i, 1+1i, "WayPoints",
111 ## [1-1i, -1,-1i, -1+1i]) 104 ## [1-1i, -1,-1i, -1+1i])
112 ## @end group 105 ## @end group
113 ## @end example 106 ## @end example
114 ## 107 ##
115 ## @noindent 108 ## @noindent
116 ## integrates @code{log (z)} along the square defined by @code{[1+1i, 109 ## integrates @code{log (z)} along the square defined by
117 ## 1-1i, -1-1i, -1+1i]} 110 ## @code{[1+1i, 1-1i, -1-1i, -1+1i]}.
118 ## 111 ##
119 ## The result of the integration is returned in @var{q}. 112 ## The result of the integration is returned in @var{q}.
113 ##
120 ## @var{err} is an approximate bound on the error in the integral 114 ## @var{err} is an approximate bound on the error in the integral
121 ## @code{abs (@var{q} - @var{I})}, where @var{I} is the exact value of the 115 ## @code{abs (@var{q} - @var{I})}, where @var{I} is the exact value of the
122 ## integral. 116 ## integral.
117 ##
118 ## Reference: @nospell{L.F. Shampine},
119 ## @cite{"Vectorized adaptive quadrature in @sc{matlab}"}, Journal of
120 ## Computational and Applied Mathematics, pp. 131--140, Vol 211, Issue 2,
121 ## Feb 2008.
123 ## 122 ##
124 ## @seealso{quad, quadv, quadl, quadcc, trapz, dblquad, triplequad} 123 ## @seealso{quad, quadv, quadl, quadcc, trapz, dblquad, triplequad}
125 ## @end deftypefn 124 ## @end deftypefn
126 125
127 function [q, err] = quadgk (f, a, b, varargin) 126 function [q, err] = quadgk (f, a, b, varargin)