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 QUAD‐
14       PACK naming convention. The available functions are:
15
16       ·  gslinteg_qng: Non-adaptive Gauss-Kronrod integration
17
18       ·  gslinteg_qag: Adaptive integration
19
20       ·  gslinteg_qags: Adaptive integration with singularities
21
22       ·  gslinteg_qagp: Adaptive integration with known singular points
23
24       ·  gslinteg_qagi: Adaptive integration on infinite interval of the form
25          (-\infty,\infty)
26
27       ·  gslinteg_qagiu: Adaptive integration on infinite interval of the
28          form (a,\infty)
29
30       ·  gslinteg_qagil: Adaptive integration on infinite interval of the
31          form (-\infty,b)
32
33       ·  gslinteg_qawc: Adaptive integration for Cauchy principal values
34
35       ·  gslinteg_qaws: Adaptive integration for singular functions
36
37       ·  gslinteg_qawo: Adaptive integration for oscillatory functions
38
39       ·  gslinteg_qawf: Adaptive integration for Fourier integrals
40
41       Each algorithm computes an approximation to the integral, I, of the
42       function f(x)w(x), where w(x) is a weight function (for general inte‐
43       grands w(x)=1). The user provides absolute and relative error bounds
44       (epsabs,epsrel) which specify the following accuracy requirement:
45
46       ⎪RESULT - I⎪  <= max(epsabs, epsrel ⎪I⎪)
47
48       The routines will fail to converge if the error bounds are too strin‐
49       gent, but always return the best approximation obtained up to that
50       stage
51
52       All functions return the result, and estimate of the absolute error and
53       an error flag (which is zero if there were no problems).  You are
54       responsible for checking for any errors, no warnings are issued unless
55       the option {Warn => 'y'} is specified in which case the reason of fail‐
56       ure will be printed.
57
58       You can nest integrals up to 20 levels. If you find yourself in the
59       unlikely situation that you need more, you can change the value of
60       'max_nested_integrals' in the first line of the file 'FUNC.c' and
61       recompile.
62
63       Please check the GSL documentation for more information.
64

SYNOPSIS

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

FUNCTIONS

