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-float block-fixnum
block-single-float 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-float matrix-fixnum
matrix-single-float 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-float vector-fixnum
vector-single-float 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.

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-float #(-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.
  • 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.