About

The GNU Scientific Library for Lisp (GSLL) allows you to use the GNU Scientific Library (GSL) from Common Lisp. This library provides a full range of common mathematical operations useful to scientific and engineering applications. The design of the GSLL interface is such that access to most of the GSL library is possible in a Lisp-natural way; the intent is that the user not be hampered by the restrictions of the C language in which GSL has been written. GSLL thus provides interactive use of GSL for getting quick answers, even for someone not intending to program in Lisp.

Topics include: polynomials, special functions, vectors and matrices, permutations, sorting, linear algebra including BLAS, eigensystems, fast Fourier transforms (FFT), quadrature, random numbers, quasi-random sequences, random distributions, statistics, histograms, N-tuples, Monte Carlo integration, simulated annealing, ordinary differential equations, interpolation, numerical integration, numerical differentiation, Chebyshev approximation, series acceleration, discrete Hankel transforms, root-finding, minimization, least-squares fitting, IEEE floating-point, discrete wavelet transforms, basis splines, physical constants. See missing-features.text on the status of some incomplete topics.

Examples

The Jacobian elliptic functions sn, cn, and dn are special functions (Chapter 7):

(jacobian-elliptic-functions 0.2d0 0.81d0)
0.19762082367187703d0
0.9802785369736752d0
0.9840560289645665d0

which returns as multiple values the three function values. The functions are defined only if the second argument m is not greater than 1, so an error is signalled if this parameter is out of range:

(jacobian-elliptic-functions 0.61802d0 1.5d0)
Input domain error |m| > 1.0 in elljac.c at line 46
   [Condition of type INPUT-DOMAIN]

This is an ordinary Lisp error which may be handled with standard definitions available in Lisp. To take the complex conjugate scalar product of two complex vectors of length 3:

(cdot #2m(#c(-34.5d0 8.24d0) #c(3.29d0 -8.93d0) #c(34.12d0 -6.15d0))
      #2m(#c(49.27d0 -13.49d0) #c(32.5d0 42.73d0) #c(-17.24d0 43.31d0)))
#C(-2940.2118d0 1861.9380999999998d0)

There are over 1500 examples available from within GSLL with the function examples. There is also a suite of over 4000 tests; many of the examples also serve as tests, and most others are ported from GSL's tests.

Requirements

GSLL should work in any Common Lisp implementation and platform combination for which the following are supported:

Most users will not need to worry about their implementation and operating system, as all these are supported if the needed libraries are installed (see below). The use of CLISP, however, is not recommended.

Download and Install

Download

Use quicklisp and follow the instructions. You will need to make sure that the libraries and header files associated with GNU Scientific Library (GSL) and libffi are installed; your distribution may name these libgsl0-dev and libffi-dev. Once they are installed and you have loaded the quicklisp file:

   (ql:quickload "gsll")

To test your installation:

   (ql:quickload "lisp-unit")
   (in-package :gsl)
   (lisp-unit:run-tests)

The result should look something like:

ABSOLUTE-DEVIATION: 1 assertions passed, 0 failed.
ABSOLUTE-SUM: 4 assertions passed, 0 failed.
AIRY: 73 assertions passed, 0 failed.

... (many lines deleted) ...

VECTOR-VARIANCE-WITH-MEAN: 10 assertions passed, 0 failed.
WEIBULL: 60 assertions passed, 0 failed.
ZETA: 6 assertions passed, 0 failed.
TOTAL: 4022 assertions passed, 1 failed, 0 execution errors.

You may see more failures; if you are not on a 64 bit platform you will see fewer assertions.

License

This software is distributed under the GPL ; see the file COPYING. There is absolutely no warranty.

Documentation

General Advice

The following techniques for using the API are advised:

Some examples are not yet present in, or are too complicated for, the function #'examples. In this case, you need to look in the relevant source file; they are in either a separate file of examples, or at the end of the file of definitions. It is advisable to look at the examples first for calculations that require more complex setup (generally, the later chapters in the GSL manual).

Arrays

GSLL has many functions that work on vectors (one-dimensional arrays) and matrices (two-dimensional arrays). Foreign arrays are defined and manipulated using the Antik which defines generic operations on array-like objects; see the Antik documentation for more information. GSLL supports all array element types that are supported by CFFI, the CL implementation, GSL, and the platform. This list is available in the variable grid:*array-element-types*.

Passing functions

Functions that are passed to GSL functions (known as callbacks in C) are specified with a function designator for the CL function, that is, either the function object itself or a symbol denoting the function. There is usually an option scalarsp for functions that take or return arrays that, if true, will send the user function the argument element by element, and expect the return values to be the individual elements.

GSL objects

There are a number of GSL objects other than arrays that can be created:

acceleration interpolation levin levin-truncated spline
nonlinear-ffit nonlinear-fdffit
one-dimensional-root-solver-f one-dimensional-root-solver-fdf
multi-dimensional-minimizer-f multi-dimensional-minimizer-fdf
fit-workspace one-dimensional-minimizer
multi-dimensional-root-solver-f multi-dimensional-root-solver-fdf
histogram histogram2d histogram-pdf histogram2d-pdf
basis-spline chebyshev hankel wavelet wavelet-workspace
random-number-generator quasi-random-number-generator discrete-random
polynomial-complex-workspace integration-workspace
qaws-table qawo-table
eigen-symm eigen-symmv eigen-herm eigen-hermv
eigen-nonsymm eigen-nonsymmv eigen-gensymm eigen-gensymmv
eigen-gen eigen-genv
monte-carlo-plain monte-carlo-miser monte-carlo-vegas
ode-stepper ode-evolution standard-control y-control
yp-control scaled-control
fft-real-wavetable-double-float fft-real-wavetable-single-float
fft-real-workspace-double-float fft-real-workspace-single-float
fft-complex-wavetable-double-float fft-complex-wavetable-single-float
fft-complex-workspace-double-float fft-complex-workspace-single-float
fft-half-complex-wavetable-double-float fft-half-complex-wavetable-single-float

An instance may be created with a function whose name is "make-" followed by the class name, e.g. make-histogram. The arguments that the function takes depends on the class.

Additional definitions

Some definitions are provided because of their usefulness, even though GSL doesn't have them.

Status

GSLL is largely complete and usable, with functioning interfaces to most of GSL. Some functionality is not yet ported; see missing-features.text for more details. Known bugs are documented in status.text. Work is ongoing to both remedy those deficiencies and to simplify the user interface by changing more required arguments into optional or key arguments with useful default values. Typically, these arguments bind GSL objects and arrays used internally or for function return.

Contact

There is a mailing list for all aspects of this project, including bug reports. See also the archives. In addition, I am frequently on #lisp IRC channel as LiamH.

For bug reports, please use the mailing list. If you have patch(es) and use git, please commit your changes and do:

git format-patch origin

This will produce one or more files whose names start with a four-digit number; please attach them all to your email.