index.html 14.4 KB
Newer Older
1
<!-- -*- mode: HTML; time-stamp-line-limit: -18; -*- -->
Liam Healy's avatar
Liam Healy committed
2
3
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
4
  <head>
Liam Healy's avatar
Liam Healy committed
5
6
7
8
9
10
11
    <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">
12
13
  </head>
  <body>
Liam Healy's avatar
Liam Healy committed
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
    <div id="banner">
      <h1>GNU Scientific Library for Lisp</h1>
      <h2><a href="index.html">GSLL</a> &nbsp;
    </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">
35
36


Liam Healy's avatar
Liam Healy committed
37
38
39
40
41
42
43
44
45
46
47
48
49
50
<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,
51
eigensystems, fast Fourier transforms (FFT), quadrature, random numbers,
Liam Healy's avatar
Liam Healy committed
52
53
54
55
56
57
58
quasi-random sequences, random distributions, statistics, histograms,
N-tuples, Monte Carlo integration, simulated annealing, 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, physical constants.  See
Liam Healy's avatar
Liam Healy committed
59
60
<a href="missing-features.text">missing-features.text</a>
on the status of some incomplete topics.
Liam Healy's avatar
Liam Healy committed
61
62
63
64
</p>

<h2>Examples</h2>
<a name="examples"/>
65
66
67
68
69
70
71
72
 <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
</pre>
73
74
75
76
<p>which returns as multiple values the three function values.  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:
77
78
<pre>
(jacobian-elliptic-functions 0.61802d0 1.5d0)
79
Input domain error |m| > 1.0 in elljac.c at line 46
80
   [Condition of type INPUT-DOMAIN]
81
</pre>
Liam Healy's avatar
Liam Healy committed
82
83
84
85
86
87
88
89
90
<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>
91
<p>There are over 1500 examples available from within GSLL with the
Liam M. Healy's avatar
Liam M. Healy committed
92
93
94
function <code>examples</code>.  There is also a suite of over
4000 tests; many of the examples also serve as tests, and most others
are ported from GSL's tests. 
95

Liam Healy's avatar
Liam Healy committed
96
97
98
99
100
101
102
103
<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>
</li>
104
<li><a href="http://common-lisp.net/project/cffi/">CFFI</a> and cffi-grovel,
Liam Healy's avatar
Liam Healy committed
105
  version 0.10.5 or newer; callbacks and <code>foreign-funcall</code> 
106
  must be supported.
Liam Healy's avatar
Liam Healy committed
107
108
</li>
<li><a href="http://www.cliki.net/trivial-garbage">trivial-garbage</a>
Liam Healy's avatar
Liam Healy committed
109
<li><a href="http://repo.or.cz/w/gsd.git">GSD</a>, the <i>Grid Structured Data</i>; in particular,
Liam M. Healy's avatar
Liam M. Healy committed
110
111
112
113
114
115
116
117
118
  the <code>foreign-array</code> and <code>grid</code> systems, which
  uses
  <ul>
  <li><a href="http://common-lisp.net/project/alexandria/">Alexandria</a>,</li>
  <li><a href="http://www.cliki.net/SPLIT-SEQUENCE">split-sequence</a>,</li>
  <li><a href="http://gitorious.org/iolib/static-vectors">static-vectors</a>
    <i>(Optional)</i>, provides direct access to foreign arrays from
    Lisp on some implementations.</li>
  </ul>  
119
120
121
<li><a href="http://www.cliki.net/asdf">ASDF</a></li>
<li><a href="http://repo.or.cz/w/lisp-unit.git">lisp-unit</a>, <i>(Optional)</i> necessary 
   to run <code>gsll-tests</code>
122
</li>
Liam Healy's avatar
Liam Healy committed
123
<li><a href="http://repo.or.cz/w/fsbv.git">FSBV</a>, <i>(Optional)</i> necessary 
124
   for functions using complex scalars or simulated annealing
