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       (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
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

NOMENCLATURE

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
62       Please check the GSL documentation for more information.
63

SYNOPSIS

65          use PDL;
66          use PDL::GSL::INTEG;
67
68          my $la = 1.2;
69          my $lb = 3.7;
70          my $epsrel = 0;
71          my $epsabs = 1e-6;
72
73          # 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
78          # 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
84          sub myf{
85            my ($x) = @_;
86            return exp(-$x**2);
87          }
88       #line 133 "INTEG.pm"
89

FUNCTIONS

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
96       info not available
97
98       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
102   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
106       info not available
107
108       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
112   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
116       info not available
117
118       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
122   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
126       info not available
127
128       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
132   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
136       info not available
137
138       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
142   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
146       info not available
147
148       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
152   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
156       info not available
157
158       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
162   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
166       info not available
167
168       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
172   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
177       info not available
178
179       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
183   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
188       info not available
189
190       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
194   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
199       info not available
200
201       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
205   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
214       Usage:
215
216         ($res,$abserr,$ierr,$neval) = gslinteg_qng($function_ref,$la,$lb,
217                                                    $epsrel,$epsabs,[{Warn => $warn}]);
218
219       Example:
220
221          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
225          sub f{
226            my ($x) = @_;
227            return ($x**2.6)*log(1.0/$x);
228          }
229
230   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
242       Please check the GSL documentation for more information.
243
244       Usage:
245
246         ($res,$abserr,$ierr) = gslinteg_qag($function_ref,$la,$lb,$epsrel,
247                                             $epsabs,$limit,$key,[{Warn => $warn}]);
248
249       Example:
250
251         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
255         sub f{
256            my ($x) = @_;
257            return ($x**2.6)*log(1.0/$x);
258          }
259
260   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
269       Please check the GSL documentation for more information.
270
271       Usage:
272
273         ($res,$abserr,$ierr) = gslinteg_qags($function_ref,$la,$lb,$epsrel,
274                                              $epsabs,$limit,[{Warn => $warn}]);
275
276       Example:
277
278         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
282         sub f{
283            my ($x) = @_;
284            return ($x)*log(1.0/$x);
285          }
286
287   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
299       Please check the GSL documentation for more information.
300
301       Usage:
302
303         ($res,$abserr,$ierr) = gslinteg_qagp($function_ref,$points,$epsabs,
304                                              $epsrel,$limit,[{Warn => $warn}])
305
306       Example:
307
308         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
313         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
320   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
328       Please check the GSL documentation for more information.
329
330       Usage:
331
332         ($res,$abserr,$ierr) = gslinteg_qagi($function_ref,$epsabs,
333                                              $epsrel,$limit,[{Warn => $warn}]);
334
335       Example:
336
337         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
341         sub myfn{
342           my ($x) = @_;
343           return exp(-$x - $x*$x) ;
344         }
345
346   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
354       Please check the GSL documentation for more information.
355
356       Usage:
357
358         ($res,$abserr,$ierr) = gslinteg_qagiu($function_ref,$la,$epsabs,
359                                               $epsrel,$limit,[{Warn => $warn}]);
360
361       Example:
362
363         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
368         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
375   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
383       Please check the GSL documentation for more information.
384
385       Usage:
386
387         ($res,$abserr,$ierr) = gslinteg_qagl($function_ref,$lb,$epsabs,
388                                              $epsrel,$limit,[{Warn => $warn}]);
389
390       Example:
391
392         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
396         sub myfn{
397           my ($x) = @_;
398           return exp($x);
399         }
400
401   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
409       Please check the GSL documentation for more information.
410
411       Usage:
412
413         ($res,$abserr,$ierr) = gslinteg_qawc($function_ref,$la,$lb,$c,$epsabs,$epsrel,$limit)
414
415       Example:
416
417         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
421         sub f{
422           my ($x) = @_;
423           return 1.0 / (5.0 * $x * $x * $x + 6.0) ;
424         }
425
426   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
436       Please check the GSL documentation for more information.
437
438       Usage:
439
440         ($res,$abserr,$ierr) =
441             gslinteg_qawc($function_ref,$alpha,$beta,$mu,$nu,$la,$lb,
442                           $epsabs,$epsrel,$limit,[{Warn => $warn}]);
443
444       Example:
445
446         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
450         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
460   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
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                                       $la,$lb,$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 - 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
499       Please check the GSL documentation for more information.
500
501       Usage:
502
503         gslinteg_qawf($function_ref,$omega,$sin_or_cos,$la,$epsabs,$limit,[opt])
504
505       Example:
506
507         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
511         sub f{
512           my ($x) = @_;
513           if ($x == 0){return 0;}
514           return 1.0/sqrt($x)
515         }
516

BUGS

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

SEE ALSO

522       PDL
523
524       The GSL documentation for numerical integration is online at
525       <https://www.gnu.org/software/gsl/doc/html/integration.html>
526

AUTHOR

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
535       The GSL integration routines were written by Brian Gough. QUADPACK was
536       written by Piessens, Doncker-Kapenga, Uberhuber and Kahaner.
537
538
539
540perl v5.36.0                      2023-01-20                          INTEG(3)
Impressum