1INTEG(3) User Contributed Perl Documentation INTEG(3)
2
6 PDL::GSL::INTEG - PDL interface to numerical integration routines in
7 GSL
8
10 This is an interface to the numerical integration package present in
11 the GNU Scientific Library, which is an implementation of QUADPACK.
12 Functions are named gslinteg_{algorithm} where {algorithm} is the
14 QUADPACK naming convention. The available functions are:
15 gslinteg_qng: Non-adaptive Gauss-Kronrod integration
17 gslinteg_qag: Adaptive integration
18 gslinteg_qags: Adaptive integration with singularities
19 gslinteg_qagp: Adaptive integration with known singular points
20 gslinteg_qagi: Adaptive integration on infinite interval of the form
21 (-\infty,\infty)
22 gslinteg_qagiu: Adaptive integration on infinite interval of the form
23 (la,\infty)
24 gslinteg_qagil: Adaptive integration on infinite interval of the form
25 (-\infty,lb)
26 gslinteg_qawc: Adaptive integration for Cauchy principal values
27 gslinteg_qaws: Adaptive integration for singular functions
28 gslinteg_qawo: Adaptive integration for oscillatory functions
29 gslinteg_qawf: Adaptive integration for Fourier integrals
30 Each algorithm computes an approximation to the integral, I, of the
32 function f(x)w(x), where w(x) is a weight function (for general
33 integrands w(x)=1). The user provides absolute and relative error
34 bounds (epsabs,epsrel) which specify the following accuracy
35 requirement:
36 |RESULT - I| <= max(epsabs, epsrel |I|)
38 The routines will fail to converge if the error bounds are too
40 stringent, but always return the best approximation obtained up to that
41 stage
42 All functions return the result, and estimate of the absolute error and
44 an error flag (which is zero if there were no problems). You are
45 responsible for checking for any errors, no warnings are issued unless
46 the option {Warn => 'y'} is specified in which case the reason of
47 failure will be printed.
48 You can nest integrals up to 20 levels. If you find yourself in the
50 unlikely situation that you need more, you can change the value of
51 'max_nested_integrals' in the first line of the file 'FUNC.c' and
52 recompile.
53
55 Throughout this documentation we strive to use the same variables that
56 are present in the original GSL documentation (see See Also).
57 Oftentimes those variables are called "a" and "b". Since good Perl
58 coding practices discourage the use of Perl variables $a and $b, here
59 we refer to Parameters "a" and "b" as $pa and $pb, respectively, and
60 Limits (of domain or integration) as $la and $lb.
61 Please check the GSL documentation for more information.
63
65 use PDL;
66 use PDL::GSL::INTEG;
67 my $la = 1.2;
69 my $lb = 3.7;
70 my $epsrel = 0;
71 my $epsabs = 1e-6;
72 # Non adaptive integration
74 my ($res,$abserr,$ierr,$neval) = gslinteg_qng(\&myf,$la,$lb,$epsrel,$epsabs);
75 # Warnings on
76 my ($res,$abserr,$ierr,$neval) = gslinteg_qng(\&myf,$la,$lb,$epsrel,$epsabs,{Warn=>'y'});
77 # Adaptive integration with warnings on
79 my $limit = 1000;
80 my $key = 5;
81 my ($res,$abserr,$ierr) = gslinteg_qag(\&myf,$la,$lb,$epsrel,
82 $epsabs,$limit,$key,{Warn=>'y'});
83 sub myf{
85 my ($x) = @_;
86 return exp(-$x**2);
87 }
88 #line 133 "INTEG.pm"
89
91 qng_meat
92 Signature: (double a(); double b(); double epsabs();
93 double epsrel(); double [o] result(); double [o] abserr();
94 int [o] neval(); int [o] ierr(); int gslwarn(); SV* function)
95 info not available
97 qng_meat does not process bad values. It will set the bad-value flag
99 of all output ndarrays if the flag is set for any of the input
100 ndarrays.
101 qag_meat
103 Signature: (double a(); double b(); double epsabs();double epsrel(); int limit();
104 int key(); double [o] result(); double [o] abserr();int n();int [o] ierr();int gslwarn();; SV* function)
105 info not available
107 qag_meat does not process bad values. It will set the bad-value flag
109 of all output ndarrays if the flag is set for any of the input
110 ndarrays.
111 qags_meat
113 Signature: (double a(); double b(); double epsabs();double epsrel(); int limit();
114 double [o] result(); double [o] abserr();int n();int [o] ierr();int gslwarn();; SV* function)
115 info not available
117 qags_meat does not process bad values. It will set the bad-value flag
119 of all output ndarrays if the flag is set for any of the input
120 ndarrays.
121 qagp_meat
123 Signature: (double pts(l); double epsabs();double epsrel();int limit();
124 double [o] result(); double [o] abserr();int n();int [o] ierr();int gslwarn();; SV* function)
125 info not available
127 qagp_meat does not process bad values. It will set the bad-value flag
129 of all output ndarrays if the flag is set for any of the input
130 ndarrays.
131 qagi_meat
133 Signature: (double epsabs();double epsrel(); int limit();
134 double [o] result(); double [o] abserr(); int n(); int [o] ierr();int gslwarn();; SV* function)
135 info not available
137 qagi_meat does not process bad values. It will set the bad-value flag
139 of all output ndarrays if the flag is set for any of the input
140 ndarrays.
141 qagiu_meat
143 Signature: (double a(); double epsabs();double epsrel();int limit();
144 double [o] result(); double [o] abserr();int n();int [o] ierr();int gslwarn();; SV* function)
145 info not available
147 qagiu_meat does not process bad values. It will set the bad-value flag
149 of all output ndarrays if the flag is set for any of the input
150 ndarrays.
151 qagil_meat
153 Signature: (double b(); double epsabs();double epsrel();int limit();
154 double [o] result(); double [o] abserr();int n();int [o] ierr();int gslwarn();; SV* function)
155 info not available
157 qagil_meat does not process bad values. It will set the bad-value flag
159 of all output ndarrays if the flag is set for any of the input
160 ndarrays.
161 qawc_meat
163 Signature: (double a(); double b(); double c(); double epsabs();double epsrel();int limit();
164 double [o] result(); double [o] abserr();int n();int [o] ierr();int gslwarn();; SV* function)
165 info not available
167 qawc_meat does not process bad values. It will set the bad-value flag
169 of all output ndarrays if the flag is set for any of the input
170 ndarrays.
171 qaws_meat
173 Signature: (double a(); double b();double epsabs();double epsrel();int limit();
174 double [o] result(); double [o] abserr();int n();
175 double alpha(); double beta(); int mu(); int nu();int [o] ierr();int gslwarn();; SV* function)
176 info not available
178 qaws_meat does not process bad values. It will set the bad-value flag
180 of all output ndarrays if the flag is set for any of the input
181 ndarrays.
182 qawo_meat
184 Signature: (double a(); double b();double epsabs();double epsrel();int limit();
185 double [o] result(); double [o] abserr();int n();
186 int sincosopt(); double omega(); double L(); int nlevels();int [o] ierr();int gslwarn();; SV* function)
187 info not available
189 qawo_meat does not process bad values. It will set the bad-value flag
191 of all output ndarrays if the flag is set for any of the input
192 ndarrays.
193 qawf_meat
195 Signature: (double a(); double epsabs();int limit();
196 double [o] result(); double [o] abserr();int n();
197 int sincosopt(); double omega(); int nlevels();int [o] ierr();int gslwarn();; SV* function)
198 info not available
200 qawf_meat does not process bad values. It will set the bad-value flag
202 of all output ndarrays if the flag is set for any of the input
203 ndarrays.
204 gslinteg_qng - Non-adaptive Gauss-Kronrod integration
206 This function applies the Gauss-Kronrod 10-point, 21-point, 43-point
207 and 87-point integration rules in succession until an estimate of the
208 integral of f over ($la,$lb) is achieved within the desired absolute
209 and relative error limits, $epsabs and $epsrel. It is meant for fast
210 integration of smooth functions. It returns an array with the result,
211 an estimate of the absolute error, an error flag and the number of
212 function evaluations performed.
213 Usage:
215 ($res,$abserr,$ierr,$neval) = gslinteg_qng($function_ref,$la,$lb,
217 $epsrel,$epsabs,[{Warn => $warn}]);
218 Example:
220 my ($res,$abserr,$ierr,$neval) = gslinteg_qng(\&f,0,1,0,1e-9);
222 # with warnings on
223 my ($res,$abserr,$ierr,$neval) = gslinteg_qng(\&f,0,1,0,1e-9,{Warn => 'y'});
224 sub f{
226 my ($x) = @_;
227 return ($x**2.6)*log(1.0/$x);
228 }
229 gslinteg_qag - Adaptive integration
231 This function applies an integration rule adaptively until an estimate
232 of the integral of f over ($la,$lb) is achieved within the desired
233 absolute and relative error limits, $epsabs and $epsrel. On each
234 iteration the adaptive integration strategy bisects the interval with
235 the largest error estimate; the maximum number of allowed subdivisions
236 is given by the parameter $limit. The integration rule is determined
237 by the value of $key, which has to be one of (1,2,3,4,5,6) and
238 correspond to the 15, 21, 31, 41, 51 and 61 point Gauss-Kronrod rules
239 respectively. It returns an array with the result, an estimate of the
240 absolute error and an error flag.
241 Please check the GSL documentation for more information.
243 Usage:
245 ($res,$abserr,$ierr) = gslinteg_qag($function_ref,$la,$lb,$epsrel,
247 $epsabs,$limit,$key,[{Warn => $warn}]);
248 Example:
250 my ($res,$abserr,$ierr) = gslinteg_qag(\&f,0,1,0,1e-10,1000,1);
252 # with warnings on
253 my ($res,$abserr,$ierr) = gslinteg_qag(\&f,0,1,0,1e-10,1000,1,{Warn => 'y'});
254 sub f{
256 my ($x) = @_;
257 return ($x**2.6)*log(1.0/$x);
258 }
259 gslinteg_qags - Adaptive integration with singularities
261 This function applies the Gauss-Kronrod 21-point integration rule
262 adaptively until an estimate of the integral of f over ($la,$lb) is
263 achieved within the desired absolute and relative error limits, $epsabs
264 and $epsrel. The algorithm is such that it accelerates the convergence
265 of the integral in the presence of discontinuities and integrable
266 singularities. The maximum number of allowed subdivisions done by the
267 adaptive algorithm must be supplied in the parameter $limit.
268 Please check the GSL documentation for more information.
270 Usage:
272 ($res,$abserr,$ierr) = gslinteg_qags($function_ref,$la,$lb,$epsrel,
274 $epsabs,$limit,[{Warn => $warn}]);
275 Example:
277 my ($res,$abserr,$ierr) = gslinteg_qags(\&f,0,1,0,1e-10,1000);
279 # with warnings on
280 ($res,$abserr,$ierr) = gslinteg_qags(\&f,0,1,0,1e-10,1000,{Warn => 'y'});
281 sub f{
283 my ($x) = @_;
284 return ($x)*log(1.0/$x);
285 }
286 gslinteg_qagp - Adaptive integration with known singular points
288 This function applies the adaptive integration algorithm used by
289 gslinteg_qags taking into account the location of singular points until
290 an estimate of the integral of f over ($la,$lb) is achieved within the
291 desired absolute and relative error limits, $epsabs and $epsrel.
292 Singular points are supplied in the ndarray $points, whose endpoints
293 determine the integration range. So, for example, if the function has
294 singular points at x_1 and x_2 and the integral is desired from a to b
295 (a < x_1 < x_2 < b), $points = pdl(a,x_1,x_2,b). The maximum number of
296 allowed subdivisions done by the adaptive algorithm must be supplied in
297 the parameter $limit.
298 Please check the GSL documentation for more information.
300 Usage:
302 ($res,$abserr,$ierr) = gslinteg_qagp($function_ref,$points,$epsabs,
304 $epsrel,$limit,[{Warn => $warn}])
305 Example:
307 my $points = pdl(0,1,sqrt(2),3);
309 my ($res,$abserr,$ierr) = gslinteg_qagp(\&f,$points,0,1e-3,1000);
310 # with warnings on
311 ($res,$abserr,$ierr) = gslinteg_qagp(\&f,$points,0,1e-3,1000,{Warn => 'y'});
312 sub f{
314 my ($x) = @_;
315 my $x2 = $x**2;
316 my $x3 = $x**3;
317 return $x3 * log(abs(($x2-1.0)*($x2-2.0)));
318 }
319 gslinteg_qagi - Adaptive integration on infinite interval
321 This function estimates the integral of the function f over the
322 infinite interval (-\infty,+\infty) within the desired absolute and
323 relative error limits, $epsabs and $epsrel. After a transformation,
324 the algorithm of gslinteg_qags with a 15-point Gauss-Kronrod rule is
325 used. The maximum number of allowed subdivisions done by the adaptive
326 algorithm must be supplied in the parameter $limit.
327 Please check the GSL documentation for more information.
329 Usage:
331 ($res,$abserr,$ierr) = gslinteg_qagi($function_ref,$epsabs,
333 $epsrel,$limit,[{Warn => $warn}]);
334 Example:
336 my ($res,$abserr,$ierr) = gslinteg_qagi(\&myfn,1e-7,0,1000);
338 # with warnings on
339 ($res,$abserr,$ierr) = gslinteg_qagi(\&myfn,1e-7,0,1000,{Warn => 'y'});
340 sub myfn{
342 my ($x) = @_;
343 return exp(-$x - $x*$x) ;
344 }
345 gslinteg_qagiu - Adaptive integration on infinite interval
347 This function estimates the integral of the function f over the
348 infinite interval (la,+\infty) within the desired absolute and relative
349 error limits, $epsabs and $epsrel. After a transformation, the
350 algorithm of gslinteg_qags with a 15-point Gauss-Kronrod rule is used.
351 The maximum number of allowed subdivisions done by the adaptive
352 algorithm must be supplied in the parameter $limit.
353 Please check the GSL documentation for more information.
355 Usage:
357 ($res,$abserr,$ierr) = gslinteg_qagiu($function_ref,$la,$epsabs,
359 $epsrel,$limit,[{Warn => $warn}]);
360 Example:
362 my $alfa = 1;
364 my ($res,$abserr,$ierr) = gslinteg_qagiu(\&f,99.9,1e-7,0,1000);
365 # with warnings on
366 ($res,$abserr,$ierr) = gslinteg_qagiu(\&f,99.9,1e-7,0,1000,{Warn => 'y'});
367 sub f{
369 my ($x) = @_;
370 if (($x==0) && ($alfa == 1)) {return 1;}
371 if (($x==0) && ($alfa > 1)) {return 0;}
372 return ($x**($alfa-1))/((1+10*$x)**2);
373 }
374 gslinteg_qagil - Adaptive integration on infinite interval
376 This function estimates the integral of the function f over the
377 infinite interval (-\infty,lb) within the desired absolute and relative
378 error limits, $epsabs and $epsrel. After a transformation, the
379 algorithm of gslinteg_qags with a 15-point Gauss-Kronrod rule is used.
380 The maximum number of allowed subdivisions done by the adaptive
381 algorithm must be supplied in the parameter $limit.
382 Please check the GSL documentation for more information.
384 Usage:
386 ($res,$abserr,$ierr) = gslinteg_qagl($function_ref,$lb,$epsabs,
388 $epsrel,$limit,[{Warn => $warn}]);
389 Example:
391 my ($res,$abserr,$ierr) = gslinteg_qagil(\&myfn,1.0,1e-7,0,1000);
393 # with warnings on
394 ($res,$abserr,$ierr) = gslinteg_qagil(\&myfn,1.0,1e-7,0,1000,{Warn => 'y'});
395 sub myfn{
397 my ($x) = @_;
398 return exp($x);
399 }
400 gslinteg_qawc - Adaptive integration for Cauchy principal values
402 This function computes the Cauchy principal value of the integral of f
403 over (la,lb), with a singularity at c, I = \int_{la}^{lb} dx f(x)/(x -
404 c). The integral is estimated within the desired absolute and relative
405 error limits, $epsabs and $epsrel. The maximum number of allowed
406 subdivisions done by the adaptive algorithm must be supplied in the
407 parameter $limit.
408 Please check the GSL documentation for more information.
410 Usage:
412 ($res,$abserr,$ierr) = gslinteg_qawc($function_ref,$la,$lb,$c,$epsabs,$epsrel,$limit)
414 Example:
416 my ($res,$abserr,$ierr) = gslinteg_qawc(\&f,-1,5,0,0,1e-3,1000);
418 # with warnings on
419 ($res,$abserr,$ierr) = gslinteg_qawc(\&f,-1,5,0,0,1e-3,1000,{Warn => 'y'});
420 sub f{
422 my ($x) = @_;
423 return 1.0 / (5.0 * $x * $x * $x + 6.0) ;
424 }
425 gslinteg_qaws - Adaptive integration for singular functions
427 The algorithm in gslinteg_qaws is designed for integrands with
428 algebraic-logarithmic singularities at the end-points of an integration
429 region. Specifically, this function computes the integral given by I =
430 \int_{la}^{lb} dx f(x) (x-la)^alpha (lb-x)^beta log^mu (x-la) log^nu
431 (lb-x). The integral is estimated within the desired absolute and
432 relative error limits, $epsabs and $epsrel. The maximum number of
433 allowed subdivisions done by the adaptive algorithm must be supplied in
434 the parameter $limit.
435 Please check the GSL documentation for more information.
437 Usage:
439 ($res,$abserr,$ierr) =
441 gslinteg_qawc($function_ref,$alpha,$beta,$mu,$nu,$la,$lb,
442 $epsabs,$epsrel,$limit,[{Warn => $warn}]);
443 Example:
445 my ($res,$abserr,$ierr) = gslinteg_qaws(\&f,0,0,1,0,0,1,0,1e-7,1000);
447 # with warnings on
448 ($res,$abserr,$ierr) = gslinteg_qaws(\&f,0,0,1,0,0,1,0,1e-7,1000,{Warn => 'y'});
449 sub f{
451 my ($x) = @_;
452 if($x==0){return 0;}
453 else{
454 my $u = log($x);
455 my $v = 1 + $u*$u;
456 return 1.0/($v*$v);
457 }
458 }
459 gslinteg_qawo - Adaptive integration for oscillatory functions
461 This function uses an adaptive algorithm to compute the integral of f
462 over (la,lb) with the weight function sin(omega*x) or cos(omega*x) --
463 which of sine or cosine is used is determined by the parameter $opt
464 ('cos' or 'sin'). The integral is estimated within the desired
465 absolute and relative error limits, $epsabs and $epsrel. The maximum
466 number of allowed subdivisions done by the adaptive algorithm must be
467 supplied in the parameter $limit.
468 Please check the GSL documentation for more information.
470 Usage:
472 ($res,$abserr,$ierr) = gslinteg_qawo($function_ref,$omega,$sin_or_cos,
474 $la,$lb,$epsabs,$epsrel,$limit,[opt])
475 Example:
477 my $PI = 3.14159265358979323846264338328;
479 my ($res,$abserr,$ierr) = PDL::GSL::INTEG::gslinteg_qawo(\&f,10*$PI,'sin',0,1,0,1e-7,1000);
480 # with warnings on
481 ($res,$abserr,$ierr) = PDL::GSL::INTEG::gslinteg_qawo(\&f,10*$PI,'sin',0,1,0,1e-7,1000,{Warn => 'y'});
482 sub f{
484 my ($x) = @_;
485 if($x==0){return 0;}
486 else{ return log($x);}
487 }
488 gslinteg_qawf - Adaptive integration for Fourier integrals
490 This function attempts to compute a Fourier integral of the function f
491 over the semi-infinite interval [la,+\infty). Specifically, it attempts
492 tp compute I = \int_{la}^{+\infty} dx f(x)w(x), where w(x) is
493 sin(omega*x) or cos(omega*x) -- which of sine or cosine is used is
494 determined by the parameter $opt ('cos' or 'sin'). The integral is
495 estimated within the desired absolute error limit $epsabs. The maximum
496 number of allowed subdivisions done by the adaptive algorithm must be
497 supplied in the parameter $limit.
498 Please check the GSL documentation for more information.
500 Usage:
502 gslinteg_qawf($function_ref,$omega,$sin_or_cos,$la,$epsabs,$limit,[opt])
504 Example:
506 my ($res,$abserr,$ierr) = gslinteg_qawf(\&f,$PI/2.0,'cos',0,1e-7,1000);
508 # with warnings on
509 ($res,$abserr,$ierr) = gslinteg_qawf(\&f,$PI/2.0,'cos',0,1e-7,1000,{Warn => 'y'});
510 sub f{
512 my ($x) = @_;
513 if ($x == 0){return 0;}
514 return 1.0/sqrt($x)
515 }
516
518 Feedback is welcome. Log bugs in the PDL bug database (the database is
519 always linked from <http://pdl.perl.org>).
520
522 PDL
523 The GSL documentation for numerical integration is online at
525 <https://www.gnu.org/software/gsl/doc/html/integration.html>
526
528 This file copyright (C) 2003,2005 Andres Jordan <ajordan@eso.org> All
529 rights reserved. There is no warranty. You are allowed to redistribute
530 this software documentation under certain conditions. For details, see
531 the file COPYING in the PDL distribution. If this file is separated
532 from the PDL distribution, the copyright notice should be included in
533 the file.
534 The GSL integration routines were written by Brian Gough. QUADPACK was
536 written by Piessens, Doncker-Kapenga, Uberhuber and Kahaner.
537perl v5.34.0 2022-02-28 INTEG(3)