91       gslinteg_qng() -- Non-adaptive Gauss-Kronrod integration
92
93       This function applies the Gauss-Kronrod 10-point, 21-point, 43-point
94       and 87-point integration rules in succession until an estimate of the
95       integral of f over ($a,$b) is achieved within the desired absolute and
96       relative error limits, $epsabs and $epsrel.  It is meant for fast inte‐
97       gration of smooth functions. It returns an array with the result, an
98       estimate of the absolute error, an error flag and the number of func‐
99       tion evaluations performed.
100
101       Usage:
102
103         ($res,$abserr,$ierr,$neval) = gslinteg_qng($function_ref,$a,$b,
104                                                    $epsrel,$epsabs,[{Warn => $warn}]);
105
106       Example:
107
108          my ($res,$abserr,$ierr,$neval) = gslinteg_qng(\&f,0,1,0,1e-9);
109          # with warnings on
110          my ($res,$abserr,$ierr,$neval) = gslinteg_qng(\&f,0,1,0,1e-9,{Warn => 'y'});
111
112          sub f{
113            my ($x) = @_;
114            return ($x**2.6)*log(1.0/$x);
115          }
116
117       gslinteg_qag() -- Adaptive integration
118
119       This function applies an integration rule adaptively until an estimate
120       of the integral of f over ($a,$b) is achieved within the desired abso‐
121       lute and relative error limits, $epsabs and $epsrel. On each iteration
122       the adaptive integration strategy bisects the interval with the largest
123       error estimate; the maximum number of allowed subdivisions is given by
124       the parameter $limit.  The integration rule is determined by the value
125       of $key, which has to be one of (1,2,3,4,5,6) and correspond to the 15,
126       21, 31, 41, 51 and 61  point Gauss-Kronrod rules respectively.  It
127       returns an array with the result, an estimate of the absolute error and
128       an error flag.
129
130       Please check the GSL documentation for more information.
131
132       Usage:
133
134         ($res,$abserr,$ierr) = gslinteg_qag($function_ref,$a,$b,$epsrel,
135                                             $epsabs,$limit,$key,[{Warn => $warn}]);
136
137       Example:
138
139         my ($res,$abserr,$ierr) = gslinteg_qag(\&f,0,1,0,1e-10,1000,1);
140         # with warnings on
141         my ($res,$abserr,$ierr) = gslinteg_qag(\&f,0,1,0,1e-10,1000,1,{Warn => 'y'});
142
143         sub f{
144            my ($x) = @_;
145            return ($x**2.6)*log(1.0/$x);
146          }
147
148       gslinteg_qags() -- Adaptive integration with singularities
149
150       This function applies the Gauss-Kronrod 21-point integration rule adap‐
151       tively until an estimate of the integral of f over ($a,$b) is achieved
152       within the desired absolute and relative error limits, $epsabs and
153       $epsrel. The algorithm is such that it accelerates the convergence of
154       the integral in the presence of discontinuities and integrable singu‐
155       larities.  The maximum number of allowed subdivisions done by the adap‐
156       tive algorithm must be supplied in the parameter $limit.
157
158       Please check the GSL documentation for more information.
159
160       Usage:
161
162         ($res,$abserr,$ierr) = gslinteg_qags($function_ref,$a,$b,$epsrel,
163                                              $epsabs,$limit,[{Warn => $warn}]);
164
165       Example:
166
167         my ($res,$abserr,$ierr) = gslinteg_qags(\&f,0,1,0,1e-10,1000);
168         # with warnings on
169         ($res,$abserr,$ierr) = gslinteg_qags(\&f,0,1,0,1e-10,1000,{Warn => 'y'});
170
171         sub f{
172            my ($x) = @_;
173            return ($x)*log(1.0/$x);
174          }
175
176       gslinteg_qagp() -- Adaptive integration with known singular points
177
178       This function applies the adaptive integration algorithm used by gslin‐
179       teg_qags taking into account the location of singular points until an
180       estimate of the integral of f over ($a,$b) is achieved within the
181       desired absolute and relative error limits, $epsabs and $epsrel.  Sin‐
182       gular points are supplied in the piddle $points, whose endpoints deter‐
183       mine the integration range.  So, for example, if the function has sin‐
184       gular points at x_1 and x_2 and the integral is desired from a to b (a
185       < x_1 < x_2 < b), $points = pdl(a,x_1,x_2,b).  The maximum number of
186       allowed subdivisions done by the adaptive algorithm must be supplied in
187       the parameter $limit.
188
189       Please check the GSL documentation for more information.
190
191       Usage:
192
193         ($res,$abserr,$ierr) = gslinteg_qagp($function_ref,$points,$epsabs,
194                                              $epsrel,$limit,[{Warn => $warn}])
195
196       Example:
197
198         my $points = pdl(0,1,sqrt(2),3);
199         my ($res,$abserr,$ierr) = gslinteg_qagp(\&f,$points,0,1e-3,1000);
200         # with warnings on
201         ($res,$abserr,$ierr) = gslinteg_qagp(\&f,$points,0,1e-3,1000,{Warn => 'y'});
202
203         sub f{
204           my ($x) = @_;
205           my $x2 = $x**2;
206           my $x3 = $x**3;
207           return $x3 * log(abs(($x2-1.0)*($x2-2.0)));
208         }
209
210       gslinteg_qagi() -- Adaptive integration on infinite interval
211
212       This function estimates the integral of the function f over the infi‐
213       nite interval (-\infty,+\infty) within the desired absolute and rela‐
214       tive error limits, $epsabs and $epsrel.  After a transformation, the
215       algorithm of gslinteg_qags with a 15-point Gauss-Kronrod rule is used.
216       The maximum number of allowed subdivisions done by the adaptive algo‐
217       rithm must be supplied in the parameter $limit.
218
219       Please check the GSL documentation for more information.
220
221       Usage:
222
223         ($res,$abserr,$ierr) = gslinteg_qagi($function_ref,$epsabs,
224                                              $epsrel,$limit,[{Warn => $warn}]);
225
226       Example:
227
228         my ($res,$abserr,$ierr) = gslinteg_qagi(\&myfn,1e-7,0,1000);
229         # with warnings on
230         ($res,$abserr,$ierr) = gslinteg_qagi(\&myfn,1e-7,0,1000,{Warn => 'y'});
231
232         sub myfn{
233           my ($x) = @_;
234           return exp(-$x - $x*$x) ;
235         }
236
237       gslinteg_qagiu() -- Adaptive integration on infinite interval
238
239       This function estimates the integral of the function f over the infi‐
240       nite interval (a,+\infty) within the desired absolute and relative
241       error limits, $epsabs and $epsrel.  After a transformation, the algo‐
242       rithm of gslinteg_qags with a 15-point Gauss-Kronrod rule is used.  The
243       maximum number of allowed subdivisions done by the adaptive algorithm
244       must be supplied in the parameter $limit.
245
246       Please check the GSL documentation for more information.
247
248       Usage:
249
250         ($res,$abserr,$ierr) = gslinteg_qagiu($function_ref,$a,$epsabs,
251                                               $epsrel,$limit,[{Warn => $warn}]);
252
253       Example:
254
255         my $alfa = 1;
256         my ($res,$abserr,$ierr) = gslinteg_qagiu(\&f,99.9,1e-7,0,1000);
257         # with warnings on
258         ($res,$abserr,$ierr) = gslinteg_qagiu(\&f,99.9,1e-7,0,1000,{Warn => 'y'});
259
260         sub f{
261           my ($x) = @_;
262           if (($x==0) && ($alfa == 1)) {return 1;}
263           if (($x==0) && ($alfa > 1)) {return 0;}
264           return ($x**($alfa-1))/((1+10*$x)**2);
265         }
266
267       gslinteg_qagil() -- Adaptive integration on infinite interval
268
269       This function estimates the integral of the function f over the infi‐
270       nite interval (-\infty,b) within the desired absolute and relative
271       error limits, $epsabs and $epsrel.  After a transformation, the algo‐
272       rithm of gslinteg_qags with a 15-point Gauss-Kronrod rule is used.  The
273       maximum number of allowed subdivisions done by the adaptive algorithm
274       must be supplied in the parameter $limit.
275
276       Please check the GSL documentation for more information.
277
278       Usage:
279
280         ($res,$abserr,$ierr) = gslinteg_qagl($function_ref,$b,$epsabs,
281                                              $epsrel,$limit,[{Warn => $warn}]);
282
283       Example:
284
285         my ($res,$abserr,$ierr) = gslinteg_qagil(\&myfn,1.0,1e-7,0,1000);
286         # with warnings on
287         ($res,$abserr,$ierr) = gslinteg_qagil(\&myfn,1.0,1e-7,0,1000,{Warn => 'y'});
288
289         sub myfn{
290           my ($x) = @_;
291           return exp($x);
292         }
293
294       gslinteg_qawc() -- Adaptive integration for Cauchy principal values
295
296       This function computes the Cauchy principal value of the integral of f
297       over (a,b), with a singularity at c, I = \int_a^b dx f(x)/(x - c). The
298       integral is estimated within the desired absolute and relative error
299       limits, $epsabs and $epsrel.  The maximum number of allowed subdivi‐
300       sions done by the adaptive algorithm must be supplied in the parameter
301       $limit.
302
303       Please check the GSL documentation for more information.
304
305       Usage:
306
307         ($res,$abserr,$ierr) = gslinteg_qawc($function_ref,$a,$b,$c,$epsabs,$epsrel,$limit)
308
309       Example:
310
311         my ($res,$abserr,$ierr) = gslinteg_qawc(\&f,-1,5,0,0,1e-3,1000);
312         # with warnings on
313         ($res,$abserr,$ierr) = gslinteg_qawc(\&f,-1,5,0,0,1e-3,1000,{Warn => 'y'});
314
315         sub f{
316           my ($x) = @_;
317           return 1.0 / (5.0 * $x * $x * $x + 6.0) ;
318         }
319
320       gslinteg_qaws() -- Adaptive integration for singular functions
321
322       The algorithm in gslinteg_qaws is designed for integrands with alge‐
323       braic-logarithmic singularities at the end-points of an integration
324       region.  Specifically, this function computes the integral given by I =
325       \int_a^b dx f(x) (x-a)^alpha (b-x)^beta log^mu (x-a) log^nu (b-x).  The
326       integral is estimated within the desired absolute and relative error
327       limits, $epsabs and $epsrel.  The maximum number of allowed subdivi‐
328       sions done by the adaptive algorithm must be supplied in the parameter
329       $limit.
330
331       Please check the GSL documentation for more information.
332
333       Usage:
334
335         ($res,$abserr,$ierr) =
336             gslinteg_qawc($function_ref,$alpha,$beta,$mu,$nu,$a,$b,
337                           $epsabs,$epsrel,$limit,[{Warn => $warn}]);
338
339       Example:
340
341         my ($res,$abserr,$ierr) = gslinteg_qaws(\&f,0,0,1,0,0,1,0,1e-7,1000);
342         # with warnings on
343         ($res,$abserr,$ierr) = gslinteg_qaws(\&f,0,0,1,0,0,1,0,1e-7,1000,{Warn => 'y'});
344
345         sub f{
346           my ($x) = @_;
347           if($x==0){return 0;}
348           else{
349             my $u = log($x);
350             my $v = 1 + $u*$u;
351             return 1.0/($v*$v);
352           }
353         }
354
355       gslinteg_qawo() -- Adaptive integration for oscillatory functions
356
357       This function uses an adaptive algorithm to compute the integral of f
358       over (a,b) with the weight function sin(omega*x) or cos(omega*x) --
359       which of sine or cosine is used is determined by the parameter $opt
360       ('cos' or 'sin').  The integral is estimated within the desired abso‐
361       lute and relative error limits, $epsabs and $epsrel.  The maximum num‐
362       ber of allowed subdivisions done by the adaptive algorithm must be sup‐
363       plied in the parameter $limit.
364
365       Please check the GSL documentation for more information.
366
367       Usage:
368
369         ($res,$abserr,$ierr) = gslinteg_qawo($function_ref,$omega,$sin_or_cos,
370                                       $a,$b,$epsabs,$epsrel,$limit,[opt])
371
372       Example:
373
374         my $PI = 3.14159265358979323846264338328;
375         my ($res,$abserr,$ierr) = PDL::GSL::INTEG::gslinteg_qawo(\&f,10*$PI,'sin',0,1,0,1e-7,1000);
376         # with warnings on
377         ($res,$abserr,$ierr) = PDL::GSL::INTEG::gslinteg_qawo(\&f,10*$PI,'sin',0,1,0,1e-7,1000,{Warn => 'y'});
378
379         sub f{
380           my ($x) = @_;
381           if($x==0){return 0;}
382           else{ return log($x);}
383         }
384
385       gslinteg_qawf() -- Adaptive integration for Fourier integrals
386
387       This function attempts to compute a Fourier integral of the function f
388       over the semi-infinite interval [a,+\infty). Specifically, it attempts
389       tp compute I = \int_a^{+\infty} dx f(x)w(x), where w(x) is sin(omega*x)
390       or cos(omega*x) -- which of sine or cosine is used is determined by the
391       parameter $opt ('cos' or 'sin').  The integral is estimated within the
392       desired absolute error limit $epsabs.  The maximum number of allowed
393       subdivisions done by the adaptive algorithm must be supplied in the
394       parameter $limit.
395
396       Please check the GSL documentation for more information.
397
398       Usage:
399
400         gslinteg_qawf($function_ref,$omega,$sin_or_cos,$a,$epsabs,$limit,[opt])
401
402       Example:
403
404         my ($res,$abserr,$ierr) = gslinteg_qawf(\&f,$PI/2.0,'cos',0,1e-7,1000);
405         # with warnings on
406         ($res,$abserr,$ierr) = gslinteg_qawf(\&f,$PI/2.0,'cos',0,1e-7,1000,{Warn => 'y'});
407
408         sub f{
409           my ($x) = @_;
410           if ($x == 0){return 0;}
411           return 1.0/sqrt($x)
412         }
413

