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.
- Look at the end of the Lisp source file, or in an "example" file
in the same directory, for examples. Often, the examples are placed
in a
make-tests
form (which will be commented out with
a #| |# block). If the
GSL documentation
provides an example, there will usually be the same or similar
example provided in 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 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.