Skip to content
Snippets Groups Projects
index.html 18.2 KiB
Newer Older
<!-- -*- mode: HTML; time-stamp-line-limit: -18; -*- -->
Liam Healy's avatar
Liam Healy committed
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
Liam Healy's avatar
Liam Healy committed
    <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">
Liam Healy's avatar
Liam Healy committed
    <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">
Liam Healy's avatar
Liam Healy committed
<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, fast Fourier transforms, quadrature, random numbers,
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
<a href="missing-features.text">missing-features.text</a>
on the status of some incomplete topics.
Liam Healy's avatar
Liam Healy committed
</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>
Liam Healy's avatar
Liam Healy committed
<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]
Liam Healy's avatar
Liam Healy committed
<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 vector arguments may be specified with reals,
Liam Healy's avatar
Liam Healy committed
<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 1500 examples available from within GSLL with the
Liam Healy's avatar
Liam Healy committed
function <code>examples</code>.  These examples also serve
as a test suite for GSLL.
Liam Healy's avatar
Liam Healy committed
<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>
<li><a href="http://common-lisp.net/project/cffi/">CFFI</a> and cffi-grovel,
  version 0.10.5 or newer; callbacks and <code>foreign-funcall</code> 
  must be supported.
Liam Healy's avatar
Liam Healy committed
</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>
</li>
<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>
Liam Healy's avatar
Liam Healy committed
<li><a href="http://repo.or.cz/w/fsbv.git">FSBV</a>, <i>(Optional)</i> necessary 
   for functions using complex scalars or simulated annealing
<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.
Liam Healy's avatar
Liam Healy committed

<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 <a href="status.text">status.text</a>.
Liam Healy's avatar
Liam Healy committed
</p>
<h2>Download and Install</h2>
 <h3>With <a href="http://git.or.cz">git</a> and asdf</h3>
Liam Healy's avatar
Liam Healy committed
<a name="getit"/>
<p>Download/update:
  <ul>
    <li><code>git clone git://repo.or.cz/gsll.git</code></li>
Liam Healy's avatar
Liam Healy committed
    <li><code>git clone git://repo.or.cz/fsbv.git</code></li>
    <li><code>darcs get http://common-lisp.net/~loliveira/darcs/trivial-garbage</code></li>
Liam Healy's avatar
Liam Healy committed
    <li><code>git pull</code> in the <code>gsll</code> and
      <code>fsbv</code> directories
    afterwards to update</li> 
  </ul>
