PDL::GSL::INTEG(3pm)

1INTEG(3)              User Contributed Perl Documentation             INTEG(3)
2
3
4

NAME

6       PDL::GSL::INTEG - PDL interface to numerical integration routines in
7       GSL
8

DESCRIPTION

10       This is an interface to the numerical integration package present in
11       the GNU Scientific Library, which is an implementation of QUADPACK.
12
13       Functions are named gslinteg_{algorithm} where {algorithm} is the
14       QUADPACK naming convention. The available functions are:
15
16       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       (a,\infty)
24       gslinteg_qagil: Adaptive integration on infinite interval of the form
25       (-\infty,b)
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
31       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
37       |RESULT - I|  <= max(epsabs, epsrel |I|)
38
39       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
43       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
49       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
54       Please check the GSL documentation for more information.
55

SYNOPSIS

57          use PDL;
58          use PDL::GSL::INTEG;
59
60          my $a = 1.2;
61          my $b = 3.7;
62          my $epsrel = 0;
63          my $epsabs = 1e-6;
64
65          # Non adaptive integration
66          my ($res,$abserr,$ierr,$neval) = gslinteg_qng(\&myf,$a,$b,$epsrel,$epsabs);
67          # Warnings on
68          my ($res,$abserr,$ierr,$neval) = gslinteg_qng(\&myf,$a,$b,$epsrel,$epsabs,{Warn=>'y'});
69
70          # Adaptive integration with warnings on
71          my $limit = 1000;
72          my $key = 5;
73          my ($res,$abserr,$ierr) = gslinteg_qag(\&myf,$a,$b,$epsrel,
74                                            $epsabs,$limit,$key,{Warn=>'y'});
75
76          sub myf{
77            my ($x) = @_;
78            return exp(-$x**2);
79          }
80

FUNCTIONS