125
</li>
126
127
128
129
130
131
132
<li>
  <a href="http://common-lisp.net/project/iterate/">iterate</a>
  and
  <a href="http://common-lisp.net/project/asdf-system-connections/">asdf-system-connnections</a>,
  <i>(Optional)</i> 
  provides a convenient way to iterate over elements or indices of
  vectors or matrices.
133
</ul>
134
135
136
137
<p>Most users will not need to worry about their implementation and
  operating system, as all these are supported if the needed libraries
  are installed (see below).  The use of CLISP, however, is not
  recommended.
Liam Healy's avatar
Liam Healy committed
138
</p>
139

140
<h2>Download and Install</h2>
Liam M. Healy's avatar
Liam M. Healy committed
141
 <h3>Download</h3>
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 <p>Use <a href="http://www.quicklisp.org/">quicklisp</a> and follow the
 instructions.  You will need to make sure that the libraries and
 header files associated with <a href="http://www.gnu.org/software/gsl/">GNU Scientific Library
(GSL)</a> and <a href="http://sourceware.org/libffi/">libffi</a> are
 installed; your distribution may name these <code>libgsl0-dev</code>
 and <code>libffi-dev</code>.  Once they are installed and you have
 loaded the quicklisp file:
 <pre>
   (ql:quickload "gsll-tests")</pre>
 <p>To test your installation:
 <pre>
   (in-package :gsl)
   (lisp-unit:run-tests)</pre>
 <p>The result should look something like:
 <pre>
ABSOLUTE-DEVIATION: 1 assertions passed, 0 failed.
ABSOLUTE-SUM: 4 assertions passed, 0 failed.
AIRY: 73 assertions passed, 0 failed.</pre>
<p>... (many lines deleted) ...
<pre>
VECTOR-VARIANCE-WITH-MEAN: 10 assertions passed, 0 failed.
WEIBULL: 60 assertions passed, 0 failed.
ZETA: 6 assertions passed, 0 failed.
TOTAL: 4019 assertions passed, 1 failed, 0 execution errors.</pre>
 <p>You may see more failures.

Liam Healy's avatar
Liam Healy committed
168
 <h3>License</h3>
169
170
<p>
This software is distributed under
171
the <a href="http://www.gnu.org/licenses/gpl.html">GPL</a>
Liam M. Healy's avatar
Liam M. Healy committed
172
173
174
<!--and <a href="http://www.gnu.org/copyleft/fdl.html">FDL</a>
	-->
; see
Liam Healy's avatar
Liam Healy committed
175
176
177
178
179
180
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>
181
 <ul>
Liam Healy's avatar
Liam Healy committed
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
 <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>
215
 </ul>
Liam Healy's avatar
Liam Healy committed
216
 <p>
Liam Healy's avatar
Liam Healy committed
217
   Some examples are not yet present in, or are too complicated for, the
Liam Healy's avatar
Liam Healy committed
218
 function <code>#'examples</code>.  In this case, you need to look in
219
 the relevant source file; they are in either a separate file of
Liam Healy's avatar
Liam Healy committed
220
221
222
223
 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).
liam's avatar
liam committed
224

Liam Healy's avatar
Liam Healy committed
225
226
227
 <h3>Arrays</h3>
<p>
GSLL has many functions that work on vectors (one-dimensional arrays)
Liam M. Healy's avatar
Liam M. Healy committed
228
229
230
231
232
233
and matrices (two-dimensional arrays).  Foreign arrays are defined and
manipulated using the GSD collection which defines generic operations
on array-like objects; see the GSD documentation for more information.
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>grid:*array-element-types*</code>.
Liam Healy's avatar
Liam Healy committed
234
<p>
Liam Healy's avatar
Liam Healy committed
235
236

<h3>Passing functions</h3>
Liam Healy's avatar
Liam Healy committed
237
238
 <p>
 Functions that are passed to GSL functions (known as <i>callbacks</i>
Liam Healy's avatar
Liam Healy committed
239
240
241
242
 in C) are specified with a
 <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_f.htm#function_designator">function
 designator</a> for the CL function, that is, either the function
 object itself or a symbol denoting the function.
