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
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
43       integrands w(x)=1). The user provides absolute and relative error
44       bounds (epsabs,epsrel) which specify the following accuracy
45       requirement:
46
47       |RESULT - I|  <= max(epsabs, epsrel |I|)
48
49       The routines will fail to converge if the error bounds are too
50       stringent, but always return the best approximation obtained up to that
51       stage
52
53       All functions return the result, and estimate of the absolute error and
54       an error flag (which is zero if there were no problems).  You are
55       responsible for checking for any errors, no warnings are issued unless
56       the option {Warn => 'y'} is specified in which case the reason of
57       failure will be printed.
58
59       You can nest integrals up to 20 levels. If you find yourself in the
60       unlikely situation that you need more, you can change the value of
61       'max_nested_integrals' in the first line of the file 'FUNC.c' and
62       recompile.
63
64       Please check the GSL documentation for more information.
65

SYNOPSIS

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

FUNCTIONS

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

BUGS

405       Feedback is welcome. Log bugs in the PDL bug database (the database is
406       always linked from http://pdl.perl.org).
407

AUTHOR

416       This file copyright (C) 2003,2005 Andres Jordan <ajordan@eso.org> All
417       rights reserved. There is no warranty. You are allowed to redistribute
418       this software documentation under certain conditions. For details, see
419       the file COPYING in the PDL distribution. If this file is separated
420       from the PDL distribution, the copyright notice should be included in
421       the file.
422
423       The GSL integration routines were written by Brian Gough. QUADPACK was
424       written by Piessens, Doncker-Kapenga, Uberhuber and Kahaner.
425

FUNCTIONS

427   qng_meat
428         Signature: (double a(); double b(); double epsabs();
429                          double epsrel(); double [o] result(); double [o] abserr();
430                          int [o] neval(); int [o] ierr(); int warn(); SV* funcion)
431
432       info not available
433
434       qng_meat does not process bad values.  It will set the bad-value flag
435       of all output piddles if the flag is set for any of the input piddles.
436
437   qag_meat
438         Signature: (double a(); double b(); double epsabs();double epsrel(); int limit();
439                          int key(); double [o] result(); double [o] abserr();int n();int [o] ierr();int warn();; SV* funcion)
440
441       info not available
442
443       qag_meat does not process bad values.  It will set the bad-value flag
444       of all output piddles if the flag is set for any of the input piddles.
445
446   qags_meat
447         Signature: (double a(); double b(); double epsabs();double epsrel(); int limit();
448                          double [o] result(); double [o] abserr();int n();int [o] ierr();int warn();; SV* funcion)
449
450       info not available
451
452       qags_meat does not process bad values.  It will set the bad-value flag
453       of all output piddles if the flag is set for any of the input piddles.
454
455   qagp_meat
456         Signature: (double pts(l); double epsabs();double epsrel();int limit();
457                          double [o] result(); double [o] abserr();int n();int [o] ierr();int warn();; SV* funcion)
458
459       info not available
460
461       qagp_meat does not process bad values.  It will set the bad-value flag
462       of all output piddles if the flag is set for any of the input piddles.
463
464   qagi_meat
465         Signature: (double epsabs();double epsrel(); int limit();
466                          double [o] result(); double [o] abserr(); int n(); int [o] ierr();int warn();; SV* funcion)
467
468       info not available
469
470       qagi_meat does not process bad values.  It will set the bad-value flag
471       of all output piddles if the flag is set for any of the input piddles.
472
473   qagiu_meat
474         Signature: (double a(); double epsabs();double epsrel();int limit();
475                          double [o] result(); double [o] abserr();int n();int [o] ierr();int warn();; SV* funcion)
476
477       info not available
478
479       qagiu_meat does not process bad values.  It will set the bad-value flag
480       of all output piddles if the flag is set for any of the input piddles.
481
482   qagil_meat
483         Signature: (double b(); double epsabs();double epsrel();int limit();
484                          double [o] result(); double [o] abserr();int n();int [o] ierr();int warn();; SV* funcion)
485
486       info not available
487
488       qagil_meat does not process bad values.  It will set the bad-value flag
489       of all output piddles if the flag is set for any of the input piddles.
490
491   qawc_meat
492         Signature: (double a(); double b(); double c(); double epsabs();double epsrel();int limit();
493                          double [o] result(); double [o] abserr();int n();int [o] ierr();int warn();; SV* funcion)
494
495       info not available
496
497       qawc_meat does not process bad values.  It will set the bad-value flag
498       of all output piddles if the flag is set for any of the input piddles.
499
500   qaws_meat
501         Signature: (double a(); double b();double epsabs();double epsrel();int limit();
502                        double [o] result(); double [o] abserr();int n();
503                        double alpha(); double beta(); int mu(); int nu();int [o] ierr();int warn();; SV* funcion)
504
505       info not available
506
507       qaws_meat does not process bad values.  It will set the bad-value flag
508       of all output piddles if the flag is set for any of the input piddles.
509
510   qawo_meat
511         Signature: (double a(); double b();double epsabs();double epsrel();int limit();
512                        double [o] result(); double [o] abserr();int n();
513                        int sincosopt(); double omega(); double L(); int nlevels();int [o] ierr();int warn();; SV* funcion)
514
515       info not available
516
517       qawo_meat does not process bad values.  It will set the bad-value flag
518       of all output piddles if the flag is set for any of the input piddles.
519
520   qawf_meat
521         Signature: (double a(); double epsabs();int limit();
522                        double [o] result(); double [o] abserr();int n();
523                        int sincosopt(); double omega(); int nlevels();int [o] ierr();int warn();; SV* funcion)
524
525       info not available
526
527       qawf_meat does not process bad values.  It will set the bad-value flag
528       of all output piddles if the flag is set for any of the input piddles.
529
530
531
532perl v5.12.3                      2011-03-31                          INTEG(3)