Liam Healy's avatar
Liam Healy committed
<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:
  <ul>
    <li><code>(asdf:operate 'asdf:load-op :gsll)</code></li>
  </ul>
Liam Healy's avatar
Liam Healy committed
 <p>If you wish to run the test suite, you must get lisp-unit and make
 it known to ASDF:
  <ul>
    <li><code>git clone git://repo.or.cz/lisp-unit.git</code></li>
  </ul>
  <p>The test suite may be run with
  <ul>
    <li><code>(asdf:operate 'asdf:load-op :gsll-tests)</code></li>
    <li><code>(in-package :gsl)</code></li>
    <li><code>(lisp-unit:run-tests)</code></li>
  </ul>
  <p>Please see <a href="status.text">status.text</a> for known failures.
 <h3>With <a href="http://common-lisp.net/project/clbuild/">clbuild</a></h3>
<p>
 Add the following to <code>wnpp-projects</code>:
  <ul>
    <li><code>gsll get_git git://repo.or.cz/gsll.git</code></li>
Liam Healy's avatar
Liam Healy committed
    <li><code>fsbv get_git git://repo.or.cz/fsbv.git</code></li>
    <li><code>trivial-garbage get_darcs http://common-lisp.net/~loliveira/darcs/trivial-garbage</code></li>
    <li><code>cl-utilities get_cvs_clnet</code></li>
  </ul>
<p>and add
  <ul>
    <li><code>gsll cffi trivial-garbage cl-utilities</code></li>
  </ul>
<p>
to <code>dependencies</code> and execute
from within the clbuild directory:
  <ul>
    <li><code>sudo ./clbuild update gsll</code></li>
  </ul>
 <h3>With Debian or Ubuntu</h3>
  <ul>
    <li><code>sudo aptitude install libgsl0-dev cl-cffi cl-utilities libffi-dev cl-iterate</code></li>
    <li><code>git clone git://repo.or.cz/gsll.git</code></li>
Liam Healy's avatar
Liam Healy committed
    <li><code>git clone git://repo.or.cz/fsbv.git</code></li>
    <li><code>darcs get http://common-lisp.net/~loliveira/darcs/trivial-garbage</code></li>
    <li><code>darcs get http://common-lisp.net/project/asdf-system-connections</code></li>
    <li><code>clc-register-user-package gsll/gsll.asd</code></li>
    <li><code>clc-register-user-package gsll/gsll-tests.asd</code></li>
    <li><code>clc-register-user-package trivial-garbage/trivial-garbage.asd</code></li>
Liam Healy's avatar
Liam Healy committed
    <li><code>clc-register-user-package fsbv/fsbv.asd</code></li>
    <li><code>clc-register-user-package asdf-system-connections/asdf-system-connections.asd</li>
  </ul>
<p>
  After starting your Lisp implementation,
  <ul>
Liam Healy's avatar
Liam Healy committed
    <li><code>(clc:clc-require :gsll-tests)</code></li>
  </ul>
 <h3>License</h3>
<p>
This software is distributed under
Liam Healy's avatar
Liam Healy committed
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>
Liam Healy's avatar
Liam Healy committed
 <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>
Liam Healy's avatar
Liam Healy committed
 <p>
   Some examples are not yet present in, or are too complicated for, the
Liam Healy's avatar
Liam Healy committed
 function <code>#'examples</code>.  In this case, you need to look in
 the relevant source file; they are in either a separate file of
Liam Healy's avatar
Liam Healy committed
 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 Healy's avatar
Liam Healy committed
 <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
Liam Healy's avatar
Liam Healy committed
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.  It should be 
 followed by a list; this list will be evaluated.  If the list
 contains <code>^</code>, the object created will be a matrix
 and each row is ended with that symbol.
Liam Healy's avatar
Liam Healy committed
 <p>
 Classes of vectors and matrices are named by appending the element
Liam Healy's avatar
Liam Healy committed
 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>
<p>Copying marrays is performed with the function <code>copy</code>.
  This works between marrays, pointers, and CL arrays.  It is useful
  for functions intended to be passed to GSL functions (for
  e.g. solving, minimizing or fitting) that need to set a GSL vector
  or matrix, because one can simply copy into the passed-in pointer.
</p>
<p>There are two functions provided to extract the dimensions of a
  vector or array: <code>dim0</code> and <code>dim1</code>; the latter
  is applicable only for matrices.
</p>  
<p>If you
  use <a href="http://common-lisp.net/project/iterate/">iterate</a>,
  there are extensions defined that make it easier to iterate over
  marrays.  These are:
  <ul>
    <li><code>matrix-row</code>, <code>matrix-row-index</code></li>
    <li><code>matrix-column</code>, <code>matrix-column-index</code></li>
    <li><code>vector-element</code>, <code>vector-element-index</code></li>
    <li><code>matrix-element</code>, <code>matrix-element-index</code></li>
  </ul>
  <p>For example,
<pre>
(defparameter m1 #m(1 2 3 ^ 0 6 8))
(iter:iter (iter:for e :matrix-element m1) (princ e) (princ " "))
1.0 2.0 3.0 0.0 0.0 6.0 8.0
</pre>
 <h3>Passing functions</h3>
 <p>
 Functions that are passed to GSL functions (known as <i>callbacks</i>
Liam Healy's avatar
Liam Healy committed
 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.
 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. 
Liam Healy's avatar
Liam Healy committed
 <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
Liam Healy's avatar
Liam Healy committed
eigen-symm eigen-symmv eigen-herm eigen-hermv
eigen-nonsymm eigen-nonsymmv eigen-gensymm eigen-gensymmv
eigen-gen eigen-genv
Liam Healy's avatar
Liam Healy committed
monte-carlo-plain monte-carlo-miser monte-carlo-vegas
ode-stepper ode-evolution standard-control y-control
yp-control scaled-control
Liam Healy's avatar
Liam Healy committed
</pre>
<p>
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
</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 functionality is not yet ported; see
<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

<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 -->
Liam Healy's avatar
Liam Healy committed
<small>
Time-stamp: <2009-10-28 22:49:53EDT index.html>
Liam Healy's avatar
Liam Healy committed
</small>
<!-- 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
  </body>