General Advice
There is little separate documentation for GSLL. Instead, 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 intentionally designed to signal an error, because the
examples also serve as a regression (unit) test suite for GSLL.
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 type | Vector class name | Matrix class name
|
single-float | vector-single-float | matrix-single-float
|
double-float | vector-double-float | matrix-double-float
|
(complex single-float) | vector-complex-single-float | matrix-complex-single-float
|
(complex double-float) | vector-complex-double-float | matrix-complex-double-float
|
(signed-byte 8) | vector-signed-byte-8 | matrix-signed-byte-8
|
(unsigned-byte 8) | vector-unsigned-byte-8 | matrix-unsigned-byte-8
|
(signed-byte 16) | vector-signed-byte-16 | matrix-signed-byte-16
|
(unsigned-byte 16) | vector-unsigned-byte-16 | matrix-unsigned-byte-16
|
(signed-byte 32) | vector-signed-byte-32 | matrix-signed-byte-32
|
(unsigned-byte 32) | vector-unsigned-byte-32 | matrix-unsigned-byte-32
|
(signed-byte 64) | vector-signed-byte-64 | matrix-signed-byte-64
|
(unsigned-byte 64) | vector-unsigned-byte-64 | matrix-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.
invert-matrix
finds the inverse of a matrix and uses
GSL's LU decomposition functions.
- IEEE floating point number analysis.
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.