243
244
245
246
 There is usually an option <code>scalarsp</code> for functions
 that take or return arrays that, if true, will
 send the user function the argument element by element, and expect
 the return values to be the individual elements. 
247
 </p>
Liam Healy's avatar
Liam Healy committed
248

Liam Healy's avatar
Liam Healy committed
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
 <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
264
qaws-table qawo-table
Liam Healy's avatar
Liam Healy committed
265
eigen-symm eigen-symmv eigen-herm eigen-hermv
266
267
eigen-nonsymm eigen-nonsymmv eigen-gensymm eigen-gensymmv
eigen-gen eigen-genv
Liam Healy's avatar
Liam Healy committed
268
monte-carlo-plain monte-carlo-miser monte-carlo-vegas
269
270
ode-stepper ode-evolution standard-control y-control
yp-control scaled-control
271
272
273
274
275
fft-real-wavetable-double-float fft-real-wavetable-single-float
fft-real-workspace-double-float fft-real-workspace-single-float
fft-complex-wavetable-double-float fft-complex-wavetable-single-float
fft-complex-workspace-double-float fft-complex-workspace-single-float
fft-half-complex-wavetable-double-float fft-half-complex-wavetable-single-float
Liam Healy's avatar
Liam Healy committed
276
277
</pre>
<p>
Liam Healy's avatar
Liam Healy committed
278
279
280
An instance may be created with a function 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.
Liam Healy's avatar
Liam Healy committed
281
282
283
284
285
286
287
288
289
290
</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>
291
292
293
294
295
296
297
298
299
300
301
302
303
  <li><code>fft-frequency-vector</code> returns a vector where the sample
  frequencies are contained. If you perform an FFT on a vector of a given size
  and :sample-size, this vector will contain the sample frequencies in order.
  If the :shifted keyword is T, then the frequencies are ordered in ascending
  order.</li>
  <li><code>fft-shift</code> returns a copy of a vector where the zero
  frequency has been shifted to the center; the frequency components will be
  sorted according to their frequency, in ascending order. Optionally, a
  :stride can be provided.</li>
  <li><code>fft-inverse-shift</code> performs the inverse action of fft-shift;
  the zero and positive frequency components are shifted to the beginning,
  so that the resulting vector is suitable for an inverse FFT. Optionally, a
  :stride can be provided.</li>
Liam Healy's avatar
Liam Healy committed
304
305
306
307
308
309
</ul>

<h2>Status</h2>
<a name="status"/>
<p>
GSLL is largely complete and usable, with functioning interfaces to
310
most of GSL.  Some functionality is not yet ported; see
Liam Healy's avatar
Liam Healy committed
311
312
313
314
315
316
317
<a href="missing-features.text">missing-features.text</a>
for more details.  Known bugs are documented in
<a href="status.text">status.text</a>.  Work is ongoing to both
remedy those deficiencies and to simplify the user interface by
changing more required arguments into optional or key arguments with
useful default values.  Typically, these arguments bind GSL objects
and arrays used internally or for function return.
Liam Healy's avatar
Liam Healy committed
318
319
320
321
322
323
324
325

<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>
326
327
328
329
330
<p>For bug reports, please use the mailing list.  If you have
patch(es) and use git, please commit your changes and do: 
<pre>git format-patch origin</pre>
<p>This will produce one or more files whose names start with a
four-digit number; please attach them all to your email.
Liam Healy's avatar
Liam Healy committed
331
332
333
334
335
</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>
336
337
<!-- Created: Feb 25 2005 -->
<!-- hhmts start -->
Liam Healy's avatar
Liam Healy committed
338
<small>
339
Time-stamp: <2010-10-12 17:46:29EDT index.html>
Liam Healy's avatar
Liam Healy committed
340
</small>
341
342
343
344
345
346
347
348
349
350
351
<!-- 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>
Liam Healy's avatar
Liam Healy committed
352
  </body>
353
</html>