Commit 262e486e authored by Liam Healy's avatar Liam Healy

Documentation current

Rewrote the documentation to reflect the current state of the
software, as a single HTML file index.html, and used a new css style
cribbed from iterate.  There are two text files added: status.text
that is a summary of test pass/fail on various implementations and
platforms, and missing-features.text that documents features of GSL
that aren't included.
parent c057c7f3
<!-- -*- mode: HTML; time-stamp-line-limit: -18; -*- -->
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.nw3.org/1999/xhtml">
<head>
<link rel="stylesheet" href="style.css" type="text/css"/>
<title>GSLL Development</title>
</head>
<body>
<div class="body">
<div class="header">
<h1>GSLL Development</h1>
<h2>GSLL Development</h2>
</div>
<h3>Goals</h3>
<p>The goal of this project is to provide as complete an interface
to the GSL as possible in as Lisp-natural a way as is reasonable. It is
written only in Common Lisp (no C), with access to the foreign library
through CFFI.
<h3>Non-goals</h3>
The following is not part of the plan for the GSLL interface:
<ul>
<li>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, Physical Constants
are all defined as C macros.</li>
<li>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.</li>
<li>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.
</li>
</ul>
<h3>Status</h3>
<div class="content">
<p>There is a <a href="http://trac.common-lisp.net/gsll">Trac page</a>
for development information and for reporting bugs. There is a <a
href="http://common-lisp.net/cgi-bin/mailman/listinfo/gsll-devel">mailing
list</a> for all aspects of this project.
</p>
<p>Most of the interface is complete, with a few chapters missing
and some functionality missing. See the <a
href="documentation.html">documentation</a> for details,
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.
<h3>Contributions</h3>
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.
The arguments and defaults provide a convenient way of defining new
functions and variables.
</div>
<h3>Regression tests</h3>
<div class="content">
<p>Regression tests using <a
href="http://www.cs.northwestern.edu/academics/courses/325/readings/lisp-unit.html">lisp-unit</a>
(provided) are given for many of the functions defined. These
also serve as examples. 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,
<pre>
(lisp-unit:run-tests)
</pre>
See <a href="documentation.html">documentation</a> regarding known failures.
</p>
<hr>
<address><a href="mailto:gsll-devel@common-lisp.net">Liam Healy</a></address>
<small>
Time-stamp: <2008-08-31 20:14:05EDT development.html>
</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>
</body>
</html>
<!-- -*- mode: HTML; time-stamp-line-limit: -18; -*- -->
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<link rel="stylesheet" href="style.css" type="text/css"/>
<title>GSLL Documentation</title>
</head>
<body>
<div class="body">
<div class="header">
<h1>GSLL Documentation</h1>
<h2>GSLL Documentation</h2>
</div>
<h3>General Advice</h3>
<div class="content">
<p>There is little separate documentation for GSLL. Instead, the
following techniques for using the API are advised:</p>
<ul>
<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>
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>
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 intentionally designed to signal an error, because the
examples also serve as a regression (unit) test suite for GSLL.</li>
</ul>
It is advisable to look at the examples first for calculations that
require more complex setup (generally, the later chapters in the GSL
manual).
</div>
<h3>GSL objects and letm </h3>
There are a number of GSL structures available that must be manually
allocated, possibly set, and freed. In
order to make this as convenient as possible, the macro
<code>letm</code> is provided. This macro acts as a
<code><a
href="http://www.lispworks.com/documentation/HyperSpec/Body/s_let_l.htm#letST">let*</a></code>,
with the additional feature that if the init-form is one of GSL objects
<pre>
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-* 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-* 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.
For Lisp environments with arglist prompting (such as SLIME), these
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>Arrays</h3>
<div class="content">
<p>FIX: #m, #nm, <code>make-array*</code>
<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, 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 ((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 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>Additional definitions</h3>
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>
<h3>Status</h3>
<div class="content">
Consistent with the <a href="development.html">development</a>
philosophy, most of the interface to the library is done. Notes
on particular chapters:
<ul>
<base href="http://www.gnu.org/software/gsl/manual/html_node/">
<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. For GSL
functions that take a stride, it is pre-set to 1 in GSLL.
<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
because GSL does not supply an example and it is not clear how it is
used. Contributions welcome.
<li><a href="Simulated-Annealing.html">Simulated Annealing</a> is
known to have problems in GSL and a replacement <a
href="https://gna.org/projects/annealing">is being redesigned</a>;
the version distributed has been ported in GSLL but does not work.
<li><a href="Wavelet-Transforms.html">Wavelet Transforms</a> has been
done but the results of the example do not agree with the GSL manual.
<li><a href="Discrete-Hankel-Transforms.html">Discrete Hankel
Transforms</a> has been done but there is no example given in the GSL
manual.
<li><a href="Basis-Splines.html">Basis splines</a> example runs, but
the GSL documentation does not provide the result for comparison.
</ul>
<p>
There are failures observed in the regression tests
<code>(lisp-unit:run-tests)</code>:
<ul>
<li>CLISP shows three "foreign callout errors." Remedy unknown.
<li>There are several regression failures that are apparently due to
changes in GSL between versions 1.8 and 1.10. These are:
beta, chi-squared, dirichlet, elliptic-functions, fdist,
gamma-randist, negative-binomial.
</ul>
<div class="footer">
<hr>
<address><a href="mailto:gsll-devel@common-lisp.net">Liam Healy</a></address>
<!-- hhmts start -->
<small>
Time-stamp: <2008-12-26 15:10:41EST documentation.html>
</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>
</body>
</html>
This diff is collapsed.
The following features are missing from GSLL:
Fast Fourier Transforms
Simulated annealing is broken
All file input and output (fread, fwrite) functions.
All submatrix functions and views.
Stride is always set to 1 in GSL functions that take a stride.
Some things that have been added to GSL since 1.8 that should be added
to GSLL:
......@@ -28,3 +37,21 @@ order exponential integral.
** Added support in gsl_ieee_set_mode for controlling SSE exceptions
and rounding through the MXCSR control word on x86 processors.
[Modify existing GSLL function.]
GSL 1.11
http://lists.gnu.org/archive/html/info-gsl/2008-03/msg00000.html
** Added new quasi random generators gsl_qrng_halton and
gsl_qrng_reversehalton which support dimensions up to 1229.
** Added function gsl_multifit_linear_residuals for computing the
residuals of the fit
** Added functions for evaluating complex polynomials
GSL 1.12
http://lists.gnu.org/archive/html/info-gsl/2008-12/msg00001.html
** Added a faster simplex mininimser gsl_multimin_fminimizer_nmsimplex2
which is O(N) instead of O(N^2) [bug #24418]
** Added new auxiliary functions gsl_cheb_order, gsl_cheb_size,
gsl_cheb_coeffs for Chebyshev series [bug #21830]
** Added missing functions gsl_vector_complex_{isnonneg,add,sub,mul,
div,scale,add_constant} and gsl_matrix_complex_float_isnonneg [bug
#22478]
/* taken & adapted with permission from John Wiegley's brilliant site
at http://www.newartisans.com/johnw/. Thanks, John! */
/* The HTML body */
body {
margin: 0px;
}
.left-float {
float: left;
padding: 20px;
}
.right-float {
float: right;
padding: 20px;
}
/* The top banner */
#banner {
color: #000000;
background-color: #E8E8E8;
padding: 10px 0px 10px 15px; /* t r b l */
}
#banner a {
color: #483D8B;
text-decoration: none;
}
#banner h1, h2 {
font-family: 'Trebuchet MS', Verdana, sans-serif;
font-weight: bold;
margin: 0px;
}
#banner h1 {
font-size: large;
line-height: 150%;
}
#banner h2 {
font-size: medium;
}
/* The true body, which remains below the banner */
#body {
font-family: Verdana, Arial, sans-serif;
margin: 0px;
}
#body a {
text-decoration: underline;
font-weight: bold;
}
#body a:link { color: #666666; }
#body a:visited { color: #666666; }
#body a:active { color: #666666; }
#body a:hover { color: #CC6600; }
#body h1, h2, h3 {
font-family: 'Trebuchet MS', Verdana, sans-serif;
font-size: large;
}
/* The content, which is the left part of the body */
#content {
padding-top: 25px;
padding-left: 15px;
padding-right: 15px;
color: #333;
background-color: #FFFFFF;
line-height: 150%;
}
#content table {
border-width: 0 0 0 0;
border-style: none;
padding-top: 10px;
margin-left: 30px;
margin-right: 30px;
}
#content td {
border-width: 0 0 0 0;
border-style: none;
padding: 1px;
}
#content th {
font-weight: bold;
text-align: left;
border-width: 0 0 1px 0;
border-style: solid;
padding: 0;
}
#content p.quoted {
margin-left: 20px;
margin-right: 20px;
}
#content hr {
margin: 0px;
}
#content dl {
margin-left: 25px;
}
#content dd {
margin-left: 25px;
margin-right: 40px;
margin-bottom: 15px;
}
#content ol {
margin-left: 30px;
}
#content li {
margin-left: 0px;
}
#content p {
margin-left: 25px;
margin-right: 15px;
margin-top: -7px;
/* text-indent: 30px; */
}
#content pre {
margin-left: 25px;
}
#content p.first { text-indent: 0px; }
#content p.quoted { text-indent: 0px; }
#content p.footnote { text-indent: 0px; }
#content hr {
margin-left: 15px;
margin-right: 15px;
margin-bottom: 10px;
}
#content h2 {
color: #666666;
font-weight: bold;
margin-top: 25px;
margin-left: 0px;
border-bottom: 1px solid #999;
margin-bottom: 15px;
}
#content h2.first {
margin-top: 0px;
}
#content h3 {
color: #000000;
font-size: medium;
font-weight: bold;
margin-left: 25px;
/*margin-bottom: -10px;*/
margin-bottom: 15px;
}
#content code {
font-family: Courier, sans-serif;
}
#content .verse {
margin-left: 45px;
text-indent: 0px;
}
#content .example {
font-family: Courier, sans-serif;
white-space: pre;
line-height: 110%;
margin-left: 40px;
color: purple;
}
/* Blog entries within the content */
#entry {
margin-top: -15px;
padding-left: 10px;
padding-right: 20px;
}
blog-entry {
margin-top: -15px;
padding-left: 10px;
padding-right: 20px;
}
#entry-head {
border-bottom: 1px solid #999;
margin-bottom: 15px;
}
entry-head {
border-bottom: 1px solid #999;
margin-bottom: 15px;
}
#entry-head h2 {
margin-top: 0px;
margin-bottom: 0px;
border-bottom: 0px;
}
entry-head h2 {
margin-top: 0px;
margin-bottom: 0px;
border-bottom: 0px;
}
#entry-date {
font-size: small;
font-weight: bold;
padding-right: 20px;
float: right;
}
entry-date {
font-size: small;
font-weight: bold;
padding-right: 20px;
float: right;
}
#entry-text {
margin-right: 20px;
}
entry-text {
margin-right: 20px;
}
#content p.quoted {
margin-left: 10px;
margin-right: 20px;
}
#entry-text img {
padding-bottom: 10px;
}
entry-text img {
padding-bottom: 10px;
}
#entry-qotd {
position: relative;
top: 0px;
right: 0px;
float: right;
margin-top: 10px;
padding: 10px;
margin-left: -40px;
}
/* Sina's style:
#entry-qotd {
background-color: #C6D1DF;
foreground-color: #304B6D;
width: 20%;
float: right;
margin-left: 25px;
padding: 5px;
padding-bottom: 25px;
border-width: 10px;
border-color: white;
}
#entry-qotd p {
margin-left: 5px;
margin-right: 5px;
}
#entry-qotd h3 {
color: white;
font-size: medium;
font-weight: bold;
margin-top: 0px;
margin-left: 0px;
margin-bottom: 15px;
}
*/
/* The sidebar, which is the right part of the body */
#sidebar {
position: relative;
top: 0px;
right: 0px;
float: right;
padding: 15px;
width: 22%;
font-family: 'Trebuchet MS', Verdana, sans-serif;
font-size: 90%;
background-color: #E8E8E8;
border-style: solid;
border-top-width: 0px;
border-right-width: 0px;
border-left-width: 25px;
border-bottom-width: 10px;
border-color: white;
}
#sidebar h2 {
color: #000000;
text-align: center;
font-weight: bold;
font-size: small;
text-transform: uppercase;
padding: 3px;
letter-spacing: .3em;
}
#sidebar a {
color: #483D8B;
}
#sidebar ul {
padding-top: 5px;
padding-left: 0px;
margin: 0px;
margin-bottom: 30px;
}
#sidebar li {
color: #000000;
line-height: 140%;
margin-top: 5px;
list-style-type: none;
}
=== Test results summary ===
64-bit SBCL: TOTAL: 1223 assertions passed, 5 failed, 0 execution errors.
64-bit CCL: TOTAL: 1228 assertions passed, 0 failed, 0 execution errors.
64-bit CLISP: not tested; bug in CLISP causes crash on loading
32-bit SBCL: TOTAL: 1069 assertions passed, 31 failed, 0 execution errors.
32-bit CLISP: TOTAL: 1051 assertions passed, 27 failed, 5 execution errors.
=== 32-bit implementations ===
Small numerical differences account for most of these errors.
In addition, CLISP has these additional problems:
CHEBYSHEV: Should have signalled TYPE-ERROR but saw #<SIMPLE-ERROR #x20EB4F1E>
COMBINATION: FFI:FOREIGN-ALLOCATE: element type has size 0: #(FFI:C-ARRAY FFI:UINT8 0)
MATRIX-SET-ALL-M+: FFI::WRITE-MEMORY-AS: NIL cannot be converted to the foreign type SINGLE-FLOAT
SHUFFLING-SAMPLING: FFI::WRITE-MEMORY-AS: NIL cannot be converted to the foreign type FFI:INT
NUMERICAL-INTEGRATION: FFI::FOREIGN-CALL-OUT: 3.1415926535897932385L0 cannot be converted to the foreign type DOUBLE-FLOAT
VECTOR-SET-ALL-M+: FFI::WRITE-MEMORY-AS: NIL cannot be converted to the foreign type SINGLE-FLOAT
=== 64-bit SBCL ===
2 failures each in matrix-min and vector-min for (signed-byte 8) and
(signed-byte 16):
Expected (-91) but saw (165)
Expected (-91) but saw (65445)
Expected (-68) but saw (188)
Expected (-68) but saw (65468)
ELLIPTIC-FUNCTIONS: (MULTIPLE-VALUE-LIST (JACOBIAN-ELLIPTIC-FUNCTIONS 0.2d0 0.81d0))
This gives an errorneous error value (4th returned value) when run
from the shell; run inside SLIME gives the c