BUGS

415       Feedback is welcome. Log bugs in the PDL bug database (the database is
416       always linked from http://pdl.perl.org).
417

AUTHOR

426       This file copyright (C) 2003,2005 Andres Jordan <ajordan@eso.org> All
427       rights reserved. There is no warranty. You are allowed to redistribute
428       this software documentation under certain conditions. For details, see
429       the file COPYING in the PDL distribution. If this file is separated
430       from the PDL distribution, the copyright notice should be included in
431       the file.
432
433       The GSL integration routines were written by Brian Gough. QUADPACK was
434       written by Piessens, Doncker-Kapenga, Uberhuber and Kahaner.
435

FUNCTIONS

437       qng_meat
438
439         Signature: (double a(); double b(); double epsabs();
440                          double epsrel(); double [o] result(); double [o] abserr();
441                          int [o] neval(); int [o] ierr(); int warn(); SV* funcion)
442
443       info not available
444
445       qag_meat
446
447         Signature: (double a(); double b(); double epsabs();double epsrel(); int limit();
448                          int key(); double [o] result(); double [o] abserr();int n();int [o] ierr();int warn();; SV* funcion)
449
450       info not available
451
452       qags_meat
453
454         Signature: (double a(); double b(); double epsabs();double epsrel(); int limit();
455                          double [o] result(); double [o] abserr();int n();int [o] ierr();int warn();; SV* funcion)
456
457       info not available
458
459       qagp_meat
460
461         Signature: (double pts(l); double epsabs();double epsrel();int limit();
462                          double [o] result(); double [o] abserr();int n();int [o] ierr();int warn();; SV* funcion)
463
464       info not available
465
466       qagi_meat
467
468         Signature: (double epsabs();double epsrel(); int limit();
469                          double [o] result(); double [o] abserr(); int n(); int [o] ierr();int warn();; SV* funcion)
470
471       info not available
472
473       qagiu_meat
474
475         Signature: (double a(); double epsabs();double epsrel();int limit();
476                          double [o] result(); double [o] abserr();int n();int [o] ierr();int warn();; SV* funcion)
477
478       info not available
479
480       qagil_meat
481
482         Signature: (double b(); double epsabs();double epsrel();int limit();
483                          double [o] result(); double [o] abserr();int n();int [o] ierr();int warn();; SV* funcion)
484
485       info not available
486
487       qawc_meat
488
489         Signature: (double a(); double b(); double c(); double epsabs();double epsrel();int limit();
490                          double [o] result(); double [o] abserr();int n();int [o] ierr();int warn();; SV* funcion)
491
492       info not available
493
494       qaws_meat
495
496         Signature: (double a(); double b();double epsabs();double epsrel();int limit();
497                        double [o] result(); double [o] abserr();int n();
498                        double alpha(); double beta(); int mu(); int nu();int [o] ierr();int warn();; SV* funcion)
499
500       info not available
501
502       qawo_meat
503
504         Signature: (double a(); double b();double epsabs();double epsrel();int limit();
505                        double [o] result(); double [o] abserr();int n();
506                        int sincosopt(); double omega(); double L(); int nlevels();int [o] ierr();int warn();; SV* funcion)
507
508       info not available
509
510       qawf_meat
511
512         Signature: (double a(); double epsabs();int limit();
513                        double [o] result(); double [o] abserr();int n();
514                        int sincosopt(); double omega(); int nlevels();int [o] ierr();int warn();; SV* funcion)
515
516       info not available
517
518
519
520perl v5.8.8                       2006-12-02                          INTEG(3)