82   qng_meat
83         Signature: (double a(); double b(); double epsabs();
84                          double epsrel(); double [o] result(); double [o] abserr();
85                          int [o] neval(); int [o] ierr(); int gslwarn(); SV* function)
86
87       info not available
88
89       qng_meat does not process bad values.  It will set the bad-value flag
90       of all output piddles if the flag is set for any of the input piddles.
91
92   qag_meat
93         Signature: (double a(); double b(); double epsabs();double epsrel(); int limit();
94                          int key(); double [o] result(); double [o] abserr();int n();int [o] ierr();int gslwarn();; SV* function)
95
96       info not available
97
98       qag_meat does not process bad values.  It will set the bad-value flag
99       of all output piddles if the flag is set for any of the input piddles.
100
101   qags_meat
102         Signature: (double a(); double b(); double epsabs();double epsrel(); int limit();
103                          double [o] result(); double [o] abserr();int n();int [o] ierr();int gslwarn();; SV* function)
104
105       info not available
106
107       qags_meat does not process bad values.  It will set the bad-value flag
108       of all output piddles if the flag is set for any of the input piddles.
109
110   qagp_meat
111         Signature: (double pts(l); double epsabs();double epsrel();int limit();
112                          double [o] result(); double [o] abserr();int n();int [o] ierr();int gslwarn();; SV* function)
113
114       info not available
115
116       qagp_meat does not process bad values.  It will set the bad-value flag
117       of all output piddles if the flag is set for any of the input piddles.
118
119   qagi_meat
120         Signature: (double epsabs();double epsrel(); int limit();
121                          double [o] result(); double [o] abserr(); int n(); int [o] ierr();int gslwarn();; SV* function)
122
123       info not available
124
125       qagi_meat does not process bad values.  It will set the bad-value flag
126       of all output piddles if the flag is set for any of the input piddles.
127
128   qagiu_meat
129         Signature: (double a(); double epsabs();double epsrel();int limit();
130                          double [o] result(); double [o] abserr();int n();int [o] ierr();int gslwarn();; SV* function)
131
132       info not available
133
134       qagiu_meat does not process bad values.  It will set the bad-value flag
135       of all output piddles if the flag is set for any of the input piddles.
136
137   qagil_meat
138         Signature: (double b(); double epsabs();double epsrel();int limit();
139                          double [o] result(); double [o] abserr();int n();int [o] ierr();int gslwarn();; SV* function)
140
141       info not available
142
143       qagil_meat does not process bad values.  It will set the bad-value flag
144       of all output piddles if the flag is set for any of the input piddles.
145
146   qawc_meat
147         Signature: (double a(); double b(); double c(); double epsabs();double epsrel();int limit();
148                          double [o] result(); double [o] abserr();int n();int [o] ierr();int gslwarn();; SV* function)
149
150       info not available
151
152       qawc_meat does not process bad values.  It will set the bad-value flag
153       of all output piddles if the flag is set for any of the input piddles.
154
155   qaws_meat
156         Signature: (double a(); double b();double epsabs();double epsrel();int limit();
157                        double [o] result(); double [o] abserr();int n();
158                        double alpha(); double beta(); int mu(); int nu();int [o] ierr();int gslwarn();; SV* function)
159
160       info not available
161
162       qaws_meat does not process bad values.  It will set the bad-value flag
163       of all output piddles if the flag is set for any of the input piddles.
164
165   qawo_meat
166         Signature: (double a(); double b();double epsabs();double epsrel();int limit();
167                        double [o] result(); double [o] abserr();int n();
168                        int sincosopt(); double omega(); double L(); int nlevels();int [o] ierr();int gslwarn();; SV* function)
169
170       info not available
171
172       qawo_meat does not process bad values.  It will set the bad-value flag
173       of all output piddles if the flag is set for any of the input piddles.
174
175   qawf_meat
176         Signature: (double a(); double epsabs();int limit();
177                        double [o] result(); double [o] abserr();int n();
178                        int sincosopt(); double omega(); int nlevels();int [o] ierr();int gslwarn();; SV* function)
179
180       info not available
181
182       qawf_meat does not process bad values.  It will set the bad-value flag
183       of all output piddles if the flag is set for any of the input piddles.
184
185   gslinteg_qng
186       Non-adaptive Gauss-Kronrod integration
187
188       This function applies the Gauss-Kronrod 10-point, 21-point, 43-point
189       and 87-point integration rules in succession until an estimate of the
190       integral of f over ($a,$b) is achieved within the desired absolute and
191       relative error limits, $epsabs and $epsrel.  It is meant for fast
192       integration of smooth functions. It returns an array with the result,
193       an estimate of the absolute error, an error flag and the number of
194       function evaluations performed.
195
196       Usage:
197
198         ($res,$abserr,$ierr,$neval) = gslinteg_qng($function_ref,$a,$b,
199                                                    $epsrel,$epsabs,[{Warn => $warn}]);
200
201       Example:
202
203          my ($res,$abserr,$ierr,$neval) = gslinteg_qng(\&f,0,1,0,1e-9);
204          # with warnings on
205          my ($res,$abserr,$ierr,$neval) = gslinteg_qng(\&f,0,1,0,1e-9,{Warn => 'y'});
206
207          sub f{
208            my ($x) = @_;
209            return ($x**2.6)*log(1.0/$x);
210          }
211
212   gslinteg_qag
213       Adaptive integration
214
215       This function applies an integration rule adaptively until an estimate
216       of the integral of f over ($a,$b) is achieved within the desired
217       absolute and relative error limits, $epsabs and $epsrel. On each
218       iteration the adaptive integration strategy bisects the interval with
219       the largest error estimate; the maximum number of allowed subdivisions
220       is given by the parameter $limit.  The integration rule is determined
221       by the value of $key, which has to be one of (1,2,3,4,5,6) and
222       correspond to the 15, 21, 31, 41, 51 and 61  point Gauss-Kronrod rules
223       respectively.  It returns an array with the result, an estimate of the
224       absolute error and an error flag.
225
226       Please check the GSL documentation for more information.
227
228       Usage:
229
230         ($res,$abserr,$ierr) = gslinteg_qag($function_ref,$a,$b,$epsrel,
231                                             $epsabs,$limit,$key,[{Warn => $warn}]);
232
233       Example:
234
235         my ($res,$abserr,$ierr) = gslinteg_qag(\&f,0,1,0,1e-10,1000,1);
236         # with warnings on
237         my ($res,$abserr,$ierr) = gslinteg_qag(\&f,0,1,0,1e-10,1000,1,{Warn => 'y'});
238
239         sub f{
240            my ($x) = @_;
241            return ($x**2.6)*log(1.0/$x);
242          }
243
244   gslinteg_qags
245       Adaptive integration with singularities
246
247       This function applies the Gauss-Kronrod 21-point integration rule
248       adaptively until an estimate of the integral of f over ($a,$b) is
249       achieved within the desired absolute and relative error limits, $epsabs
250       and $epsrel. The algorithm is such that it accelerates the convergence
251       of the integral in the presence of discontinuities and integrable
252       singularities.  The maximum number of allowed subdivisions done by the
253       adaptive algorithm must be supplied in the parameter $limit.
254
255       Please check the GSL documentation for more information.
256
257       Usage:
258
259         ($res,$abserr,$ierr) = gslinteg_qags($function_ref,$a,$b,$epsrel,
260                                              $epsabs,$limit,[{Warn => $warn}]);
261
262       Example:
263
264         my ($res,$abserr,$ierr) = gslinteg_qags(\&f,0,1,0,1e-10,1000);
265         # with warnings on
266         ($res,$abserr,$ierr) = gslinteg_qags(\&f,0,1,0,1e-10,1000,{Warn => 'y'});
267
268         sub f{
269            my ($x) = @_;
270            return ($x)*log(1.0/$x);
271          }
272
273   gslinteg_qagp
274       Adaptive integration with known singular points
275
276       This function applies the adaptive integration algorithm used by
277       gslinteg_qags taking into account the location of singular points until
278       an estimate of the integral of f over ($a,$b) is achieved within the
279       desired absolute and relative error limits, $epsabs and $epsrel.
280       Singular points are supplied in the piddle $points, whose endpoints
281       determine the integration range.  So, for example, if the function has
282       singular points at x_1 and x_2 and the integral is desired from a to b
283       (a < x_1 < x_2 < b), $points = pdl(a,x_1,x_2,b).  The maximum number of
284       allowed subdivisions done by the adaptive algorithm must be supplied in
285       the parameter $limit.
286
287       Please check the GSL documentation for more information.
288
289       Usage:
290
291         ($res,$abserr,$ierr) = gslinteg_qagp($function_ref,$points,$epsabs,
292                                              $epsrel,$limit,[{Warn => $warn}])
293
294       Example:
295
296         my $points = pdl(0,1,sqrt(2),3);
297         my ($res,$abserr,$ierr) = gslinteg_qagp(\&f,$points,0,1e-3,1000);
298         # with warnings on
299         ($res,$abserr,$ierr) = gslinteg_qagp(\&f,$points,0,1e-3,1000,{Warn => 'y'});
300
301         sub f{
302           my ($x) = @_;
303           my $x2 = $x**2;
304           my $x3 = $x**3;
305           return $x3 * log(abs(($x2-1.0)*($x2-2.0)));
306         }
307
308   gslinteg_qagi
309       Adaptive integration on infinite interval
310
311       This function estimates the integral of the function f over the
312       infinite interval (-\infty,+\infty) within the desired absolute and
313       relative error limits, $epsabs and $epsrel.  After a transformation,
314       the algorithm of gslinteg_qags with a 15-point Gauss-Kronrod rule is
315       used.  The maximum number of allowed subdivisions done by the adaptive
316       algorithm must be supplied in the parameter $limit.
317
318       Please check the GSL documentation for more information.
319
320       Usage:
321
322         ($res,$abserr,$ierr) = gslinteg_qagi($function_ref,$epsabs,
323                                              $epsrel,$limit,[{Warn => $warn}]);
324
325       Example:
326
327         my ($res,$abserr,$ierr) = gslinteg_qagi(\&myfn,1e-7,0,1000);
328         # with warnings on
329         ($res,$abserr,$ierr) = gslinteg_qagi(\&myfn,1e-7,0,1000,{Warn => 'y'});
330
331         sub myfn{
332           my ($x) = @_;
333           return exp(-$x - $x*$x) ;
334         }
335
336   gslinteg_qagiu
337       Adaptive integration on infinite interval
338
339       This function estimates the integral of the function f over the
340       infinite interval (a,+\infty) within the desired absolute and relative
341       error limits, $epsabs and $epsrel.  After a transformation, the
342       algorithm of gslinteg_qags with a 15-point Gauss-Kronrod rule is used.
343       The maximum number of allowed subdivisions done by the adaptive
344       algorithm must be supplied in the parameter $limit.
345
346       Please check the GSL documentation for more information.
347
348       Usage:
349
350         ($res,$abserr,$ierr) = gslinteg_qagiu($function_ref,$a,$epsabs,
351                                               $epsrel,$limit,[{Warn => $warn}]);
352
353       Example:
354
355         my $alfa = 1;
356         my ($res,$abserr,$ierr) = gslinteg_qagiu(\&f,99.9,1e-7,0,1000);
357         # with warnings on
358         ($res,$abserr,$ierr) = gslinteg_qagiu(\&f,99.9,1e-7,0,1000,{Warn => 'y'});
359
360         sub f{
361           my ($x) = @_;
362           if (($x==0) && ($alfa == 1)) {return 1;}
363           if (($x==0) && ($alfa > 1)) {return 0;}
364           return ($x**($alfa-1))/((1+10*$x)**2);
365         }
366
367   gslinteg_qagil
368       Adaptive integration on infinite interval
369
370       This function estimates the integral of the function f over the
371       infinite interval (-\infty,b) within the desired absolute and relative
372       error limits, $epsabs and $epsrel.  After a transformation, the
373       algorithm of gslinteg_qags with a 15-point Gauss-Kronrod rule is used.
374       The maximum number of allowed subdivisions done by the adaptive
375       algorithm must be supplied in the parameter $limit.
376
377       Please check the GSL documentation for more information.
378
379       Usage:
380
381         ($res,$abserr,$ierr) = gslinteg_qagl($function_ref,$b,$epsabs,
382                                              $epsrel,$limit,[{Warn => $warn}]);
383
384       Example:
385
386         my ($res,$abserr,$ierr) = gslinteg_qagil(\&myfn,1.0,1e-7,0,1000);
387         # with warnings on
388         ($res,$abserr,$ierr) = gslinteg_qagil(\&myfn,1.0,1e-7,0,1000,{Warn => 'y'});
389
390         sub myfn{
391           my ($x) = @_;
392           return exp($x);
393         }
394
395   gslinteg_qawc
396       Adaptive integration for Cauchy principal values
397
398       This function computes the Cauchy principal value of the integral of f
399       over (a,b), with a singularity at c, I = \int_a^b dx f(x)/(x - c). The
400       integral is estimated within the desired absolute and relative error
401       limits, $epsabs and $epsrel.  The maximum number of allowed
402       subdivisions done by the adaptive algorithm must be supplied in the
403       parameter $limit.
404
405       Please check the GSL documentation for more information.
406
407       Usage:
408
409         ($res,$abserr,$ierr) = gslinteg_qawc($function_ref,$a,$b,$c,$epsabs,$epsrel,$limit)
410
411       Example:
412
413         my ($res,$abserr,$ierr) = gslinteg_qawc(\&f,-1,5,0,0,1e-3,1000);
414         # with warnings on
415         ($res,$abserr,$ierr) = gslinteg_qawc(\&f,-1,5,0,0,1e-3,1000,{Warn => 'y'});
416
417         sub f{
418           my ($x) = @_;
419           return 1.0 / (5.0 * $x * $x * $x + 6.0) ;
420         }
421
422   gslinteg_qaws
423       Adaptive integration for singular functions
424
425       The algorithm in gslinteg_qaws is designed for integrands with
426       algebraic-logarithmic singularities at the end-points of an integration
427       region.  Specifically, this function computes the integral given by I =
428       \int_a^b dx f(x) (x-a)^alpha (b-x)^beta log^mu (x-a) log^nu (b-x).  The
429       integral is estimated within the desired absolute and relative error
430       limits, $epsabs and $epsrel.  The maximum number of allowed
431       subdivisions done by the adaptive algorithm must be supplied in the
432       parameter $limit.
433
434       Please check the GSL documentation for more information.
435
436       Usage:
437
438         ($res,$abserr,$ierr) =
439             gslinteg_qawc($function_ref,$alpha,$beta,$mu,$nu,$a,$b,
440                           $epsabs,$epsrel,$limit,[{Warn => $warn}]);
441
442       Example:
443
444         my ($res,$abserr,$ierr) = gslinteg_qaws(\&f,0,0,1,0,0,1,0,1e-7,1000);
445         # with warnings on
446         ($res,$abserr,$ierr) = gslinteg_qaws(\&f,0,0,1,0,0,1,0,1e-7,1000,{Warn => 'y'});
447
448         sub f{
449           my ($x) = @_;
450           if($x==0){return 0;}
451           else{
452             my $u = log($x);
453             my $v = 1 + $u*$u;
454             return 1.0/($v*$v);
455           }
456         }
457
458   gslinteg_qawo
459       Adaptive integration for oscillatory functions
460
461       This function uses an adaptive algorithm to compute the integral of f
462       over (a,b) 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
469       Please check the GSL documentation for more information.
470
471       Usage:
472
473         ($res,$abserr,$ierr) = gslinteg_qawo($function_ref,$omega,$sin_or_cos,
474                                       $a,$b,$epsabs,$epsrel,$limit,[opt])
475
476       Example:
477
478         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
483         sub f{
484           my ($x) = @_;
485           if($x==0){return 0;}
486           else{ return log($x);}
487         }
488
489   gslinteg_qawf
490       Adaptive integration for Fourier integrals
491
492       This function attempts to compute a Fourier integral of the function f
493       over the semi-infinite interval [a,+\infty). Specifically, it attempts
494       tp compute I = \int_a^{+\infty} dx f(x)w(x), where w(x) is sin(omega*x)
495       or cos(omega*x) -- which of sine or cosine is used is determined by the
496       parameter $opt ('cos' or 'sin').  The integral is estimated within the
497       desired absolute error limit $epsabs.  The maximum number of allowed
498       subdivisions done by the adaptive algorithm must be supplied in the
499       parameter $limit.
500
501       Please check the GSL documentation for more information.
502
503       Usage:
504
505         gslinteg_qawf($function_ref,$omega,$sin_or_cos,$a,$epsabs,$limit,[opt])
506
507       Example:
508
509         my ($res,$abserr,$ierr) = gslinteg_qawf(\&f,$PI/2.0,'cos',0,1e-7,1000);
510         # with warnings on
511         ($res,$abserr,$ierr) = gslinteg_qawf(\&f,$PI/2.0,'cos',0,1e-7,1000,{Warn => 'y'});
512
513         sub f{
514           my ($x) = @_;
515           if ($x == 0){return 0;}
516           return 1.0/sqrt($x)
517         }
518

BUGS

520       Feedback is welcome. Log bugs in the PDL bug database (the database is
521       always linked from <http://pdl.perl.org>).
522

AUTHOR

531       This file copyright (C) 2003,2005 Andres Jordan <ajordan@eso.org> All
532       rights reserved. There is no warranty. You are allowed to redistribute
533       this software documentation under certain conditions. For details, see
534       the file COPYING in the PDL distribution. If this file is separated
535       from the PDL distribution, the copyright notice should be included in
536       the file.
537
538       The GSL integration routines were written by Brian Gough. QUADPACK was
539       written by Piessens, Doncker-Kapenga, Uberhuber and Kahaner.
540
541
542
543perl v5.30.0                      2019-09-05                          INTEG(3)

NAME

DESCRIPTION

SYNOPSIS

FUNCTIONS

BUGS

SEE ALSO

AUTHOR