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 block-complex block-double block-fixnum
block-single 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-complex matrix-double
matrix-fixnum matrix-single 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-complex vector-double vector-fixnum vector-single 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 let binding.

Data: vectors, matrices, etc.

Collectively, vectors, matrices, histograms and the like are called data. There are many different types of vectors and matrices supported by GSL, but GSLL has implemented only a few of these: complex, double-float, single-float, and fixnum, because those types are defined by the Common Lisp standard.

Vectors and matrices can be converted to and from their Lisp counterparts with data and (setf data). Setting the GSL value to a Lisp value at initialization can be done within the letm by giving the Lisp value as the first argument after the type, for example

(letm ((vec (vector-double #(-3.21d0 1.0d0 12.8d0))))
   (data vec))
Individual elements of data may be accessed with maref, either directly or in a setf.

Status

Consistent with the development philosophy, most of the interface to the library is done. Notes on particular chapters:
  • Vectors and Matrices are done for integer, real, double, complex. Subvectors and views don't work. Other element types may be difficult to port due to lack of CL definition.
  • Functions that provide file input and output to files are not tested and likely will need other definitions (perhaps in C) to function properly, unless CFFI and the CL platform provide C stream compatibility.
  • Some sorting functions fail on amd64 platforms, perhaps because of lack of unsigned integer vectors.
  • 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 used. Contributions welcome.
  • Simulated Annealing has been done 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.
  • Sorting shows two failures on amd64 platforms. This is possibly because of the use of integer vectors to store unsigned integer vectors.
  • 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.