1 This is gsl-ref.info, produced by makeinfo version 4.8 from
4 INFO-DIR-SECTION Scientific software
6 * gsl-ref: (gsl-ref). GNU Scientific Library - Reference
9 Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,
10 2005, 2006, 2007 The GSL Team.
12 Permission is granted to copy, distribute and/or modify this document
13 under the terms of the GNU Free Documentation License, Version 1.2 or
14 any later version published by the Free Software Foundation; with the
15 Invariant Sections being "GNU General Public License" and "Free Software
16 Needs Free Documentation", the Front-Cover text being "A GNU Manual",
17 and with the Back-Cover Text being (a) (see below). A copy of the
18 license is included in the section entitled "GNU Free Documentation
21 (a) The Back-Cover Text is: "You have the freedom to copy and modify
25 File: gsl-ref.info, Node: Providing a function to minimize, Next: Multimin Iteration, Prev: Initializing the Multidimensional Minimizer, Up: Multidimensional Minimization
27 35.4 Providing a function to minimize
28 =====================================
30 You must provide a parametric function of n variables for the
31 minimizers to operate on. You may also need to provide a routine which
32 calculates the gradient of the function and a third routine which
33 calculates both the function value and the gradient together. In order
34 to allow for general parameters the functions are defined by the
37 -- Data Type: gsl_multimin_function_fdf
38 This data type defines a general function of n variables with
39 parameters and the corresponding gradient vector of derivatives,
41 `double (* f) (const gsl_vector * X, void * PARAMS)'
42 this function should return the result f(x,params) for
43 argument X and parameters PARAMS. If the function cannot be
44 computed, an error value of `GSL_NAN' should be returned.
46 `void (* df) (const gsl_vector * X, void * PARAMS, gsl_vector * G)'
47 this function should store the N-dimensional gradient g_i = d
48 f(x,params) / d x_i in the vector G for argument X and
49 parameters PARAMS, returning an appropriate error code if the
50 function cannot be computed.
52 `void (* fdf) (const gsl_vector * X, void * PARAMS, double * f, gsl_vector * G)'
53 This function should set the values of the F and G as above,
54 for arguments X and parameters PARAMS. This function
55 provides an optimization of the separate functions for f(x)
56 and g(x)--it is always faster to compute the function and its
57 derivative at the same time.
60 the dimension of the system, i.e. the number of components of
64 a pointer to the parameters of the function.
66 -- Data Type: gsl_multimin_function
67 This data type defines a general function of n variables with
70 `double (* f) (const gsl_vector * X, void * PARAMS)'
71 this function should return the result f(x,params) for
72 argument X and parameters PARAMS. If the function cannot be
73 computed, an error value of `GSL_NAN' should be returned.
76 the dimension of the system, i.e. the number of components of
80 a pointer to the parameters of the function.
82 The following example function defines a simple two-dimensional
83 paraboloid with five parameters,
85 /* Paraboloid centered on (p[0],p[1]), with
86 scale factors (p[2],p[3]) and minimum p[4] */
89 my_f (const gsl_vector *v, void *params)
92 double *p = (double *)params;
94 x = gsl_vector_get(v, 0);
95 y = gsl_vector_get(v, 1);
97 return p[2] * (x - p[0]) * (x - p[0]) +
98 p[3] * (y - p[1]) * (y - p[1]) + p[4];
101 /* The gradient of f, df = (df/dx, df/dy). */
103 my_df (const gsl_vector *v, void *params,
107 double *p = (double *)params;
109 x = gsl_vector_get(v, 0);
110 y = gsl_vector_get(v, 1);
112 gsl_vector_set(df, 0, 2.0 * p[2] * (x - p[0]));
113 gsl_vector_set(df, 1, 2.0 * p[3] * (y - p[1]));
116 /* Compute both f and df together. */
118 my_fdf (const gsl_vector *x, void *params,
119 double *f, gsl_vector *df)
121 *f = my_f(x, params);
122 my_df(x, params, df);
125 The function can be initialized using the following code,
127 gsl_multimin_function_fdf my_func;
129 /* Paraboloid center at (1,2), scale factors (10, 20),
131 double p[5] = { 1.0, 2.0, 10.0, 20.0, 30.0 };
133 my_func.n = 2; /* number of function components */
136 my_func.fdf = &my_fdf;
137 my_func.params = (void *)p;
140 File: gsl-ref.info, Node: Multimin Iteration, Next: Multimin Stopping Criteria, Prev: Providing a function to minimize, Up: Multidimensional Minimization
145 The following function drives the iteration of each algorithm. The
146 function performs one iteration to update the state of the minimizer.
147 The same function works for all minimizers so that different methods can
148 be substituted at runtime without modifications to the code.
150 -- Function: int gsl_multimin_fdfminimizer_iterate
151 (gsl_multimin_fdfminimizer * S)
152 -- Function: int gsl_multimin_fminimizer_iterate
153 (gsl_multimin_fminimizer * S)
154 These functions perform a single iteration of the minimizer S. If
155 the iteration encounters an unexpected problem then an error code
158 The minimizer maintains a current best estimate of the minimum at all
159 times. This information can be accessed with the following auxiliary
162 -- Function: gsl_vector * gsl_multimin_fdfminimizer_x (const
163 gsl_multimin_fdfminimizer * S)
164 -- Function: gsl_vector * gsl_multimin_fminimizer_x (const
165 gsl_multimin_fminimizer * S)
166 -- Function: double gsl_multimin_fdfminimizer_minimum (const
167 gsl_multimin_fdfminimizer * S)
168 -- Function: double gsl_multimin_fminimizer_minimum (const
169 gsl_multimin_fminimizer * S)
170 -- Function: gsl_vector * gsl_multimin_fdfminimizer_gradient (const
171 gsl_multimin_fdfminimizer * S)
172 -- Function: double gsl_multimin_fminimizer_size (const
173 gsl_multimin_fminimizer * S)
174 These functions return the current best estimate of the location
175 of the minimum, the value of the function at that point, its
176 gradient, and minimizer specific characteristic size for the
179 -- Function: int gsl_multimin_fdfminimizer_restart
180 (gsl_multimin_fdfminimizer * S)
181 This function resets the minimizer S to use the current point as a
185 File: gsl-ref.info, Node: Multimin Stopping Criteria, Next: Multimin Algorithms, Prev: Multimin Iteration, Up: Multidimensional Minimization
187 35.6 Stopping Criteria
188 ======================
190 A minimization procedure should stop when one of the following
193 * A minimum has been found to within the user-specified precision.
195 * A user-specified maximum number of iterations has been reached.
197 * An error has occurred.
199 The handling of these conditions is under user control. The functions
200 below allow the user to test the precision of the current result.
202 -- Function: int gsl_multimin_test_gradient (const gsl_vector * G,
204 This function tests the norm of the gradient G against the
205 absolute tolerance EPSABS. The gradient of a multidimensional
206 function goes to zero at a minimum. The test returns `GSL_SUCCESS'
207 if the following condition is achieved,
211 and returns `GSL_CONTINUE' otherwise. A suitable choice of EPSABS
212 can be made from the desired accuracy in the function for small
213 variations in x. The relationship between these quantities is
214 given by \delta f = g \delta x.
216 -- Function: int gsl_multimin_test_size (const double SIZE, double
218 This function tests the minimizer specific characteristic size (if
219 applicable to the used minimizer) against absolute tolerance
220 EPSABS. The test returns `GSL_SUCCESS' if the size is smaller
221 than tolerance, otherwise `GSL_CONTINUE' is returned.
224 File: gsl-ref.info, Node: Multimin Algorithms, Next: Multimin Examples, Prev: Multimin Stopping Criteria, Up: Multidimensional Minimization
229 There are several minimization methods available. The best choice of
230 algorithm depends on the problem. All of the algorithms use the value
231 of the function and its gradient at each evaluation point, except for
232 the Simplex algorithm which uses function values only.
234 -- Minimizer: gsl_multimin_fdfminimizer_conjugate_fr
235 This is the Fletcher-Reeves conjugate gradient algorithm. The
236 conjugate gradient algorithm proceeds as a succession of line
237 minimizations. The sequence of search directions is used to build
238 up an approximation to the curvature of the function in the
239 neighborhood of the minimum.
241 An initial search direction P is chosen using the gradient, and
242 line minimization is carried out in that direction. The accuracy
243 of the line minimization is specified by the parameter TOL. The
244 minimum along this line occurs when the function gradient G and
245 the search direction P are orthogonal. The line minimization
246 terminates when dot(p,g) < tol |p| |g|. The search direction is
247 updated using the Fletcher-Reeves formula p' = g' - \beta g where
248 \beta=-|g'|^2/|g|^2, and the line minimization is then repeated
249 for the new search direction.
251 -- Minimizer: gsl_multimin_fdfminimizer_conjugate_pr
252 This is the Polak-Ribiere conjugate gradient algorithm. It is
253 similar to the Fletcher-Reeves method, differing only in the
254 choice of the coefficient \beta. Both methods work well when the
255 evaluation point is close enough to the minimum of the objective
256 function that it is well approximated by a quadratic hypersurface.
258 -- Minimizer: gsl_multimin_fdfminimizer_vector_bfgs2
259 -- Minimizer: gsl_multimin_fdfminimizer_vector_bfgs
260 These methods use the vector Broyden-Fletcher-Goldfarb-Shanno
261 (BFGS) algorithm. This is a quasi-Newton method which builds up
262 an approximation to the second derivatives of the function f using
263 the difference between successive gradient vectors. By combining
264 the first and second derivatives the algorithm is able to take
265 Newton-type steps towards the function minimum, assuming quadratic
266 behavior in that region.
268 The `bfgs2' version of this minimizer is the most efficient
269 version available, and is a faithful implementation of the line
270 minimization scheme described in Fletcher's `Practical Methods of
271 Optimization', Algorithms 2.6.2 and 2.6.4. It supercedes the
272 original `bfgs' routine and requires substantially fewer function
273 and gradient evaluations. The user-supplied tolerance TOL
274 corresponds to the parameter \sigma used by Fletcher. A value of
275 0.1 is recommended for typical use (larger values correspond to
276 less accurate line searches).
279 -- Minimizer: gsl_multimin_fdfminimizer_steepest_descent
280 The steepest descent algorithm follows the downhill gradient of the
281 function at each step. When a downhill step is successful the
282 step-size is increased by a factor of two. If the downhill step
283 leads to a higher function value then the algorithm backtracks and
284 the step size is decreased using the parameter TOL. A suitable
285 value of TOL for most applications is 0.1. The steepest descent
286 method is inefficient and is included only for demonstration
289 -- Minimizer: gsl_multimin_fminimizer_nmsimplex
290 This is the Simplex algorithm of Nelder and Mead. It constructs n
291 vectors p_i from the starting vector X and the vector STEP_SIZE as
294 p_0 = (x_0, x_1, ... , x_n)
295 p_1 = (x_0 + step_size_0, x_1, ... , x_n)
296 p_2 = (x_0, x_1 + step_size_1, ... , x_n)
298 p_n = (x_0, x_1, ... , x_n+step_size_n)
300 These vectors form the n+1 vertices of a simplex in n dimensions.
301 On each iteration the algorithm tries to improve the parameter
302 vector p_i corresponding to the highest function value by simple
303 geometrical transformations. These are reflection, reflection
304 followed by expansion, contraction and multiple contraction. Using
305 these transformations the simplex moves through the parameter
306 space towards the minimum, where it contracts itself.
308 After each iteration, the best vertex is returned. Note, that due
309 to the nature of the algorithm not every step improves the current
310 best parameter vector. Usually several iterations are required.
312 The routine calculates the minimizer specific characteristic size
313 as the average distance from the geometrical center of the simplex
314 to all its vertices. This size can be used as a stopping
315 criteria, as the simplex contracts itself near the minimum. The
316 size is returned by the function `gsl_multimin_fminimizer_size'.
319 File: gsl-ref.info, Node: Multimin Examples, Next: Multimin References and Further Reading, Prev: Multimin Algorithms, Up: Multidimensional Minimization
324 This example program finds the minimum of the paraboloid function
325 defined earlier. The location of the minimum is offset from the origin
326 in x and y, and the function value at the minimum is non-zero. The main
327 program is given below, it requires the example function given earlier
336 const gsl_multimin_fdfminimizer_type *T;
337 gsl_multimin_fdfminimizer *s;
339 /* Position of the minimum (1,2), scale factors
341 double par[5] = { 1.0, 2.0, 10.0, 20.0, 30.0 };
344 gsl_multimin_function_fdf my_func;
349 my_func.fdf = &my_fdf;
350 my_func.params = ∥
352 /* Starting point, x = (5,7) */
353 x = gsl_vector_alloc (2);
354 gsl_vector_set (x, 0, 5.0);
355 gsl_vector_set (x, 1, 7.0);
357 T = gsl_multimin_fdfminimizer_conjugate_fr;
358 s = gsl_multimin_fdfminimizer_alloc (T, 2);
360 gsl_multimin_fdfminimizer_set (s, &my_func, x, 0.01, 1e-4);
365 status = gsl_multimin_fdfminimizer_iterate (s);
370 status = gsl_multimin_test_gradient (s->gradient, 1e-3);
372 if (status == GSL_SUCCESS)
373 printf ("Minimum found at:\n");
375 printf ("%5d %.5f %.5f %10.5f\n", iter,
376 gsl_vector_get (s->x, 0),
377 gsl_vector_get (s->x, 1),
381 while (status == GSL_CONTINUE && iter < 100);
383 gsl_multimin_fdfminimizer_free (s);
389 The initial step-size is chosen as 0.01, a conservative estimate in this
390 case, and the line minimization parameter is set at 0.0001. The program
391 terminates when the norm of the gradient has been reduced below 0.001.
392 The output of the program is shown below,
395 1 4.99629 6.99072 687.84780
396 2 4.98886 6.97215 683.55456
397 3 4.97400 6.93501 675.01278
398 4 4.94429 6.86073 658.10798
399 5 4.88487 6.71217 625.01340
400 6 4.76602 6.41506 561.68440
401 7 4.52833 5.82083 446.46694
402 8 4.05295 4.63238 261.79422
403 9 3.10219 2.25548 75.49762
404 10 2.85185 1.62963 67.03704
405 11 2.19088 1.76182 45.31640
406 12 0.86892 2.02622 30.18555
408 13 1.00000 2.00000 30.00000
410 Note that the algorithm gradually increases the step size as it
411 successfully moves downhill, as can be seen by plotting the successive
414 The conjugate gradient algorithm finds the minimum on its second
415 direction because the function is purely quadratic. Additional
416 iterations would be needed for a more complicated function.
418 Here is another example using the Nelder-Mead Simplex algorithm to
419 minimize the same example object function, as above.
424 double par[5] = {1.0, 2.0, 10.0, 20.0, 30.0};
426 const gsl_multimin_fminimizer_type *T =
427 gsl_multimin_fminimizer_nmsimplex;
428 gsl_multimin_fminimizer *s = NULL;
430 gsl_multimin_function minex_func;
437 x = gsl_vector_alloc (2);
438 gsl_vector_set (x, 0, 5.0);
439 gsl_vector_set (x, 1, 7.0);
441 /* Set initial step sizes to 1 */
442 ss = gsl_vector_alloc (2);
443 gsl_vector_set_all (ss, 1.0);
445 /* Initialize method and iterate */
447 minex_func.f = &my_f;
448 minex_func.params = (void *)∥
450 s = gsl_multimin_fminimizer_alloc (T, 2);
451 gsl_multimin_fminimizer_set (s, &minex_func, x, ss);
456 status = gsl_multimin_fminimizer_iterate(s);
461 size = gsl_multimin_fminimizer_size (s);
462 status = gsl_multimin_test_size (size, 1e-2);
464 if (status == GSL_SUCCESS)
466 printf ("converged to minimum at\n");
469 printf ("%5d %10.3e %10.3ef f() = %7.3f size = %.3f\n",
471 gsl_vector_get (s->x, 0),
472 gsl_vector_get (s->x, 1),
475 while (status == GSL_CONTINUE && iter < 100);
479 gsl_multimin_fminimizer_free (s);
484 The minimum search stops when the Simplex size drops to 0.01. The
485 output is shown below.
487 1 6.500e+00 5.000e+00 f() = 512.500 size = 1.082
488 2 5.250e+00 4.000e+00 f() = 290.625 size = 1.372
489 3 5.250e+00 4.000e+00 f() = 290.625 size = 1.372
490 4 5.500e+00 1.000e+00 f() = 252.500 size = 1.372
491 5 2.625e+00 3.500e+00 f() = 101.406 size = 1.823
492 6 3.469e+00 1.375e+00 f() = 98.760 size = 1.526
493 7 1.820e+00 3.156e+00 f() = 63.467 size = 1.105
494 8 1.820e+00 3.156e+00 f() = 63.467 size = 1.105
495 9 1.016e+00 2.812e+00 f() = 43.206 size = 1.105
496 10 2.041e+00 2.008e+00 f() = 40.838 size = 0.645
497 11 1.236e+00 1.664e+00 f() = 32.816 size = 0.645
498 12 1.236e+00 1.664e+00 f() = 32.816 size = 0.447
499 13 5.225e-01 1.980e+00 f() = 32.288 size = 0.447
500 14 1.103e+00 2.073e+00 f() = 30.214 size = 0.345
501 15 1.103e+00 2.073e+00 f() = 30.214 size = 0.264
502 16 1.103e+00 2.073e+00 f() = 30.214 size = 0.160
503 17 9.864e-01 1.934e+00 f() = 30.090 size = 0.132
504 18 9.190e-01 1.987e+00 f() = 30.069 size = 0.092
505 19 1.028e+00 2.017e+00 f() = 30.013 size = 0.056
506 20 1.028e+00 2.017e+00 f() = 30.013 size = 0.046
507 21 1.028e+00 2.017e+00 f() = 30.013 size = 0.033
508 22 9.874e-01 1.985e+00 f() = 30.006 size = 0.028
509 23 9.846e-01 1.995e+00 f() = 30.003 size = 0.023
510 24 1.007e+00 2.003e+00 f() = 30.001 size = 0.012
511 converged to minimum at
512 25 1.007e+00 2.003e+00 f() = 30.001 size = 0.010
514 The simplex size first increases, while the simplex moves towards the
515 minimum. After a while the size begins to decrease as the simplex
516 contracts around the minimum.
519 File: gsl-ref.info, Node: Multimin References and Further Reading, Prev: Multimin Examples, Up: Multidimensional Minimization
521 35.9 References and Further Reading
522 ===================================
524 The conjugate gradient and BFGS methods are described in detail in the
527 R. Fletcher, `Practical Methods of Optimization (Second Edition)'
528 Wiley (1987), ISBN 0471915475.
530 A brief description of multidimensional minimization algorithms and
531 more recent references can be found in,
533 C.W. Ueberhuber, `Numerical Computation (Volume 2)', Chapter 14,
534 Section 4.4 "Minimization Methods", p. 325-335, Springer (1997),
537 The simplex algorithm is described in the following paper,
539 J.A. Nelder and R. Mead, `A simplex method for function
540 minimization', Computer Journal vol. 7 (1965), 308-315.
544 File: gsl-ref.info, Node: Least-Squares Fitting, Next: Nonlinear Least-Squares Fitting, Prev: Multidimensional Minimization, Up: Top
546 36 Least-Squares Fitting
547 ************************
549 This chapter describes routines for performing least squares fits to
550 experimental data using linear combinations of functions. The data may
551 be weighted or unweighted, i.e. with known or unknown errors. For
552 weighted data the functions compute the best fit parameters and their
553 associated covariance matrix. For unweighted data the covariance
554 matrix is estimated from the scatter of the points, giving a
555 variance-covariance matrix.
557 The functions are divided into separate versions for simple one- or
558 two-parameter regression and multiple-parameter fits. The functions
559 are declared in the header file `gsl_fit.h'.
564 * Linear regression::
565 * Linear fitting without a constant term::
566 * Multi-parameter fitting::
568 * Fitting References and Further Reading::
571 File: gsl-ref.info, Node: Fitting Overview, Next: Linear regression, Up: Least-Squares Fitting
576 Least-squares fits are found by minimizing \chi^2 (chi-squared), the
577 weighted sum of squared residuals over n experimental datapoints (x_i,
578 y_i) for the model Y(c,x),
580 \chi^2 = \sum_i w_i (y_i - Y(c, x_i))^2
582 The p parameters of the model are c = {c_0, c_1, ...}. The weight
583 factors w_i are given by w_i = 1/\sigma_i^2, where \sigma_i is the
584 experimental error on the data-point y_i. The errors are assumed to be
585 gaussian and uncorrelated. For unweighted data the chi-squared sum is
586 computed without any weight factors.
588 The fitting routines return the best-fit parameters c and their p
589 \times p covariance matrix. The covariance matrix measures the
590 statistical errors on the best-fit parameters resulting from the errors
591 on the data, \sigma_i, and is defined as C_{ab} = <\delta c_a \delta
592 c_b> where < > denotes an average over the gaussian error distributions
593 of the underlying datapoints.
595 The covariance matrix is calculated by error propagation from the
596 data errors \sigma_i. The change in a fitted parameter \delta c_a
597 caused by a small change in the data \delta y_i is given by
599 \delta c_a = \sum_i (dc_a/dy_i) \delta y_i
601 allowing the covariance matrix to be written in terms of the errors on
604 C_{ab} = \sum_{i,j} (dc_a/dy_i) (dc_b/dy_j) <\delta y_i \delta y_j>
606 For uncorrelated data the fluctuations of the underlying datapoints
607 satisfy <\delta y_i \delta y_j> = \sigma_i^2 \delta_{ij}, giving a
608 corresponding parameter covariance matrix of
610 C_{ab} = \sum_i (1/w_i) (dc_a/dy_i) (dc_b/dy_i)
612 When computing the covariance matrix for unweighted data, i.e. data
613 with unknown errors, the weight factors w_i in this sum are replaced by
614 the single estimate w = 1/\sigma^2, where \sigma^2 is the computed
615 variance of the residuals about the best-fit model, \sigma^2 = \sum
616 (y_i - Y(c,x_i))^2 / (n-p). This is referred to as the
617 "variance-covariance matrix".
619 The standard deviations of the best-fit parameters are given by the
620 square root of the corresponding diagonal elements of the covariance
621 matrix, \sigma_{c_a} = \sqrt{C_{aa}}. The correlation coefficient of
622 the fit parameters c_a and c_b is given by \rho_{ab} = C_{ab} /
623 \sqrt{C_{aa} C_{bb}}.
626 File: gsl-ref.info, Node: Linear regression, Next: Linear fitting without a constant term, Prev: Fitting Overview, Up: Least-Squares Fitting
628 36.2 Linear regression
629 ======================
631 The functions described in this section can be used to perform
632 least-squares fits to a straight line model, Y(c,x) = c_0 + c_1 x.
634 -- Function: int gsl_fit_linear (const double * X, const size_t
635 XSTRIDE, const double * Y, const size_t YSTRIDE, size_t N,
636 double * C0, double * C1, double * COV00, double * COV01,
637 double * COV11, double * SUMSQ)
638 This function computes the best-fit linear regression coefficients
639 (C0,C1) of the model Y = c_0 + c_1 X for the dataset (X, Y), two
640 vectors of length N with strides XSTRIDE and YSTRIDE. The errors
641 on Y are assumed unknown so the variance-covariance matrix for the
642 parameters (C0, C1) is estimated from the scatter of the points
643 around the best-fit line and returned via the parameters (COV00,
644 COV01, COV11). The sum of squares of the residuals from the
645 best-fit line is returned in SUMSQ. Note: the correlation
646 coefficient of the data can be computed using
647 `gsl_stats_correlation' (*note Correlation::), it does not depend
650 -- Function: int gsl_fit_wlinear (const double * X, const size_t
651 XSTRIDE, const double * W, const size_t WSTRIDE, const double
652 * Y, const size_t YSTRIDE, size_t N, double * C0, double *
653 C1, double * COV00, double * COV01, double * COV11, double *
655 This function computes the best-fit linear regression coefficients
656 (C0,C1) of the model Y = c_0 + c_1 X for the weighted dataset (X,
657 Y), two vectors of length N with strides XSTRIDE and YSTRIDE. The
658 vector W, of length N and stride WSTRIDE, specifies the weight of
659 each datapoint. The weight is the reciprocal of the variance for
662 The covariance matrix for the parameters (C0, C1) is computed
663 using the weights and returned via the parameters (COV00, COV01,
664 COV11). The weighted sum of squares of the residuals from the
665 best-fit line, \chi^2, is returned in CHISQ.
667 -- Function: int gsl_fit_linear_est (double X, double C0, double C1,
668 double COV00, double COV01, double COV11, double * Y, double
670 This function uses the best-fit linear regression coefficients C0,
671 C1 and their covariance COV00, COV01, COV11 to compute the fitted
672 function Y and its standard deviation Y_ERR for the model Y = c_0
673 + c_1 X at the point X.
676 File: gsl-ref.info, Node: Linear fitting without a constant term, Next: Multi-parameter fitting, Prev: Linear regression, Up: Least-Squares Fitting
678 36.3 Linear fitting without a constant term
679 ===========================================
681 The functions described in this section can be used to perform
682 least-squares fits to a straight line model without a constant term, Y
685 -- Function: int gsl_fit_mul (const double * X, const size_t XSTRIDE,
686 const double * Y, const size_t YSTRIDE, size_t N, double *
687 C1, double * COV11, double * SUMSQ)
688 This function computes the best-fit linear regression coefficient
689 C1 of the model Y = c_1 X for the datasets (X, Y), two vectors of
690 length N with strides XSTRIDE and YSTRIDE. The errors on Y are
691 assumed unknown so the variance of the parameter C1 is estimated
692 from the scatter of the points around the best-fit line and
693 returned via the parameter COV11. The sum of squares of the
694 residuals from the best-fit line is returned in SUMSQ.
696 -- Function: int gsl_fit_wmul (const double * X, const size_t XSTRIDE,
697 const double * W, const size_t WSTRIDE, const double * Y,
698 const size_t YSTRIDE, size_t N, double * C1, double * COV11,
700 This function computes the best-fit linear regression coefficient
701 C1 of the model Y = c_1 X for the weighted datasets (X, Y), two
702 vectors of length N with strides XSTRIDE and YSTRIDE. The vector
703 W, of length N and stride WSTRIDE, specifies the weight of each
704 datapoint. The weight is the reciprocal of the variance for each
707 The variance of the parameter C1 is computed using the weights and
708 returned via the parameter COV11. The weighted sum of squares of
709 the residuals from the best-fit line, \chi^2, is returned in CHISQ.
711 -- Function: int gsl_fit_mul_est (double X, double C1, double COV11,
712 double * Y, double * Y_ERR)
713 This function uses the best-fit linear regression coefficient C1
714 and its covariance COV11 to compute the fitted function Y and its
715 standard deviation Y_ERR for the model Y = c_1 X at the point X.
718 File: gsl-ref.info, Node: Multi-parameter fitting, Next: Fitting Examples, Prev: Linear fitting without a constant term, Up: Least-Squares Fitting
720 36.4 Multi-parameter fitting
721 ============================
723 The functions described in this section perform least-squares fits to a
724 general linear model, y = X c where y is a vector of n observations, X
725 is an n by p matrix of predictor variables, and the elements of the
726 vector c are the p unknown best-fit parameters which are to be
727 estimated. The chi-squared value is given by \chi^2 = \sum_i w_i (y_i
728 - \sum_j X_{ij} c_j)^2.
730 This formulation can be used for fits to any number of functions
731 and/or variables by preparing the n-by-p matrix X appropriately. For
732 example, to fit to a p-th order polynomial in X, use the following
737 where the index i runs over the observations and the index j runs from
740 To fit to a set of p sinusoidal functions with fixed frequencies
741 \omega_1, \omega_2, ..., \omega_p, use,
743 X_{ij} = sin(\omega_j x_i)
745 To fit to p independent variables x_1, x_2, ..., x_p, use,
749 where x_j(i) is the i-th value of the predictor variable x_j.
751 The functions described in this section are declared in the header
752 file `gsl_multifit.h'.
754 The solution of the general linear least-squares system requires an
755 additional working space for intermediate results, such as the singular
756 value decomposition of the matrix X.
758 -- Function: gsl_multifit_linear_workspace * gsl_multifit_linear_alloc
760 This function allocates a workspace for fitting a model to N
761 observations using P parameters.
763 -- Function: void gsl_multifit_linear_free
764 (gsl_multifit_linear_workspace * WORK)
765 This function frees the memory associated with the workspace W.
767 -- Function: int gsl_multifit_linear (const gsl_matrix * X, const
768 gsl_vector * Y, gsl_vector * C, gsl_matrix * COV, double *
769 CHISQ, gsl_multifit_linear_workspace * WORK)
770 -- Function: int gsl_multifit_linear_svd (const gsl_matrix * X, const
771 gsl_vector * Y, double TOL, size_t * RANK, gsl_vector * C,
772 gsl_matrix * COV, double * CHISQ,
773 gsl_multifit_linear_workspace * WORK)
774 These functions compute the best-fit parameters C of the model y =
775 X c for the observations Y and the matrix of predictor variables
776 X. The variance-covariance matrix of the model parameters COV is
777 estimated from the scatter of the observations about the best-fit.
778 The sum of squares of the residuals from the best-fit, \chi^2, is
779 returned in CHISQ. If the coefficient of determination is desired,
780 it can be computed from the expression R^2 = 1 - \chi^2 / TSS,
781 where the total sum of squares (TSS) of the observations Y may be
782 computed from `gsl_stats_tss'.
784 The best-fit is found by singular value decomposition of the matrix
785 X using the preallocated workspace provided in WORK. The modified
786 Golub-Reinsch SVD algorithm is used, with column scaling to
787 improve the accuracy of the singular values. Any components which
788 have zero singular value (to machine precision) are discarded from
789 the fit. In the second form of the function the components are
790 discarded if the ratio of singular values s_i/s_0 falls below the
791 user-specified tolerance TOL, and the effective rank is returned
794 -- Function: int gsl_multifit_wlinear (const gsl_matrix * X, const
795 gsl_vector * W, const gsl_vector * Y, gsl_vector * C,
796 gsl_matrix * COV, double * CHISQ,
797 gsl_multifit_linear_workspace * WORK)
798 -- Function: int gsl_multifit_wlinear_svd (const gsl_matrix * X, const
799 gsl_vector * W, const gsl_vector * Y, double TOL, size_t *
800 RANK, gsl_vector * C, gsl_matrix * COV, double * CHISQ,
801 gsl_multifit_linear_workspace * WORK)
802 This function computes the best-fit parameters C of the weighted
803 model y = X c for the observations Y with weights W and the matrix
804 of predictor variables X. The covariance matrix of the model
805 parameters COV is computed with the given weights. The weighted
806 sum of squares of the residuals from the best-fit, \chi^2, is
807 returned in CHISQ. If the coefficient of determination is desired,
808 it can be computed from the expression R^2 = 1 - \chi^2 / WTSS,
809 where the weighted total sum of squares (WTSS) of the observations
810 Y may be computed from `gsl_stats_wtss'.
812 The best-fit is found by singular value decomposition of the matrix
813 X using the preallocated workspace provided in WORK. Any
814 components which have zero singular value (to machine precision)
815 are discarded from the fit. In the second form of the function the
816 components are discarded if the ratio of singular values s_i/s_0
817 falls below the user-specified tolerance TOL, and the effective
818 rank is returned in RANK.
820 -- Function: int gsl_multifit_linear_est (const gsl_vector * X, const
821 gsl_vector * C, const gsl_matrix * COV, double * Y, double *
823 This function uses the best-fit multilinear regression coefficients
824 C and their covariance matrix COV to compute the fitted function
825 value Y and its standard deviation Y_ERR for the model y = x.c at
828 -- Function: int gsl_multifit_linear_residuals (const gsl_matrix * X,
829 const gsl_vector * Y, const gsl_vector * C, gsl_vector * R)
830 This function computes the vector of residuals r = y - X c for the
831 observations Y, coefficients C and matrix of predictor variables X.
834 File: gsl-ref.info, Node: Fitting Examples, Next: Fitting References and Further Reading, Prev: Multi-parameter fitting, Up: Least-Squares Fitting
839 The following program computes a least squares straight-line fit to a
840 simple dataset, and outputs the best-fit line and its associated one
841 standard-deviation error bars.
844 #include <gsl/gsl_fit.h>
850 double x[4] = { 1970, 1980, 1990, 2000 };
851 double y[4] = { 12, 11, 14, 13 };
852 double w[4] = { 0.1, 0.2, 0.3, 0.4 };
854 double c0, c1, cov00, cov01, cov11, chisq;
856 gsl_fit_wlinear (x, 1, w, 1, y, 1, n,
857 &c0, &c1, &cov00, &cov01, &cov11,
860 printf ("# best fit: Y = %g + %g X\n", c0, c1);
861 printf ("# covariance matrix:\n");
862 printf ("# [ %g, %g\n# %g, %g]\n",
863 cov00, cov01, cov01, cov11);
864 printf ("# chisq = %g\n", chisq);
866 for (i = 0; i < n; i++)
867 printf ("data: %g %g %g\n",
868 x[i], y[i], 1/sqrt(w[i]));
872 for (i = -30; i < 130; i++)
874 double xf = x[0] + (i/100.0) * (x[n-1] - x[0]);
877 gsl_fit_linear_est (xf,
882 printf ("fit: %g %g\n", xf, yf);
883 printf ("hi : %g %g\n", xf, yf + yf_err);
884 printf ("lo : %g %g\n", xf, yf - yf_err);
889 The following commands extract the data from the output of the program
890 and display it using the GNU plotutils `graph' utility,
894 # best fit: Y = -106.6 + 0.06 X
900 $ for n in data fit hi lo ;
902 grep "^$n" tmp | cut -d: -f2 > $n ;
904 $ graph -T X -X x -Y y -y 0 20 -m 0 -S 2 -Ie data
905 -S 0 -I a -m 1 fit -m 2 hi -m 2 lo
907 The next program performs a quadratic fit y = c_0 + c_1 x + c_2 x^2
908 to a weighted dataset using the generalised linear fitting function
909 `gsl_multifit_wlinear'. The model matrix X for a quadratic fit is
912 X = [ 1 , x_0 , x_0^2 ;
917 where the column of ones corresponds to the constant term c_0. The two
918 remaining columns corresponds to the terms c_1 x and c_2 x^2.
920 The program reads N lines of data in the format (X, Y, ERR) where
921 ERR is the error (standard deviation) in the value Y.
924 #include <gsl/gsl_multifit.h>
927 main (int argc, char **argv)
930 double xi, yi, ei, chisq;
932 gsl_vector *y, *w, *c;
936 fprintf (stderr,"usage: fit n < data\n");
942 X = gsl_matrix_alloc (n, 3);
943 y = gsl_vector_alloc (n);
944 w = gsl_vector_alloc (n);
946 c = gsl_vector_alloc (3);
947 cov = gsl_matrix_alloc (3, 3);
949 for (i = 0; i < n; i++)
951 int count = fscanf (stdin, "%lg %lg %lg",
956 fprintf (stderr, "error reading file\n");
960 printf ("%g %g +/- %g\n", xi, yi, ei);
962 gsl_matrix_set (X, i, 0, 1.0);
963 gsl_matrix_set (X, i, 1, xi);
964 gsl_matrix_set (X, i, 2, xi*xi);
966 gsl_vector_set (y, i, yi);
967 gsl_vector_set (w, i, 1.0/(ei*ei));
971 gsl_multifit_linear_workspace * work
972 = gsl_multifit_linear_alloc (n, 3);
973 gsl_multifit_wlinear (X, w, y, c, cov,
975 gsl_multifit_linear_free (work);
978 #define C(i) (gsl_vector_get(c,(i)))
979 #define COV(i,j) (gsl_matrix_get(cov,(i),(j)))
982 printf ("# best fit: Y = %g + %g X + %g X^2\n",
985 printf ("# covariance matrix:\n");
986 printf ("[ %+.5e, %+.5e, %+.5e \n",
987 COV(0,0), COV(0,1), COV(0,2));
988 printf (" %+.5e, %+.5e, %+.5e \n",
989 COV(1,0), COV(1,1), COV(1,2));
990 printf (" %+.5e, %+.5e, %+.5e ]\n",
991 COV(2,0), COV(2,1), COV(2,2));
992 printf ("# chisq = %g\n", chisq);
999 gsl_matrix_free (cov);
1004 A suitable set of data for fitting can be generated using the following
1005 program. It outputs a set of points with gaussian errors from the curve
1006 y = e^x in the region 0 < x < 2.
1010 #include <gsl/gsl_randist.h>
1016 const gsl_rng_type * T;
1019 gsl_rng_env_setup ();
1021 T = gsl_rng_default;
1022 r = gsl_rng_alloc (T);
1024 for (x = 0.1; x < 2; x+= 0.1)
1026 double y0 = exp (x);
1027 double sigma = 0.1 * y0;
1028 double dy = gsl_ran_gaussian (r, sigma);
1030 printf ("%g %g %g\n", x, y0 + dy, sigma);
1038 The data can be prepared by running the resulting executable program,
1040 $ ./generate > exp.dat
1042 0.1 0.97935 0.110517
1044 0.3 1.52573 0.134986
1045 0.4 1.60318 0.149182
1046 0.5 1.81731 0.164872
1047 0.6 1.92475 0.182212
1050 To fit the data use the previous program, with the number of data points
1051 given as the first argument. In this case there are 19 data points.
1053 $ ./fit 19 < exp.dat
1054 0.1 0.97935 +/- 0.110517
1055 0.2 1.3359 +/- 0.12214
1057 # best fit: Y = 1.02318 + 0.956201 X + 0.876796 X^2
1058 # covariance matrix:
1059 [ +1.25612e-02, -3.64387e-02, +1.94389e-02
1060 -3.64387e-02, +1.42339e-01, -8.48761e-02
1061 +1.94389e-02, -8.48761e-02, +5.60243e-02 ]
1064 The parameters of the quadratic fit match the coefficients of the
1065 expansion of e^x, taking into account the errors on the parameters and
1066 the O(x^3) difference between the exponential and quadratic functions
1067 for the larger values of x. The errors on the parameters are given by
1068 the square-root of the corresponding diagonal elements of the
1069 covariance matrix. The chi-squared per degree of freedom is 1.4,
1070 indicating a reasonable fit to the data.
1073 File: gsl-ref.info, Node: Fitting References and Further Reading, Prev: Fitting Examples, Up: Least-Squares Fitting
1075 36.6 References and Further Reading
1076 ===================================
1078 A summary of formulas and techniques for least squares fitting can be
1079 found in the "Statistics" chapter of the Annual Review of Particle
1080 Physics prepared by the Particle Data Group,
1082 `Review of Particle Properties', R.M. Barnett et al., Physical
1083 Review D54, 1 (1996) `http://pdg.lbl.gov/'
1085 The Review of Particle Physics is available online at the website given
1088 The tests used to prepare these routines are based on the NIST
1089 Statistical Reference Datasets. The datasets and their documentation are
1090 available from NIST at the following website,
1092 `http://www.nist.gov/itl/div898/strd/index.html'.
1095 File: gsl-ref.info, Node: Nonlinear Least-Squares Fitting, Next: Basis Splines, Prev: Least-Squares Fitting, Up: Top
1097 37 Nonlinear Least-Squares Fitting
1098 **********************************
1100 This chapter describes functions for multidimensional nonlinear
1101 least-squares fitting. The library provides low level components for a
1102 variety of iterative solvers and convergence tests. These can be
1103 combined by the user to achieve the desired solution, with full access
1104 to the intermediate steps of the iteration. Each class of methods uses
1105 the same framework, so that you can switch between solvers at runtime
1106 without needing to recompile your program. Each instance of a solver
1107 keeps track of its own state, allowing the solvers to be used in
1108 multi-threaded programs.
1110 The header file `gsl_multifit_nlin.h' contains prototypes for the
1111 multidimensional nonlinear fitting functions and related declarations.
1115 * Overview of Nonlinear Least-Squares Fitting::
1116 * Initializing the Nonlinear Least-Squares Solver::
1117 * Providing the Function to be Minimized::
1118 * Iteration of the Minimization Algorithm::
1119 * Search Stopping Parameters for Minimization Algorithms::
1120 * Minimization Algorithms using Derivatives::
1121 * Minimization Algorithms without Derivatives::
1122 * Computing the covariance matrix of best fit parameters::
1123 * Example programs for Nonlinear Least-Squares Fitting::
1124 * References and Further Reading for Nonlinear Least-Squares Fitting::
1127 File: gsl-ref.info, Node: Overview of Nonlinear Least-Squares Fitting, Next: Initializing the Nonlinear Least-Squares Solver, Up: Nonlinear Least-Squares Fitting
1132 The problem of multidimensional nonlinear least-squares fitting requires
1133 the minimization of the squared residuals of n functions, f_i, in p
1136 \Phi(x) = (1/2) || F(x) ||^2
1137 = (1/2) \sum_{i=1}^{n} f_i(x_1, ..., x_p)^2
1139 All algorithms proceed from an initial guess using the linearization,
1141 \psi(p) = || F(x+p) || ~=~ || F(x) + J p ||
1143 where x is the initial point, p is the proposed step and J is the
1144 Jacobian matrix J_{ij} = d f_i / d x_j. Additional strategies are used
1145 to enlarge the region of convergence. These include requiring a
1146 decrease in the norm ||F|| on each step or using a trust region to
1147 avoid steps which fall outside the linear regime.
1149 To perform a weighted least-squares fit of a nonlinear model Y(x,t)
1150 to data (t_i, y_i) with independent gaussian errors \sigma_i, use
1151 function components of the following form,
1153 f_i = (Y(x, t_i) - y_i) / \sigma_i
1155 Note that the model parameters are denoted by x in this chapter since
1156 the non-linear least-squares algorithms are described geometrically
1157 (i.e. finding the minimum of a surface). The independent variable of
1158 any data to be fitted is denoted by t.
1160 With the definition above the Jacobian is J_{ij} =(1 / \sigma_i) d
1161 Y_i / d x_j, where Y_i = Y(x,t_i).
1164 File: gsl-ref.info, Node: Initializing the Nonlinear Least-Squares Solver, Next: Providing the Function to be Minimized, Prev: Overview of Nonlinear Least-Squares Fitting, Up: Nonlinear Least-Squares Fitting
1166 37.2 Initializing the Solver
1167 ============================
1169 -- Function: gsl_multifit_fsolver * gsl_multifit_fsolver_alloc (const
1170 gsl_multifit_fsolver_type * T, size_t N, size_t P)
1171 This function returns a pointer to a newly allocated instance of a
1172 solver of type T for N observations and P parameters. The number
1173 of observations N must be greater than or equal to parameters P.
1175 If there is insufficient memory to create the solver then the
1176 function returns a null pointer and the error handler is invoked
1177 with an error code of `GSL_ENOMEM'.
1179 -- Function: gsl_multifit_fdfsolver * gsl_multifit_fdfsolver_alloc
1180 (const gsl_multifit_fdfsolver_type * T, size_t N, size_t P)
1181 This function returns a pointer to a newly allocated instance of a
1182 derivative solver of type T for N observations and P parameters.
1183 For example, the following code creates an instance of a
1184 Levenberg-Marquardt solver for 100 data points and 3 parameters,
1186 const gsl_multifit_fdfsolver_type * T
1187 = gsl_multifit_fdfsolver_lmder;
1188 gsl_multifit_fdfsolver * s
1189 = gsl_multifit_fdfsolver_alloc (T, 100, 3);
1191 The number of observations N must be greater than or equal to
1194 If there is insufficient memory to create the solver then the
1195 function returns a null pointer and the error handler is invoked
1196 with an error code of `GSL_ENOMEM'.
1198 -- Function: int gsl_multifit_fsolver_set (gsl_multifit_fsolver * S,
1199 gsl_multifit_function * F, gsl_vector * X)
1200 This function initializes, or reinitializes, an existing solver S
1201 to use the function F and the initial guess X.
1203 -- Function: int gsl_multifit_fdfsolver_set (gsl_multifit_fdfsolver *
1204 S, gsl_multifit_function_fdf * FDF, gsl_vector * X)
1205 This function initializes, or reinitializes, an existing solver S
1206 to use the function and derivative FDF and the initial guess X.
1208 -- Function: void gsl_multifit_fsolver_free (gsl_multifit_fsolver * S)
1209 -- Function: void gsl_multifit_fdfsolver_free (gsl_multifit_fdfsolver
1211 These functions free all the memory associated with the solver S.
1213 -- Function: const char * gsl_multifit_fsolver_name (const
1214 gsl_multifit_fsolver * S)
1215 -- Function: const char * gsl_multifit_fdfsolver_name (const
1216 gsl_multifit_fdfsolver * S)
1217 These functions return a pointer to the name of the solver. For
1220 printf ("s is a '%s' solver\n",
1221 gsl_multifit_fdfsolver_name (s));
1223 would print something like `s is a 'lmder' solver'.
1226 File: gsl-ref.info, Node: Providing the Function to be Minimized, Next: Iteration of the Minimization Algorithm, Prev: Initializing the Nonlinear Least-Squares Solver, Up: Nonlinear Least-Squares Fitting
1228 37.3 Providing the Function to be Minimized
1229 ===========================================
1231 You must provide n functions of p variables for the minimization
1232 algorithms to operate on. In order to allow for arbitrary parameters
1233 the functions are defined by the following data types:
1235 -- Data Type: gsl_multifit_function
1236 This data type defines a general system of functions with
1237 arbitrary parameters.
1239 `int (* f) (const gsl_vector * X, void * PARAMS, gsl_vector * F)'
1240 this function should store the vector result f(x,params) in F
1241 for argument X and arbitrary parameters PARAMS, returning an
1242 appropriate error code if the function cannot be computed.
1245 the number of functions, i.e. the number of components of the
1249 the number of independent variables, i.e. the number of
1250 components of the vector X.
1253 a pointer to the arbitrary parameters of the function.
1255 -- Data Type: gsl_multifit_function_fdf
1256 This data type defines a general system of functions with
1257 arbitrary parameters and the corresponding Jacobian matrix of
1260 `int (* f) (const gsl_vector * X, void * PARAMS, gsl_vector * F)'
1261 this function should store the vector result f(x,params) in F
1262 for argument X and arbitrary parameters PARAMS, returning an
1263 appropriate error code if the function cannot be computed.
1265 `int (* df) (const gsl_vector * X, void * PARAMS, gsl_matrix * J)'
1266 this function should store the N-by-P matrix result J_ij = d
1267 f_i(x,params) / d x_j in J for argument X and arbitrary
1268 parameters PARAMS, returning an appropriate error code if the
1269 function cannot be computed.
1271 `int (* fdf) (const gsl_vector * X, void * PARAMS, gsl_vector * F, gsl_matrix * J)'
1272 This function should set the values of the F and J as above,
1273 for arguments X and arbitrary parameters PARAMS. This
1274 function provides an optimization of the separate functions
1275 for f(x) and J(x)--it is always faster to compute the
1276 function and its derivative at the same time.
1279 the number of functions, i.e. the number of components of the
1283 the number of independent variables, i.e. the number of
1284 components of the vector X.
1287 a pointer to the arbitrary parameters of the function.
1289 Note that when fitting a non-linear model against experimental data,
1290 the data is passed to the functions above using the PARAMS argument and
1291 the trial best-fit parameters through the X argument.
1294 File: gsl-ref.info, Node: Iteration of the Minimization Algorithm, Next: Search Stopping Parameters for Minimization Algorithms, Prev: Providing the Function to be Minimized, Up: Nonlinear Least-Squares Fitting
1299 The following functions drive the iteration of each algorithm. Each
1300 function performs one iteration to update the state of any solver of the
1301 corresponding type. The same functions work for all solvers so that
1302 different methods can be substituted at runtime without modifications to
1305 -- Function: int gsl_multifit_fsolver_iterate (gsl_multifit_fsolver *
1307 -- Function: int gsl_multifit_fdfsolver_iterate
1308 (gsl_multifit_fdfsolver * S)
1309 These functions perform a single iteration of the solver S. If
1310 the iteration encounters an unexpected problem then an error code
1311 will be returned. The solver maintains a current estimate of the
1312 best-fit parameters at all times.
1314 The solver struct S contains the following entries, which can be
1315 used to track the progress of the solution:
1318 The current position.
1321 The function value at the current position.
1324 The difference between the current position and the previous
1325 position, i.e. the last step, taken as a vector.
1328 The Jacobian matrix at the current position (for the
1329 `gsl_multifit_fdfsolver' struct only)
1331 The best-fit information also can be accessed with the following
1332 auxiliary functions,
1334 -- Function: gsl_vector * gsl_multifit_fsolver_position (const
1335 gsl_multifit_fsolver * S)
1336 -- Function: gsl_vector * gsl_multifit_fdfsolver_position (const
1337 gsl_multifit_fdfsolver * S)
1338 These functions return the current position (i.e. best-fit
1339 parameters) `s->x' of the solver S.
1342 File: gsl-ref.info, Node: Search Stopping Parameters for Minimization Algorithms, Next: Minimization Algorithms using Derivatives, Prev: Iteration of the Minimization Algorithm, Up: Nonlinear Least-Squares Fitting
1344 37.5 Search Stopping Parameters
1345 ===============================
1347 A minimization procedure should stop when one of the following
1350 * A minimum has been found to within the user-specified precision.
1352 * A user-specified maximum number of iterations has been reached.
1354 * An error has occurred.
1356 The handling of these conditions is under user control. The functions
1357 below allow the user to test the current estimate of the best-fit
1358 parameters in several standard ways.
1360 -- Function: int gsl_multifit_test_delta (const gsl_vector * DX, const
1361 gsl_vector * X, double EPSABS, double EPSREL)
1362 This function tests for the convergence of the sequence by
1363 comparing the last step DX with the absolute error EPSABS and
1364 relative error EPSREL to the current position X. The test returns
1365 `GSL_SUCCESS' if the following condition is achieved,
1367 |dx_i| < epsabs + epsrel |x_i|
1369 for each component of X and returns `GSL_CONTINUE' otherwise.
1371 -- Function: int gsl_multifit_test_gradient (const gsl_vector * G,
1373 This function tests the residual gradient G against the absolute
1374 error bound EPSABS. Mathematically, the gradient should be
1375 exactly zero at the minimum. The test returns `GSL_SUCCESS' if the
1376 following condition is achieved,
1378 \sum_i |g_i| < epsabs
1380 and returns `GSL_CONTINUE' otherwise. This criterion is suitable
1381 for situations where the precise location of the minimum, x, is
1382 unimportant provided a value can be found where the gradient is
1385 -- Function: int gsl_multifit_gradient (const gsl_matrix * J, const
1386 gsl_vector * F, gsl_vector * G)
1387 This function computes the gradient G of \Phi(x) = (1/2)
1388 ||F(x)||^2 from the Jacobian matrix J and the function values F,
1389 using the formula g = J^T f.
1392 File: gsl-ref.info, Node: Minimization Algorithms using Derivatives, Next: Minimization Algorithms without Derivatives, Prev: Search Stopping Parameters for Minimization Algorithms, Up: Nonlinear Least-Squares Fitting
1394 37.6 Minimization Algorithms using Derivatives
1395 ==============================================
1397 The minimization algorithms described in this section make use of both
1398 the function and its derivative. They require an initial guess for the
1399 location of the minimum. There is no absolute guarantee of
1400 convergence--the function must be suitable for this technique and the
1401 initial guess must be sufficiently close to the minimum for it to work.
1403 -- Derivative Solver: gsl_multifit_fdfsolver_lmsder
1404 This is a robust and efficient version of the Levenberg-Marquardt
1405 algorithm as implemented in the scaled LMDER routine in MINPACK.
1406 Minpack was written by Jorge J. More', Burton S. Garbow and
1407 Kenneth E. Hillstrom.
1409 The algorithm uses a generalized trust region to keep each step
1410 under control. In order to be accepted a proposed new position x'
1411 must satisfy the condition |D (x' - x)| < \delta, where D is a
1412 diagonal scaling matrix and \delta is the size of the trust
1413 region. The components of D are computed internally, using the
1414 column norms of the Jacobian to estimate the sensitivity of the
1415 residual to each component of x. This improves the behavior of the
1416 algorithm for badly scaled functions.
1418 On each iteration the algorithm attempts to minimize the linear
1419 system |F + J p| subject to the constraint |D p| < \Delta. The
1420 solution to this constrained linear system is found using the
1421 Levenberg-Marquardt method.
1423 The proposed step is now tested by evaluating the function at the
1424 resulting point, x'. If the step reduces the norm of the function
1425 sufficiently, and follows the predicted behavior of the function
1426 within the trust region, then it is accepted and the size of the
1427 trust region is increased. If the proposed step fails to improve
1428 the solution, or differs significantly from the expected behavior
1429 within the trust region, then the size of the trust region is
1430 decreased and another trial step is computed.
1432 The algorithm also monitors the progress of the solution and
1433 returns an error if the changes in the solution are smaller than
1434 the machine precision. The possible error codes are,
1437 the decrease in the function falls below machine precision
1440 the change in the position vector falls below machine
1444 the norm of the gradient, relative to the norm of the
1445 function, falls below machine precision
1447 These error codes indicate that further iterations will be
1448 unlikely to change the solution from its current value.
1451 -- Derivative Solver: gsl_multifit_fdfsolver_lmder
1452 This is an unscaled version of the LMDER algorithm. The elements
1453 of the diagonal scaling matrix D are set to 1. This algorithm may
1454 be useful in circumstances where the scaled version of LMDER
1455 converges too slowly, or the function is already scaled
1459 File: gsl-ref.info, Node: Minimization Algorithms without Derivatives, Next: Computing the covariance matrix of best fit parameters, Prev: Minimization Algorithms using Derivatives, Up: Nonlinear Least-Squares Fitting
1461 37.7 Minimization Algorithms without Derivatives
1462 ================================================
1464 There are no algorithms implemented in this section at the moment.
1467 File: gsl-ref.info, Node: Computing the covariance matrix of best fit parameters, Next: Example programs for Nonlinear Least-Squares Fitting, Prev: Minimization Algorithms without Derivatives, Up: Nonlinear Least-Squares Fitting
1469 37.8 Computing the covariance matrix of best fit parameters
1470 ===========================================================
1472 -- Function: int gsl_multifit_covar (const gsl_matrix * J, double
1473 EPSREL, gsl_matrix * COVAR)
1474 This function uses the Jacobian matrix J to compute the covariance
1475 matrix of the best-fit parameters, COVAR. The parameter EPSREL is
1476 used to remove linear-dependent columns when J is rank deficient.
1478 The covariance matrix is given by,
1480 covar = (J^T J)^{-1}
1482 and is computed by QR decomposition of J with column-pivoting. Any
1483 columns of R which satisfy
1485 |R_{kk}| <= epsrel |R_{11}|
1487 are considered linearly-dependent and are excluded from the
1488 covariance matrix (the corresponding rows and columns of the
1489 covariance matrix are set to zero).
1491 If the minimisation uses the weighted least-squares function f_i =
1492 (Y(x, t_i) - y_i) / \sigma_i then the covariance matrix above
1493 gives the statistical error on the best-fit parameters resulting
1494 from the gaussian errors \sigma_i on the underlying data y_i.
1495 This can be verified from the relation \delta f = J \delta c and
1496 the fact that the fluctuations in f from the data y_i are
1497 normalised by \sigma_i and so satisfy <\delta f \delta f^T> = I.
1499 For an unweighted least-squares function f_i = (Y(x, t_i) - y_i)
1500 the covariance matrix above should be multiplied by the variance
1501 of the residuals about the best-fit \sigma^2 = \sum (y_i -
1502 Y(x,t_i))^2 / (n-p) to give the variance-covariance matrix
1503 \sigma^2 C. This estimates the statistical error on the best-fit
1504 parameters from the scatter of the underlying data.
1506 For more information about covariance matrices see *Note Fitting
1510 File: gsl-ref.info, Node: Example programs for Nonlinear Least-Squares Fitting, Next: References and Further Reading for Nonlinear Least-Squares Fitting, Prev: Computing the covariance matrix of best fit parameters, Up: Nonlinear Least-Squares Fitting
1515 The following example program fits a weighted exponential model with
1516 background to experimental data, Y = A \exp(-\lambda t) + b. The first
1517 part of the program sets up the functions `expb_f' and `expb_df' to
1518 calculate the model and its Jacobian. The appropriate fitting function
1521 f_i = ((A \exp(-\lambda t_i) + b) - y_i)/\sigma_i
1523 where we have chosen t_i = i. The Jacobian matrix J is the derivative
1524 of these functions with respect to the three parameters (A, \lambda,
1527 J_{ij} = d f_i / d x_j
1529 where x_0 = A, x_1 = \lambda and x_2 = b.
1531 /* expfit.c -- model functions for exponential + background */
1540 expb_f (const gsl_vector * x, void *data,
1543 size_t n = ((struct data *)data)->n;
1544 double *y = ((struct data *)data)->y;
1545 double *sigma = ((struct data *) data)->sigma;
1547 double A = gsl_vector_get (x, 0);
1548 double lambda = gsl_vector_get (x, 1);
1549 double b = gsl_vector_get (x, 2);
1553 for (i = 0; i < n; i++)
1555 /* Model Yi = A * exp(-lambda * i) + b */
1557 double Yi = A * exp (-lambda * t) + b;
1558 gsl_vector_set (f, i, (Yi - y[i])/sigma[i]);
1565 expb_df (const gsl_vector * x, void *data,
1568 size_t n = ((struct data *)data)->n;
1569 double *sigma = ((struct data *) data)->sigma;
1571 double A = gsl_vector_get (x, 0);
1572 double lambda = gsl_vector_get (x, 1);
1576 for (i = 0; i < n; i++)
1578 /* Jacobian matrix J(i,j) = dfi / dxj, */
1579 /* where fi = (Yi - yi)/sigma[i], */
1580 /* Yi = A * exp(-lambda * i) + b */
1581 /* and the xj are the parameters (A,lambda,b) */
1583 double s = sigma[i];
1584 double e = exp(-lambda * t);
1585 gsl_matrix_set (J, i, 0, e/s);
1586 gsl_matrix_set (J, i, 1, -t * A * e/s);
1587 gsl_matrix_set (J, i, 2, 1/s);
1593 expb_fdf (const gsl_vector * x, void *data,
1594 gsl_vector * f, gsl_matrix * J)
1596 expb_f (x, data, f);
1597 expb_df (x, data, J);
1602 The main part of the program sets up a Levenberg-Marquardt solver and
1603 some simulated random data. The data uses the known parameters
1604 (1.0,5.0,0.1) combined with gaussian noise (standard deviation = 0.1)
1605 over a range of 40 timesteps. The initial guess for the parameters is
1606 chosen as (0.0, 1.0, 0.0).
1610 #include <gsl/gsl_rng.h>
1611 #include <gsl/gsl_randist.h>
1612 #include <gsl/gsl_vector.h>
1613 #include <gsl/gsl_blas.h>
1614 #include <gsl/gsl_multifit_nlin.h>
1620 void print_state (size_t iter, gsl_multifit_fdfsolver * s);
1625 const gsl_multifit_fdfsolver_type *T;
1626 gsl_multifit_fdfsolver *s;
1628 unsigned int i, iter = 0;
1632 gsl_matrix *covar = gsl_matrix_alloc (p, p);
1633 double y[N], sigma[N];
1634 struct data d = { n, y, sigma};
1635 gsl_multifit_function_fdf f;
1636 double x_init[3] = { 1.0, 0.0, 0.0 };
1637 gsl_vector_view x = gsl_vector_view_array (x_init, p);
1638 const gsl_rng_type * type;
1641 gsl_rng_env_setup();
1643 type = gsl_rng_default;
1644 r = gsl_rng_alloc (type);
1653 /* This is the data to be fitted */
1655 for (i = 0; i < n; i++)
1658 y[i] = 1.0 + 5 * exp (-0.1 * t)
1659 + gsl_ran_gaussian (r, 0.1);
1661 printf ("data: %u %g %g\n", i, y[i], sigma[i]);
1664 T = gsl_multifit_fdfsolver_lmsder;
1665 s = gsl_multifit_fdfsolver_alloc (T, n, p);
1666 gsl_multifit_fdfsolver_set (s, &f, &x.vector);
1668 print_state (iter, s);
1673 status = gsl_multifit_fdfsolver_iterate (s);
1675 printf ("status = %s\n", gsl_strerror (status));
1677 print_state (iter, s);
1682 status = gsl_multifit_test_delta (s->dx, s->x,
1685 while (status == GSL_CONTINUE && iter < 500);
1687 gsl_multifit_covar (s->J, 0.0, covar);
1689 #define FIT(i) gsl_vector_get(s->x, i)
1690 #define ERR(i) sqrt(gsl_matrix_get(covar,i,i))
1693 double chi = gsl_blas_dnrm2(s->f);
1695 double c = GSL_MAX_DBL(1, chi / sqrt(dof));
1697 printf("chisq/dof = %g\n", pow(chi, 2.0) / dof);
1699 printf ("A = %.5f +/- %.5f\n", FIT(0), c*ERR(0));
1700 printf ("lambda = %.5f +/- %.5f\n", FIT(1), c*ERR(1));
1701 printf ("b = %.5f +/- %.5f\n", FIT(2), c*ERR(2));
1704 printf ("status = %s\n", gsl_strerror (status));
1706 gsl_multifit_fdfsolver_free (s);
1707 gsl_matrix_free (covar);
1713 print_state (size_t iter, gsl_multifit_fdfsolver * s)
1715 printf ("iter: %3u x = % 15.8f % 15.8f % 15.8f "
1718 gsl_vector_get (s->x, 0),
1719 gsl_vector_get (s->x, 1),
1720 gsl_vector_get (s->x, 2),
1721 gsl_blas_dnrm2 (s->f));
1724 The iteration terminates when the change in x is smaller than 0.0001, as
1725 both an absolute and relative change. Here are the results of running
1728 iter: 0 x=1.00000000 0.00000000 0.00000000 |f(x)|=117.349
1730 iter: 1 x=1.64659312 0.01814772 0.64659312 |f(x)|=76.4578
1732 iter: 2 x=2.85876037 0.08092095 1.44796363 |f(x)|=37.6838
1734 iter: 3 x=4.94899512 0.11942928 1.09457665 |f(x)|=9.58079
1736 iter: 4 x=5.02175572 0.10287787 1.03388354 |f(x)|=5.63049
1738 iter: 5 x=5.04520433 0.10405523 1.01941607 |f(x)|=5.44398
1740 iter: 6 x=5.04535782 0.10404906 1.01924871 |f(x)|=5.44397
1741 chisq/dof = 0.800996
1742 A = 5.04536 +/- 0.06028
1743 lambda = 0.10405 +/- 0.00316
1744 b = 1.01925 +/- 0.03782
1747 The approximate values of the parameters are found correctly, and the
1748 chi-squared value indicates a good fit (the chi-squared per degree of
1749 freedom is approximately 1). In this case the errors on the parameters
1750 can be estimated from the square roots of the diagonal elements of the
1753 If the chi-squared value shows a poor fit (i.e. chi^2/dof >> 1) then
1754 the error estimates obtained from the covariance matrix will be too
1755 small. In the example program the error estimates are multiplied by
1756 \sqrt{\chi^2/dof} in this case, a common way of increasing the errors
1757 for a poor fit. Note that a poor fit will result from the use an
1758 inappropriate model, and the scaled error estimates may then be outside
1759 the range of validity for gaussian errors.
1762 File: gsl-ref.info, Node: References and Further Reading for Nonlinear Least-Squares Fitting, Prev: Example programs for Nonlinear Least-Squares Fitting, Up: Nonlinear Least-Squares Fitting
1764 37.10 References and Further Reading
1765 ====================================
1767 The MINPACK algorithm is described in the following article,
1769 J.J. More', `The Levenberg-Marquardt Algorithm: Implementation and
1770 Theory', Lecture Notes in Mathematics, v630 (1978), ed G. Watson.
1772 The following paper is also relevant to the algorithms described in this
1775 J.J. More', B.S. Garbow, K.E. Hillstrom, "Testing Unconstrained
1776 Optimization Software", ACM Transactions on Mathematical Software,
1777 Vol 7, No 1 (1981), p 17-41.
1780 File: gsl-ref.info, Node: Basis Splines, Next: Physical Constants, Prev: Nonlinear Least-Squares Fitting, Up: Top
1785 This chapter describes functions for the computation of smoothing basis
1786 splines (B-splines). The header file `gsl_bspline.h' contains
1787 prototypes for the bspline functions and related declarations.
1791 * Overview of B-splines::
1792 * Initializing the B-splines solver::
1793 * Constructing the knots vector::
1794 * Evaluation of B-spline basis functions::
1795 * Example programs for B-splines::
1796 * References and Further Reading::
1799 File: gsl-ref.info, Node: Overview of B-splines, Next: Initializing the B-splines solver, Up: Basis Splines
1804 B-splines are commonly used as basis functions to fit smoothing curves
1805 to large data sets. To do this, the abscissa axis is broken up into
1806 some number of intervals, where the endpoints of each interval are
1807 called "breakpoints". These breakpoints are then converted to "knots"
1808 by imposing various continuity and smoothness conditions at each
1809 interface. Given a nondecreasing knot vector t = {t_0, t_1, ...,
1810 t_{n+k-1}}, the n basis splines of order k are defined by
1812 B_(i,1)(x) = (1, t_i <= x < t_(i+1)
1814 B_(i,k)(x) = [(x - t_i)/(t_(i+k-1) - t_i)] B_(i,k-1)(x) + [(t_(i+k) - x)/(t_(i+k) - t_(i+1))] B_(i+1,k-1)(x)
1816 for i = 0, ..., n-1. The common case of cubic B-splines is given by
1817 k = 4. The above recurrence relation can be evaluated in a numerically
1818 stable way by the de Boor algorithm.
1820 If we define appropriate knots on an interval [a,b] then the
1821 B-spline basis functions form a complete set on that interval.
1822 Therefore we can expand a smoothing function as
1824 f(x) = \sum_i c_i B_(i,k)(x)
1826 given enough (x_j, f(x_j)) data pairs. The c_i can be readily
1827 obtained from a least-squares fit.
1830 File: gsl-ref.info, Node: Initializing the B-splines solver, Next: Constructing the knots vector, Prev: Overview of B-splines, Up: Basis Splines
1832 38.2 Initializing the B-splines solver
1833 ======================================
1835 -- Function: gsl_bspline_workspace * gsl_bspline_alloc (const size_t
1836 K, const size_t NBREAK)
1837 This function allocates a workspace for computing B-splines of
1838 order K. The number of breakpoints is given by NBREAK. This leads
1839 to n = nbreak + k - 2 basis functions. Cubic B-splines are
1840 specified by k = 4. The size of the workspace is O(5k + nbreak).
1842 -- Function: void gsl_bspline_free (gsl_bspline_workspace * W)
1843 This function frees the memory associated with the workspace W.
1846 File: gsl-ref.info, Node: Constructing the knots vector, Next: Evaluation of B-spline basis functions, Prev: Initializing the B-splines solver, Up: Basis Splines
1848 38.3 Constructing the knots vector
1849 ==================================
1851 -- Function: int gsl_bspline_knots (const gsl_vector * BREAKPTS,
1852 gsl_bspline_workspace * W)
1853 This function computes the knots associated with the given
1854 breakpoints and stores them internally in `w->knots'.
1856 -- Function: int gsl_bspline_knots_uniform (const double a, const
1857 double b, gsl_bspline_workspace * W)
1858 This function assumes uniformly spaced breakpoints on [a,b] and
1859 constructs the corresponding knot vector using the previously
1860 specified NBREAK parameter. The knots are stored in `w->knots'.
1863 File: gsl-ref.info, Node: Evaluation of B-spline basis functions, Next: Example programs for B-splines, Prev: Constructing the knots vector, Up: Basis Splines
1865 38.4 Evaluation of B-splines
1866 ============================
1868 -- Function: int gsl_bspline_eval (const double X, gsl_vector * B,
1869 gsl_bspline_workspace * W)
1870 This function evaluates all B-spline basis functions at the
1871 position X and stores them in B, so that the ith element of B is
1872 B_i(x). B must be of length n = nbreak + k - 2. This value may
1873 also be obtained by calling `gsl_bspline_ncoeffs'. It is far more
1874 efficient to compute all of the basis functions at once than to
1875 compute them individually, due to the nature of the defining
1876 recurrence relation.
1878 -- Function: size_t gsl_bspline_ncoeffs (gsl_bspline_workspace * W)
1879 This function returns the number of B-spline coefficients given by
1883 File: gsl-ref.info, Node: Example programs for B-splines, Next: References and Further Reading, Prev: Evaluation of B-spline basis functions, Up: Basis Splines
1885 38.5 Example programs for B-splines
1886 ===================================
1888 The following program computes a linear least squares fit to data using
1889 cubic B-spline basis functions with uniform breakpoints. The data is
1890 generated from the curve y(x) = \cos(x) \exp(-x/10) on [0, 15] with
1891 gaussian noise added.
1896 #include <gsl/gsl_bspline.h>
1897 #include <gsl/gsl_multifit.h>
1898 #include <gsl/gsl_rng.h>
1899 #include <gsl/gsl_randist.h>
1900 #include <gsl/gsl_statistics.h>
1902 /* number of data points to fit */
1905 /* number of fit coefficients */
1908 /* nbreak = ncoeffs + 2 - k = ncoeffs - 2 since k = 4 */
1909 #define NBREAK (NCOEFFS - 2)
1915 const size_t ncoeffs = NCOEFFS;
1916 const size_t nbreak = NBREAK;
1918 gsl_bspline_workspace *bw;
1924 gsl_matrix *X, *cov;
1925 gsl_multifit_linear_workspace *mw;
1930 gsl_rng_env_setup();
1931 r = gsl_rng_alloc(gsl_rng_default);
1933 /* allocate a cubic bspline workspace (k = 4) */
1934 bw = gsl_bspline_alloc(4, nbreak);
1935 B = gsl_vector_alloc(ncoeffs);
1937 x = gsl_vector_alloc(n);
1938 y = gsl_vector_alloc(n);
1939 X = gsl_matrix_alloc(n, ncoeffs);
1940 c = gsl_vector_alloc(ncoeffs);
1941 w = gsl_vector_alloc(n);
1942 cov = gsl_matrix_alloc(ncoeffs, ncoeffs);
1943 mw = gsl_multifit_linear_alloc(n, ncoeffs);
1945 printf("#m=0,S=0\n");
1946 /* this is the data to be fitted */
1947 for (i = 0; i < n; ++i)
1950 double xi = (15.0 / (N - 1)) * i;
1951 double yi = cos(xi) * exp(-0.1 * xi);
1954 dy = gsl_ran_gaussian(r, sigma);
1957 gsl_vector_set(x, i, xi);
1958 gsl_vector_set(y, i, yi);
1959 gsl_vector_set(w, i, 1.0 / (sigma * sigma));
1961 printf("%f %f\n", xi, yi);
1964 /* use uniform breakpoints on [0, 15] */
1965 gsl_bspline_knots_uniform(0.0, 15.0, bw);
1967 /* construct the fit matrix X */
1968 for (i = 0; i < n; ++i)
1970 double xi = gsl_vector_get(x, i);
1972 /* compute B_j(xi) for all j */
1973 gsl_bspline_eval(xi, B, bw);
1975 /* fill in row i of X */
1976 for (j = 0; j < ncoeffs; ++j)
1978 double Bj = gsl_vector_get(B, j);
1979 gsl_matrix_set(X, i, j, Bj);
1984 gsl_multifit_wlinear(X, w, y, c, cov, &chisq, mw);
1987 Rsq = 1.0 - chisq / gsl_stats_wtss(w->data, 1, y->data, 1, y->size);
1989 fprintf(stderr, "chisq/dof = %e, Rsq = %f\n", chisq / dof, Rsq);
1991 /* output the smoothed curve */
1993 double xi, yi, yerr;
1995 printf("#m=1,S=0\n");
1996 for (xi = 0.0; xi < 15.0; xi += 0.1)
1998 gsl_bspline_eval(xi, B, bw);
1999 gsl_multifit_linear_est(B, c, cov, &yi, &yerr);
2000 printf("%f %f\n", xi, yi);
2005 gsl_bspline_free(bw);
2012 gsl_matrix_free(cov);
2013 gsl_multifit_linear_free(mw);
2018 The output can be plotted with GNU `graph'.
2020 $ ./a.out > bspline.dat
2021 chisq/dof = 1.118217e+00, Rsq = 0.989771
2022 $ graph -T ps -X x -Y y -x 0 15 -y -1 1.3 < bspline.dat > bspline.ps
2025 File: gsl-ref.info, Node: References and Further Reading, Prev: Example programs for B-splines, Up: Basis Splines
2027 38.6 References and Further Reading
2028 ===================================
2030 Further information on the algorithms described in this section can be
2031 found in the following book,
2033 C. de Boor, `A Practical Guide to Splines' (1978), Springer-Verlag,
2036 A large collection of B-spline routines is available in the PPPACK
2037 library available at `http://www.netlib.org/pppack'.
2040 File: gsl-ref.info, Node: Physical Constants, Next: IEEE floating-point arithmetic, Prev: Basis Splines, Up: Top
2042 39 Physical Constants
2043 *********************
2045 This chapter describes macros for the values of physical constants, such
2046 as the speed of light, c, and gravitational constant, G. The values
2047 are available in different unit systems, including the standard MKSA
2048 system (meters, kilograms, seconds, amperes) and the CGSM system
2049 (centimeters, grams, seconds, gauss), which is commonly used in
2052 The definitions of constants in the MKSA system are available in the
2053 file `gsl_const_mksa.h'. The constants in the CGSM system are defined
2054 in `gsl_const_cgsm.h'. Dimensionless constants, such as the fine
2055 structure constant, which are pure numbers are defined in
2060 * Fundamental Constants::
2061 * Astronomy and Astrophysics::
2062 * Atomic and Nuclear Physics::
2063 * Measurement of Time::
2065 * Speed and Nautical Units::
2067 * Volume Area and Length::
2068 * Mass and Weight ::
2069 * Thermal Energy and Power::
2072 * Light and Illumination::
2074 * Force and Energy::
2076 * Physical Constant Examples::
2077 * Physical Constant References and Further Reading::
2079 The full list of constants is described briefly below. Consult the
2080 header files themselves for the values of the constants used in the
2084 File: gsl-ref.info, Node: Fundamental Constants, Next: Astronomy and Astrophysics, Up: Physical Constants
2086 39.1 Fundamental Constants
2087 ==========================
2089 `GSL_CONST_MKSA_SPEED_OF_LIGHT'
2090 The speed of light in vacuum, c.
2092 `GSL_CONST_MKSA_VACUUM_PERMEABILITY'
2093 The permeability of free space, \mu_0. This constant is defined in
2094 the MKSA system only.
2096 `GSL_CONST_MKSA_VACUUM_PERMITTIVITY'
2097 The permittivity of free space, \epsilon_0. This constant is
2098 defined in the MKSA system only.
2100 `GSL_CONST_MKSA_PLANCKS_CONSTANT_H'
2101 Planck's constant, h.
2103 `GSL_CONST_MKSA_PLANCKS_CONSTANT_HBAR'
2104 Planck's constant divided by 2\pi, \hbar.
2106 `GSL_CONST_NUM_AVOGADRO'
2107 Avogadro's number, N_a.
2109 `GSL_CONST_MKSA_FARADAY'
2110 The molar charge of 1 Faraday.
2112 `GSL_CONST_MKSA_BOLTZMANN'
2113 The Boltzmann constant, k.
2115 `GSL_CONST_MKSA_MOLAR_GAS'
2116 The molar gas constant, R_0.
2118 `GSL_CONST_MKSA_STANDARD_GAS_VOLUME'
2119 The standard gas volume, V_0.
2121 `GSL_CONST_MKSA_STEFAN_BOLTZMANN_CONSTANT'
2122 The Stefan-Boltzmann radiation constant, \sigma.
2124 `GSL_CONST_MKSA_GAUSS'
2125 The magnetic field of 1 Gauss.
2128 File: gsl-ref.info, Node: Astronomy and Astrophysics, Next: Atomic and Nuclear Physics, Prev: Fundamental Constants, Up: Physical Constants
2130 39.2 Astronomy and Astrophysics
2131 ===============================
2133 `GSL_CONST_MKSA_ASTRONOMICAL_UNIT'
2134 The length of 1 astronomical unit (mean earth-sun distance), au.
2136 `GSL_CONST_MKSA_GRAVITATIONAL_CONSTANT'
2137 The gravitational constant, G.
2139 `GSL_CONST_MKSA_LIGHT_YEAR'
2140 The distance of 1 light-year, ly.
2142 `GSL_CONST_MKSA_PARSEC'
2143 The distance of 1 parsec, pc.
2145 `GSL_CONST_MKSA_GRAV_ACCEL'
2146 The standard gravitational acceleration on Earth, g.
2148 `GSL_CONST_MKSA_SOLAR_MASS'
2149 The mass of the Sun.
2152 File: gsl-ref.info, Node: Atomic and Nuclear Physics, Next: Measurement of Time, Prev: Astronomy and Astrophysics, Up: Physical Constants
2154 39.3 Atomic and Nuclear Physics
2155 ===============================
2157 `GSL_CONST_MKSA_ELECTRON_CHARGE'
2158 The charge of the electron, e.
2160 `GSL_CONST_MKSA_ELECTRON_VOLT'
2161 The energy of 1 electron volt, eV.
2163 `GSL_CONST_MKSA_UNIFIED_ATOMIC_MASS'
2164 The unified atomic mass, amu.
2166 `GSL_CONST_MKSA_MASS_ELECTRON'
2167 The mass of the electron, m_e.
2169 `GSL_CONST_MKSA_MASS_MUON'
2170 The mass of the muon, m_\mu.
2172 `GSL_CONST_MKSA_MASS_PROTON'
2173 The mass of the proton, m_p.
2175 `GSL_CONST_MKSA_MASS_NEUTRON'
2176 The mass of the neutron, m_n.
2178 `GSL_CONST_NUM_FINE_STRUCTURE'
2179 The electromagnetic fine structure constant \alpha.
2181 `GSL_CONST_MKSA_RYDBERG'
2182 The Rydberg constant, Ry, in units of energy. This is related to
2183 the Rydberg inverse wavelength R by Ry = h c R.
2185 `GSL_CONST_MKSA_BOHR_RADIUS'
2186 The Bohr radius, a_0.
2188 `GSL_CONST_MKSA_ANGSTROM'
2189 The length of 1 angstrom.
2191 `GSL_CONST_MKSA_BARN'
2194 `GSL_CONST_MKSA_BOHR_MAGNETON'
2195 The Bohr Magneton, \mu_B.
2197 `GSL_CONST_MKSA_NUCLEAR_MAGNETON'
2198 The Nuclear Magneton, \mu_N.
2200 `GSL_CONST_MKSA_ELECTRON_MAGNETIC_MOMENT'
2201 The absolute value of the magnetic moment of the electron, \mu_e.
2202 The physical magnetic moment of the electron is negative.
2204 `GSL_CONST_MKSA_PROTON_MAGNETIC_MOMENT'
2205 The magnetic moment of the proton, \mu_p.
2207 `GSL_CONST_MKSA_THOMSON_CROSS_SECTION'
2208 The Thomson cross section, \sigma_T.
2210 `GSL_CONST_MKSA_DEBYE'
2211 The electric dipole moment of 1 Debye, D.
2214 File: gsl-ref.info, Node: Measurement of Time, Next: Imperial Units, Prev: Atomic and Nuclear Physics, Up: Physical Constants
2216 39.4 Measurement of Time
2217 ========================
2219 `GSL_CONST_MKSA_MINUTE'
2220 The number of seconds in 1 minute.
2222 `GSL_CONST_MKSA_HOUR'
2223 The number of seconds in 1 hour.
2225 `GSL_CONST_MKSA_DAY'
2226 The number of seconds in 1 day.
2228 `GSL_CONST_MKSA_WEEK'
2229 The number of seconds in 1 week.
2232 File: gsl-ref.info, Node: Imperial Units, Next: Speed and Nautical Units, Prev: Measurement of Time, Up: Physical Constants
2237 `GSL_CONST_MKSA_INCH'
2238 The length of 1 inch.
2240 `GSL_CONST_MKSA_FOOT'
2241 The length of 1 foot.
2243 `GSL_CONST_MKSA_YARD'
2244 The length of 1 yard.
2246 `GSL_CONST_MKSA_MILE'
2247 The length of 1 mile.
2249 `GSL_CONST_MKSA_MIL'
2250 The length of 1 mil (1/1000th of an inch).
2253 File: gsl-ref.info, Node: Speed and Nautical Units, Next: Printers Units, Prev: Imperial Units, Up: Physical Constants
2255 39.6 Speed and Nautical Units
2256 =============================
2258 `GSL_CONST_MKSA_KILOMETERS_PER_HOUR'
2259 The speed of 1 kilometer per hour.
2261 `GSL_CONST_MKSA_MILES_PER_HOUR'
2262 The speed of 1 mile per hour.
2264 `GSL_CONST_MKSA_NAUTICAL_MILE'
2265 The length of 1 nautical mile.
2267 `GSL_CONST_MKSA_FATHOM'
2268 The length of 1 fathom.
2270 `GSL_CONST_MKSA_KNOT'
2271 The speed of 1 knot.
2274 File: gsl-ref.info, Node: Printers Units, Next: Volume Area and Length, Prev: Speed and Nautical Units, Up: Physical Constants
2279 `GSL_CONST_MKSA_POINT'
2280 The length of 1 printer's point (1/72 inch).
2282 `GSL_CONST_MKSA_TEXPOINT'
2283 The length of 1 TeX point (1/72.27 inch).
2286 File: gsl-ref.info, Node: Volume Area and Length, Next: Mass and Weight, Prev: Printers Units, Up: Physical Constants
2288 39.8 Volume, Area and Length
2289 ============================
2291 `GSL_CONST_MKSA_MICRON'
2292 The length of 1 micron.
2294 `GSL_CONST_MKSA_HECTARE'
2295 The area of 1 hectare.
2297 `GSL_CONST_MKSA_ACRE'
2300 `GSL_CONST_MKSA_LITER'
2301 The volume of 1 liter.
2303 `GSL_CONST_MKSA_US_GALLON'
2304 The volume of 1 US gallon.
2306 `GSL_CONST_MKSA_CANADIAN_GALLON'
2307 The volume of 1 Canadian gallon.
2309 `GSL_CONST_MKSA_UK_GALLON'
2310 The volume of 1 UK gallon.
2312 `GSL_CONST_MKSA_QUART'
2313 The volume of 1 quart.
2315 `GSL_CONST_MKSA_PINT'
2316 The volume of 1 pint.
2319 File: gsl-ref.info, Node: Mass and Weight, Next: Thermal Energy and Power, Prev: Volume Area and Length, Up: Physical Constants
2321 39.9 Mass and Weight
2322 ====================
2324 `GSL_CONST_MKSA_POUND_MASS'
2325 The mass of 1 pound.
2327 `GSL_CONST_MKSA_OUNCE_MASS'
2328 The mass of 1 ounce.
2330 `GSL_CONST_MKSA_TON'
2333 `GSL_CONST_MKSA_METRIC_TON'
2334 The mass of 1 metric ton (1000 kg).
2336 `GSL_CONST_MKSA_UK_TON'
2337 The mass of 1 UK ton.
2339 `GSL_CONST_MKSA_TROY_OUNCE'
2340 The mass of 1 troy ounce.
2342 `GSL_CONST_MKSA_CARAT'
2343 The mass of 1 carat.
2345 `GSL_CONST_MKSA_GRAM_FORCE'
2346 The force of 1 gram weight.
2348 `GSL_CONST_MKSA_POUND_FORCE'
2349 The force of 1 pound weight.
2351 `GSL_CONST_MKSA_KILOPOUND_FORCE'
2352 The force of 1 kilopound weight.
2354 `GSL_CONST_MKSA_POUNDAL'
2355 The force of 1 poundal.
2358 File: gsl-ref.info, Node: Thermal Energy and Power, Next: Pressure, Prev: Mass and Weight, Up: Physical Constants
2360 39.10 Thermal Energy and Power
2361 ==============================
2363 `GSL_CONST_MKSA_CALORIE'
2364 The energy of 1 calorie.
2366 `GSL_CONST_MKSA_BTU'
2367 The energy of 1 British Thermal Unit, btu.
2369 `GSL_CONST_MKSA_THERM'
2370 The energy of 1 Therm.
2372 `GSL_CONST_MKSA_HORSEPOWER'
2373 The power of 1 horsepower.
2376 File: gsl-ref.info, Node: Pressure, Next: Viscosity, Prev: Thermal Energy and Power, Up: Physical Constants
2381 `GSL_CONST_MKSA_BAR'
2382 The pressure of 1 bar.
2384 `GSL_CONST_MKSA_STD_ATMOSPHERE'
2385 The pressure of 1 standard atmosphere.
2387 `GSL_CONST_MKSA_TORR'
2388 The pressure of 1 torr.
2390 `GSL_CONST_MKSA_METER_OF_MERCURY'
2391 The pressure of 1 meter of mercury.
2393 `GSL_CONST_MKSA_INCH_OF_MERCURY'
2394 The pressure of 1 inch of mercury.
2396 `GSL_CONST_MKSA_INCH_OF_WATER'
2397 The pressure of 1 inch of water.
2399 `GSL_CONST_MKSA_PSI'
2400 The pressure of 1 pound per square inch.
2403 File: gsl-ref.info, Node: Viscosity, Next: Light and Illumination, Prev: Pressure, Up: Physical Constants
2408 `GSL_CONST_MKSA_POISE'
2409 The dynamic viscosity of 1 poise.
2411 `GSL_CONST_MKSA_STOKES'
2412 The kinematic viscosity of 1 stokes.
2415 File: gsl-ref.info, Node: Light and Illumination, Next: Radioactivity, Prev: Viscosity, Up: Physical Constants
2417 39.13 Light and Illumination
2418 ============================
2420 `GSL_CONST_MKSA_STILB'
2421 The luminance of 1 stilb.
2423 `GSL_CONST_MKSA_LUMEN'
2424 The luminous flux of 1 lumen.
2426 `GSL_CONST_MKSA_LUX'
2427 The illuminance of 1 lux.
2429 `GSL_CONST_MKSA_PHOT'
2430 The illuminance of 1 phot.
2432 `GSL_CONST_MKSA_FOOTCANDLE'
2433 The illuminance of 1 footcandle.
2435 `GSL_CONST_MKSA_LAMBERT'
2436 The luminance of 1 lambert.
2438 `GSL_CONST_MKSA_FOOTLAMBERT'
2439 The luminance of 1 footlambert.
2442 File: gsl-ref.info, Node: Radioactivity, Next: Force and Energy, Prev: Light and Illumination, Up: Physical Constants
2447 `GSL_CONST_MKSA_CURIE'
2448 The activity of 1 curie.
2450 `GSL_CONST_MKSA_ROENTGEN'
2451 The exposure of 1 roentgen.
2453 `GSL_CONST_MKSA_RAD'
2454 The absorbed dose of 1 rad.
2457 File: gsl-ref.info, Node: Force and Energy, Next: Prefixes, Prev: Radioactivity, Up: Physical Constants
2459 39.15 Force and Energy
2460 ======================
2462 `GSL_CONST_MKSA_NEWTON'
2463 The SI unit of force, 1 Newton.
2465 `GSL_CONST_MKSA_DYNE'
2466 The force of 1 Dyne = 10^-5 Newton.
2468 `GSL_CONST_MKSA_JOULE'
2469 The SI unit of energy, 1 Joule.
2471 `GSL_CONST_MKSA_ERG'
2472 The energy 1 erg = 10^-7 Joule.
2475 File: gsl-ref.info, Node: Prefixes, Next: Physical Constant Examples, Prev: Force and Energy, Up: Physical Constants
2480 These constants are dimensionless scaling factors.
2482 `GSL_CONST_NUM_YOTTA'
2485 `GSL_CONST_NUM_ZETTA'
2491 `GSL_CONST_NUM_PETA'
2494 `GSL_CONST_NUM_TERA'
2497 `GSL_CONST_NUM_GIGA'
2500 `GSL_CONST_NUM_MEGA'
2503 `GSL_CONST_NUM_KILO'
2506 `GSL_CONST_NUM_MILLI'
2509 `GSL_CONST_NUM_MICRO'
2512 `GSL_CONST_NUM_NANO'
2515 `GSL_CONST_NUM_PICO'
2518 `GSL_CONST_NUM_FEMTO'
2521 `GSL_CONST_NUM_ATTO'
2524 `GSL_CONST_NUM_ZEPTO'
2527 `GSL_CONST_NUM_YOCTO'
2531 File: gsl-ref.info, Node: Physical Constant Examples, Next: Physical Constant References and Further Reading, Prev: Prefixes, Up: Physical Constants
2536 The following program demonstrates the use of the physical constants in
2537 a calculation. In this case, the goal is to calculate the range of
2538 light-travel times from Earth to Mars.
2540 The required data is the average distance of each planet from the
2541 Sun in astronomical units (the eccentricities and inclinations of the
2542 orbits will be neglected for the purposes of this calculation). The
2543 average radius of the orbit of Mars is 1.52 astronomical units, and for
2544 the orbit of Earth it is 1 astronomical unit (by definition). These
2545 values are combined with the MKSA values of the constants for the speed
2546 of light and the length of an astronomical unit to produce a result for
2547 the shortest and longest light-travel times in seconds. The figures are
2548 converted into minutes before being displayed.
2551 #include <gsl/gsl_const_mksa.h>
2556 double c = GSL_CONST_MKSA_SPEED_OF_LIGHT;
2557 double au = GSL_CONST_MKSA_ASTRONOMICAL_UNIT;
2558 double minutes = GSL_CONST_MKSA_MINUTE;
2560 /* distance stored in meters */
2561 double r_earth = 1.00 * au;
2562 double r_mars = 1.52 * au;
2564 double t_min, t_max;
2566 t_min = (r_mars - r_earth) / c;
2567 t_max = (r_mars + r_earth) / c;
2569 printf ("light travel time from Earth to Mars:\n");
2570 printf ("minimum = %.1f minutes\n", t_min / minutes);
2571 printf ("maximum = %.1f minutes\n", t_max / minutes);
2576 Here is the output from the program,
2578 light travel time from Earth to Mars:
2579 minimum = 4.3 minutes
2580 maximum = 21.0 minutes
2583 File: gsl-ref.info, Node: Physical Constant References and Further Reading, Prev: Physical Constant Examples, Up: Physical Constants
2585 39.18 References and Further Reading
2586 ====================================
2588 The authoritative sources for physical constants are the 2002 CODATA
2589 recommended values, published in the articles below. Further information
2590 on the values of physical constants is also available from the cited
2591 articles and the NIST website.
2593 Journal of Physical and Chemical Reference Data, 28(6), 1713-1852,
2596 Reviews of Modern Physics, 72(2), 351-495, 2000
2598 `http://www.physics.nist.gov/cuu/Constants/index.html'
2600 `http://physics.nist.gov/Pubs/SP811/appenB9.html'
2603 File: gsl-ref.info, Node: IEEE floating-point arithmetic, Next: Debugging Numerical Programs, Prev: Physical Constants, Up: Top
2605 40 IEEE floating-point arithmetic
2606 *********************************
2608 This chapter describes functions for examining the representation of
2609 floating point numbers and controlling the floating point environment of
2610 your program. The functions described in this chapter are declared in
2611 the header file `gsl_ieee_utils.h'.
2615 * Representation of floating point numbers::
2616 * Setting up your IEEE environment::
2617 * IEEE References and Further Reading::
2620 File: gsl-ref.info, Node: Representation of floating point numbers, Next: Setting up your IEEE environment, Up: IEEE floating-point arithmetic
2622 40.1 Representation of floating point numbers
2623 =============================================
2625 The IEEE Standard for Binary Floating-Point Arithmetic defines binary
2626 formats for single and double precision numbers. Each number is
2627 composed of three parts: a "sign bit" (s), an "exponent" (E) and a
2628 "fraction" (f). The numerical value of the combination (s,E,f) is
2629 given by the following formula,
2631 (-1)^s (1.fffff...) 2^E
2633 The sign bit is either zero or one. The exponent ranges from a minimum
2634 value E_min to a maximum value E_max depending on the precision. The
2635 exponent is converted to an unsigned number e, known as the "biased
2636 exponent", for storage by adding a "bias" parameter, e = E + bias. The
2637 sequence fffff... represents the digits of the binary fraction f. The
2638 binary digits are stored in "normalized form", by adjusting the
2639 exponent to give a leading digit of 1. Since the leading digit is
2640 always 1 for normalized numbers it is assumed implicitly and does not
2641 have to be stored. Numbers smaller than 2^(E_min) are be stored in
2642 "denormalized form" with a leading zero,
2644 (-1)^s (0.fffff...) 2^(E_min)
2646 This allows gradual underflow down to 2^(E_min - p) for p bits of
2647 precision. A zero is encoded with the special exponent of 2^(E_min -
2648 1) and infinities with the exponent of 2^(E_max + 1).
2650 The format for single precision numbers uses 32 bits divided in the
2653 seeeeeeeefffffffffffffffffffffff
2656 e = exponent, 8 bits (E_min=-126, E_max=127, bias=127)
2657 f = fraction, 23 bits
2659 The format for double precision numbers uses 64 bits divided in the
2662 seeeeeeeeeeeffffffffffffffffffffffffffffffffffffffffffffffffffff
2665 e = exponent, 11 bits (E_min=-1022, E_max=1023, bias=1023)
2666 f = fraction, 52 bits
2668 It is often useful to be able to investigate the behavior of a
2669 calculation at the bit-level and the library provides functions for
2670 printing the IEEE representations in a human-readable form.
2672 -- Function: void gsl_ieee_fprintf_float (FILE * STREAM, const float *
2674 -- Function: void gsl_ieee_fprintf_double (FILE * STREAM, const double
2676 These functions output a formatted version of the IEEE
2677 floating-point number pointed to by X to the stream STREAM. A
2678 pointer is used to pass the number indirectly, to avoid any
2679 undesired promotion from `float' to `double'. The output takes
2680 one of the following forms,
2683 the Not-a-Number symbol
2686 positive or negative infinity
2688 `1.fffff...*2^E, -1.fffff...*2^E'
2689 a normalized floating point number
2691 `0.fffff...*2^E, -0.fffff...*2^E'
2692 a denormalized floating point number
2695 positive or negative zero
2698 The output can be used directly in GNU Emacs Calc mode by
2699 preceding it with `2#' to indicate binary.
2701 -- Function: void gsl_ieee_printf_float (const float * X)
2702 -- Function: void gsl_ieee_printf_double (const double * X)
2703 These functions output a formatted version of the IEEE
2704 floating-point number pointed to by X to the stream `stdout'.
2706 The following program demonstrates the use of the functions by printing
2707 the single and double precision representations of the fraction 1/3.
2708 For comparison the representation of the value promoted from single to
2709 double precision is also printed.
2712 #include <gsl/gsl_ieee_utils.h>
2720 double fd = f; /* promote from float to double */
2722 printf (" f="); gsl_ieee_printf_float(&f);
2725 printf ("fd="); gsl_ieee_printf_double(&fd);
2728 printf (" d="); gsl_ieee_printf_double(&d);
2734 The binary representation of 1/3 is 0.01010101... . The output below
2735 shows that the IEEE format normalizes this fraction to give a leading
2738 f= 1.01010101010101010101011*2^-2
2739 fd= 1.0101010101010101010101100000000000000000000000000000*2^-2
2740 d= 1.0101010101010101010101010101010101010101010101010101*2^-2
2742 The output also shows that a single-precision number is promoted to
2743 double-precision by adding zeros in the binary representation.
2746 File: gsl-ref.info, Node: Setting up your IEEE environment, Next: IEEE References and Further Reading, Prev: Representation of floating point numbers, Up: IEEE floating-point arithmetic
2748 40.2 Setting up your IEEE environment
2749 =====================================
2751 The IEEE standard defines several "modes" for controlling the behavior
2752 of floating point operations. These modes specify the important
2753 properties of computer arithmetic: the direction used for rounding (e.g.
2754 whether numbers should be rounded up, down or to the nearest number),
2755 the rounding precision and how the program should handle arithmetic
2756 exceptions, such as division by zero.
2758 Many of these features can now be controlled via standard functions
2759 such as `fpsetround', which should be used whenever they are available.
2760 Unfortunately in the past there has been no universal API for
2761 controlling their behavior--each system has had its own low-level way
2762 of accessing them. To help you write portable programs GSL allows you
2763 to specify modes in a platform-independent way using the environment
2764 variable `GSL_IEEE_MODE'. The library then takes care of all the
2765 necessary machine-specific initializations for you when you call the
2766 function `gsl_ieee_env_setup'.
2768 -- Function: void gsl_ieee_env_setup ()
2769 This function reads the environment variable `GSL_IEEE_MODE' and
2770 attempts to set up the corresponding specified IEEE modes. The
2771 environment variable should be a list of keywords, separated by
2774 `GSL_IEEE_MODE' = "KEYWORD,KEYWORD,..."
2776 where KEYWORD is one of the following mode-names,
2782 `extended-precision'
2798 `mask-division-by-zero'
2808 If `GSL_IEEE_MODE' is empty or undefined then the function returns
2809 immediately and no attempt is made to change the system's IEEE
2810 mode. When the modes from `GSL_IEEE_MODE' are turned on the
2811 function prints a short message showing the new settings to remind
2812 you that the results of the program will be affected.
2814 If the requested modes are not supported by the platform being
2815 used then the function calls the error handler and returns an
2816 error code of `GSL_EUNSUP'.
2818 When options are specified using this method, the resulting mode is
2819 based on a default setting of the highest available precision
2820 (double precision or extended precision, depending on the
2821 platform) in round-to-nearest mode, with all exceptions enabled
2822 apart from the INEXACT exception. The INEXACT exception is
2823 generated whenever rounding occurs, so it must generally be
2824 disabled in typical scientific calculations. All other
2825 floating-point exceptions are enabled by default, including
2826 underflows and the use of denormalized numbers, for safety. They
2827 can be disabled with the individual `mask-' settings or together
2830 The following adjusted combination of modes is convenient for many
2833 GSL_IEEE_MODE="double-precision,"\
2837 This choice ignores any errors relating to small numbers (either
2838 denormalized, or underflowing to zero) but traps overflows,
2839 division by zero and invalid operations.
2841 Note that on the x86 series of processors this function sets both
2842 the original x87 mode and the newer MXCSR mode, which controls SSE
2843 floating-point operations. The SSE floating-point units do not
2844 have a precision-control bit, and always work in double-precision.
2845 The single-precision and extended-precision keywords have no
2846 effect in this case.
2848 To demonstrate the effects of different rounding modes consider the
2849 following program which computes e, the base of natural logarithms, by
2850 summing a rapidly-decreasing series,
2852 e = 1 + 1/2! + 1/3! + 1/4! + ...
2856 #include <gsl/gsl_math.h>
2857 #include <gsl/gsl_ieee_utils.h>
2862 double x = 1, oldsum = 0, sum = 0;
2865 gsl_ieee_env_setup (); /* read GSL_IEEE_MODE */
2875 printf ("i=%2d sum=%.18f error=%g\n",
2881 while (sum != oldsum);
2886 Here are the results of running the program in `round-to-nearest' mode.
2887 This is the IEEE default so it isn't really necessary to specify it
2890 $ GSL_IEEE_MODE="round-to-nearest" ./a.out
2891 i= 1 sum=1.000000000000000000 error=-1.71828
2892 i= 2 sum=2.000000000000000000 error=-0.718282
2894 i=18 sum=2.718281828459045535 error=4.44089e-16
2895 i=19 sum=2.718281828459045535 error=4.44089e-16
2897 After nineteen terms the sum converges to within 4 \times 10^-16 of the
2898 correct value. If we now change the rounding mode to `round-down' the
2899 final result is less accurate,
2901 $ GSL_IEEE_MODE="round-down" ./a.out
2902 i= 1 sum=1.000000000000000000 error=-1.71828
2904 i=19 sum=2.718281828459041094 error=-3.9968e-15
2906 The result is about 4 \times 10^-15 below the correct value, an order
2907 of magnitude worse than the result obtained in the `round-to-nearest'
2910 If we change to rounding mode to `round-up' then the final result is
2911 higher than the correct value (when we add each term to the sum the
2912 final result is always rounded up, which increases the sum by at least
2913 one tick until the added term underflows to zero). To avoid this
2914 problem we would need to use a safer converge criterion, such as `while
2915 (fabs(sum - oldsum) > epsilon)', with a suitably chosen value of
2918 Finally we can see the effect of computing the sum using
2919 single-precision rounding, in the default `round-to-nearest' mode. In
2920 this case the program thinks it is still using double precision numbers
2921 but the CPU rounds the result of each floating point operation to
2922 single-precision accuracy. This simulates the effect of writing the
2923 program using single-precision `float' variables instead of `double'
2924 variables. The iteration stops after about half the number of
2925 iterations and the final result is much less accurate,
2927 $ GSL_IEEE_MODE="single-precision" ./a.out
2929 i=12 sum=2.718281984329223633 error=1.5587e-07
2931 with an error of O(10^-7), which corresponds to single precision
2932 accuracy (about 1 part in 10^7). Continuing the iterations further
2933 does not decrease the error because all the subsequent results are
2934 rounded to the same value.
2937 File: gsl-ref.info, Node: IEEE References and Further Reading, Prev: Setting up your IEEE environment, Up: IEEE floating-point arithmetic
2939 40.3 References and Further Reading
2940 ===================================
2942 The reference for the IEEE standard is,
2944 ANSI/IEEE Std 754-1985, IEEE Standard for Binary Floating-Point
2947 A more pedagogical introduction to the standard can be found in the
2950 David Goldberg: What Every Computer Scientist Should Know About
2951 Floating-Point Arithmetic. `ACM Computing Surveys', Vol. 23, No. 1
2952 (March 1991), pages 5-48.
2954 Corrigendum: `ACM Computing Surveys', Vol. 23, No. 3 (September
2955 1991), page 413. and see also the sections by B. A. Wichmann and
2956 Charles B. Dunham in Surveyor's Forum: "What Every Computer
2957 Scientist Should Know About Floating-Point Arithmetic". `ACM
2958 Computing Surveys', Vol. 24, No. 3 (September 1992), page 319.
2960 A detailed textbook on IEEE arithmetic and its practical use is
2961 available from SIAM Press,
2963 Michael L. Overton, `Numerical Computing with IEEE Floating Point
2964 Arithmetic', SIAM Press, ISBN 0898715717.
2968 File: gsl-ref.info, Node: Debugging Numerical Programs, Next: Contributors to GSL, Prev: IEEE floating-point arithmetic, Up: Top
2970 Appendix A Debugging Numerical Programs
2971 ***************************************
2973 This chapter describes some tips and tricks for debugging numerical
2974 programs which use GSL.
2979 * Examining floating point registers::
2980 * Handling floating point exceptions::
2981 * GCC warning options for numerical programs::
2982 * Debugging References::
2985 File: gsl-ref.info, Node: Using gdb, Next: Examining floating point registers, Up: Debugging Numerical Programs
2990 Any errors reported by the library are passed to the function
2991 `gsl_error'. By running your programs under gdb and setting a
2992 breakpoint in this function you can automatically catch any library
2993 errors. You can add a breakpoint for every session by putting
2997 into your `.gdbinit' file in the directory where your program is
3000 If the breakpoint catches an error then you can use a backtrace
3001 (`bt') to see the call-tree, and the arguments which possibly caused
3002 the error. By moving up into the calling function you can investigate
3003 the values of variables at that point. Here is an example from the
3004 program `fft/test_trap', which contains the following line,
3006 status = gsl_fft_complex_wavetable_alloc (0, &complex_wavetable);
3008 The function `gsl_fft_complex_wavetable_alloc' takes the length of an
3009 FFT as its first argument. When this line is executed an error will be
3010 generated because the length of an FFT is not allowed to be zero.
3012 To debug this problem we start `gdb', using the file `.gdbinit' to
3013 define a breakpoint in `gsl_error',
3017 GDB is free software and you are welcome to distribute copies
3018 of it under certain conditions; type "show copying" to see
3019 the conditions. There is absolutely no warranty for GDB;
3020 type "show warranty" for details. GDB 4.16 (i586-debian-linux),
3021 Copyright 1996 Free Software Foundation, Inc.
3023 Breakpoint 1 at 0x8050b1e: file error.c, line 14.
3025 When we run the program this breakpoint catches the error and shows the
3029 Starting program: test_trap
3031 Breakpoint 1, gsl_error (reason=0x8052b0d
3032 "length n must be positive integer",
3033 file=0x8052b04 "c_init.c", line=108, gsl_errno=1)
3035 14 if (gsl_error_handler)
3037 The first argument of `gsl_error' is always a string describing the
3038 error. Now we can look at the backtrace to see what caused the problem,
3041 #0 gsl_error (reason=0x8052b0d
3042 "length n must be positive integer",
3043 file=0x8052b04 "c_init.c", line=108, gsl_errno=1)
3045 #1 0x8049376 in gsl_fft_complex_wavetable_alloc (n=0,
3046 wavetable=0xbffff778) at c_init.c:108
3047 #2 0x8048a00 in main (argc=1, argv=0xbffff9bc)
3049 #3 0x80488be in ___crt_dummy__ ()
3051 We can see that the error was generated in the function
3052 `gsl_fft_complex_wavetable_alloc' when it was called with an argument
3053 of N=0. The original call came from line 94 in the file `test_trap.c'.
3055 By moving up to the level of the original call we can find the line
3056 that caused the error,
3059 #1 0x8049376 in gsl_fft_complex_wavetable_alloc (n=0,
3060 wavetable=0xbffff778) at c_init.c:108
3061 108 GSL_ERROR ("length n must be positive integer", GSL_EDOM);
3063 #2 0x8048a00 in main (argc=1, argv=0xbffff9bc)
3065 94 status = gsl_fft_complex_wavetable_alloc (0,
3066 &complex_wavetable);
3068 Thus we have found the line that caused the problem. From this point we
3069 could also print out the values of other variables such as
3070 `complex_wavetable'.
3073 File: gsl-ref.info, Node: Examining floating point registers, Next: Handling floating point exceptions, Prev: Using gdb, Up: Debugging Numerical Programs
3075 A.2 Examining floating point registers
3076 ======================================
3078 The contents of floating point registers can be examined using the
3079 command `info float' (on supported platforms).
3082 st0: 0xc4018b895aa17a945000 Valid Normal -7.838871e+308
3083 st1: 0x3ff9ea3f50e4d7275000 Valid Normal 0.0285946
3084 st2: 0x3fe790c64ce27dad4800 Valid Normal 6.7415931e-08
3085 st3: 0x3ffaa3ef0df6607d7800 Spec Normal 0.0400229
3086 st4: 0x3c028000000000000000 Valid Normal 4.4501477e-308
3087 st5: 0x3ffef5412c22219d9000 Zero Normal 0.9580257
3088 st6: 0x3fff8000000000000000 Valid Normal 1
3089 st7: 0xc4028b65a1f6d243c800 Valid Normal -1.566206e+309
3090 fctrl: 0x0272 53 bit; NEAR; mask DENOR UNDER LOS;
3091 fstat: 0xb9ba flags 0001; top 7; excep DENOR OVERF UNDER LOS
3098 Individual registers can be examined using the variables $REG, where
3099 REG is the register name.
3102 $1 = 0.02859464454261210347719
3105 File: gsl-ref.info, Node: Handling floating point exceptions, Next: GCC warning options for numerical programs, Prev: Examining floating point registers, Up: Debugging Numerical Programs
3107 A.3 Handling floating point exceptions
3108 ======================================
3110 It is possible to stop the program whenever a `SIGFPE' floating point
3111 exception occurs. This can be useful for finding the cause of an
3112 unexpected infinity or `NaN'. The current handler settings can be
3113 shown with the command `info signal SIGFPE'.
3115 (gdb) info signal SIGFPE
3116 Signal Stop Print Pass to program Description
3117 SIGFPE Yes Yes Yes Arithmetic exception
3119 Unless the program uses a signal handler the default setting should be
3120 changed so that SIGFPE is not passed to the program, as this would cause
3121 it to exit. The command `handle SIGFPE stop nopass' prevents this.
3123 (gdb) handle SIGFPE stop nopass
3124 Signal Stop Print Pass to program Description
3125 SIGFPE Yes Yes No Arithmetic exception
3127 Depending on the platform it may be necessary to instruct the kernel to
3128 generate signals for floating point exceptions. For programs using GSL
3129 this can be achieved using the `GSL_IEEE_MODE' environment variable in
3130 conjunction with the function `gsl_ieee_env_setup' as described in
3131 *note IEEE floating-point arithmetic::.
3133 (gdb) set env GSL_IEEE_MODE=double-precision
3136 File: gsl-ref.info, Node: GCC warning options for numerical programs, Next: Debugging References, Prev: Handling floating point exceptions, Up: Debugging Numerical Programs
3138 A.4 GCC warning options for numerical programs
3139 ==============================================
3141 Writing reliable numerical programs in C requires great care. The
3142 following GCC warning options are recommended when compiling numerical
3145 gcc -ansi -pedantic -Werror -Wall -W
3146 -Wmissing-prototypes -Wstrict-prototypes
3147 -Wtraditional -Wconversion -Wshadow
3148 -Wpointer-arith -Wcast-qual -Wcast-align
3149 -Wwrite-strings -Wnested-externs
3150 -fshort-enums -fno-common -Dinline= -g -O2
3152 For details of each option consult the manual `Using and Porting GCC'.
3153 The following table gives a brief explanation of what types of errors
3154 these options catch.
3157 Use ANSI C, and reject any non-ANSI extensions. These flags help
3158 in writing portable programs that will compile on other systems.
3161 Consider warnings to be errors, so that compilation stops. This
3162 prevents warnings from scrolling off the top of the screen and
3163 being lost. You won't be able to compile the program until it is
3164 completely warning-free.
3167 This turns on a set of warnings for common programming problems.
3168 You need `-Wall', but it is not enough on its own.
3171 Turn on optimization. The warnings for uninitialized variables in
3172 `-Wall' rely on the optimizer to analyze the code. If there is no
3173 optimization then these warnings aren't generated.
3176 This turns on some extra warnings not included in `-Wall', such as
3177 missing return values and comparisons between signed and unsigned
3180 `-Wmissing-prototypes -Wstrict-prototypes'
3181 Warn if there are any missing or inconsistent prototypes. Without
3182 prototypes it is harder to detect problems with incorrect
3186 This warns about certain constructs that behave differently in
3187 traditional and ANSI C. Whether the traditional or ANSI
3188 interpretation is used might be unpredictable on other compilers.
3191 The main use of this option is to warn about conversions from
3192 signed to unsigned integers. For example, `unsigned int x = -1'.
3193 If you need to perform such a conversion you can use an explicit
3197 This warns whenever a local variable shadows another local
3198 variable. If two variables have the same name then it is a
3199 potential source of confusion.
3201 `-Wpointer-arith -Wcast-qual -Wcast-align'
3202 These options warn if you try to do pointer arithmetic for types
3203 which don't have a size, such as `void', if you remove a `const'
3204 cast from a pointer, or if you cast a pointer to a type which has a
3205 different size, causing an invalid alignment.
3208 This option gives string constants a `const' qualifier so that it
3209 will be a compile-time error to attempt to overwrite them.
3212 This option makes the type of `enum' as short as possible.
3213 Normally this makes an `enum' different from an `int'.
3214 Consequently any attempts to assign a pointer-to-int to a
3215 pointer-to-enum will generate a cast-alignment warning.
3218 This option prevents global variables being simultaneously defined
3219 in different object files (you get an error at link time). Such a
3220 variable should be defined in one file and referred to in other
3221 files with an `extern' declaration.
3224 This warns if an `extern' declaration is encountered within a
3228 The `inline' keyword is not part of ANSI C. Thus if you want to use
3229 `-ansi' with a program which uses inline functions you can use this
3230 preprocessor definition to remove the `inline' keywords.
3233 It always makes sense to put debugging symbols in the executable
3234 so that you can debug it using `gdb'. The only effect of
3235 debugging symbols is to increase the size of the file, and you can
3236 use the `strip' command to remove them later if necessary.
3239 File: gsl-ref.info, Node: Debugging References, Prev: GCC warning options for numerical programs, Up: Debugging Numerical Programs
3241 A.5 References and Further Reading
3242 ==================================
3244 The following books are essential reading for anyone writing and
3245 debugging numerical programs with GCC and GDB.
3247 R.M. Stallman, `Using and Porting GNU CC', Free Software
3248 Foundation, ISBN 1882114388
3250 R.M. Stallman, R.H. Pesch, `Debugging with GDB: The GNU
3251 Source-Level Debugger', Free Software Foundation, ISBN 1882114779
3253 For a tutorial introduction to the GNU C Compiler and related programs,
3256 B.J. Gough, `An Introduction to GCC', Network Theory Ltd, ISBN
3260 File: gsl-ref.info, Node: Contributors to GSL, Next: Autoconf Macros, Prev: Debugging Numerical Programs, Up: Top
3262 Appendix B Contributors to GSL
3263 ******************************
3265 (See the AUTHORS file in the distribution for up-to-date information.)
3268 Conceived GSL (with James Theiler) and wrote the design document.
3269 Wrote the simulated annealing package and the relevant chapter in
3273 Conceived GSL (with Mark Galassi). Wrote the random number
3274 generators and the relevant chapter in this manual.
3277 Wrote the statistical routines and the relevant chapter in this
3281 FFTs, numerical integration, random number generators and
3282 distributions, root finding, minimization and fitting, polynomial
3283 solvers, complex numbers, physical constants, permutations, vector
3284 and matrix functions, histograms, statistics, ieee-utils, revised
3285 CBLAS Level 2 & 3, matrix decompositions, eigensystems, cumulative
3286 distribution functions, testing, documentation and releases.
3289 Wrote and documented the initial version of the root finding
3290 routines while at Los Alamos National Laboratory, Mathematical
3291 Modeling and Analysis Group.
3294 Special Functions, Series acceleration, ODEs, BLAS, Linear Algebra,
3295 Eigensystems, Hankel Transforms.
3298 Wrote the Monte Carlo library.
3300 *Jorma Olavi Ta"htinen*
3301 Wrote the initial complex arithmetic functions.
3304 Wrote the initial heapsort routines and cholesky decomposition.
3307 Multidimensional minimization.
3310 Implementation of the random number generators in Knuth's
3311 `Seminumerical Algorithms', 3rd Ed.
3313 *Szymon Jaroszewicz*
3314 Wrote the routines for generating combinations.
3317 Wrote the cyclic functions and the initial functions for canonical
3321 Wrote the major cumulative distribution functions.
3324 Wrote the routines for wavelet transforms.
3327 Improved the implementation of the ODE solvers.
3330 Implementation of the Mathieu functions.
3333 Implementation of non-symmetric and generalized eigensystems and
3337 Thanks to Nigel Lowry for help in proofreading the manual.
3339 The non-symmetric eigensystems routines contain code based on the
3340 LAPACK linear algebra library. LAPACK is distributed under the
3344 Copyright (c) 1992-2006 The University of Tennessee. All rights
3347 Redistribution and use in source and binary forms, with or without
3348 modification, are permitted provided that the following conditions
3351 * Redistributions of source code must retain the above copyright
3352 notice, this list of conditions and the following disclaimer.
3354 * Redistributions in binary form must reproduce the above copyright
3355 notice, this list of conditions and the following disclaimer listed
3356 in this license in the documentation and/or other materials
3357 provided with the distribution.
3359 * Neither the name of the copyright holders nor the names of its
3360 contributors may be used to endorse or promote products derived
3361 from this software without specific prior written permission.
3363 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
3364 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
3365 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
3366 FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
3367 COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
3368 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
3369 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
3370 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
3371 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
3372 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
3373 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
3374 EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
3377 File: gsl-ref.info, Node: Autoconf Macros, Next: GSL CBLAS Library, Prev: Contributors to GSL, Up: Top
3379 Appendix C Autoconf Macros
3380 **************************
3382 For applications using `autoconf' the standard macro `AC_CHECK_LIB' can
3383 be used to link with GSL automatically from a `configure' script. The
3384 library itself depends on the presence of a CBLAS and math library as
3385 well, so these must also be located before linking with the main
3386 `libgsl' file. The following commands should be placed in the
3387 `configure.ac' file to perform these tests,
3389 AC_CHECK_LIB([m],[cos])
3390 AC_CHECK_LIB([gslcblas],[cblas_dgemm])
3391 AC_CHECK_LIB([gsl],[gsl_blas_dgemm])
3393 It is important to check for `libm' and `libgslcblas' before `libgsl',
3394 otherwise the tests will fail. Assuming the libraries are found the
3395 output during the configure stage looks like this,
3397 checking for cos in -lm... yes
3398 checking for cblas_dgemm in -lgslcblas... yes
3399 checking for gsl_blas_dgemm in -lgsl... yes
3401 If the library is found then the tests will define the macros
3402 `HAVE_LIBGSL', `HAVE_LIBGSLCBLAS', `HAVE_LIBM' and add the options
3403 `-lgsl -lgslcblas -lm' to the variable `LIBS'.
3405 The tests above will find any version of the library. They are
3406 suitable for general use, where the versions of the functions are not
3407 important. An alternative macro is available in the file `gsl.m4' to
3408 test for a specific version of the library. To use this macro simply
3409 add the following line to your `configure.in' file instead of the tests
3412 AX_PATH_GSL(GSL_VERSION,
3414 [action-if-not-found])
3416 The argument `GSL_VERSION' should be the two or three digit MAJOR.MINOR
3417 or MAJOR.MINOR.MICRO version number of the release you require. A
3418 suitable choice for `action-if-not-found' is,
3420 AC_MSG_ERROR(could not find required version of GSL)
3422 Then you can add the variables `GSL_LIBS' and `GSL_CFLAGS' to your
3423 Makefile.am files to obtain the correct compiler flags. `GSL_LIBS' is
3424 equal to the output of the `gsl-config --libs' command and `GSL_CFLAGS'
3425 is equal to `gsl-config --cflags' command. For example,
3427 libfoo_la_LDFLAGS = -lfoo $(GSL_LIBS) -lgslcblas
3429 Note that the macro `AX_PATH_GSL' needs to use the C compiler so it
3430 should appear in the `configure.in' file before the macro
3431 `AC_LANG_CPLUSPLUS' for programs that use C++.
3433 To test for `inline' the following test should be placed in your
3434 `configure.in' file,
3438 if test "$ac_cv_c_inline" != no ; then
3439 AC_DEFINE(HAVE_INLINE,1)
3440 AC_SUBST(HAVE_INLINE)
3443 and the macro will then be defined in the compilation flags or by
3444 including the file `config.h' before any library headers.
3446 The following autoconf test will check for `extern inline',
3448 dnl Check for "extern inline", using a modified version
3449 dnl of the test for AC_C_INLINE from acspecific.mt
3451 AC_CACHE_CHECK([for extern inline], ac_cv_c_extern_inline,
3452 [ac_cv_c_extern_inline=no
3453 AC_TRY_COMPILE([extern $ac_cv_c_inline double foo(double x);
3454 extern $ac_cv_c_inline double foo(double x) { return x+1.0; };
3455 double foo (double x) { return x + 1.0; };],
3457 [ac_cv_c_extern_inline="yes"])
3460 if test "$ac_cv_c_extern_inline" != no ; then
3461 AC_DEFINE(HAVE_INLINE,1)
3462 AC_SUBST(HAVE_INLINE)
3465 The substitution of portability functions can be made automatically
3466 if you use `autoconf'. For example, to test whether the BSD function
3467 `hypot' is available you can include the following line in the
3468 configure file `configure.in' for your application,
3470 AC_CHECK_FUNCS(hypot)
3472 and place the following macro definitions in the file `config.h.in',
3474 /* Substitute gsl_hypot for missing system hypot */
3477 #define hypot gsl_hypot
3480 The application source files can then use the include command `#include
3481 <config.h>' to substitute `gsl_hypot' for each occurrence of `hypot'
3482 when `hypot' is not available.
3485 File: gsl-ref.info, Node: GSL CBLAS Library, Next: Free Software Needs Free Documentation, Prev: Autoconf Macros, Up: Top
3487 Appendix D GSL CBLAS Library
3488 ****************************
3490 The prototypes for the low-level CBLAS functions are declared in the
3491 file `gsl_cblas.h'. For the definition of the functions consult the
3492 documentation available from Netlib (*note BLAS References and Further
3497 * Level 1 CBLAS Functions::
3498 * Level 2 CBLAS Functions::
3499 * Level 3 CBLAS Functions::
3500 * GSL CBLAS Examples::
3503 File: gsl-ref.info, Node: Level 1 CBLAS Functions, Next: Level 2 CBLAS Functions, Up: GSL CBLAS Library
3508 -- Function: float cblas_sdsdot (const int N, const float ALPHA, const
3509 float * X, const int INCX, const float * Y, const int INCY)
3511 -- Function: double cblas_dsdot (const int N, const float * X, const
3512 int INCX, const float * Y, const int INCY)
3514 -- Function: float cblas_sdot (const int N, const float * X, const int
3515 INCX, const float * Y, const int INCY)
3517 -- Function: double cblas_ddot (const int N, const double * X, const
3518 int INCX, const double * Y, const int INCY)
3520 -- Function: void cblas_cdotu_sub (const int N, const void * X, const
3521 int INCX, const void * Y, const int INCY, void * DOTU)
3523 -- Function: void cblas_cdotc_sub (const int N, const void * X, const
3524 int INCX, const void * Y, const int INCY, void * DOTC)
3526 -- Function: void cblas_zdotu_sub (const int N, const void * X, const
3527 int INCX, const void * Y, const int INCY, void * DOTU)
3529 -- Function: void cblas_zdotc_sub (const int N, const void * X, const
3530 int INCX, const void * Y, const int INCY, void * DOTC)
3532 -- Function: float cblas_snrm2 (const int N, const float * X, const
3535 -- Function: float cblas_sasum (const int N, const float * X, const
3538 -- Function: double cblas_dnrm2 (const int N, const double * X, const
3541 -- Function: double cblas_dasum (const int N, const double * X, const
3544 -- Function: float cblas_scnrm2 (const int N, const void * X, const
3547 -- Function: float cblas_scasum (const int N, const void * X, const
3550 -- Function: double cblas_dznrm2 (const int N, const void * X, const
3553 -- Function: double cblas_dzasum (const int N, const void * X, const
3556 -- Function: CBLAS_INDEX cblas_isamax (const int N, const float * X,
3559 -- Function: CBLAS_INDEX cblas_idamax (const int N, const double * X,
3562 -- Function: CBLAS_INDEX cblas_icamax (const int N, const void * X,
3565 -- Function: CBLAS_INDEX cblas_izamax (const int N, const void * X,
3568 -- Function: void cblas_sswap (const int N, float * X, const int INCX,
3569 float * Y, const int INCY)
3571 -- Function: void cblas_scopy (const int N, const float * X, const int
3572 INCX, float * Y, const int INCY)
3574 -- Function: void cblas_saxpy (const int N, const float ALPHA, const
3575 float * X, const int INCX, float * Y, const int INCY)
3577 -- Function: void cblas_dswap (const int N, double * X, const int
3578 INCX, double * Y, const int INCY)
3580 -- Function: void cblas_dcopy (const int N, const double * X, const
3581 int INCX, double * Y, const int INCY)
3583 -- Function: void cblas_daxpy (const int N, const double ALPHA, const
3584 double * X, const int INCX, double * Y, const int INCY)
3586 -- Function: void cblas_cswap (const int N, void * X, const int INCX,
3587 void * Y, const int INCY)
3589 -- Function: void cblas_ccopy (const int N, const void * X, const int
3590 INCX, void * Y, const int INCY)
3592 -- Function: void cblas_caxpy (const int N, const void * ALPHA, const
3593 void * X, const int INCX, void * Y, const int INCY)
3595 -- Function: void cblas_zswap (const int N, void * X, const int INCX,
3596 void * Y, const int INCY)
3598 -- Function: void cblas_zcopy (const int N, const void * X, const int
3599 INCX, void * Y, const int INCY)
3601 -- Function: void cblas_zaxpy (const int N, const void * ALPHA, const
3602 void * X, const int INCX, void * Y, const int INCY)
3604 -- Function: void cblas_srotg (float * A, float * B, float * C, float
3607 -- Function: void cblas_srotmg (float * D1, float * D2, float * B1,
3608 const float B2, float * P)
3610 -- Function: void cblas_srot (const int N, float * X, const int INCX,
3611 float * Y, const int INCY, const float C, const float S)
3613 -- Function: void cblas_srotm (const int N, float * X, const int INCX,
3614 float * Y, const int INCY, const float * P)
3616 -- Function: void cblas_drotg (double * A, double * B, double * C,
3619 -- Function: void cblas_drotmg (double * D1, double * D2, double * B1,
3620 const double B2, double * P)
3622 -- Function: void cblas_drot (const int N, double * X, const int INCX,
3623 double * Y, const int INCY, const double C, const double S)
3625 -- Function: void cblas_drotm (const int N, double * X, const int
3626 INCX, double * Y, const int INCY, const double * P)
3628 -- Function: void cblas_sscal (const int N, const float ALPHA, float *
3631 -- Function: void cblas_dscal (const int N, const double ALPHA, double
3632 * X, const int INCX)
3634 -- Function: void cblas_cscal (const int N, const void * ALPHA, void *
3637 -- Function: void cblas_zscal (const int N, const void * ALPHA, void *
3640 -- Function: void cblas_csscal (const int N, const float ALPHA, void *
3643 -- Function: void cblas_zdscal (const int N, const double ALPHA, void
3644 * X, const int INCX)
3647 File: gsl-ref.info, Node: Level 2 CBLAS Functions, Next: Level 3 CBLAS Functions, Prev: Level 1 CBLAS Functions, Up: GSL CBLAS Library
3652 -- Function: void cblas_sgemv (const enum CBLAS_ORDER ORDER, const
3653 enum CBLAS_TRANSPOSE TRANSA, const int M, const int N, const
3654 float ALPHA, const float * A, const int LDA, const float * X,
3655 const int INCX, const float BETA, float * Y, const int INCY)
3657 -- Function: void cblas_sgbmv (const enum CBLAS_ORDER ORDER, const
3658 enum CBLAS_TRANSPOSE TRANSA, const int M, const int N, const
3659 int KL, const int KU, const float ALPHA, const float * A,
3660 const int LDA, const float * X, const int INCX, const float
3661 BETA, float * Y, const int INCY)
3663 -- Function: void cblas_strmv (const enum CBLAS_ORDER ORDER, const
3664 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3665 const enum CBLAS_DIAG DIAG, const int N, const float * A,
3666 const int LDA, float * X, const int INCX)
3668 -- Function: void cblas_stbmv (const enum CBLAS_ORDER ORDER, const
3669 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3670 const enum CBLAS_DIAG DIAG, const int N, const int K, const
3671 float * A, const int LDA, float * X, const int INCX)
3673 -- Function: void cblas_stpmv (const enum CBLAS_ORDER ORDER, const
3674 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3675 const enum CBLAS_DIAG DIAG, const int N, const float * AP,
3676 float * X, const int INCX)
3678 -- Function: void cblas_strsv (const enum CBLAS_ORDER ORDER, const
3679 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3680 const enum CBLAS_DIAG DIAG, const int N, const float * A,
3681 const int LDA, float * X, const int INCX)
3683 -- Function: void cblas_stbsv (const enum CBLAS_ORDER ORDER, const
3684 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3685 const enum CBLAS_DIAG DIAG, const int N, const int K, const
3686 float * A, const int LDA, float * X, const int INCX)
3688 -- Function: void cblas_stpsv (const enum CBLAS_ORDER ORDER, const
3689 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3690 const enum CBLAS_DIAG DIAG, const int N, const float * AP,
3691 float * X, const int INCX)
3693 -- Function: void cblas_dgemv (const enum CBLAS_ORDER ORDER, const
3694 enum CBLAS_TRANSPOSE TRANSA, const int M, const int N, const
3695 double ALPHA, const double * A, const int LDA, const double *
3696 X, const int INCX, const double BETA, double * Y, const int
3699 -- Function: void cblas_dgbmv (const enum CBLAS_ORDER ORDER, const
3700 enum CBLAS_TRANSPOSE TRANSA, const int M, const int N, const
3701 int KL, const int KU, const double ALPHA, const double * A,
3702 const int LDA, const double * X, const int INCX, const double
3703 BETA, double * Y, const int INCY)
3705 -- Function: void cblas_dtrmv (const enum CBLAS_ORDER ORDER, const
3706 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3707 const enum CBLAS_DIAG DIAG, const int N, const double * A,
3708 const int LDA, double * X, const int INCX)
3710 -- Function: void cblas_dtbmv (const enum CBLAS_ORDER ORDER, const
3711 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3712 const enum CBLAS_DIAG DIAG, const int N, const int K, const
3713 double * A, const int LDA, double * X, const int INCX)
3715 -- Function: void cblas_dtpmv (const enum CBLAS_ORDER ORDER, const
3716 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3717 const enum CBLAS_DIAG DIAG, const int N, const double * AP,
3718 double * X, const int INCX)
3720 -- Function: void cblas_dtrsv (const enum CBLAS_ORDER ORDER, const
3721 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3722 const enum CBLAS_DIAG DIAG, const int N, const double * A,
3723 const int LDA, double * X, const int INCX)
3725 -- Function: void cblas_dtbsv (const enum CBLAS_ORDER ORDER, const
3726 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3727 const enum CBLAS_DIAG DIAG, const int N, const int K, const
3728 double * A, const int LDA, double * X, const int INCX)
3730 -- Function: void cblas_dtpsv (const enum CBLAS_ORDER ORDER, const
3731 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3732 const enum CBLAS_DIAG DIAG, const int N, const double * AP,
3733 double * X, const int INCX)
3735 -- Function: void cblas_cgemv (const enum CBLAS_ORDER ORDER, const
3736 enum CBLAS_TRANSPOSE TRANSA, const int M, const int N, const
3737 void * ALPHA, const void * A, const int LDA, const void * X,
3738 const int INCX, const void * BETA, void * Y, const int INCY)
3740 -- Function: void cblas_cgbmv (const enum CBLAS_ORDER ORDER, const
3741 enum CBLAS_TRANSPOSE TRANSA, const int M, const int N, const
3742 int KL, const int KU, const void * ALPHA, const void * A,
3743 const int LDA, const void * X, const int INCX, const void *
3744 BETA, void * Y, const int INCY)
3746 -- Function: void cblas_ctrmv (const enum CBLAS_ORDER ORDER, const
3747 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3748 const enum CBLAS_DIAG DIAG, const int N, const void * A,
3749 const int LDA, void * X, const int INCX)
3751 -- Function: void cblas_ctbmv (const enum CBLAS_ORDER ORDER, const
3752 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3753 const enum CBLAS_DIAG DIAG, const int N, const int K, const
3754 void * A, const int LDA, void * X, const int INCX)
3756 -- Function: void cblas_ctpmv (const enum CBLAS_ORDER ORDER, const
3757 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3758 const enum CBLAS_DIAG DIAG, const int N, const void * AP,
3759 void * X, const int INCX)
3761 -- Function: void cblas_ctrsv (const enum CBLAS_ORDER ORDER, const
3762 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3763 const enum CBLAS_DIAG DIAG, const int N, const void * A,
3764 const int LDA, void * X, const int INCX)
3766 -- Function: void cblas_ctbsv (const enum CBLAS_ORDER ORDER, const
3767 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3768 const enum CBLAS_DIAG DIAG, const int N, const int K, const
3769 void * A, const int LDA, void * X, const int INCX)
3771 -- Function: void cblas_ctpsv (const enum CBLAS_ORDER ORDER, const
3772 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3773 const enum CBLAS_DIAG DIAG, const int N, const void * AP,
3774 void * X, const int INCX)
3776 -- Function: void cblas_zgemv (const enum CBLAS_ORDER ORDER, const
3777 enum CBLAS_TRANSPOSE TRANSA, const int M, const int N, const
3778 void * ALPHA, const void * A, const int LDA, const void * X,
3779 const int INCX, const void * BETA, void * Y, const int INCY)
3781 -- Function: void cblas_zgbmv (const enum CBLAS_ORDER ORDER, const
3782 enum CBLAS_TRANSPOSE TRANSA, const int M, const int N, const
3783 int KL, const int KU, const void * ALPHA, const void * A,
3784 const int LDA, const void * X, const int INCX, const void *
3785 BETA, void * Y, const int INCY)
3787 -- Function: void cblas_ztrmv (const enum CBLAS_ORDER ORDER, const
3788 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3789 const enum CBLAS_DIAG DIAG, const int N, const void * A,
3790 const int LDA, void * X, const int INCX)
3792 -- Function: void cblas_ztbmv (const enum CBLAS_ORDER ORDER, const
3793 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3794 const enum CBLAS_DIAG DIAG, const int N, const int K, const
3795 void * A, const int LDA, void * X, const int INCX)
3797 -- Function: void cblas_ztpmv (const enum CBLAS_ORDER ORDER, const
3798 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3799 const enum CBLAS_DIAG DIAG, const int N, const void * AP,
3800 void * X, const int INCX)
3802 -- Function: void cblas_ztrsv (const enum CBLAS_ORDER ORDER, const
3803 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3804 const enum CBLAS_DIAG DIAG, const int N, const void * A,
3805 const int LDA, void * X, const int INCX)
3807 -- Function: void cblas_ztbsv (const enum CBLAS_ORDER ORDER, const
3808 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3809 const enum CBLAS_DIAG DIAG, const int N, const int K, const
3810 void * A, const int LDA, void * X, const int INCX)
3812 -- Function: void cblas_ztpsv (const enum CBLAS_ORDER ORDER, const
3813 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANSA,
3814 const enum CBLAS_DIAG DIAG, const int N, const void * AP,
3815 void * X, const int INCX)
3817 -- Function: void cblas_ssymv (const enum CBLAS_ORDER ORDER, const
3818 enum CBLAS_UPLO UPLO, const int N, const float ALPHA, const
3819 float * A, const int LDA, const float * X, const int INCX,
3820 const float BETA, float * Y, const int INCY)
3822 -- Function: void cblas_ssbmv (const enum CBLAS_ORDER ORDER, const
3823 enum CBLAS_UPLO UPLO, const int N, const int K, const float
3824 ALPHA, const float * A, const int LDA, const float * X, const
3825 int INCX, const float BETA, float * Y, const int INCY)
3827 -- Function: void cblas_sspmv (const enum CBLAS_ORDER ORDER, const
3828 enum CBLAS_UPLO UPLO, const int N, const float ALPHA, const
3829 float * AP, const float * X, const int INCX, const float
3830 BETA, float * Y, const int INCY)
3832 -- Function: void cblas_sger (const enum CBLAS_ORDER ORDER, const int
3833 M, const int N, const float ALPHA, const float * X, const int
3834 INCX, const float * Y, const int INCY, float * A, const int
3837 -- Function: void cblas_ssyr (const enum CBLAS_ORDER ORDER, const enum
3838 CBLAS_UPLO UPLO, const int N, const float ALPHA, const float
3839 * X, const int INCX, float * A, const int LDA)
3841 -- Function: void cblas_sspr (const enum CBLAS_ORDER ORDER, const enum
3842 CBLAS_UPLO UPLO, const int N, const float ALPHA, const float
3843 * X, const int INCX, float * AP)
3845 -- Function: void cblas_ssyr2 (const enum CBLAS_ORDER ORDER, const
3846 enum CBLAS_UPLO UPLO, const int N, const float ALPHA, const
3847 float * X, const int INCX, const float * Y, const int INCY,
3848 float * A, const int LDA)
3850 -- Function: void cblas_sspr2 (const enum CBLAS_ORDER ORDER, const
3851 enum CBLAS_UPLO UPLO, const int N, const float ALPHA, const
3852 float * X, const int INCX, const float * Y, const int INCY,
3855 -- Function: void cblas_dsymv (const enum CBLAS_ORDER ORDER, const
3856 enum CBLAS_UPLO UPLO, const int N, const double ALPHA, const
3857 double * A, const int LDA, const double * X, const int INCX,
3858 const double BETA, double * Y, const int INCY)
3860 -- Function: void cblas_dsbmv (const enum CBLAS_ORDER ORDER, const
3861 enum CBLAS_UPLO UPLO, const int N, const int K, const double
3862 ALPHA, const double * A, const int LDA, const double * X,
3863 const int INCX, const double BETA, double * Y, const int INCY)
3865 -- Function: void cblas_dspmv (const enum CBLAS_ORDER ORDER, const
3866 enum CBLAS_UPLO UPLO, const int N, const double ALPHA, const
3867 double * AP, const double * X, const int INCX, const double
3868 BETA, double * Y, const int INCY)
3870 -- Function: void cblas_dger (const enum CBLAS_ORDER ORDER, const int
3871 M, const int N, const double ALPHA, const double * X, const
3872 int INCX, const double * Y, const int INCY, double * A, const
3875 -- Function: void cblas_dsyr (const enum CBLAS_ORDER ORDER, const enum
3876 CBLAS_UPLO UPLO, const int N, const double ALPHA, const
3877 double * X, const int INCX, double * A, const int LDA)
3879 -- Function: void cblas_dspr (const enum CBLAS_ORDER ORDER, const enum
3880 CBLAS_UPLO UPLO, const int N, const double ALPHA, const
3881 double * X, const int INCX, double * AP)
3883 -- Function: void cblas_dsyr2 (const enum CBLAS_ORDER ORDER, const
3884 enum CBLAS_UPLO UPLO, const int N, const double ALPHA, const
3885 double * X, const int INCX, const double * Y, const int INCY,
3886 double * A, const int LDA)
3888 -- Function: void cblas_dspr2 (const enum CBLAS_ORDER ORDER, const
3889 enum CBLAS_UPLO UPLO, const int N, const double ALPHA, const
3890 double * X, const int INCX, const double * Y, const int INCY,
3893 -- Function: void cblas_chemv (const enum CBLAS_ORDER ORDER, const
3894 enum CBLAS_UPLO UPLO, const int N, const void * ALPHA, const
3895 void * A, const int LDA, const void * X, const int INCX,
3896 const void * BETA, void * Y, const int INCY)
3898 -- Function: void cblas_chbmv (const enum CBLAS_ORDER ORDER, const
3899 enum CBLAS_UPLO UPLO, const int N, const int K, const void *
3900 ALPHA, const void * A, const int LDA, const void * X, const
3901 int INCX, const void * BETA, void * Y, const int INCY)
3903 -- Function: void cblas_chpmv (const enum CBLAS_ORDER ORDER, const
3904 enum CBLAS_UPLO UPLO, const int N, const void * ALPHA, const
3905 void * AP, const void * X, const int INCX, const void * BETA,
3906 void * Y, const int INCY)
3908 -- Function: void cblas_cgeru (const enum CBLAS_ORDER ORDER, const int
3909 M, const int N, const void * ALPHA, const void * X, const int
3910 INCX, const void * Y, const int INCY, void * A, const int LDA)
3912 -- Function: void cblas_cgerc (const enum CBLAS_ORDER ORDER, const int
3913 M, const int N, const void * ALPHA, const void * X, const int
3914 INCX, const void * Y, const int INCY, void * A, const int LDA)
3916 -- Function: void cblas_cher (const enum CBLAS_ORDER ORDER, const enum
3917 CBLAS_UPLO UPLO, const int N, const float ALPHA, const void *
3918 X, const int INCX, void * A, const int LDA)
3920 -- Function: void cblas_chpr (const enum CBLAS_ORDER ORDER, const enum
3921 CBLAS_UPLO UPLO, const int N, const float ALPHA, const void *
3922 X, const int INCX, void * A)
3924 -- Function: void cblas_cher2 (const enum CBLAS_ORDER ORDER, const
3925 enum CBLAS_UPLO UPLO, const int N, const void * ALPHA, const
3926 void * X, const int INCX, const void * Y, const int INCY,
3927 void * A, const int LDA)
3929 -- Function: void cblas_chpr2 (const enum CBLAS_ORDER ORDER, const
3930 enum CBLAS_UPLO UPLO, const int N, const void * ALPHA, const
3931 void * X, const int INCX, const void * Y, const int INCY,
3934 -- Function: void cblas_zhemv (const enum CBLAS_ORDER ORDER, const
3935 enum CBLAS_UPLO UPLO, const int N, const void * ALPHA, const
3936 void * A, const int LDA, const void * X, const int INCX,
3937 const void * BETA, void * Y, const int INCY)
3939 -- Function: void cblas_zhbmv (const enum CBLAS_ORDER ORDER, const
3940 enum CBLAS_UPLO UPLO, const int N, const int K, const void *
3941 ALPHA, const void * A, const int LDA, const void * X, const
3942 int INCX, const void * BETA, void * Y, const int INCY)
3944 -- Function: void cblas_zhpmv (const enum CBLAS_ORDER ORDER, const
3945 enum CBLAS_UPLO UPLO, const int N, const void * ALPHA, const
3946 void * AP, const void * X, const int INCX, const void * BETA,
3947 void * Y, const int INCY)
3949 -- Function: void cblas_zgeru (const enum CBLAS_ORDER ORDER, const int
3950 M, const int N, const void * ALPHA, const void * X, const int
3951 INCX, const void * Y, const int INCY, void * A, const int LDA)
3953 -- Function: void cblas_zgerc (const enum CBLAS_ORDER ORDER, const int
3954 M, const int N, const void * ALPHA, const void * X, const int
3955 INCX, const void * Y, const int INCY, void * A, const int LDA)
3957 -- Function: void cblas_zher (const enum CBLAS_ORDER ORDER, const enum
3958 CBLAS_UPLO UPLO, const int N, const double ALPHA, const void
3959 * X, const int INCX, void * A, const int LDA)
3961 -- Function: void cblas_zhpr (const enum CBLAS_ORDER ORDER, const enum
3962 CBLAS_UPLO UPLO, const int N, const double ALPHA, const void
3963 * X, const int INCX, void * A)
3965 -- Function: void cblas_zher2 (const enum CBLAS_ORDER ORDER, const
3966 enum CBLAS_UPLO UPLO, const int N, const void * ALPHA, const
3967 void * X, const int INCX, const void * Y, const int INCY,
3968 void * A, const int LDA)
3970 -- Function: void cblas_zhpr2 (const enum CBLAS_ORDER ORDER, const
3971 enum CBLAS_UPLO UPLO, const int N, const void * ALPHA, const
3972 void * X, const int INCX, const void * Y, const int INCY,
3976 File: gsl-ref.info, Node: Level 3 CBLAS Functions, Next: GSL CBLAS Examples, Prev: Level 2 CBLAS Functions, Up: GSL CBLAS Library
3981 -- Function: void cblas_sgemm (const enum CBLAS_ORDER ORDER, const
3982 enum CBLAS_TRANSPOSE TRANSA, const enum CBLAS_TRANSPOSE
3983 TRANSB, const int M, const int N, const int K, const float
3984 ALPHA, const float * A, const int LDA, const float * B, const
3985 int LDB, const float BETA, float * C, const int LDC)
3987 -- Function: void cblas_ssymm (const enum CBLAS_ORDER ORDER, const
3988 enum CBLAS_SIDE SIDE, const enum CBLAS_UPLO UPLO, const int
3989 M, const int N, const float ALPHA, const float * A, const int
3990 LDA, const float * B, const int LDB, const float BETA, float
3993 -- Function: void cblas_ssyrk (const enum CBLAS_ORDER ORDER, const
3994 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANS, const
3995 int N, const int K, const float ALPHA, const float * A, const
3996 int LDA, const float BETA, float * C, const int LDC)
3998 -- Function: void cblas_ssyr2k (const enum CBLAS_ORDER ORDER, const
3999 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANS, const
4000 int N, const int K, const float ALPHA, const float * A, const
4001 int LDA, const float * B, const int LDB, const float BETA,
4002 float * C, const int LDC)
4004 -- Function: void cblas_strmm (const enum CBLAS_ORDER ORDER, const
4005 enum CBLAS_SIDE SIDE, const enum CBLAS_UPLO UPLO, const enum
4006 CBLAS_TRANSPOSE TRANSA, const enum CBLAS_DIAG DIAG, const int
4007 M, const int N, const float ALPHA, const float * A, const int
4008 LDA, float * B, const int LDB)
4010 -- Function: void cblas_strsm (const enum CBLAS_ORDER ORDER, const
4011 enum CBLAS_SIDE SIDE, const enum CBLAS_UPLO UPLO, const enum
4012 CBLAS_TRANSPOSE TRANSA, const enum CBLAS_DIAG DIAG, const int
4013 M, const int N, const float ALPHA, const float * A, const int
4014 LDA, float * B, const int LDB)
4016 -- Function: void cblas_dgemm (const enum CBLAS_ORDER ORDER, const
4017 enum CBLAS_TRANSPOSE TRANSA, const enum CBLAS_TRANSPOSE
4018 TRANSB, const int M, const int N, const int K, const double
4019 ALPHA, const double * A, const int LDA, const double * B,
4020 const int LDB, const double BETA, double * C, const int LDC)
4022 -- Function: void cblas_dsymm (const enum CBLAS_ORDER ORDER, const
4023 enum CBLAS_SIDE SIDE, const enum CBLAS_UPLO UPLO, const int
4024 M, const int N, const double ALPHA, const double * A, const
4025 int LDA, const double * B, const int LDB, const double BETA,
4026 double * C, const int LDC)
4028 -- Function: void cblas_dsyrk (const enum CBLAS_ORDER ORDER, const
4029 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANS, const
4030 int N, const int K, const double ALPHA, const double * A,
4031 const int LDA, const double BETA, double * C, const int LDC)
4033 -- Function: void cblas_dsyr2k (const enum CBLAS_ORDER ORDER, const
4034 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANS, const
4035 int N, const int K, const double ALPHA, const double * A,
4036 const int LDA, const double * B, const int LDB, const double
4037 BETA, double * C, const int LDC)
4039 -- Function: void cblas_dtrmm (const enum CBLAS_ORDER ORDER, const
4040 enum CBLAS_SIDE SIDE, const enum CBLAS_UPLO UPLO, const enum
4041 CBLAS_TRANSPOSE TRANSA, const enum CBLAS_DIAG DIAG, const int
4042 M, const int N, const double ALPHA, const double * A, const
4043 int LDA, double * B, const int LDB)
4045 -- Function: void cblas_dtrsm (const enum CBLAS_ORDER ORDER, const
4046 enum CBLAS_SIDE SIDE, const enum CBLAS_UPLO UPLO, const enum
4047 CBLAS_TRANSPOSE TRANSA, const enum CBLAS_DIAG DIAG, const int
4048 M, const int N, const double ALPHA, const double * A, const
4049 int LDA, double * B, const int LDB)
4051 -- Function: void cblas_cgemm (const enum CBLAS_ORDER ORDER, const
4052 enum CBLAS_TRANSPOSE TRANSA, const enum CBLAS_TRANSPOSE
4053 TRANSB, const int M, const int N, const int K, const void *
4054 ALPHA, const void * A, const int LDA, const void * B, const
4055 int LDB, const void * BETA, void * C, const int LDC)
4057 -- Function: void cblas_csymm (const enum CBLAS_ORDER ORDER, const
4058 enum CBLAS_SIDE SIDE, const enum CBLAS_UPLO UPLO, const int
4059 M, const int N, const void * ALPHA, const void * A, const int
4060 LDA, const void * B, const int LDB, const void * BETA, void *
4063 -- Function: void cblas_csyrk (const enum CBLAS_ORDER ORDER, const
4064 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANS, const
4065 int N, const int K, const void * ALPHA, const void * A, const
4066 int LDA, const void * BETA, void * C, const int LDC)
4068 -- Function: void cblas_csyr2k (const enum CBLAS_ORDER ORDER, const
4069 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANS, const
4070 int N, const int K, const void * ALPHA, const void * A, const
4071 int LDA, const void * B, const int LDB, const void * BETA,
4072 void * C, const int LDC)
4074 -- Function: void cblas_ctrmm (const enum CBLAS_ORDER ORDER, const
4075 enum CBLAS_SIDE SIDE, const enum CBLAS_UPLO UPLO, const enum
4076 CBLAS_TRANSPOSE TRANSA, const enum CBLAS_DIAG DIAG, const int
4077 M, const int N, const void * ALPHA, const void * A, const int
4078 LDA, void * B, const int LDB)
4080 -- Function: void cblas_ctrsm (const enum CBLAS_ORDER ORDER, const
4081 enum CBLAS_SIDE SIDE, const enum CBLAS_UPLO UPLO, const enum
4082 CBLAS_TRANSPOSE TRANSA, const enum CBLAS_DIAG DIAG, const int
4083 M, const int N, const void * ALPHA, const void * A, const int
4084 LDA, void * B, const int LDB)
4086 -- Function: void cblas_zgemm (const enum CBLAS_ORDER ORDER, const
4087 enum CBLAS_TRANSPOSE TRANSA, const enum CBLAS_TRANSPOSE
4088 TRANSB, const int M, const int N, const int K, const void *
4089 ALPHA, const void * A, const int LDA, const void * B, const
4090 int LDB, const void * BETA, void * C, const int LDC)
4092 -- Function: void cblas_zsymm (const enum CBLAS_ORDER ORDER, const
4093 enum CBLAS_SIDE SIDE, const enum CBLAS_UPLO UPLO, const int
4094 M, const int N, const void * ALPHA, const void * A, const int
4095 LDA, const void * B, const int LDB, const void * BETA, void *
4098 -- Function: void cblas_zsyrk (const enum CBLAS_ORDER ORDER, const
4099 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANS, const
4100 int N, const int K, const void * ALPHA, const void * A, const
4101 int LDA, const void * BETA, void * C, const int LDC)
4103 -- Function: void cblas_zsyr2k (const enum CBLAS_ORDER ORDER, const
4104 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANS, const
4105 int N, const int K, const void * ALPHA, const void * A, const
4106 int LDA, const void * B, const int LDB, const void * BETA,
4107 void * C, const int LDC)
4109 -- Function: void cblas_ztrmm (const enum CBLAS_ORDER ORDER, const
4110 enum CBLAS_SIDE SIDE, const enum CBLAS_UPLO UPLO, const enum
4111 CBLAS_TRANSPOSE TRANSA, const enum CBLAS_DIAG DIAG, const int
4112 M, const int N, const void * ALPHA, const void * A, const int
4113 LDA, void * B, const int LDB)
4115 -- Function: void cblas_ztrsm (const enum CBLAS_ORDER ORDER, const
4116 enum CBLAS_SIDE SIDE, const enum CBLAS_UPLO UPLO, const enum
4117 CBLAS_TRANSPOSE TRANSA, const enum CBLAS_DIAG DIAG, const int
4118 M, const int N, const void * ALPHA, const void * A, const int
4119 LDA, void * B, const int LDB)
4121 -- Function: void cblas_chemm (const enum CBLAS_ORDER ORDER, const
4122 enum CBLAS_SIDE SIDE, const enum CBLAS_UPLO UPLO, const int
4123 M, const int N, const void * ALPHA, const void * A, const int
4124 LDA, const void * B, const int LDB, const void * BETA, void *
4127 -- Function: void cblas_cherk (const enum CBLAS_ORDER ORDER, const
4128 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANS, const
4129 int N, const int K, const float ALPHA, const void * A, const
4130 int LDA, const float BETA, void * C, const int LDC)
4132 -- Function: void cblas_cher2k (const enum CBLAS_ORDER ORDER, const
4133 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANS, const
4134 int N, const int K, const void * ALPHA, const void * A, const
4135 int LDA, const void * B, const int LDB, const float BETA,
4136 void * C, const int LDC)
4138 -- Function: void cblas_zhemm (const enum CBLAS_ORDER ORDER, const
4139 enum CBLAS_SIDE SIDE, const enum CBLAS_UPLO UPLO, const int
4140 M, const int N, const void * ALPHA, const void * A, const int
4141 LDA, const void * B, const int LDB, const void * BETA, void *
4144 -- Function: void cblas_zherk (const enum CBLAS_ORDER ORDER, const
4145 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANS, const
4146 int N, const int K, const double ALPHA, const void * A, const
4147 int LDA, const double BETA, void * C, const int LDC)
4149 -- Function: void cblas_zher2k (const enum CBLAS_ORDER ORDER, const
4150 enum CBLAS_UPLO UPLO, const enum CBLAS_TRANSPOSE TRANS, const
4151 int N, const int K, const void * ALPHA, const void * A, const
4152 int LDA, const void * B, const int LDB, const double BETA,
4153 void * C, const int LDC)
4155 -- Function: void cblas_xerbla (int P, const char * ROUT, const char *
4159 File: gsl-ref.info, Node: GSL CBLAS Examples, Prev: Level 3 CBLAS Functions, Up: GSL CBLAS Library
4164 The following program computes the product of two matrices using the
4165 Level-3 BLAS function SGEMM,
4167 [ 0.11 0.12 0.13 ] [ 1011 1012 ] [ 367.76 368.12 ]
4168 [ 0.21 0.22 0.23 ] [ 1021 1022 ] = [ 674.06 674.72 ]
4171 The matrices are stored in row major order but could be stored in column
4172 major order if the first argument of the call to `cblas_sgemm' was
4173 changed to `CblasColMajor'.
4176 #include <gsl/gsl_cblas.h>
4183 float A[] = { 0.11, 0.12, 0.13,
4188 float B[] = { 1011, 1012,
4194 float C[] = { 0.00, 0.00,
4197 /* Compute C = A B */
4199 cblas_sgemm (CblasRowMajor,
4200 CblasNoTrans, CblasNoTrans, 2, 2, 3,
4201 1.0, A, lda, B, ldb, 0.0, C, ldc);
4203 printf ("[ %g, %g\n", C[0], C[1]);
4204 printf (" %g, %g ]\n", C[2], C[3]);
4209 To compile the program use the following command line,
4211 $ gcc -Wall demo.c -lgslcblas
4213 There is no need to link with the main library `-lgsl' in this case as
4214 the CBLAS library is an independent unit. Here is the output from the
4222 File: gsl-ref.info, Node: Free Software Needs Free Documentation, Next: GNU General Public License, Prev: GSL CBLAS Library, Up: Top
4224 Free Software Needs Free Documentation
4225 **************************************
4227 The following article was written by Richard Stallman, founder of
4230 The biggest deficiency in the free software community today is not in
4231 the software--it is the lack of good free documentation that we can
4232 include with the free software. Many of our most important programs do
4233 not come with free reference manuals and free introductory texts.
4234 Documentation is an essential part of any software package; when an
4235 important free software package does not come with a free manual and a
4236 free tutorial, that is a major gap. We have many such gaps today.
4238 Consider Perl, for instance. The tutorial manuals that people
4239 normally use are non-free. How did this come about? Because the
4240 authors of those manuals published them with restrictive terms--no
4241 copying, no modification, source files not available--which exclude
4242 them from the free software world.
4244 That wasn't the first time this sort of thing happened, and it was
4245 far from the last. Many times we have heard a GNU user eagerly
4246 describe a manual that he is writing, his intended contribution to the
4247 community, only to learn that he had ruined everything by signing a
4248 publication contract to make it non-free.
4250 Free documentation, like free software, is a matter of freedom, not
4251 price. The problem with the non-free manual is not that publishers
4252 charge a price for printed copies--that in itself is fine. (The Free
4253 Software Foundation sells printed copies of manuals, too.) The problem
4254 is the restrictions on the use of the manual. Free manuals are
4255 available in source code form, and give you permission to copy and
4256 modify. Non-free manuals do not allow this.
4258 The criteria of freedom for a free manual are roughly the same as for
4259 free software. Redistribution (including the normal kinds of
4260 commercial redistribution) must be permitted, so that the manual can
4261 accompany every copy of the program, both on-line and on paper.
4263 Permission for modification of the technical content is crucial too.
4264 When people modify the software, adding or changing features, if they
4265 are conscientious they will change the manual too--so they can provide
4266 accurate and clear documentation for the modified program. A manual
4267 that leaves you no choice but to write a new manual to document a
4268 changed version of the program is not really available to our community.
4270 Some kinds of limits on the way modification is handled are
4271 acceptable. For example, requirements to preserve the original
4272 author's copyright notice, the distribution terms, or the list of
4273 authors, are ok. It is also no problem to require modified versions to
4274 include notice that they were modified. Even entire sections that may
4275 not be deleted or changed are acceptable, as long as they deal with
4276 nontechnical topics (like this one). These kinds of restrictions are
4277 acceptable because they don't obstruct the community's normal use of
4280 However, it must be possible to modify all the _technical_ content
4281 of the manual, and then distribute the result in all the usual media,
4282 through all the usual channels. Otherwise, the restrictions obstruct
4283 the use of the manual, it is not free, and we need another manual to
4286 Please spread the word about this issue. Our community continues to
4287 lose manuals to proprietary publishing. If we spread the word that
4288 free software needs free reference manuals and free tutorials, perhaps
4289 the next person who wants to contribute by writing documentation will
4290 realize, before it is too late, that only free manuals contribute to
4291 the free software community.
4293 If you are writing documentation, please insist on publishing it
4294 under the GNU Free Documentation License or another free documentation
4295 license. Remember that this decision requires your approval--you don't
4296 have to let the publisher decide. Some commercial publishers will use
4297 a free license if you insist, but they will not propose the option; it
4298 is up to you to raise the issue and say firmly that this is what you
4299 want. If the publisher you are dealing with refuses, please try other
4300 publishers. If you're not sure whether a proposed license is free,
4301 write to <licensing@gnu.org>.
4303 You can encourage commercial publishers to sell more free, copylefted
4304 manuals and tutorials by buying them, and particularly by buying copies
4305 from the publishers that paid for their writing or for major
4306 improvements. Meanwhile, try to avoid buying non-free documentation at
4307 all. Check the distribution terms of a manual before you buy it, and
4308 insist that whoever seeks your business must respect your freedom.
4309 Check the history of the book, and try reward the publishers that have
4310 paid or pay the authors to work on it.
4312 The Free Software Foundation maintains a list of free documentation
4313 published by other publishers:
4315 `http://www.fsf.org/doc/other-free-books.html'
4318 File: gsl-ref.info, Node: GNU General Public License, Next: GNU Free Documentation License, Prev: Free Software Needs Free Documentation, Up: Top
4320 GNU General Public License
4321 **************************
4323 Version 3, 29 June 2007
4324 Copyright (C) 2007 Free Software Foundation, Inc. `http://fsf.org/'
4326 Everyone is permitted to copy and distribute verbatim copies of this
4327 license document, but changing it is not allowed.
4332 The GNU General Public License is a free, copyleft license for software
4333 and other kinds of works.
4335 The licenses for most software and other practical works are designed
4336 to take away your freedom to share and change the works. By contrast,
4337 the GNU General Public License is intended to guarantee your freedom to
4338 share and change all versions of a program-to make sure it remains free
4339 software for all its users. We, the Free Software Foundation, use the
4340 GNU General Public License for most of our software; it applies also to
4341 any other work released this way by its authors. You can apply it to
4344 When we speak of free software, we are referring to freedom, not
4345 price. Our General Public Licenses are designed to make sure that you
4346 have the freedom to distribute copies of free software (and charge for
4347 them if you wish), that you receive source code or can get it if you
4348 want it, that you can change the software or use pieces of it in new
4349 free programs, and that you know you can do these things.
4351 To protect your rights, we need to prevent others from denying you
4352 these rights or asking you to surrender the rights. Therefore, you
4353 have certain responsibilities if you distribute copies of the software,
4354 or if you modify it: responsibilities to respect the freedom of others.
4356 For example, if you distribute copies of such a program, whether
4357 gratis or for a fee, you must pass on to the recipients the same
4358 freedoms that you received. You must make sure that they, too, receive
4359 or can get the source code. And you must show them these terms so they
4362 Developers that use the GNU GPL protect your rights with two steps:
4363 (1) assert copyright on the software, and (2) offer you this License
4364 giving you legal permission to copy, distribute and/or modify it.
4366 For the developers' and authors' protection, the GPL clearly explains
4367 that there is no warranty for this free software. For both users' and
4368 authors' sake, the GPL requires that modified versions be marked as
4369 changed, so that their problems will not be attributed erroneously to
4370 authors of previous versions.
4372 Some devices are designed to deny users access to install or run
4373 modified versions of the software inside them, although the
4374 manufacturer can do so. This is fundamentally incompatible with the
4375 aim of protecting users' freedom to change the software. The
4376 systematic pattern of such abuse occurs in the area of products for
4377 individuals to use, which is precisely where it is most unacceptable.
4378 Therefore, we have designed this version of the GPL to prohibit the
4379 practice for those products. If such problems arise substantially in
4380 other domains, we stand ready to extend this provision to those domains
4381 in future versions of the GPL, as needed to protect the freedom of
4384 Finally, every program is threatened constantly by software patents.
4385 States should not allow patents to restrict development and use of
4386 software on general-purpose computers, but in those that do, we wish to
4387 avoid the special danger that patents applied to a free program could
4388 make it effectively proprietary. To prevent this, the GPL assures that
4389 patents cannot be used to render the program non-free.
4391 The precise terms and conditions for copying, distribution and
4392 modification follow.
4394 TERMS AND CONDITIONS
4395 ====================
4399 "This License" refers to version 3 of the GNU General Public
4402 "Copyright" also means copyright-like laws that apply to other
4403 kinds of works, such as semiconductor masks.
4405 "The Program" refers to any copyrightable work licensed under this
4406 License. Each licensee is addressed as "you". "Licensees" and
4407 "recipients" may be individuals or organizations.
4409 To "modify" a work means to copy from or adapt all or part of the
4410 work in a fashion requiring copyright permission, other than the
4411 making of an exact copy. The resulting work is called a "modified
4412 version" of the earlier work or a work "based on" the earlier work.
4414 A "covered work" means either the unmodified Program or a work
4415 based on the Program.
4417 To "propagate" a work means to do anything with it that, without
4418 permission, would make you directly or secondarily liable for
4419 infringement under applicable copyright law, except executing it
4420 on a computer or modifying a private copy. Propagation includes
4421 copying, distribution (with or without modification), making
4422 available to the public, and in some countries other activities as
4425 To "convey" a work means any kind of propagation that enables other
4426 parties to make or receive copies. Mere interaction with a user
4427 through a computer network, with no transfer of a copy, is not
4430 An interactive user interface displays "Appropriate Legal Notices"
4431 to the extent that it includes a convenient and prominently visible
4432 feature that (1) displays an appropriate copyright notice, and (2)
4433 tells the user that there is no warranty for the work (except to
4434 the extent that warranties are provided), that licensees may
4435 convey the work under this License, and how to view a copy of this
4436 License. If the interface presents a list of user commands or
4437 options, such as a menu, a prominent item in the list meets this
4442 The "source code" for a work means the preferred form of the work
4443 for making modifications to it. "Object code" means any
4444 non-source form of a work.
4446 A "Standard Interface" means an interface that either is an
4447 official standard defined by a recognized standards body, or, in
4448 the case of interfaces specified for a particular programming
4449 language, one that is widely used among developers working in that
4452 The "System Libraries" of an executable work include anything,
4453 other than the work as a whole, that (a) is included in the normal
4454 form of packaging a Major Component, but which is not part of that
4455 Major Component, and (b) serves only to enable use of the work
4456 with that Major Component, or to implement a Standard Interface
4457 for which an implementation is available to the public in source
4458 code form. A "Major Component", in this context, means a major
4459 essential component (kernel, window system, and so on) of the
4460 specific operating system (if any) on which the executable work
4461 runs, or a compiler used to produce the work, or an object code
4462 interpreter used to run it.
4464 The "Corresponding Source" for a work in object code form means all
4465 the source code needed to generate, install, and (for an executable
4466 work) run the object code and to modify the work, including
4467 scripts to control those activities. However, it does not include
4468 the work's System Libraries, or general-purpose tools or generally
4469 available free programs which are used unmodified in performing
4470 those activities but which are not part of the work. For example,
4471 Corresponding Source includes interface definition files
4472 associated with source files for the work, and the source code for
4473 shared libraries and dynamically linked subprograms that the work
4474 is specifically designed to require, such as by intimate data
4475 communication or control flow between those subprograms and other
4478 The Corresponding Source need not include anything that users can
4479 regenerate automatically from other parts of the Corresponding
4482 The Corresponding Source for a work in source code form is that
4485 2. Basic Permissions.
4487 All rights granted under this License are granted for the term of
4488 copyright on the Program, and are irrevocable provided the stated
4489 conditions are met. This License explicitly affirms your unlimited
4490 permission to run the unmodified Program. The output from running
4491 a covered work is covered by this License only if the output,
4492 given its content, constitutes a covered work. This License
4493 acknowledges your rights of fair use or other equivalent, as
4494 provided by copyright law.
4496 You may make, run and propagate covered works that you do not
4497 convey, without conditions so long as your license otherwise
4498 remains in force. You may convey covered works to others for the
4499 sole purpose of having them make modifications exclusively for
4500 you, or provide you with facilities for running those works,
4501 provided that you comply with the terms of this License in
4502 conveying all material for which you do not control copyright.
4503 Those thus making or running the covered works for you must do so
4504 exclusively on your behalf, under your direction and control, on
4505 terms that prohibit them from making any copies of your
4506 copyrighted material outside their relationship with you.
4508 Conveying under any other circumstances is permitted solely under
4509 the conditions stated below. Sublicensing is not allowed; section
4510 10 makes it unnecessary.
4512 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
4514 No covered work shall be deemed part of an effective technological
4515 measure under any applicable law fulfilling obligations under
4516 article 11 of the WIPO copyright treaty adopted on 20 December
4517 1996, or similar laws prohibiting or restricting circumvention of
4520 When you convey a covered work, you waive any legal power to forbid
4521 circumvention of technological measures to the extent such
4522 circumvention is effected by exercising rights under this License
4523 with respect to the covered work, and you disclaim any intention
4524 to limit operation or modification of the work as a means of
4525 enforcing, against the work's users, your or third parties' legal
4526 rights to forbid circumvention of technological measures.
4528 4. Conveying Verbatim Copies.
4530 You may convey verbatim copies of the Program's source code as you
4531 receive it, in any medium, provided that you conspicuously and
4532 appropriately publish on each copy an appropriate copyright notice;
4533 keep intact all notices stating that this License and any
4534 non-permissive terms added in accord with section 7 apply to the
4535 code; keep intact all notices of the absence of any warranty; and
4536 give all recipients a copy of this License along with the Program.
4538 You may charge any price or no price for each copy that you convey,
4539 and you may offer support or warranty protection for a fee.
4541 5. Conveying Modified Source Versions.
4543 You may convey a work based on the Program, or the modifications to
4544 produce it from the Program, in the form of source code under the
4545 terms of section 4, provided that you also meet all of these
4548 a. The work must carry prominent notices stating that you
4549 modified it, and giving a relevant date.
4551 b. The work must carry prominent notices stating that it is
4552 released under this License and any conditions added under
4553 section 7. This requirement modifies the requirement in
4554 section 4 to "keep intact all notices".
4556 c. You must license the entire work, as a whole, under this
4557 License to anyone who comes into possession of a copy. This
4558 License will therefore apply, along with any applicable
4559 section 7 additional terms, to the whole of the work, and all
4560 its parts, regardless of how they are packaged. This License
4561 gives no permission to license the work in any other way, but
4562 it does not invalidate such permission if you have separately
4565 d. If the work has interactive user interfaces, each must display
4566 Appropriate Legal Notices; however, if the Program has
4567 interactive interfaces that do not display Appropriate Legal
4568 Notices, your work need not make them do so.
4570 A compilation of a covered work with other separate and independent
4571 works, which are not by their nature extensions of the covered
4572 work, and which are not combined with it such as to form a larger
4573 program, in or on a volume of a storage or distribution medium, is
4574 called an "aggregate" if the compilation and its resulting
4575 copyright are not used to limit the access or legal rights of the
4576 compilation's users beyond what the individual works permit.
4577 Inclusion of a covered work in an aggregate does not cause this
4578 License to apply to the other parts of the aggregate.
4580 6. Conveying Non-Source Forms.
4582 You may convey a covered work in object code form under the terms
4583 of sections 4 and 5, provided that you also convey the
4584 machine-readable Corresponding Source under the terms of this
4585 License, in one of these ways:
4587 a. Convey the object code in, or embodied in, a physical product
4588 (including a physical distribution medium), accompanied by the
4589 Corresponding Source fixed on a durable physical medium
4590 customarily used for software interchange.
4592 b. Convey the object code in, or embodied in, a physical product
4593 (including a physical distribution medium), accompanied by a
4594 written offer, valid for at least three years and valid for
4595 as long as you offer spare parts or customer support for that
4596 product model, to give anyone who possesses the object code
4597 either (1) a copy of the Corresponding Source for all the
4598 software in the product that is covered by this License, on a
4599 durable physical medium customarily used for software
4600 interchange, for a price no more than your reasonable cost of
4601 physically performing this conveying of source, or (2) access
4602 to copy the Corresponding Source from a network server at no
4605 c. Convey individual copies of the object code with a copy of
4606 the written offer to provide the Corresponding Source. This
4607 alternative is allowed only occasionally and noncommercially,
4608 and only if you received the object code with such an offer,
4609 in accord with subsection 6b.
4611 d. Convey the object code by offering access from a designated
4612 place (gratis or for a charge), and offer equivalent access
4613 to the Corresponding Source in the same way through the same
4614 place at no further charge. You need not require recipients
4615 to copy the Corresponding Source along with the object code.
4616 If the place to copy the object code is a network server, the
4617 Corresponding Source may be on a different server (operated
4618 by you or a third party) that supports equivalent copying
4619 facilities, provided you maintain clear directions next to
4620 the object code saying where to find the Corresponding Source.
4621 Regardless of what server hosts the Corresponding Source, you
4622 remain obligated to ensure that it is available for as long
4623 as needed to satisfy these requirements.
4625 e. Convey the object code using peer-to-peer transmission,
4626 provided you inform other peers where the object code and
4627 Corresponding Source of the work are being offered to the
4628 general public at no charge under subsection 6d.
4631 A separable portion of the object code, whose source code is
4632 excluded from the Corresponding Source as a System Library, need
4633 not be included in conveying the object code work.
4635 A "User Product" is either (1) a "consumer product", which means
4636 any tangible personal property which is normally used for personal,
4637 family, or household purposes, or (2) anything designed or sold for
4638 incorporation into a dwelling. In determining whether a product
4639 is a consumer product, doubtful cases shall be resolved in favor of
4640 coverage. For a particular product received by a particular user,
4641 "normally used" refers to a typical or common use of that class of
4642 product, regardless of the status of the particular user or of the
4643 way in which the particular user actually uses, or expects or is
4644 expected to use, the product. A product is a consumer product
4645 regardless of whether the product has substantial commercial,
4646 industrial or non-consumer uses, unless such uses represent the
4647 only significant mode of use of the product.
4649 "Installation Information" for a User Product means any methods,
4650 procedures, authorization keys, or other information required to
4651 install and execute modified versions of a covered work in that
4652 User Product from a modified version of its Corresponding Source.
4653 The information must suffice to ensure that the continued
4654 functioning of the modified object code is in no case prevented or
4655 interfered with solely because modification has been made.
4657 If you convey an object code work under this section in, or with,
4658 or specifically for use in, a User Product, and the conveying
4659 occurs as part of a transaction in which the right of possession
4660 and use of the User Product is transferred to the recipient in
4661 perpetuity or for a fixed term (regardless of how the transaction
4662 is characterized), the Corresponding Source conveyed under this
4663 section must be accompanied by the Installation Information. But
4664 this requirement does not apply if neither you nor any third party
4665 retains the ability to install modified object code on the User
4666 Product (for example, the work has been installed in ROM).
4668 The requirement to provide Installation Information does not
4669 include a requirement to continue to provide support service,
4670 warranty, or updates for a work that has been modified or
4671 installed by the recipient, or for the User Product in which it
4672 has been modified or installed. Access to a network may be denied
4673 when the modification itself materially and adversely affects the
4674 operation of the network or violates the rules and protocols for
4675 communication across the network.
4677 Corresponding Source conveyed, and Installation Information
4678 provided, in accord with this section must be in a format that is
4679 publicly documented (and with an implementation available to the
4680 public in source code form), and must require no special password
4681 or key for unpacking, reading or copying.
4683 7. Additional Terms.
4685 "Additional permissions" are terms that supplement the terms of
4686 this License by making exceptions from one or more of its
4687 conditions. Additional permissions that are applicable to the
4688 entire Program shall be treated as though they were included in
4689 this License, to the extent that they are valid under applicable
4690 law. If additional permissions apply only to part of the Program,
4691 that part may be used separately under those permissions, but the
4692 entire Program remains governed by this License without regard to
4693 the additional permissions.
4695 When you convey a copy of a covered work, you may at your option
4696 remove any additional permissions from that copy, or from any part
4697 of it. (Additional permissions may be written to require their own
4698 removal in certain cases when you modify the work.) You may place
4699 additional permissions on material, added by you to a covered work,
4700 for which you have or can give appropriate copyright permission.
4702 Notwithstanding any other provision of this License, for material
4703 you add to a covered work, you may (if authorized by the copyright
4704 holders of that material) supplement the terms of this License
4707 a. Disclaiming warranty or limiting liability differently from
4708 the terms of sections 15 and 16 of this License; or
4710 b. Requiring preservation of specified reasonable legal notices
4711 or author attributions in that material or in the Appropriate
4712 Legal Notices displayed by works containing it; or
4714 c. Prohibiting misrepresentation of the origin of that material,
4715 or requiring that modified versions of such material be
4716 marked in reasonable ways as different from the original
4719 d. Limiting the use for publicity purposes of names of licensors
4720 or authors of the material; or
4722 e. Declining to grant rights under trademark law for use of some
4723 trade names, trademarks, or service marks; or
4725 f. Requiring indemnification of licensors and authors of that
4726 material by anyone who conveys the material (or modified
4727 versions of it) with contractual assumptions of liability to
4728 the recipient, for any liability that these contractual
4729 assumptions directly impose on those licensors and authors.
4731 All other non-permissive additional terms are considered "further
4732 restrictions" within the meaning of section 10. If the Program as
4733 you received it, or any part of it, contains a notice stating that
4734 it is governed by this License along with a term that is a further
4735 restriction, you may remove that term. If a license document
4736 contains a further restriction but permits relicensing or
4737 conveying under this License, you may add to a covered work
4738 material governed by the terms of that license document, provided
4739 that the further restriction does not survive such relicensing or
4742 If you add terms to a covered work in accord with this section, you
4743 must place, in the relevant source files, a statement of the
4744 additional terms that apply to those files, or a notice indicating
4745 where to find the applicable terms.
4747 Additional terms, permissive or non-permissive, may be stated in
4748 the form of a separately written license, or stated as exceptions;
4749 the above requirements apply either way.
4753 You may not propagate or modify a covered work except as expressly
4754 provided under this License. Any attempt otherwise to propagate or
4755 modify it is void, and will automatically terminate your rights
4756 under this License (including any patent licenses granted under
4757 the third paragraph of section 11).
4759 However, if you cease all violation of this License, then your
4760 license from a particular copyright holder is reinstated (a)
4761 provisionally, unless and until the copyright holder explicitly
4762 and finally terminates your license, and (b) permanently, if the
4763 copyright holder fails to notify you of the violation by some
4764 reasonable means prior to 60 days after the cessation.
4766 Moreover, your license from a particular copyright holder is
4767 reinstated permanently if the copyright holder notifies you of the
4768 violation by some reasonable means, this is the first time you have
4769 received notice of violation of this License (for any work) from
4770 that copyright holder, and you cure the violation prior to 30 days
4771 after your receipt of the notice.
4773 Termination of your rights under this section does not terminate
4774 the licenses of parties who have received copies or rights from
4775 you under this License. If your rights have been terminated and
4776 not permanently reinstated, you do not qualify to receive new
4777 licenses for the same material under section 10.
4779 9. Acceptance Not Required for Having Copies.
4781 You are not required to accept this License in order to receive or
4782 run a copy of the Program. Ancillary propagation of a covered work
4783 occurring solely as a consequence of using peer-to-peer
4784 transmission to receive a copy likewise does not require
4785 acceptance. However, nothing other than this License grants you
4786 permission to propagate or modify any covered work. These actions
4787 infringe copyright if you do not accept this License. Therefore,
4788 by modifying or propagating a covered work, you indicate your
4789 acceptance of this License to do so.
4791 10. Automatic Licensing of Downstream Recipients.
4793 Each time you convey a covered work, the recipient automatically
4794 receives a license from the original licensors, to run, modify and
4795 propagate that work, subject to this License. You are not
4796 responsible for enforcing compliance by third parties with this
4799 An "entity transaction" is a transaction transferring control of an
4800 organization, or substantially all assets of one, or subdividing an
4801 organization, or merging organizations. If propagation of a
4802 covered work results from an entity transaction, each party to that
4803 transaction who receives a copy of the work also receives whatever
4804 licenses to the work the party's predecessor in interest had or
4805 could give under the previous paragraph, plus a right to
4806 possession of the Corresponding Source of the work from the
4807 predecessor in interest, if the predecessor has it or can get it
4808 with reasonable efforts.
4810 You may not impose any further restrictions on the exercise of the
4811 rights granted or affirmed under this License. For example, you
4812 may not impose a license fee, royalty, or other charge for
4813 exercise of rights granted under this License, and you may not
4814 initiate litigation (including a cross-claim or counterclaim in a
4815 lawsuit) alleging that any patent claim is infringed by making,
4816 using, selling, offering for sale, or importing the Program or any
4821 A "contributor" is a copyright holder who authorizes use under this
4822 License of the Program or a work on which the Program is based.
4823 The work thus licensed is called the contributor's "contributor
4826 A contributor's "essential patent claims" are all patent claims
4827 owned or controlled by the contributor, whether already acquired or
4828 hereafter acquired, that would be infringed by some manner,
4829 permitted by this License, of making, using, or selling its
4830 contributor version, but do not include claims that would be
4831 infringed only as a consequence of further modification of the
4832 contributor version. For purposes of this definition, "control"
4833 includes the right to grant patent sublicenses in a manner
4834 consistent with the requirements of this License.
4836 Each contributor grants you a non-exclusive, worldwide,
4837 royalty-free patent license under the contributor's essential
4838 patent claims, to make, use, sell, offer for sale, import and
4839 otherwise run, modify and propagate the contents of its
4840 contributor version.
4842 In the following three paragraphs, a "patent license" is any
4843 express agreement or commitment, however denominated, not to
4844 enforce a patent (such as an express permission to practice a
4845 patent or covenant not to sue for patent infringement). To
4846 "grant" such a patent license to a party means to make such an
4847 agreement or commitment not to enforce a patent against the party.
4849 If you convey a covered work, knowingly relying on a patent
4850 license, and the Corresponding Source of the work is not available
4851 for anyone to copy, free of charge and under the terms of this
4852 License, through a publicly available network server or other
4853 readily accessible means, then you must either (1) cause the
4854 Corresponding Source to be so available, or (2) arrange to deprive
4855 yourself of the benefit of the patent license for this particular
4856 work, or (3) arrange, in a manner consistent with the requirements
4857 of this License, to extend the patent license to downstream
4858 recipients. "Knowingly relying" means you have actual knowledge
4859 that, but for the patent license, your conveying the covered work
4860 in a country, or your recipient's use of the covered work in a
4861 country, would infringe one or more identifiable patents in that
4862 country that you have reason to believe are valid.
4864 If, pursuant to or in connection with a single transaction or
4865 arrangement, you convey, or propagate by procuring conveyance of, a
4866 covered work, and grant a patent license to some of the parties
4867 receiving the covered work authorizing them to use, propagate,
4868 modify or convey a specific copy of the covered work, then the
4869 patent license you grant is automatically extended to all
4870 recipients of the covered work and works based on it.
4872 A patent license is "discriminatory" if it does not include within
4873 the scope of its coverage, prohibits the exercise of, or is
4874 conditioned on the non-exercise of one or more of the rights that
4875 are specifically granted under this License. You may not convey a
4876 covered work if you are a party to an arrangement with a third
4877 party that is in the business of distributing software, under
4878 which you make payment to the third party based on the extent of
4879 your activity of conveying the work, and under which the third
4880 party grants, to any of the parties who would receive the covered
4881 work from you, a discriminatory patent license (a) in connection
4882 with copies of the covered work conveyed by you (or copies made
4883 from those copies), or (b) primarily for and in connection with
4884 specific products or compilations that contain the covered work,
4885 unless you entered into that arrangement, or that patent license
4886 was granted, prior to 28 March 2007.
4888 Nothing in this License shall be construed as excluding or limiting
4889 any implied license or other defenses to infringement that may
4890 otherwise be available to you under applicable patent law.
4892 12. No Surrender of Others' Freedom.
4894 If conditions are imposed on you (whether by court order,
4895 agreement or otherwise) that contradict the conditions of this
4896 License, they do not excuse you from the conditions of this
4897 License. If you cannot convey a covered work so as to satisfy
4898 simultaneously your obligations under this License and any other
4899 pertinent obligations, then as a consequence you may not convey it
4900 at all. For example, if you agree to terms that obligate you to
4901 collect a royalty for further conveying from those to whom you
4902 convey the Program, the only way you could satisfy both those
4903 terms and this License would be to refrain entirely from conveying
4906 13. Use with the GNU Affero General Public License.
4908 Notwithstanding any other provision of this License, you have
4909 permission to link or combine any covered work with a work licensed
4910 under version 3 of the GNU Affero General Public License into a
4911 single combined work, and to convey the resulting work. The terms
4912 of this License will continue to apply to the part which is the
4913 covered work, but the special requirements of the GNU Affero
4914 General Public License, section 13, concerning interaction through
4915 a network will apply to the combination as such.
4917 14. Revised Versions of this License.
4919 The Free Software Foundation may publish revised and/or new
4920 versions of the GNU General Public License from time to time.
4921 Such new versions will be similar in spirit to the present
4922 version, but may differ in detail to address new problems or
4925 Each version is given a distinguishing version number. If the
4926 Program specifies that a certain numbered version of the GNU
4927 General Public License "or any later version" applies to it, you
4928 have the option of following the terms and conditions either of
4929 that numbered version or of any later version published by the
4930 Free Software Foundation. If the Program does not specify a
4931 version number of the GNU General Public License, you may choose
4932 any version ever published by the Free Software Foundation.
4934 If the Program specifies that a proxy can decide which future
4935 versions of the GNU General Public License can be used, that
4936 proxy's public statement of acceptance of a version permanently
4937 authorizes you to choose that version for the Program.
4939 Later license versions may give you additional or different
4940 permissions. However, no additional obligations are imposed on any
4941 author or copyright holder as a result of your choosing to follow a
4944 15. Disclaimer of Warranty.
4946 THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
4947 APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
4948 COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS"
4949 WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
4950 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
4951 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE
4952 RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.
4953 SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
4954 NECESSARY SERVICING, REPAIR OR CORRECTION.
4956 16. Limitation of Liability.
4958 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
4959 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES
4960 AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
4961 FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
4962 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
4963 THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
4964 BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
4965 PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
4966 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
4967 THE POSSIBILITY OF SUCH DAMAGES.
4969 17. Interpretation of Sections 15 and 16.
4971 If the disclaimer of warranty and limitation of liability provided
4972 above cannot be given local legal effect according to their terms,
4973 reviewing courts shall apply local law that most closely
4974 approximates an absolute waiver of all civil liability in
4975 connection with the Program, unless a warranty or assumption of
4976 liability accompanies a copy of the Program in return for a fee.
4979 END OF TERMS AND CONDITIONS
4980 ===========================
4982 How to Apply These Terms to Your New Programs
4983 =============================================
4985 If you develop a new program, and you want it to be of the greatest
4986 possible use to the public, the best way to achieve this is to make it
4987 free software which everyone can redistribute and change under these
4990 To do so, attach the following notices to the program. It is safest
4991 to attach them to the start of each source file to most effectively
4992 state the exclusion of warranty; and each file should have at least the
4993 "copyright" line and a pointer to where the full notice is found.
4995 one line to give the program's name and a brief idea
4997 Copyright (C) YEAR NAME OF AUTHOR
4999 This program is free software: you can redistribute it and/or modify
5000 it under the terms of the GNU General Public License as published by
5001 the Free Software Foundation, either version 3 of the License, or (at
5002 your option) any later version.
5004 This program is distributed in the hope that it will be useful, but
5005 WITHOUT ANY WARRANTY; without even the implied warranty of
5006 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
5007 General Public License for more details.
5009 You should have received a copy of the GNU General Public License
5010 along with this program. If not, see `http://www.gnu.org/licenses/'.
5012 Also add information on how to contact you by electronic and paper
5015 If the program does terminal interaction, make it output a short
5016 notice like this when it starts in an interactive mode:
5018 PROGRAM Copyright (C) YEAR NAME OF AUTHOR
5019 This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
5020 This is free software, and you are welcome to redistribute it
5021 under certain conditions; type `show c' for details.
5023 The hypothetical commands `show w' and `show c' should show the
5024 appropriate parts of the General Public License. Of course, your
5025 program's commands might be different; for a GUI interface, you would
5028 You should also get your employer (if you work as a programmer) or
5029 school, if any, to sign a "copyright disclaimer" for the program, if
5030 necessary. For more information on this, and how to apply and follow
5031 the GNU GPL, see `http://www.gnu.org/licenses/'.
5033 The GNU General Public License does not permit incorporating your
5034 program into proprietary programs. If your program is a subroutine
5035 library, you may consider it more useful to permit linking proprietary
5036 applications with the library. If this is what you want to do, use the
5037 GNU Lesser General Public License instead of this License. But first,
5038 please read `http://www.gnu.org/philosophy/why-not-lgpl.html'.
5041 File: gsl-ref.info, Node: GNU Free Documentation License, Next: Function Index, Prev: GNU General Public License, Up: Top
5043 GNU Free Documentation License
5044 ******************************
5046 Version 1.2, November 2002
5047 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
5048 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
5050 Everyone is permitted to copy and distribute verbatim copies of this license
5051 document, but changing it is not allowed.
5055 The purpose of this License is to make a manual, textbook, or other
5056 functional and useful document "free" in the sense of freedom: to
5057 assure everyone the effective freedom to copy and redistribute it,
5058 with or without modifying it, either commercially or
5059 noncommercially. Secondarily, this License preserves for the
5060 author and publisher a way to get credit for their work, while not
5061 being considered responsible for modifications made by others.
5063 This License is a kind of "copyleft", which means that derivative
5064 works of the document must themselves be free in the same sense.
5065 It complements the GNU General Public License, which is a copyleft
5066 license designed for free software.
5068 We have designed this License in order to use it for manuals for
5069 free software, because free software needs free documentation: a
5070 free program should come with manuals providing the same freedoms
5071 that the software does. But this License is not limited to
5072 software manuals; it can be used for any textual work, regardless
5073 of subject matter or whether it is published as a printed book.
5074 We recommend this License principally for works whose purpose is
5075 instruction or reference.
5077 1. APPLICABILITY AND DEFINITIONS
5079 This License applies to any manual or other work, in any medium,
5080 that contains a notice placed by the copyright holder saying it
5081 can be distributed under the terms of this License. Such a notice
5082 grants a world-wide, royalty-free license, unlimited in duration,
5083 to use that work under the conditions stated herein. The
5084 "Document", below, refers to any such manual or work. Any member
5085 of the public is a licensee, and is addressed as "you". You
5086 accept the license if you copy, modify or distribute the work in a
5087 way requiring permission under copyright law.
5089 A "Modified Version" of the Document means any work containing the
5090 Document or a portion of it, either copied verbatim, or with
5091 modifications and/or translated into another language.
5093 A "Secondary Section" is a named appendix or a front-matter section
5094 of the Document that deals exclusively with the relationship of the
5095 publishers or authors of the Document to the Document's overall
5096 subject (or to related matters) and contains nothing that could
5097 fall directly within that overall subject. (Thus, if the Document
5098 is in part a textbook of mathematics, a Secondary Section may not
5099 explain any mathematics.) The relationship could be a matter of
5100 historical connection with the subject or with related matters, or
5101 of legal, commercial, philosophical, ethical or political position
5104 The "Invariant Sections" are certain Secondary Sections whose
5105 titles are designated, as being those of Invariant Sections, in
5106 the notice that says that the Document is released under this
5107 License. If a section does not fit the above definition of
5108 Secondary then it is not allowed to be designated as Invariant.
5109 The Document may contain zero Invariant Sections. If the Document
5110 does not identify any Invariant Sections then there are none.
5112 The "Cover Texts" are certain short passages of text that are
5113 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
5114 that says that the Document is released under this License. A
5115 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
5116 be at most 25 words.
5118 A "Transparent" copy of the Document means a machine-readable copy,
5119 represented in a format whose specification is available to the
5120 general public, that is suitable for revising the document
5121 straightforwardly with generic text editors or (for images
5122 composed of pixels) generic paint programs or (for drawings) some
5123 widely available drawing editor, and that is suitable for input to
5124 text formatters or for automatic translation to a variety of
5125 formats suitable for input to text formatters. A copy made in an
5126 otherwise Transparent file format whose markup, or absence of
5127 markup, has been arranged to thwart or discourage subsequent
5128 modification by readers is not Transparent. An image format is
5129 not Transparent if used for any substantial amount of text. A
5130 copy that is not "Transparent" is called "Opaque".
5132 Examples of suitable formats for Transparent copies include plain
5133 ASCII without markup, Texinfo input format, LaTeX input format,
5134 SGML or XML using a publicly available DTD, and
5135 standard-conforming simple HTML, PostScript or PDF designed for
5136 human modification. Examples of transparent image formats include
5137 PNG, XCF and JPG. Opaque formats include proprietary formats that
5138 can be read and edited only by proprietary word processors, SGML or
5139 XML for which the DTD and/or processing tools are not generally
5140 available, and the machine-generated HTML, PostScript or PDF
5141 produced by some word processors for output purposes only.
5143 The "Title Page" means, for a printed book, the title page itself,
5144 plus such following pages as are needed to hold, legibly, the
5145 material this License requires to appear in the title page. For
5146 works in formats which do not have any title page as such, "Title
5147 Page" means the text near the most prominent appearance of the
5148 work's title, preceding the beginning of the body of the text.
5150 A section "Entitled XYZ" means a named subunit of the Document
5151 whose title either is precisely XYZ or contains XYZ in parentheses
5152 following text that translates XYZ in another language. (Here XYZ
5153 stands for a specific section name mentioned below, such as
5154 "Acknowledgements", "Dedications", "Endorsements", or "History".)
5155 To "Preserve the Title" of such a section when you modify the
5156 Document means that it remains a section "Entitled XYZ" according
5159 The Document may include Warranty Disclaimers next to the notice
5160 which states that this License applies to the Document. These
5161 Warranty Disclaimers are considered to be included by reference in
5162 this License, but only as regards disclaiming warranties: any other
5163 implication that these Warranty Disclaimers may have is void and
5164 has no effect on the meaning of this License.
5168 You may copy and distribute the Document in any medium, either
5169 commercially or noncommercially, provided that this License, the
5170 copyright notices, and the license notice saying this License
5171 applies to the Document are reproduced in all copies, and that you
5172 add no other conditions whatsoever to those of this License. You
5173 may not use technical measures to obstruct or control the reading
5174 or further copying of the copies you make or distribute. However,
5175 you may accept compensation in exchange for copies. If you
5176 distribute a large enough number of copies you must also follow
5177 the conditions in section 3.
5179 You may also lend copies, under the same conditions stated above,
5180 and you may publicly display copies.
5182 3. COPYING IN QUANTITY
5184 If you publish printed copies (or copies in media that commonly
5185 have printed covers) of the Document, numbering more than 100, and
5186 the Document's license notice requires Cover Texts, you must
5187 enclose the copies in covers that carry, clearly and legibly, all
5188 these Cover Texts: Front-Cover Texts on the front cover, and
5189 Back-Cover Texts on the back cover. Both covers must also clearly
5190 and legibly identify you as the publisher of these copies. The
5191 front cover must present the full title with all words of the
5192 title equally prominent and visible. You may add other material
5193 on the covers in addition. Copying with changes limited to the
5194 covers, as long as they preserve the title of the Document and
5195 satisfy these conditions, can be treated as verbatim copying in
5198 If the required texts for either cover are too voluminous to fit
5199 legibly, you should put the first ones listed (as many as fit
5200 reasonably) on the actual cover, and continue the rest onto
5203 If you publish or distribute Opaque copies of the Document
5204 numbering more than 100, you must either include a
5205 machine-readable Transparent copy along with each Opaque copy, or
5206 state in or with each Opaque copy a computer-network location from
5207 which the general network-using public has access to download
5208 using public-standard network protocols a complete Transparent
5209 copy of the Document, free of added material. If you use the
5210 latter option, you must take reasonably prudent steps, when you
5211 begin distribution of Opaque copies in quantity, to ensure that
5212 this Transparent copy will remain thus accessible at the stated
5213 location until at least one year after the last time you
5214 distribute an Opaque copy (directly or through your agents or
5215 retailers) of that edition to the public.
5217 It is requested, but not required, that you contact the authors of
5218 the Document well before redistributing any large number of
5219 copies, to give them a chance to provide you with an updated
5220 version of the Document.
5224 You may copy and distribute a Modified Version of the Document
5225 under the conditions of sections 2 and 3 above, provided that you
5226 release the Modified Version under precisely this License, with
5227 the Modified Version filling the role of the Document, thus
5228 licensing distribution and modification of the Modified Version to
5229 whoever possesses a copy of it. In addition, you must do these
5230 things in the Modified Version:
5232 A. Use in the Title Page (and on the covers, if any) a title
5233 distinct from that of the Document, and from those of
5234 previous versions (which should, if there were any, be listed
5235 in the History section of the Document). You may use the
5236 same title as a previous version if the original publisher of
5237 that version gives permission.
5239 B. List on the Title Page, as authors, one or more persons or
5240 entities responsible for authorship of the modifications in
5241 the Modified Version, together with at least five of the
5242 principal authors of the Document (all of its principal
5243 authors, if it has fewer than five), unless they release you
5244 from this requirement.
5246 C. State on the Title page the name of the publisher of the
5247 Modified Version, as the publisher.
5249 D. Preserve all the copyright notices of the Document.
5251 E. Add an appropriate copyright notice for your modifications
5252 adjacent to the other copyright notices.
5254 F. Include, immediately after the copyright notices, a license
5255 notice giving the public permission to use the Modified
5256 Version under the terms of this License, in the form shown in
5259 G. Preserve in that license notice the full lists of Invariant
5260 Sections and required Cover Texts given in the Document's
5263 H. Include an unaltered copy of this License.
5265 I. Preserve the section Entitled "History", Preserve its Title,
5266 and add to it an item stating at least the title, year, new
5267 authors, and publisher of the Modified Version as given on
5268 the Title Page. If there is no section Entitled "History" in
5269 the Document, create one stating the title, year, authors,
5270 and publisher of the Document as given on its Title Page,
5271 then add an item describing the Modified Version as stated in
5272 the previous sentence.
5274 J. Preserve the network location, if any, given in the Document
5275 for public access to a Transparent copy of the Document, and
5276 likewise the network locations given in the Document for
5277 previous versions it was based on. These may be placed in
5278 the "History" section. You may omit a network location for a
5279 work that was published at least four years before the
5280 Document itself, or if the original publisher of the version
5281 it refers to gives permission.
5283 K. For any section Entitled "Acknowledgements" or "Dedications",
5284 Preserve the Title of the section, and preserve in the
5285 section all the substance and tone of each of the contributor
5286 acknowledgements and/or dedications given therein.
5288 L. Preserve all the Invariant Sections of the Document,
5289 unaltered in their text and in their titles. Section numbers
5290 or the equivalent are not considered part of the section
5293 M. Delete any section Entitled "Endorsements". Such a section
5294 may not be included in the Modified Version.
5296 N. Do not retitle any existing section to be Entitled
5297 "Endorsements" or to conflict in title with any Invariant
5300 O. Preserve any Warranty Disclaimers.
5302 If the Modified Version includes new front-matter sections or
5303 appendices that qualify as Secondary Sections and contain no
5304 material copied from the Document, you may at your option
5305 designate some or all of these sections as invariant. To do this,
5306 add their titles to the list of Invariant Sections in the Modified
5307 Version's license notice. These titles must be distinct from any
5308 other section titles.
5310 You may add a section Entitled "Endorsements", provided it contains
5311 nothing but endorsements of your Modified Version by various
5312 parties--for example, statements of peer review or that the text
5313 has been approved by an organization as the authoritative
5314 definition of a standard.
5316 You may add a passage of up to five words as a Front-Cover Text,
5317 and a passage of up to 25 words as a Back-Cover Text, to the end
5318 of the list of Cover Texts in the Modified Version. Only one
5319 passage of Front-Cover Text and one of Back-Cover Text may be
5320 added by (or through arrangements made by) any one entity. If the
5321 Document already includes a cover text for the same cover,
5322 previously added by you or by arrangement made by the same entity
5323 you are acting on behalf of, you may not add another; but you may
5324 replace the old one, on explicit permission from the previous
5325 publisher that added the old one.
5327 The author(s) and publisher(s) of the Document do not by this
5328 License give permission to use their names for publicity for or to
5329 assert or imply endorsement of any Modified Version.
5331 5. COMBINING DOCUMENTS
5333 You may combine the Document with other documents released under
5334 this License, under the terms defined in section 4 above for
5335 modified versions, provided that you include in the combination
5336 all of the Invariant Sections of all of the original documents,
5337 unmodified, and list them all as Invariant Sections of your
5338 combined work in its license notice, and that you preserve all
5339 their Warranty Disclaimers.
5341 The combined work need only contain one copy of this License, and
5342 multiple identical Invariant Sections may be replaced with a single
5343 copy. If there are multiple Invariant Sections with the same name
5344 but different contents, make the title of each such section unique
5345 by adding at the end of it, in parentheses, the name of the
5346 original author or publisher of that section if known, or else a
5347 unique number. Make the same adjustment to the section titles in
5348 the list of Invariant Sections in the license notice of the
5351 In the combination, you must combine any sections Entitled
5352 "History" in the various original documents, forming one section
5353 Entitled "History"; likewise combine any sections Entitled
5354 "Acknowledgements", and any sections Entitled "Dedications". You
5355 must delete all sections Entitled "Endorsements."
5357 6. COLLECTIONS OF DOCUMENTS
5359 You may make a collection consisting of the Document and other
5360 documents released under this License, and replace the individual
5361 copies of this License in the various documents with a single copy
5362 that is included in the collection, provided that you follow the
5363 rules of this License for verbatim copying of each of the
5364 documents in all other respects.
5366 You may extract a single document from such a collection, and
5367 distribute it individually under this License, provided you insert
5368 a copy of this License into the extracted document, and follow
5369 this License in all other respects regarding verbatim copying of
5372 7. AGGREGATION WITH INDEPENDENT WORKS
5374 A compilation of the Document or its derivatives with other
5375 separate and independent documents or works, in or on a volume of
5376 a storage or distribution medium, is called an "aggregate" if the
5377 copyright resulting from the compilation is not used to limit the
5378 legal rights of the compilation's users beyond what the individual
5379 works permit. When the Document is included in an aggregate, this
5380 License does not apply to the other works in the aggregate which
5381 are not themselves derivative works of the Document.
5383 If the Cover Text requirement of section 3 is applicable to these
5384 copies of the Document, then if the Document is less than one half
5385 of the entire aggregate, the Document's Cover Texts may be placed
5386 on covers that bracket the Document within the aggregate, or the
5387 electronic equivalent of covers if the Document is in electronic
5388 form. Otherwise they must appear on printed covers that bracket
5389 the whole aggregate.
5393 Translation is considered a kind of modification, so you may
5394 distribute translations of the Document under the terms of section
5395 4. Replacing Invariant Sections with translations requires special
5396 permission from their copyright holders, but you may include
5397 translations of some or all Invariant Sections in addition to the
5398 original versions of these Invariant Sections. You may include a
5399 translation of this License, and all the license notices in the
5400 Document, and any Warranty Disclaimers, provided that you also
5401 include the original English version of this License and the
5402 original versions of those notices and disclaimers. In case of a
5403 disagreement between the translation and the original version of
5404 this License or a notice or disclaimer, the original version will
5407 If a section in the Document is Entitled "Acknowledgements",
5408 "Dedications", or "History", the requirement (section 4) to
5409 Preserve its Title (section 1) will typically require changing the
5414 You may not copy, modify, sublicense, or distribute the Document
5415 except as expressly provided for under this License. Any other
5416 attempt to copy, modify, sublicense or distribute the Document is
5417 void, and will automatically terminate your rights under this
5418 License. However, parties who have received copies, or rights,
5419 from you under this License will not have their licenses
5420 terminated so long as such parties remain in full compliance.
5422 10. FUTURE REVISIONS OF THIS LICENSE
5424 The Free Software Foundation may publish new, revised versions of
5425 the GNU Free Documentation License from time to time. Such new
5426 versions will be similar in spirit to the present version, but may
5427 differ in detail to address new problems or concerns. See
5428 `http://www.gnu.org/copyleft/'.
5430 Each version of the License is given a distinguishing version
5431 number. If the Document specifies that a particular numbered
5432 version of this License "or any later version" applies to it, you
5433 have the option of following the terms and conditions either of
5434 that specified version or of any later version that has been
5435 published (not as a draft) by the Free Software Foundation. If
5436 the Document does not specify a version number of this License,
5437 you may choose any version ever published (not as a draft) by the
5438 Free Software Foundation.
5440 ADDENDUM: How to use this License for your documents
5441 ====================================================
5443 To use this License in a document you have written, include a copy of
5444 the License in the document and put the following copyright and license
5445 notices just after the title page:
5447 Copyright (C) YEAR YOUR NAME.
5448 Permission is granted to copy, distribute and/or modify
5449 this document under the terms of the GNU Free
5450 Documentation License, Version 1.2 or any later version
5451 published by the Free Software Foundation; with no
5452 Invariant Sections, no Front-Cover Texts, and no
5453 Back-Cover Texts. A copy of the license is included in
5454 the section entitled ``GNU Free Documentation License''.
5456 If you have Invariant Sections, Front-Cover Texts and Back-Cover
5457 Texts, replace the "with...Texts." line with this:
5459 with the Invariant Sections being LIST THEIR
5460 TITLES, with the Front-Cover Texts being LIST, and
5461 with the Back-Cover Texts being LIST.
5463 If you have Invariant Sections without Cover Texts, or some other
5464 combination of the three, merge those two alternatives to suit the
5467 If your document contains nontrivial examples of program code, we
5468 recommend releasing these examples in parallel under your choice of
5469 free software license, such as the GNU General Public License, to
5470 permit their use in free software.