GSLL Documentation

GSLL Documentation

General Advice

There is little separate documentation for GSLL. Instead, the following techniques for using the API are advised:

It is advisable to look at the examples first for calculations that require more complex setup (generally, the later chapters in the GSL manual).

GSL objects and letm

There are a number of GSL structures available that must be manually allocated, possibly set, and freed. In order to make this as convenient as possible, the macro letm is provided. This macro acts as a let*, with the additional feature that if the init-form is one of GSL objects
acceleration basis-spline chebyshev combination complex-workspace
discrete-random eigen-herm eigen-hermv eigen-symm eigen-symmv
fdfsolver fit-workspace fminimizer fsolver hankel histogram
integration-workspace interpolation levin levin-truncated
matrix-* mfdfminimizer mfdfsolver mfminimizer mfsolver
monte-carlo-miser monte-carlo-plain monte-carlo-vegas
nonlinear-fdffit nonlinear-ffit permutation
quasi-random-number-generator random-number-generator spline
vector-* wavelet wavelet-workspace
the appropriate object will be allocated and bound to the variable, optionally set, and then freed when the body of the let is exited. For Lisp environments with arglist prompting (such as SLIME), these are functions whose symbols are exported so that an arglist prompt will be visible; however, the function should not be used outside a letm binding.

Arrays

FIX: #m, #nm, make-array*

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, and GSL. This list is available in the variable *array-element-types*. These arrays are foreign-friendly, meaning that on platforms 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-array*; the syntax is similar to Common Lisp's make-array except that the second argument element-type is mandatory. If this function is used, the resultant array is foreign friendly. It can then be used as an argument in the letm binding. Alternatively, a literal array can be created in the letm binding using the macros a (non-evaluating) or a* (evaluating).

Classes of vectors and matrices are names by appending the element type as hypenated words to "vector" or "matrix". The following table shows the classes available on SBCL on an amd64 platform.

Element types, vector and matrix classes
Element typeVector class nameMatrix class name
single-floatvector-single-floatmatrix-single-float
double-floatvector-double-floatmatrix-double-float
(complex single-float)vector-complex-single-floatmatrix-complex-single-float
(complex double-float)vector-complex-double-floatmatrix-complex-double-float
(signed-byte 8)vector-signed-byte-8matrix-signed-byte-8
(unsigned-byte 8)vector-unsigned-byte-8matrix-unsigned-byte-8
(signed-byte 16)vector-signed-byte-16matrix-signed-byte-16
(unsigned-byte 16)vector-unsigned-byte-16matrix-unsigned-byte-16
(signed-byte 32)vector-signed-byte-32matrix-signed-byte-32
(unsigned-byte 32)vector-unsigned-byte-32matrix-unsigned-byte-32
(signed-byte 64)vector-signed-byte-64matrix-signed-byte-64
(unsigned-byte 64)vector-unsigned-byte-64matrix-unsigned-byte-64

The class name serves as the binding form in the letm. For example, the following form sums two vectors:

(letm ((vec1 (vector-double-float (a -3.21d0 1.0d0 12.8d0)))
       (vec2 (vector-double-float (a -1.88d0 -1.0d0 4.1d0))))
   (m+ vec1 vec2))
#<VECTOR-DOUBLE-FLOAT #(-5.09d0 0.0d0 16.9d0)>

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. This array may subsequently be used in later GSL functions by providing it as the argument in the letm binding.

Additional definitions

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

Status

Consistent with the development philosophy, most of the interface to the library is done. Notes on particular chapters:
  • Reading and writing through the GSL library is not supported due to lack of support for foreign streams in Lisp.
  • For Vectors and Matrices, subvectors and views are not defined. For GSL functions that take a stride, it is pre-set to 1 in GSLL.
  • BLAS is completed, but with only very limited testing.
  • FFTs have not been done because GSL does not supply an example and it is not clear how it is used. Contributions welcome.
  • Simulated Annealing is known to have problems in GSL and a replacement is being redesigned; the version distributed has been ported in GSLL but does not work.
  • Wavelet Transforms has been done but the results of the example do not agree with the GSL manual.
  • Discrete Hankel Transforms has been done but there is no example given in the GSL manual.
  • Basis splines example runs, but the GSL documentation does not provide the result for comparison.

There are failures observed in the regression tests (lisp-unit:run-tests):

  • CLISP shows three "foreign callout errors." Remedy unknown.
  • There are several regression failures that are apparently due to changes in GSL between versions 1.8 and 1.10. These are: beta, chi-squared, dirichlet, elliptic-functions, fdist, gamma-randist, negative-binomial.