Commit 8d9ce4e8 authored by Liam Healy's avatar Liam Healy

Updated documentation

Updated the documentation to reflect changes in the new branch with
foreign-friendly arrays.  This is now better reflective or the current
definitions, but work needs to be done.  Added a dependency that was
missing: matrix exponential needs special functions to define sf-mode.
parent 1decdc13
......@@ -39,11 +39,6 @@
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.
</li>
<li>Data types that are not defined in Common Lisp portably (such as
uint) may not be well supported. Others may be added but it
may be difficult to do so in a portable way. There are several
macros to help with the definitions.
</li>
</ul>
<h3>Status</h3>
......@@ -60,18 +55,16 @@
particularly known failures.
It is possible that the library API will change but probably not
substantially; most of the remaining work is to fix bugs.
<p>
Wishlist features include:<ul>
<li>Native vectors like <code>sb-sys:vector-sap</code> in SBCL.
</ul>
<h3>Contributions</h3>
Contributions to the development of GSLL are welcome; see
the <a href="http://trac.common-lisp.net/gsll">Trac page</a> .
This make take the form of bug reports and fixes, suggestions for new
interface design, or of porting the remaining unported functions.
The supplied macros
Contributions to the development of GSLL are welcome; the primary
way to get started is by posting to the
<a href="http://common-lisp.net/cgi-bin/mailman/listinfo/gsll-devel">mailing
list</a>; also see
the <a href="http://trac.common-lisp.net/gsll">Trac page</a>. A
contribution may take the form of bug reports and fixes, suggestions
for new interface design, porting the remaining unported
functions, testing on a new platform or compiler. The supplied macros
<code>defmfun</code> and <code>defmpar</code>
define virtually all of the interface functions and variables
respectively, which simplifies the process of porting.
......@@ -96,7 +89,7 @@ See <a href="documentation.html">documentation</a> regarding known failures.
<hr>
<address><a href="mailto:gsll-devel@common-lisp.net">Liam Healy</a></address>
<small>
Time-stamp: <2008-03-08 11:07:51EST development.html>
Time-stamp: <2008-08-31 20:14:05EDT development.html>
</small>
<!-- hhmts end -->
</div>
......
......@@ -62,18 +62,15 @@ href="http://www.lispworks.com/documentation/HyperSpec/Body/s_let_l.htm#letST">l
with the additional feature that if the init-form is one of GSL objects
<pre>
acceleration basis-spline block-complex block-double-float block-fixnum
block-single-float chebyshev combination complex-workspace
acceleration basis-spline 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
matrix-* 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
vector-* wavelet wavelet-workspace
</pre>
the appropriate object will be allocated and bound to the variable,
optionally set, and then freed when the body of the let is exited.
......@@ -82,28 +79,70 @@ are functions whose symbols are exported so that an arglist prompt
will be visible; however, the function should not be used outside a
<code>letm</code> binding.
<h3>Data: vectors, matrices, etc.</h3>
<h3>Data: vectors and matrices</h3>
<div class="content">
<p>
Collectively, vectors, matrices, histograms and the like are called
<i>data</i>. 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.
<p>FIXME Vectors and matrices can be converted to and from their Lisp
counterparts with <code>data</code> and <code>(setf data)</code>.
Setting the GSL value to a Lisp value at initialization
can be done within the <code>letm</code> by giving the Lisp value as
the first argument after the type, for example
Collectively vectors and matrices and are called
<i>data</i>. GSLL supports all element types that are supported by
CFFI, the CL implementation, and GSL. This list is
available in the variable <code>*array-element-types*</code>.
These arrays are <i>foreign-friendly</i>, meaning that
on platforms 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>
Common Lisp arrays should be created with <code>make-array*</code>;
the syntax is similar to Common Lisp's <code>make-array</code>
except that the second argument <code>element-type</code> is
mandatory. If this function is used, the resultant array is
foreign friendly. It can then be used as an argument in the letm
binding. Alternatively, a literal array can be created in the letm
binding using the macros <code>a</code> (non-evaluating)
or <code>a*</code> (evaluating).
<p>
Classes of vectors and matrices are names by appending the element
type as hypenated words to "vector" or "matrix". The following table
shows the classes available on SBCL on an amd64 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>Element type<td><b>Vector class name</b><td><b>Matrix class name</b>
</thead>
<tbody>
<tr><td>single-float<td>vector-single-float<td>matrix-single-float
<tr><td>double-float<td>vector-double-float<td>matrix-double-float
<tr><td>(complex single-float)<td>vector-complex-single-float<td>matrix-complex-single-float
<tr><td>(complex double-float)<td>vector-complex-double-float<td>matrix-complex-double-float
<tr><td>(signed-byte 8)<td>vector-signed-byte-8<td>matrix-signed-byte-8
<tr><td>(unsigned-byte 8)<td>vector-unsigned-byte-8<td>matrix-unsigned-byte-8
<tr><td>(signed-byte 16)<td>vector-signed-byte-16<td>matrix-signed-byte-16
<tr><td>(unsigned-byte 16)<td>vector-unsigned-byte-16<td>matrix-unsigned-byte-16
<tr><td>(signed-byte 32)<td>vector-signed-byte-32<td>matrix-signed-byte-32
<tr><td>(unsigned-byte 32)<td>vector-unsigned-byte-32<td>matrix-unsigned-byte-32
<tr><td>(signed-byte 64)<td>vector-signed-byte-64<td>matrix-signed-byte-64
<tr><td>(unsigned-byte 64)<td>vector-unsigned-byte-64<td>matrix-unsigned-byte-64
</tbody>
</table>
</center>
<p>
The class name serves as the binding form in the letm. For example,
the following form sums two vectors:
<pre>
(letm ((vec (vector-double-float (a -3.21d0 1.0d0 12.8d0))))
(???? vec))
(letm ((vec1 (vector-double-float (a -3.21d0 1.0d0 12.8d0)))
(vec2 (vector-double-float (a -1.88d0 -1.0d0 4.1d0))))
(m+ vec1 vec2))
#&lt;VECTOR-DOUBLE-FLOAT #(-5.09d0 0.0d0 16.9d0)&gt;
</pre>
<p>
Individual elements of data may be accessed with <code>maref</code>,
either directly or in a <code>setf</code>.
The macro #'a is a convenience for the specification of an array
with literal content.
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>. This array
may subsequently be used in later GSL functions by providing it as
the argument in the letm binding.
</p>
<h3>Status</h3>
......@@ -113,14 +152,11 @@ will be visible; however, the function should not be used outside a
on particular chapters:
<ul>
<base href="http://www.gnu.org/software/gsl/manual/html_node/">
<li><a href="Vectors-and-Matrices.html">Vectors and Matrices</a>
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.
<li>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.
<li>Reading and writing through the GSL library is not supported due
to lack of support for foreign streams in Lisp.</li>
<li>For <a href="Vectors-and-Matrices.html">Vectors and Matrices</a>,
subvectors and views are not defined. In many functions, the
stride is pre-set to 1.
<li><a href="BLAS-Support.html">BLAS</a> is completed, but with only very
limited testing.
<li><a href="Fast-Fourier-Transforms.html">FFTs</a> have not been done
......@@ -154,7 +190,7 @@ gamma-randist, negative-binomial.
<address><a href="mailto:gsll-devel@common-lisp.net">Liam Healy</a></address>
<!-- hhmts start -->
<small>
Time-stamp: <2008-08-31 17:21:56EDT documentation.html>
Time-stamp: <2008-08-31 18:40:51EDT documentation.html>
</small>
<!-- hhmts end -->
</div>
......
......@@ -84,15 +84,16 @@ Input domain error |m| > 1.0 in elljac.c at line 46
<ul>
<li><a href="http://www.gnu.org/software/gsl/">GSL</a></li>
<li><a href="http://common-lisp.net/project/cffi/">CFFI</a>
(Note: you will need a version <i>newer</i> than the current version
0.9.2. Use the darcs repository, a newer tarball, or Debian
testing/unstable.)</li>
(Version 0.10.0 or newer,
or <a href="http://packages.debian.org/lenny/cl-cffi">the
version in Debian/lenny</a>)
</li>
<li><a href="http://www.cliki.net/asdf">ASDF</a>
</ul>
<p>
In <a href="http://www.debian.org">Debian</a> unstable or testing,
In <a href="http://www.debian.org">Debian</a> Lenny (5.0) or newer,
the following should work:</p>
<blockquote><pre>apt-get install <a
<blockquote><pre>aptitude install <a
href="http://packages.debian.org/lenny/libgsl0ldbl">libgsl0ldbl</a> <a href="http://packages.debian.org/lenny/cl-cffi">cl-cffi</a></pre></blockquote>
(asdf is automatically installed with your CL implementation).
Once your CL implementation is running, do
......@@ -111,20 +112,6 @@ Input domain error |m| > 1.0 in elljac.c at line 46
<div class="content">
<p>You may browse or download as follows:</p>
<ul>
<li><a href="http://subversion.tigris.org/">Subversion</a>:
Repository at
svn://common-lisp.net/project/gsll/svn/trunk. For
example,
<pre>
svn list svn://common-lisp.net/project/gsll/svn/trunk
svn checkout svn://common-lisp.net/project/gsll/svn/trunk gsll
</pre>
<li>Web:
<a href="http://trac.common-lisp.net/gsll/browser/trunk">browse</a>
using Trac.
<li>Git: Thanks to Leonardo Varuzza, who is maintaining a
<a href="http://www.lambdatau.com/git/gsll.git">git mirror</a>
of the Subversion repository.
</ul>
<p>Due to frequent changes, no tarballs are yet available.</p>
</div>
......@@ -144,12 +131,12 @@ svn checkout svn://common-lisp.net/project/gsll/svn/trunk gsll
<h3>Similar or related projects from others</h3>
<div class="content">
A partial automatically-generated interface to GSL is provided in <a
href="http://common-lisp.net/project/cl-gsl/">cl-gsl</a>.
A Matlab-like array syntax and plotting is provided by
<a href="http://nlisp.info/">NLISP</a> which might work well with
GSLL. Other numerical mathematics software for Lisp may be found
<a href="http://www.cliki.net/Mathematics">on Clicki</a>.
A partial interface to GSL is provided in <a
href="http://common-lisp.net/project/cl-gsl/">cl-gsl</a>.
</div>
<div class="footer">
......@@ -158,7 +145,7 @@ svn checkout svn://common-lisp.net/project/gsll/svn/trunk gsll
<!-- Created: Feb 25 2005 -->
<!-- hhmts start -->
<small>
Time-stamp: <2008-03-27 23:08:11EDT index.html>
Time-stamp: <2008-08-31 22:54:34EDT index.html>
</small>
<!-- hhmts end -->
</div>
......
;; Definition of GSLL system
;; Liam Healy
;; Time-stamp: <2008-08-31 12:49:38EDT gsll.asd>
;; Time-stamp: <2008-08-31 22:50:22EDT gsll.asd>
;; $Id$
(asdf:defsystem "gsll"
......@@ -78,7 +78,7 @@
(:file "zeta" :depends-on (return-structures))))
(:file "sorting" :depends-on (init data))
(:module linear-algebra
:depends-on (init data)
:depends-on (init data special-functions)
:components
((:file "blas1")
(:file "blas2")
......
;; GSL errors
;; Liam Healy Sat Mar 4 2006 - 18:33
;; Time-stamp: <2008-03-27 23:07:29EDT conditions.lisp>
;; Time-stamp: <2008-08-31 22:52:09EDT conditions.lisp>
;; $Id$
(in-package :gsl)
......@@ -26,6 +26,14 @@
(:documentation
"A condition that has been signalled by the GNU Scientific Library."))
#|
;;; This makes the printing of the condition object more informative,
;;; but also overrides the :report which I don't want to do.
(defmethod print-object ((object gsl-condition) stream)
(print-unreadable-object (object stream :type t :identity t)
(format stream "~a (GSL condition)" (error-text object))))
|#
(defparameter *errorno-keyword* nil)
(defmacro define-gsl-condition (keyword number text)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment