Newer
Older
<!-- -*- mode: HTML; time-stamp-line-limit: -18; -*- -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
<title>GSLL, the GNU Scientific Library for Lisp
</title>
<meta name="generator" content="muse.el">
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<link rev="made" href="mailto:lhealy@common-lisp.net">
<link rel="stylesheet" type="text/css" href="site.css">
</head>
<body>
<div id="banner">
<h1>GNU Scientific Library for Lisp</h1>
<h2><a href="index.html">GSLL</a>
</div>
<div id="sidebar">
<ul>
<li><a href="#about">About</a></li>
<li><a href="#examples">Examples</a></li>
<li><a href="#require">Requirements</a></li>
<li><a href="#getit">Download</a></li>
<li><a href="#documentation">Documentation</a></li>
<li><a href="#status">Status</a></li>
<li><a href="#contact">Contact</a></li>
</ul>
<!-- Insertion Mark -->
</div>
<div id="content">
<!-- Page published by Emacs Muse begins here -->
<h2>About</h2>
<a name="about"/>
<p class="first">
<p>The GNU Scientific Library for Lisp (GSLL) allows you to use
the <a href="http://www.gnu.org/software/gsl/">GNU Scientific Library
(GSL)</a> from <a href="http://www.lisp.org">Common Lisp</a>. 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.
</p>
<p>Topics include: polynomials, special functions, vectors and
matrices, permutations, sorting, linear algebra including BLAS,
eigensystems, quadrature, random numbers, quasi-random sequences,
random distributions, statistics, histograms, N-tuples, Monte Carlo
integration, ordinary differential equations, interpolation, numerical
integration, numerical differentiation, Chebyshev approximation,
series acceleration, discrete Hankel transforms, root-finding,
minimization, least-squares fitting, IEEE floating-point, discrete
wavelet transforms, basis splines. See the file
documentation/missing-features.text on the status of some incomplete
topics.
</p>
<h2>Examples</h2>
<a name="examples"/>
<p>The <a href="http://www.gnu.org/software/gsl/manual/html_node/Elliptic-Functions-_0028Jacobi_0029.html">Jacobian elliptic functions</a> <i>sn</i>, <i>cn</i>, and
<i>dn</i> are special functions (Chapter 7):</p>
<pre>
(jacobian-elliptic-functions 0.2d0 0.81d0)
0.19762082367187703d0
0.9802785369736752d0
0.9840560289645665d0
1.828927267118668d-318
1.4821969375237396d-321
2.023692885365746d-320
</pre>
<p>which returns as multiple values the three function values, along
with the estimated errors of each. The functions are defined
only if the second argument <i>m</i> is not greater than 1,
so an error is signalled if this parameter is out of range:
<pre>
(jacobian-elliptic-functions 0.61802d0 1.5d0)
Input domain error |m| > 1.0 in elljac.c at line 46
[Condition of type INPUT-DOMAIN]
<p>This is an ordinary Lisp error which may be handled with standard
definitions available in Lisp. To take the
<a href="file:///usr/share/doc/gsl-ref-html/Level-1-GSL-BLAS-Interface.html">
complex conjugate scalar product</a> of two complex vectors of length 3:
<pre>
(cdot #2m(#c(-34.5d0 8.24d0) #c(3.29d0 -8.93d0) #c(34.12d0 -6.15d0))
#2m(#c(49.27d0 -13.49d0) #c(32.5d0 42.73d0) #c(-17.24d0 43.31d0)))
#C(-2940.2118d0 1861.9380999999998d0)
</pre>
<p>or equivalently the initial vectors may be specified with reals,
<pre>
(cdot #2m(-34.5d0 8.24d0 3.29d0 -8.93d0 34.12d0 -6.15d0)
#2m(49.27d0 -13.49d0 32.5d0 42.73d0 -17.24d0 43.31d0))
#C(-2940.2118d0 1861.9380999999998d0)
</pre>
<p>There are over 1200 examples available from within GSLL with the
function <code>examples</code>. These examples also serve
as a test suite for GSLL.
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
<h2>Requirements</h2>
<a name="require"/>
<p>
GSLL should work in any Common Lisp implementation and platform
combination for which the following are supported:</p>
<ul>
<li><a href="http://www.gnu.org/software/gsl/">GSL</a>
(<a href="http://packages.debian.org/lenny/libgsl0ldbl">libgsl0ldbl</a>
in Debian/Ubuntu)
</li>
<li><a href="http://common-lisp.net/project/cffi/">CFFI</a>,
version 0.10.0 or newer;
only platforms and implementations which have callbacks and
foreign-funcall support will work
(<a href="http://packages.debian.org/lenny/cl-cffi">cl-cffi</a>
in Debian/Ubuntu)
</li>
<li><a href="http://www.cliki.net/trivial-garbage">trivial-garbage</a>
<li><a href="http://common-lisp.net/project/cl-utilities/">cl-utilities</a>
(<a href="http://packages.debian.org/lenny/cl-utilities">cl-utilities</a>
in Debian/Ubuntu)</li>
<li><a href="http://www.cliki.net/asdf">ASDF</a></li></ul>
<p>GSLL has been tested with
<a href="http://sbcl.sourceforge.net/">SBCL</a>
and
<a href="http://trac.clozure.com/openmcl">CCL</a>
on Debian amd64, and
<a href="http://sbcl.sourceforge.net/">SBCL</a>
and
<a href="http://clisp.cons.org/">CLISP</a> on Debian i386. There
are some known failures; see the file documentation/status.text.
</p>
<p>Use <a href="http://git.or.cz">git</a> to download:
<pre>
git clone git://repo.or.cz/gsll.git
</pre>
<p>The <a href="http://repo.or.cz/w/gsll.git"> repository web page</a>
can be used to browse or retrieve a compressed tarball (click the most
recent "snapshot" link).
You will need to make a link of <code>gsll.asd</code> and
optionally <code>gsll-tests.asd</code> to some directory known to ASDF.
Then in Lisp, load the system:
<pre>(asdf:operate 'asdf:load-op :gsll)</pre>
<p>and if you wish to run the test suite,
<pre>(asdf:operate 'asdf:load-op :gsll-tests)</pre>
<p>
This software is distributed under
the <a href="http://www.cliki.net/LLGPL">LLGPL</a>
and <a href="http://www.gnu.org/copyleft/fdl.html">FDL</a>; see
the file COPYING. There is absolutely no warranty.</p>
<h2>Documentation</h2>
<a name="documentation"/>
<h3>General Advice</h3>
<p>The following techniques for using the API are advised:</p>
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
<li>Find the appropriate function(s) in the <a
href="http://www.gnu.org/software/gsl/manual/">GSL
documentation</a>.</li>
<li>Use the GSLL function <code>gsl-lookup</code>
to find the equivalent GSLL function, for example
<pre>
(gsl-lookup "gsl_sf_elljac_e")
JACOBIAN-ELLIPTIC-FUNCTIONS
T
</pre>
<p>
to find that the Lisp function name is <code>#'jacobian-elliptic-functions</code>.
</li>
<li>Look at the documentation for that Lisp function, e.g.
<pre>(documentation #'jacobian-elliptic-functions 'function)
"The Jacobian elliptic functions sn(u|m),
cn(u|m), dn(u|m) computed by descending Landen transformations."
</pre>
<p>
to get an explanation of the arguments etc.
</li>
<li>Use the function <code>(examples)</code> 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
<code>(examples 'higher-moments)</code>. The result will be a list
of forms, each providing an example of usage in the relevant topic.
If the
<a href="http://www.gnu.org/software/gsl/manual/">GSL
documentation</a> provides an example, there will usually be the same
or similar example provided in GSLL. <i>Note:</i> Some of the
examples are intentionally designed to signal an error, because the
examples also serve as a regression (unit) test suite for GSLL.</li>
<p>
Some examples are not yet present, or are too complicated for, the
function <code>#'examples</code>. In this case, you need to look in
the relevant source file; they are in either a separate file of
examples, or at the end of the file of definitions.
It is advisable to look at the examples first for calculations that
require more complex setup (generally, the later chapters in the GSL
manual).
<h3>Arrays</h3>
<p>
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,
GSL, and the platform. This list is available in the
variable <code>*array-element-types*</code>. On implementations 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.</p>
<p>
Common Lisp arrays should be created with <code>make-marray</code> or
<code>#m</code>:
The #m reader macro in the default form creates a vector or matrix of
element type double-float, which is the most common type needed for
GSL functions. It optionally takes a numeric argument prefix as in
the example above to make an array with a different element type; a
guide to the numeric argument is given below. If the macro is
followed by a list of numbers, a vector is created, if it is followed
by a list of lists of number, each of the same length, a matrix is
created.
<p>
Classes of vectors and matrices are named by appending the element
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
type as hypenated words to "vector" or "matrix". The following table
shows the classes available on a 64-bit platform:
<center>
<table border=5 frame=all cellpadding=4 cellspacing=4 cols=6>
<caption align=top>Element types, vector and matrix
classes</caption>
<thead>
<tr><th><b>Element type</b><td><b>Vector class name</b>
<td><b>Matrix class name</b><td><b>#m prefix</b></thead>
<tbody>
<tr><td>double-float<td>vector-double-float<td>matrix-double-float
<td>1 or empty
<tr><td>(complex double-float)<td>vector-complex-double-float<td>matrix-complex-double-float<td>2
<tr><td>single-float<td>vector-single-float<td>matrix-single-float<td>3
<tr><td>(complex single-float)<td>vector-complex-single-float<td>matrix-complex-single-float<td>4
<tr><td>(signed-byte 8)<td>vector-signed-byte-8<td>matrix-signed-byte-8<td>7
<tr><td>(unsigned-byte 8)<td>vector-unsigned-byte-8<td>matrix-unsigned-byte-8<td>8
<tr><td>(signed-byte 16)<td>vector-signed-byte-16<td>matrix-signed-byte-16<td>15
<tr><td>(unsigned-byte 16)<td>vector-unsigned-byte-16<td>matrix-unsigned-byte-16<td>16
<tr><td>(signed-byte 32)<td>vector-signed-byte-32<td>matrix-signed-byte-32<td>31
<tr><td>(unsigned-byte 32)<td>vector-unsigned-byte-32<td>matrix-unsigned-byte-32<td>32
<tr><td>(signed-byte 64)<td>vector-signed-byte-64<td>matrix-signed-byte-64<td>63
<tr><td>(unsigned-byte 64)<td>vector-unsigned-byte-64<td>matrix-unsigned-byte-64<td>64
</tbody>
</table>
</center>
<p>
Individual elements are obtained using <code>maref</code> (analogous
to Lisp's <code>aref</code>), and are set
with <code>setf maref</code>. A complete CL array may
be extracted with the function <code>#'cl-array</code>.
</p>
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
<h3>GSL objects</h3>
<p>
There are a number of GSL objects other than arrays that can be
created:
<pre>
acceleration interpolation levin levin-truncated spline
nonlinear-ffit nonlinear-fdffit
one-dimensional-root-solver-f one-dimensional-root-solver-fdf
multi-dimensional-minimizer-f multi-dimensional-minimizer-fdf
fit-workspace one-dimensional-minimizer
multi-dimensional-root-solver-f multi-dimensional-root-solver-fdf
histogram histogram2d histogram-pdf histogram2d-pdf
basis-spline chebyshev hankel wavelet wavelet-workspace
random-number-generator quasi-random-number-generator discrete-random
polynomial-complex-workspace integration-workspace
eigen-symm eigen-symmv eigen-herm eigen-hermv
monte-carlo-plain monte-carlo-miser monte-carlo-vegas
</pre>
<p>
An instance each may be created with a function that whose name is
"make-" followed by the class name, e.g. <code>make-histogram</code>.
The arguments that the function takes depends on the class.
</p>
<h3>Additional definitions</h3>
<p>
Some definitions are provided because of their usefulness, even though
GSL doesn't have them.
<ul>
<li><code>invert-matrix</code> finds the inverse of a matrix and uses
GSL's LU decomposition functions.</li>
<li>IEEE floating point number analysis.</li>
</ul>
<h2>Status</h2>
<a name="status"/>
<p>
GSLL is largely complete and usable, with functioning interfaces to
most of GSL. Some chapters are not yet ported. Known bugs are
documented in the file documentation/status.text. It is possible the
user interface will change but not to a great extent, so the current
version should still be considered alpha.
<h2>Contact</h2>
<a name="contact"/>
<p>There is a <a
href="http://common-lisp.net/cgi-bin/mailman/listinfo/gsll-devel">mailing
list</a> for all aspects of this project, including bug reports. In
addition, I am frequently on #lisp IRC channel as LiamH.
</p>
</div>
<!-- Page published by Emacs Muse ends here -->
<div class="footer">
<hr>
<address><a href="mailto:gsll-devel@common-lisp.net">Liam Healy</a></address>
<!-- Created: Feb 25 2005 -->
<!-- hhmts start -->
Time-stamp: <2009-01-07 22:25:08EST index.html>
<!-- hhmts end -->
</div>
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
var pageTracker = _gat._getTracker("UA-3669275-1");
pageTracker._initData();
pageTracker._trackPageview();
</script>