GNU Scientic Library { Reference Manual
Edition 0.4after, for gsl Version 0.4after
Mark Galassi
Cygnus Solutions and Los Alamos National Laboratory
rosalia@nis.lanl.gov
Jim Davies
Space Data Systems Group, Los Alamos National Laboratory and
Department of Computer Science, Georgia Institute of Technology
jimmyd@nis.lanl.gov
James Theiler
Astrophysics and Radiation Measurements Group, Los Alamos National Laboratory
jt@nis.lanl.gov
Brian Gough
Theoretical Particle Physics Group, Los Alamos National Laboratory
bjg@vvv.lanl.gov
Reid Priedhorsky
Mathematical Modeling and Analysis Group, Los Alamos National Laboratory
rp@lanl.gov
Gerard Jungman
Theoretical Particle Physics Group, Los Alamos National Laboratory
jungman@nnn.lanl.gov
Michael Booth
Department of Physics and Astronomy, The Johns Hopkins University
booth@planck.pha.jhu.edu or booth@debian.org
Copyright c 1996, 1997, 1998 The GSL Project.
Permission is granted to make and distribute verbatim copies of this manual provided the
copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modied versions of this manual under the con-
ditions for verbatim copying, provided that the entire resulting derived work is distributed
under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual into another lan-
guage, under the above conditions for modied versions, except that this permission notice
may be stated in a translation approved by the Foundation.
i
Table of Contents
1 Preliminaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2 Using the library . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1 Inline functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.2 Long double . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
3 Error handling in GSL . . . . . . . . . . . . . . . . . . . . 3
3.1 Error reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.2 Error handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.3 Error streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.4 Manipulating the error stream. . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.5 Using GSL error reporting in your own functions . . . . . . . . . . 7
4 Random number generation . . . . . . . . . . . . . . . 9
4.1 General comments on random numbers . . . . . . . . . . . . . . . . . . . 9
4.2 The Random Number Generator Interface . . . . . . . . . . . . . . . . . 9
4.2.1 Random number generator initialization .. . . . . . . . . 9
4.2.2 Sampling from a random number generator . . . . . . 11
4.2.3 Auxiliary random number generator functions . . . 11
4.2.4 Random number environment variables . . . . . . . . . . 12
4.2.5 Saving and restoring random number generator state
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3 Available random number generator algorithms .. . . . . . . . . . 13
4.3.1 Simulation quality generators . . . . . . . . . . . . . . . . . . . 14
4.3.2 Generators provided for compatibility . . . . . . . . . . . 16
4.3.2.1 Unix random number generators . . . . . . . 16
4.3.2.2 Numerical Recipes generators . . . . . . . . . . 17
4.3.2.3 Other random number generators . . . . . . 18
4.4 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.5 Random Number Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.5.1 The Gaussian Distribution . . . . . . . . . . . . . . . . . . . . . 23
4.5.2 The Bivariate Gaussian Distribution . . . . . . . . . . . . 24
4.5.3 The Exponential Distribution. . . . . . . . . . . . . . . . . . . 25
4.5.4 The Laplace Distribution .. . . . . . . . . . . . . . . . . . . . . . 26
4.5.5 The Exponential Power Distribution . . . . . . . . . . . . 27
4.5.6 The Cauchy Distribution . . . . . . . . . . . . . . . . . . . . . . . 28
4.5.7 The Rayleigh Distribution .. . . . . . . . . . . . . . . . . . . . . 29
4.5.8 The Rayleigh Tail Distribution . . . . . . . . . . . . . . . . . 30
4.5.9 The Symmetric Levy Distribution. . . . . . . . . . . . . . . 31
4.5.10 The Gamma Distribution . . . . . . . . . . . . . . . . . . . . . 32
4.5.11 The Flat (Uniform) Distribution .. . . . . . . . . . . . . . 33
ii
4.5.12 The Lognormal Distribution . . . . . . . . . . . . . . . . . . . 34
4.5.13 The Chi-squared Distribution. . . . . . . . . . . . . . . . . . 35
4.5.14 The F-distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.5.15 The t-distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.5.16 The Beta Distribution . . . . . . . . . . . . . . . . . . . . . . . . 38
4.5.17 The Logistic Distribution . . . . . . . . . . . . . . . . . . . . . 39
4.5.18 The Pareto Distribution. . . . . . . . . . . . . . . . . . . . . . . 40
4.5.19 The Spherical Distribution (2D & 3D) . . . . . . . . . 41
4.5.20 The Weibull Distribution .. . . . . . . . . . . . . . . . . . . . . 42
4.5.21 The Gumbel Distribution . . . . . . . . . . . . . . . . . . . . . 43
4.6 Discrete distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.6.1 The Poisson Distribution .. . . . . . . . . . . . . . . . . . . . . . 44
4.6.2 The Bernoulli Distribution . . . . . . . . . . . . . . . . . . . . . 45
4.6.3 The Binomial Distribution . . . . . . . . . . . . . . . . . . . . . 46
4.6.4 The Negative Binomial Distribution. . . . . . . . . . . . . 47
4.6.5 The Geometric Distribution . . . . . . . . . . . . . . . . . . . . 49
4.6.6 The Hypergeometric Distribution .. . . . . . . . . . . . . . 50
4.6.7 The Logarithmic Distribution.. . . . . . . . . . . . . . . . . . 51
4.7 Shuing and Sampling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
4.8 Random Number References and Further Reading . . . . . . . . 52
4.9 Random Number Acknowledgements. . . . . . . . . . . . . . . . . . . . . 53
5 Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.1 Statistical Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.2 Mean, Standard Deviation and Variance . . . . . . . . . . . . . . . . . 55
5.3 Absolute deviation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.4 Higher moments (skewness and kurtosis) . . . . . . . . . . . . . . . . . 57
5.5 Maximum and Minimum values . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.6 Median and Percentiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.7 Statistical tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.8 Example statistical programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.9 Statistics References and Further Reading . . . . . . . . . . . . . . . . 62
6 Fast Fourier Transforms (FFTs) . . . . . . . . . . . 63
6.1 Mathematical Denitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
6.2 FFTs of complex data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.2.1 Radix-2 FFT routines for complex data . . . . . . . . . 65
6.2.2 Example of using radix-2 FFT routines for complex
data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
6.2.3 Mixed-radix FFT routines for complex data . . . . . 67
6.2.4 Example of using mixed-radix FFT routines for
complex data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
6.3 FFTs of real data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
6.3.1 Radix-2 FFT routines for real data. . . . . . . . . . . . . . 72
6.3.2 Mixed-radix FFT routines for real data. . . . . . . . . . 73
6.3.3 Example of using mixed-radix FFT routines for real
data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
6.4 FFT References and Further Reading . . . . . . . . . . . . . . . . . . . . 78
iii
7 Root nding . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
7.1 Root Finding Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
7.2 Root Finder Exit Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
7.3 Providing the Function to Search . . . . . . . . . . . . . . . . . . . . . . . . 81
7.4 Search Bounds and Guesses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
7.5 Search Stopping Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
7.6 Bisection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
7.7 Brent-Dekker Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
7.8 False Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
7.9 Secant Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
7.10 Newtons Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
7.11 Root Finder Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
8 Special Functions . . . . . . . . . . . . . . . . . . . . . . . . 92
8.1 Airy Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
8.2 Bessel Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
8.3 Chebyshev Polynomials .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
8.4 Coulomb Wave Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
8.5 Dilogarithm.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
8.6 Error Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
8.7 Fermi-Dirac Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
8.8 Gamma Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
8.9 Laguerre Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
8.10 Legendre Functions and Spherical Harmonics . . . . . . . . . . . . 93
8.11 Logarithm (Complex) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
8.12 Power Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
8.13 Psi (DiGamma) Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
8.14 Trigonometric Functions (Complex) . . . . . . . . . . . . . . . . . . . . 93
9 Series Acceleration . . . . . . . . . . . . . . . . . . . . . . 94
9.1 Acceleration functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
9.2 Example of accelerating a series . . . . . . . . . . . . . . . . . . . . . . . . . 94
9.3 Series Acceleration References . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
10 Simulated Annealing . . . . . . . . . . . . . . . . . . . . 96
10.1 Simulated Annealing algorithm . . . . . . . . . . . . . . . . . . . . . . . . . 96
10.2 Simulated Annealing functions . . . . . . . . . . . . . . . . . . . . . . . . . 96
10.3 Examples with Simulated Annealing . . . . . . . . . . . . . . . . . . . . 97
10.3.1 Trivial example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
10.3.2 Traveling Salesman Problem . . . . . . . . . . . . . . . . . . . 99
iv
11 Vectors and Matrices . . . . . . . . . . . . . . . . . . 102
11.1 The vector struct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
11.2 Vector allocation .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
11.3 Accessing vector elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
11.4 Reading and writing vectors . . . . . . . . . . . . . . . . . . . . . . . . . . 104
11.5 Example programs for vectors . . . . . . . . . . . . . . . . . . . . . . . . . 105
11.6 The matrix struct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
11.7 Matrix allocation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
11.8 Accessing matrix elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
11.9 Reading and writing matrices . . . . . . . . . . . . . . . . . . . . . . . . . 109
11.10 Example programs for matrices . . . . . . . . . . . . . . . . . . . . . . 110
12 Histograms . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
12.1 The histogram struct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
12.2 Histogram allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
12.3 Updating and accessing histogram elements . . . . . . . . . . . . 115
12.4 Searching histogram ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
12.5 Reading and writing histograms . . . . . . . . . . . . . . . . . . . . . . . 116
12.6 Resampling from histograms .. . . . . . . . . . . . . . . . . . . . . . . . . 117
12.7 The histogram probability distribution struct. . . . . . . . . . . 118
12.8 Example programs for histograms . . . . . . . . . . . . . . . . . . . . . 119
12.9 Two dimensional histograms . . . . . . . . . . . . . . . . . . . . . . . . . . 120
12.10 The 2D histogram struct . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
12.11 2D Histogram allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
12.12 Updating and accessing 2D histogram elements . . . . . . . . 122
12.13 Searching 2D histogram ranges . . . . . . . . . . . . . . . . . . . . . . . 123
12.14 Reading and writing 2D histograms . . . . . . . . . . . . . . . . . . 123
12.15 Resampling from 2D histograms . . . . . . . . . . . . . . . . . . . . . . 125
12.16 Example programs for 2D histograms . . . . . . . . . . . . . . . . . 126
13 Numerical Integration . . . . . . . . . . . . . . . . . 128
13.1 Numerical integration References and Further Reading . . 128
14 Monte Carlo Integration . . . . . . . . . . . . . . . 129
14.1 Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
14.1.1 PLAIN (or Simple) Monte Carlo . . . . . . . . . . . . . . 129
14.1.2 MISER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
14.1.3 VEGAS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
14.2 Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
14.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
14.4 The Future . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
15 The IEEE standard for oating-point
arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
15.1 Representation of oating point numbers. . . . . . . . . . . . . . . 134
15.2 Setting up your IEEE environment . . . . . . . . . . . . . . . . . . . . 135
15.3 IEEE References and Further Reading . . . . . . . . . . . . . . . . . 137
v
Appendix A Debugging Numerical Programs
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
A.1 Using gdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
A.2 GCC warning options for numerical programs . . . . . . . . . . . 139
Appendix B Contributors to GSL . . . . . . . . . . 143
Appendix C Copying . . . . . . . . . . . . . . . . . . . . . 144
Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Function Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Variable Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Type Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Chapter 1: Preliminaries
1
1 Preliminaries
The GNU Scientic Library (GSL) is a collection of routines for numerical analysis.
The routines are written from scratch by the GSL team (see Appendix B [Contributors
to GSL], page 143) in C, and are meant to present a modern Applications Programming
Interface (API) for C programmers, while allowing wrappers to be written for very high
level languages.