pod/Integration.pod

   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 ] );
  41
  42 __END__
  43
  44 =head1 NAME
  45
  46 Math::GSL::Integration - Routines for performing numerical integration (quadrature) of a function in one dimension
  47
  48 =head1 SYNOPSIS
  49
  50     use Math::GSL::Integration qw /:all/;
  51
  52     my $function = sub { $_[0]**2 } ;
  53     my ($lower, $upper ) = (0,1);
  54     my ($relerr,$abserr) = (0,1e-7);
  55
  56     my ($status, $result, $abserr, $num_evals) = gsl_integration_qng ( $function,
  57                                                     $lower, $upper, $relerr, $abserr
  58                                                  );
  59
  60 =head1 DESCRIPTION
  61
  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.
  66
  67
  68 =over
  69
  70 =item * C<gsl_integration_workspace_alloc($n)>
  71
  72 This function allocates a workspace sufficient to hold $n double precision
  73 intervals, their integration results and error estimates.
  74
  75 =item * C<gsl_integration_workspace_free($w)>
  76
  77  This function frees the memory associated with the workspace $w.
  78
  79 =item * C<gsl_integration_qaws_table_alloc($alpha, $beta, $mu, $nu)>
  80
  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,
  86
  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)
  91
  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.
  96
  97 =item * C<gsl_integration_qaws_table_set($t, $alpha, $beta, $mu, $nu)>
  98
  99  This function modifies the parameters ($alpha, $beta, $mu, $nu) of an existing
 100  gsl_integration_qaws_table struct $t.
 101
 102 =item * C<gsl_integration_qaws_table_free($t)>
 103
 104  This function frees all the memory associated with the
 105  gsl_integration_qaws_table struct $t.
 106
 107 =item * C<gsl_integration_qawo_table_alloc($omega, $L, $sine, $n)>
 108
 109 =item * C<gsl_integration_qawo_table_set($t, $omega, $L, $sine, $n)>
 110
 111  This function changes the parameters omega, L and sine of the existing
 112  workspace $t.
 113
 114 =item * C<gsl_integration_qawo_table_set_length($t, $L)>
 115
 116  This function allows the length parameter $L of the workspace $t to be
 117  changed.
 118
 119 =item * C<gsl_integration_qawo_table_free($t)>
 120
 121  This function frees all the memory associated with the workspace $t.
 122
 123 =item * C<gsl_integration_qk15($function,$a,$b,$resabs,$resasc) >
 124
 125 =item * C<gsl_integration_qk21($function,$a,$b,$resabs,$resasc) >
 126
 127 =item * C<gsl_integration_qk31($function,$a,$b,$resabs,$resasc) >
 128
 129 =item * C<gsl_integration_qk41($function,$a,$b,$resabs,$resasc) >
 130
 131 =item * C<gsl_integration_qk51($function,$a,$b,$resabs,$resasc) >
 132
 133 =item * C<gsl_integration_qk61($function,$a,$b,$resabs,$resasc) >
 134
 135 =item * C<gsl_integration_qcheb($function, $a, $b, $cheb12, $cheb24) >
 136
 137 =item * C<gsl_integration_qk >
 138
 139 =item * C<gsl_integration_qng($function,$a,$b,$epsabs,$epsrel,$num_evals) >
 140
 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.
 147
 148 =item * C<gsl_integration_qag($function,$a,$b,$epsabs,$epsrel,$limit,$key,$workspace) >
 149
 150 This routine QAG (Quadrature Adaptive Gaussian) ...
 151
 152 =item * C<gsl_integration_qagi($function,$epsabs,$epsrel,$limit,$workspace) >
 153
 154 =item * C<gsl_integration_qagiu($function,$a,$epsabs,$epsrel,$limit,$workspace) >
 155
 156 =item * C<gsl_integration_qagil($function,$b,$epsabs,$epsrel,$limit,$workspace) >
 157
 158 =item * C<gsl_integration_qags($func,$a,$b,$epsabs,$epsrel,$limit,$workspace)>
 159
 160     ($status, $result, $abserr) = gsl_integration_qags (
 161                             sub { 1/$_[0]} ,
 162                             1, 10, 0, 1e-7, 1000,
 163                             $workspace,
 164                         );
 165
 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.
 170
 171
 172 =item * C<gsl_integration_qagp($function, $pts, $npts, $epsbs, $epsrel, $limit, $workspace) >
 173
 174 =item * C<gsl_integration_qawc($function, $a, $b, $c, $epsabs, $epsrel, $limit, $workspace) >
 175
 176 =item * C<gsl_integration_qaws($function, $a, $b, $qaws_table, $epsabs, $epsrel, $limit, $workspace) >
 177
 178 =item * C<gsl_integration_qawo($function, $a, $epsabs, $epsrel, $limit, $workspace, $qawo_table) >
 179
 180 =item * C<gsl_integration_qawf($function, $a, $epsabs, $limit, $workspace, $cycle_workspace, $qawo_table) >
 181
 182 =back
 183
 184 This module also includes the following constants :
 185
 186 =over
 187
 188 =item * $GSL_INTEG_COSINE
 189
 190 =item * $GSL_INTEG_SINE
 191
 192 =item * $GSL_INTEG_GAUSS15
 193
 194 =item * $GSL_INTEG_GAUSS21
 195
 196 =item * $GSL_INTEG_GAUSS31
 197
 198 =item * $GSL_INTEG_GAUSS41
 199
 200 =item * $GSL_INTEG_GAUSS51
 201
 202 =item * $GSL_INTEG_GAUSS61
 203
 204 =back
 205
 206 The following error constants are part of the Math::GSL::Errno module and can
 207 be returned by the gsl_integration_* functions :
 208
 209 =over
 210
 211 =item * $GSL_EMAXITER
 212
 213 Maximum number of subdivisions was exceeded.
 214
 215 =item * $GSL_EROUND
 216
 217 Cannot reach tolerance because of roundoff error, or roundoff error was detected in the extrapolation table.
 218
 219 =item * GSL_ESING
 220
 221 A non-integrable singularity or other bad integrand behavior was found in the integration interval.
 222
 223 =item * GSL_EDIVERGE
 224
 225 The integral is divergent, or too slowly convergent to be integrated numerically.
 226
 227 =back
 228
 229 =head1 MORE INFO
 230
 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/>
 233
 234 =head1 AUTHORS
 235
 236 Jonathan Leto <jonathan@leto.net> and Thierry Moisan <thierry.moisan@gmail.com>
 237
 238 =head1 COPYRIGHT AND LICENSE
 239
 240 Copyright (C) 2008-2009 Jonathan Leto and Thierry Moisan
 241
 242 This program is free software; you can redistribute it and/or modify it
 243 under the same terms as Perl itself.
 244
 245 =cut
 246
 247 %}
 248