Introduction
The GNU Scientific Library for Lisp (GSLL) allows you to use
the GNU Scientific
Library (GSL) from Common Lisp. This library provides a
full range of common mathematical operations useful to
scientific and engineering applications. The design of the GSLL
interface is such that access to most of the GSL library is
possible in a Lisp-natural way; the intent is that the user not
be hampered by the restrictions of the C language in which GSL
has been written. GSLL thus provides interactive use of GSL for
getting quick answers, even for someone not intending
to program in Lisp.
This code should be considered alpha but it is largely usable
now, with some GSL capability not yet available. See
Development section below.
This software is distributed under the GPL
and FDL.
See COPYING.
Examples
The Jacobian elliptic functions sn, cn, and
dn are special functions (Chapter 7):
(jacobian-elliptic-functions 0.2d0 0.81d0)
0.19762082367187703d0
0.9802785369736752d0
0.9840560289645665d0
1.828927267118668d-318
1.4821969375237396d-321
2.023692885365746d-320
which returns the three function values in succession, along
with the estimated errors of each. The functions are defined
only if the second argument m is not greater than 1,
so an error is signalled if this parameter is out of range:
(jacobian-elliptic-functions 0.61802d0 1.5d0)
debugger invoked on a GSL-ERROR in thread #:
Input domain error (EDOM), |m| > 1.0 in elljac.c at line 46
Documentation
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 . "gsl_sf_elljac_e"))
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 @math{sn(u|m)},
@math{cn(u|m)}, @math{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
lisp-unit:define-test
form, and therefore show the answer
expected.
It is advisable to look at the examples first for calculations that
require more complex setup (generally, the later chapters in the GSL
manual) because often there are convenience macros defined to make
the setup simpler.
Requirements and Platforms
GSLL should work in
any Common Lisp implementation and platform combination
that has CFFI
with callbacks and defcfun support. You will need
In Debian,
the following should work:
apt-get install libgsl0 cl-cffi
(asdf is automatically installed with your CL implementation).
Once your CL implementation is running, do
(asdf:operate 'asdf:compile-op :gsll)
or, if using Debian with the
common-lisp-controller,
(clc:clc-require :gsll)
GSLL has been tested with SBCL on Debian i386 and amd64.
Source downloads [not yet available]
You may browse or download the Subversion
repository at
svn://common-lisp.net/project/gsll/subversion/trunk. For
example,
svn list svn://common-lisp.net/project/gsll/subversion/trunk
svn checkout svn://common-lisp.net/project/gsll/subversion/trunk
.
Project Development
This project has been in development since March 2006. A majority is
done, but there is still much work to do. The status is summarized
below, by reference to the Chapters in the GSL manual.
It is possible that the library API will change but probably not
substantially; most of the remaining work involves added functions.
GSLL is written in pure Common Lisp; there is no C "glue" layer.
As such, most every function can be defined with the supplied macro
defun-gsl
, which simplifies the process of porting.
The arguments and defaults provide a convenient way of defining new
functions; it is likely this will not change as the rest of GSL
functionality is added to GSLL. Where functions in the GSL library
do input and output to files, the remainder of the necessary
file-related operations must also be performed in C; no CL
interface is yet provided.
A Trac web page will soon be set up for those interested in
development, and for reporting bugs. In the meantime, send email to
me at this address: lhealy
-at-
common-lisp
-dot- net
.
In addition to the chapters below, it would be nice if the following
were done
- Native vectors like
sb-sys:vector-sap
in SBCL.
The following is not part of the plan for the GSLL interface:
- Anything that is defined solely in C header files and not in the .so
library will not be a part of GSLL, because of the lack of access
through the library. For example, Chapter 38, Physical Constants,
are all defined as C macros.
- Anything for which there are two near-equivalent GSL functions
and for which one is already provided. For example, all of the
special functions have two forms, one which provides the answer(s)
with an estimated error as a structure, and one which just provides
the answer as a double. This makes a
difference when C programming, but GSLL always uses the form with the
error estimate and returns the error as a later multiple value so
that it can easily be ignored.
- Anything for which there is a Common Lisp
equivalent probably won't be done, unless there is a need to have it
present for some other GSL functionality that isn't present in CL.
The following is the status of the project by GSL
manual chapter. When marked "Done" it means that all or a
substantial portion
that is planned that GSLL will cover has been defined and some of those
definitions have been tested. Improvements may still be
desirable.
Regression Tests
Regression tests using lisp-unit
(provided) are given for many of the functions defined. These
also serve as examples. The judgement of floating point numbers as
equivalent is a hack, and needs to be replaced; I am looking for
good ideas. Note that most of the result have not been verified
with an independent source; the values given are from previous
tests. To run the tests,
(lisp-unit:run-tests)
and expect a few failures on amd64 (four), none? on i386. Often, the
failures aren't really failures, just floating point numbers that
aren't close enough to pass.
Related projects from others
A partial automatically-generated interface to GSL is provided in
cl-gsl.
A matlab-like array syntax and plotting is provided by
NLISP which might work well with
GSLL. Some math functions implemented natively in CL are provided
in
cl-numlib.