Comment out some more free() calls, which need to be turned on per-subsystem to weed...
[Math-GSL.git] / pod / Integration.pod
blob02c9f6a995b7699692dcca3eb56ba0bf684314fc
1 %perlcode %{
2 @EXPORT_OK = qw/
3                gsl_integration_workspace_alloc 
4                gsl_integration_workspace_free 
5                gsl_integration_qaws_table_alloc 
6                gsl_integration_qaws_table_set 
7                gsl_integration_qaws_table_free 
8                gsl_integration_qawo_table_alloc 
9                gsl_integration_qawo_table_set 
10                gsl_integration_qawo_table_set_length 
11                gsl_integration_qawo_table_free 
12                gsl_integration_qk15 
13                gsl_integration_qk21 
14                gsl_integration_qk31 
15                gsl_integration_qk41 
16                gsl_integration_qk51 
17                gsl_integration_qk61 
18                gsl_integration_qcheb 
19                gsl_integration_qk 
20                gsl_integration_qng 
21                gsl_integration_qag 
22                gsl_integration_qagi 
23                gsl_integration_qagiu 
24                gsl_integration_qagil 
25                gsl_integration_qags 
26                gsl_integration_qagp 
27                gsl_integration_qawc 
28                gsl_integration_qaws 
29                gsl_integration_qawo 
30                gsl_integration_qawf 
31                $GSL_INTEG_COSINE 
32                $GSL_INTEG_SINE 
33                $GSL_INTEG_GAUSS15 
34                $GSL_INTEG_GAUSS21 
35                $GSL_INTEG_GAUSS31 
36                $GSL_INTEG_GAUSS41 
37                $GSL_INTEG_GAUSS51 
38                $GSL_INTEG_GAUSS61 
39              /;
40 %EXPORT_TAGS = ( all => [ @EXPORT_OK ] );
42 __END__
44 =head1 NAME
46 Math::GSL::Integration - Routines for performing numerical integration (quadrature) of a function in one dimension
48 =head1 SYNOPSIS
50     use Math::GSL::Integration qw /:all/;
52     my $function = sub { $_[0]**2 } ;
53     my ($lower, $upper ) = (0,1);
54     my ($relerr,$abserr) = (0,1e-7);
56     my ($status, $result, $abserr, $num_evals) = gsl_integration_qng ( $function,
57                                                     $lower, $upper, $relerr, $abserr
58                                                  );
60 =head1 DESCRIPTION
62 This module allows you to numerically integrate a Perl subroutine. Depending
63 on the properties of your function (singularities, smoothness) and the type
64 of integration range (finite, infinite, semi-infinite), you will need to 
65 choose a quadrature routine that fits your needs.
68 =over 
70 =item * C<gsl_integration_workspace_alloc($n)> 
72 This function allocates a workspace sufficient to hold $n double precision
73 intervals, their integration results and error estimates.
75 =item * C<gsl_integration_workspace_free($w)> 
77  This function frees the memory associated with the workspace $w.
79 =item * C<gsl_integration_qaws_table_alloc($alpha, $beta, $mu, $nu)> 
81  This function allocates space for a gsl_integration_qaws_table struct
82  describing a singular weight function W(x) with the parameters ($alpha, $beta,
83  $mu, $nu), W(x) = (x-a)^alpha (b-x)^beta log^mu (x-a) log^nu (b-x) where
84  $alpha > -1, $beta > -1, and $mu = 0, 1, $nu = 0, 1. The weight function can
85  take four different forms depending on the values of $mu and $nu,
87               W(x) = (x-a)^alpha (b-x)^beta                   (mu = 0, nu = 0)
88               W(x) = (x-a)^alpha (b-x)^beta log(x-a)          (mu = 1, nu = 0)
89               W(x) = (x-a)^alpha (b-x)^beta log(b-x)          (mu = 0, nu = 1)
90               W(x) = (x-a)^alpha (b-x)^beta log(x-a) log(b-x) (mu = 1, nu = 1)
92 The singular points (a,b) do not have to be specified until the integral is
93 computed, where they are the endpoints of the integration range.  The function
94 returns a pointer to the newly allocated table gsl_integration_qaws_table if no
95 errors were detected, and 0 in the case of error. 
97 =item * C<gsl_integration_qaws_table_set($t, $alpha, $beta, $mu, $nu)> 
99  This function modifies the parameters ($alpha, $beta, $mu, $nu) of an existing
100  gsl_integration_qaws_table struct $t.
102 =item * C<gsl_integration_qaws_table_free($t)> 
104  This function frees all the memory associated with the
105  gsl_integration_qaws_table struct $t.
107 =item * C<gsl_integration_qawo_table_alloc($omega, $L, $sine, $n)>
109 =item * C<gsl_integration_qawo_table_set($t, $omega, $L, $sine, $n)> 
111  This function changes the parameters omega, L and sine of the existing
112  workspace $t.
114 =item * C<gsl_integration_qawo_table_set_length($t, $L)> 
116  This function allows the length parameter $L of the workspace $t to be
117  changed.
119 =item * C<gsl_integration_qawo_table_free($t)> 
121  This function frees all the memory associated with the workspace $t.
123 =item * C<gsl_integration_qk15($function,$a,$b,$resabs,$resasc) >
125 =item * C<gsl_integration_qk21($function,$a,$b,$resabs,$resasc) >
127 =item * C<gsl_integration_qk31($function,$a,$b,$resabs,$resasc) >
129 =item * C<gsl_integration_qk41($function,$a,$b,$resabs,$resasc) >
131 =item * C<gsl_integration_qk51($function,$a,$b,$resabs,$resasc) >
133 =item * C<gsl_integration_qk61($function,$a,$b,$resabs,$resasc) >
135 =item * C<gsl_integration_qcheb($function, $a, $b, $cheb12, $cheb24) >
137 =item * C<gsl_integration_qk >
139 =item * C<gsl_integration_qng($function,$a,$b,$epsabs,$epsrel,$num_evals) >
141 This routine QNG (Quadrature Non-Adaptive Gaussian) is inexpensive is the sense
142 that it will evaluate the function much fewer times than the adaptive routines.
143 Because of this it does not need any workspaces, so it is also more memory
144 efficient. It should be perfectly fine for well-behaved functions (smooth and
145 nonsingular), but will not be able to get the required accuracy or may not
146 converge for more complicated functions.
148 =item * C<gsl_integration_qag($function,$a,$b,$epsabs,$epsrel,$limit,$key,$workspace) >
150 This routine QAG (Quadrature Adaptive Gaussian) ...
152 =item * C<gsl_integration_qagi($function,$epsabs,$epsrel,$limit,$workspace) >
154 =item * C<gsl_integration_qagiu($function,$a,$epsabs,$epsrel,$limit,$workspace) >
156 =item * C<gsl_integration_qagil($function,$b,$epsabs,$epsrel,$limit,$workspace) >
158 =item * C<gsl_integration_qags($func,$a,$b,$epsabs,$epsrel,$limit,$workspace)>
160     ($status, $result, $abserr) = gsl_integration_qags (
161                             sub { 1/$_[0]} , 
162                             1, 10, 0, 1e-7, 1000,
163                             $workspace,
164                         );
166  This function applies the Gauss-Kronrod 21-point integration rule
167  adaptively until an estimate of the integral of $func over ($a,$b) is
168  achieved within the desired absolute and relative error limits,
169  $epsabs and $epsrel. 
172 =item * C<gsl_integration_qagp($function, $pts, $npts, $epsbs, $epsrel, $limit, $workspace) >
174 =item * C<gsl_integration_qawc($function, $a, $b, $c, $epsabs, $epsrel, $limit, $workspace) >
176 =item * C<gsl_integration_qaws($function, $a, $b, $qaws_table, $epsabs, $epsrel, $limit, $workspace) >
178 =item * C<gsl_integration_qawo($function, $a, $epsabs, $epsrel, $limit, $workspace, $qawo_table) >
180 =item * C<gsl_integration_qawf($function, $a, $epsabs, $limit, $workspace, $cycle_workspace, $qawo_table) >
182 =back
184 This module also includes the following constants :
186 =over
188 =item * $GSL_INTEG_COSINE 
190 =item * $GSL_INTEG_SINE 
192 =item * $GSL_INTEG_GAUSS15 
194 =item * $GSL_INTEG_GAUSS21 
196 =item * $GSL_INTEG_GAUSS31 
198 =item * $GSL_INTEG_GAUSS41 
200 =item * $GSL_INTEG_GAUSS51 
202 =item * $GSL_INTEG_GAUSS61 
204 =back
206 The following error constants are part of the Math::GSL::Errno module and can
207 be returned by the gsl_integration_* functions :
209 =over
211 =item * $GSL_EMAXITER 
213 Maximum number of subdivisions was exceeded.
215 =item * $GSL_EROUND 
217 Cannot reach tolerance because of roundoff error, or roundoff error was detected in the extrapolation table. 
219 =item * GSL_ESING 
221 A non-integrable singularity or other bad integrand behavior was found in the integration interval.
223 =item * GSL_EDIVERGE 
225 The integral is divergent, or too slowly convergent to be integrated numerically. 
227 =back 
229 =head1 MORE INFO
231 For more informations on the functions, we refer you to the GSL offcial
232 documentation: L<http://www.gnu.org/software/gsl/manual/html_node/>
234 =head1 AUTHORS
236 Jonathan Leto <jonathan@leto.net> and Thierry Moisan <thierry.moisan@gmail.com>
238 =head1 COPYRIGHT AND LICENSE
240 Copyright (C) 2008-2009 Jonathan Leto and Thierry Moisan
242 This program is free software; you can redistribute it and/or modify it
243 under the same terms as Perl itself.
245 =cut