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-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
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-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.