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 1.828927267118668d-318 1.4821969375237396d-321 2.023692885365746d-320
which returns as multiple values the three function values, along with the estimated errors of each. 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)
or equivalently the vector arguments may be specified with reals,
(cdot #2m(-34.5d0 8.24d0 3.29d0 -8.93d0 34.12d0 -6.15d0) #2m(49.27d0 -13.49d0 32.5d0 42.73d0 -17.24d0 43.31d0)) #C(-2940.2118d0 1861.9380999999998d0)
There are over 1500 examples available from within GSLL with the
function examples
. These examples also serve
as a test suite for GSLL.
Requirements
GSLL should work in any Common Lisp implementation and platform combination for which the following are supported:
- GSL
- CFFI and cffi-grovel,
version 0.10.5 or newer; callbacks and
foreign-funcall
must be supported. - trivial-garbage
- cl-utilities
- ASDF
- lisp-unit, (Optional) necessary
to run
gsll-tests
- FSBV, (Optional) necessary for functions using complex scalars or simulated annealing
- iterate and asdf-system-connnections, (Optional) provides a convenient way to iterate over elements or indices of vectors or matrices.
GSLL has been tested with SBCL and CCL on Debian amd64, and SBCL and CLISP on Debian i386. There are some known failures; see status.text.
Download and Install
With git and asdf
Download/update:
git clone git://repo.or.cz/gsll.git
git clone git://repo.or.cz/fsbv.git
darcs get http://common-lisp.net/~loliveira/darcs/trivial-garbage
git pull
in thegsll
andfsbv
directories afterwards to update
The repository web page
can be used to browse or retrieve a compressed tarball (click the most
recent "snapshot" link).
You will need to make a link of gsll.asd
and
optionally gsll-tests.asd
to some directory known to ASDF.
Then in Lisp, load the system:
(asdf:operate 'asdf:load-op :gsll)
If you wish to run the test suite, you must get lisp-unit and make it known to ASDF:
git clone git://repo.or.cz/lisp-unit.git
The test suite may be run with
(asdf:operate 'asdf:load-op :gsll-tests)
(in-package :gsl)
(lisp-unit:run-tests)
Please see status.text for known failures.
With clbuild
First, make sure that the development versions of GSL and libffi are
loaded, e.g. in Debian/Ubuntu libgsl0-dev
and libffi-dev
.
Add the following to wnpp-projects
:
gsll get_git git://repo.or.cz/gsll.git
fsbv get_git git://repo.or.cz/fsbv.git
lisp-unit get_git git://repo.or.cz/lisp-unit.git
and add
gsll cffi trivial-garbage cl-utilities lisp-unit fsbv iterate asdf-system-connections
to dependencies
and execute
from within the clbuild directory:
sudo ./clbuild update gsll
With Debian or Ubuntu
sudo aptitude install libgsl0-dev cl-cffi cl-utilities libffi-dev cl-iterate
git clone git://repo.or.cz/gsll.git
git clone git://repo.or.cz/fsbv.git
darcs get http://common-lisp.net/~loliveira/darcs/trivial-garbage
darcs get http://common-lisp.net/project/asdf-system-connections
clc-register-user-package gsll/gsll.asd
clc-register-user-package gsll/gsll-tests.asd
clc-register-user-package trivial-garbage/trivial-garbage.asd
clc-register-user-package fsbv/fsbv.asd
clc-register-user-package asdf-system-connections/asdf-system-connections.asd
After starting your Lisp implementation,
(clc:clc-require :gsll-tests)
License
This software is distributed under the LLGPL and FDL; see the file COPYING. There is absolutely no warranty.
Documentation
General Advice
The following techniques for using the API are advised:
- Find the appropriate function(s) in the GSL documentation.
- Use the GSLL function
gsl-lookup
to find the equivalent GSLL function, for example(gsl-lookup "gsl_sf_elljac_e") JACOBIAN-ELLIPTIC-FUNCTIONS T
to find that the Lisp function name is
#'jacobian-elliptic-functions
. - Look at the documentation for that Lisp function, e.g.
(documentation #'jacobian-elliptic-functions 'function) "The Jacobian elliptic functions sn(u|m), cn(u|m), dn(u|m) computed by descending Landen transformations."
to get an explanation of the arguments etc.
- Use the function
(examples)
without an argument to get a list of example categories. Then use the function with a category name as the argument to get a list of examples under that category, for example(examples 'higher-moments)
. The result will be a list of forms, each providing an example of usage in the relevant topic. If the GSL documentation provides an example, there will usually be the same or similar example provided in GSLL. Note: Some of the examples are intentionally designed to signal an error, because the examples also serve as a regression (unit) test suite for GSLL.
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). 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 *array-element-types*
. On implementations that
support it (currently only SBCL), the contents are directly available
to the GSL functions without copying between the Lisp area and the C
area of memory.
Common Lisp arrays should be created with make-marray
or
#m
:
The #m reader macro in the default form creates a vector or matrix of
element type double-float, which is the most common type needed for
GSL functions. It optionally takes a numeric argument prefix as in
the example above to make an array with a different element type; a
guide to the numeric argument is given below. It should be
followed by a list; this list will be evaluated. If the list
contains ^
, the object created will be a matrix
and each row is ended with that symbol.
Classes of vectors and matrices are named by appending the element type as hypenated words to "vector" or "matrix". The following table shows the classes available on a 64-bit platform:
Element type | Vector class name | Matrix class name | #m prefix |
---|---|---|---|
double-float | vector-double-float | matrix-double-float | 1 or empty |
(complex double-float) | vector-complex-double-float | matrix-complex-double-float | 2 |
single-float | vector-single-float | matrix-single-float | 3 |
(complex single-float) | vector-complex-single-float | matrix-complex-single-float | 4 |
(signed-byte 8) | vector-signed-byte-8 | matrix-signed-byte-8 | 7 |
(unsigned-byte 8) | vector-unsigned-byte-8 | matrix-unsigned-byte-8 | 8 |
(signed-byte 16) | vector-signed-byte-16 | matrix-signed-byte-16 | 15 |
(unsigned-byte 16) | vector-unsigned-byte-16 | matrix-unsigned-byte-16 | 16 |
(signed-byte 32) | vector-signed-byte-32 | matrix-signed-byte-32 | 31 |
(unsigned-byte 32) | vector-unsigned-byte-32 | matrix-unsigned-byte-32 | 32 |
(signed-byte 64) | vector-signed-byte-64 | matrix-signed-byte-64 | 63 |
(unsigned-byte 64) | vector-unsigned-byte-64 | matrix-unsigned-byte-64 | 64 |
Individual elements are obtained using maref
(analogous
to Lisp's aref
), and are set
with setf maref
. A complete CL array may
be extracted with the function #'cl-array
.
Copying marrays is performed with the function copy
.
This works between marrays, pointers, and CL arrays. It is useful
for functions intended to be passed to GSL functions (for
e.g. solving, minimizing or fitting) that need to set a GSL vector
or matrix, because one can simply copy into the passed-in pointer.
There are two functions provided to extract the dimensions of a
vector or array: dim0
and dim1
; the latter
is applicable only for matrices.
If you use iterate, there are extensions defined that make it easier to iterate over marrays. These are:
matrix-row
,matrix-row-index
matrix-column
,matrix-column-index
vector-element
,vector-element-index
matrix-element
,matrix-element-index
For example,
(defparameter m1 #m(1 2 3 ^ 0 6 8)) (iter:iter (iter:for e :matrix-element m1) (princ e) (princ " ")) 1.0 2.0 3.0 0.0 0.0 6.0 8.0
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.
invert-matrix
finds the inverse of a matrix and uses GSL's LU decomposition functions.- IEEE floating point number analysis.
fft-frequency-vector
returns a vector where the sample frequencies are contained. If you perform an FFT on a vector of a given size and :sample-size, this vector will contain the sample frequencies in order. If the :shifted keyword is T, then the frequencies are ordered in ascending order.fft-shift
returns a copy of a vector where the zero frequency has been shifted to the center; the frequency components will be sorted according to their frequency, in ascending order. Optionally, a :stride can be provided.fft-inverse-shift
performs the inverse action of fft-shift; the zero and positive frequency components are shifted to the beginning, so that the resulting vector is suitable for an inverse FFT. Optionally, a :stride can be provided.
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. In addition, I am frequently on #lisp IRC channel as LiamH.