diff --git a/documentation/development.html b/documentation/development.html deleted file mode 100644 index 7bc19d03d78dbcb101f6c41a8cfd818facae7561..0000000000000000000000000000000000000000 --- a/documentation/development.html +++ /dev/null @@ -1,106 +0,0 @@ -<!-- -*- 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> diff --git a/documentation/documentation.html b/documentation/documentation.html deleted file mode 100644 index ee1ad8e72e4b19608886663c6d4c3f92cc6a0bd4..0000000000000000000000000000000000000000 --- a/documentation/documentation.html +++ /dev/null @@ -1,224 +0,0 @@ -<!-- -*- 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)) -#<VECTOR-DOUBLE-FLOAT #(-5.09d0 0.0d0 16.9d0)> -</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> diff --git a/documentation/index.html b/documentation/index.html index 44c14972040080860e300c08053920299c0e70a9..55e46a0856ed6073e1b1a9b9d4d6dbf0062b9b2e 100644 --- a/documentation/index.html +++ b/documentation/index.html @@ -1,56 +1,66 @@ <!-- -*- 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"> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> +<html> <head> - <link rel="stylesheet" href="style.css" type="text/css"/> - <title>GSLL, the GNU Scientific Library for Lisp</title> + <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 class="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"> - <div class="header"> - <h1>GSLL</h1> - <h2>GNU Scientific Library for Lisp</h2> - </div> - <h3>Introduction</h3> - <div class="content"> - <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 Common Lisp. 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: roots of polynomials, special functions, - vectors and matrices, permutations, sorting, BLAS (basic - linear algebra subprograms), linear algebra, eigensystems, - fast Fourier transforms, quadrature, random numbers, - quasi-random sequences, random distributions, statistics, - histograms, N-tuples, Monte Carlo integration, simulated - annealing, differential equations, interpolation, numerical - differentiation, Chebyshev approximation, series acceleration, - discrete Hankel transforms, root-finding, minimization - least-squares fitting, IEEE floating-point, discrete wavelet - transforms. See documentation on status of some incomplete - topics. - <p>This code should be considered alpha and is still under - development, but it is largely usable - now, with some GSL capability not yet available.</p> - <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 COPYING. There is absolutely no warranty.</p> - </div> - - <h3>Examples</h3> - <div class="content"> +<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> @@ -62,99 +72,252 @@ 1.4821969375237396d-321 2.023692885365746d-320 </pre> - <p>which returns the three function values in succession, 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: </p> +<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] </pre> - </div> +<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 many examples available from within GSLL with the +function <code>examples</code>. These examples also serve +as a test suite for GSLL. -<h3>Requirements and Platforms</h3> - <div class="content"> - <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> - (Version 0.10.0 or newer, - or <a href="http://packages.debian.org/lenny/cl-cffi">the - version in Debian/lenny</a>) - Only platforms and implementations which have callbacks and - foreign-funcall support will work. - </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> - </ul> - <p> - In <a href="http://www.debian.org">Debian</a> Lenny (5.0) or newer, - the following should work:</p> -<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> - and you will need to manually download and install - trivial-garbage; ASDF is automatically installed with your CL - implementation. Once your CL implementation is running, do - <code>(asdf:operate 'asdf:compile-op :gsll)</code> - or, if using Debian with the - <a href="http://packages.debian.org/common-lisp-controller"> - common-lisp-controller</a>, install with - <code>clc-register-user-package</code> and then within Lisp - <code>(clc:clc-require :gsll)</code>. - <p>GSLL has been tested with <a - href="http://sbcl.sourceforge.net/">SBCL</a> on Debian amd64.</p> - </div> +<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> +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:compile-op :gsll)</pre> +<p>and if you wish to run the test suite, +<pre>(asdf:operate 'asdf:compile-op :gsll-tests)</pre> +<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> - <h3>Downloads</h3> - <div class="content"> - <p>See <a href="http://repo.or.cz/w/gsll.git">the official - repository</a> to browse or download. To clone: +<h2>Download</h2> +<a name="getit"/> +<p>Use <a href="http://git.or.cz">git</a> to install: <pre> git clone git://repo.or.cz/gsll.git </pre> -To retrieve a compressed tarball, click one of the "snapshot" links on -the repository web page. - </p> - <ul> - - </ul> - </div> - - <h3>Additional information</h3> +<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). 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> <ul> - <li>A <a href="documentation.html">documentation</a> guide is - available. - <li>The <a href="development.html">development</a> process is described - separately for those interested. - <li>There is a <a - href="http://common-lisp.net/cgi-bin/mailman/listinfo/gsll-devel">mailing - list</a> for all aspects of this project. + <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> </ul> + <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; there is 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>Similar or related projects from others</h3> - <div class="content"> - 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> + <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, and +GSL. This list is available in the +variable <code>*array-element-types*</code>. 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> +<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 names by appending the element + 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> - <div class="footer"> - <hr> - <address><a href="mailto:gsll-devel@common-lisp.net">Liam Healy</a></address> + <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 --> - <small> - Time-stamp: <2008-12-27 14:33:37EST index.html> - </small> +<small> +Time-stamp: <2009-01-01 22:34:36EST index.html> +</small> <!-- hhmts end --> </div> <script type="text/javascript"> @@ -166,5 +329,5 @@ var pageTracker = _gat._getTracker("UA-3669275-1"); pageTracker._initData(); pageTracker._trackPageview(); </script> - </body> + </body> </html> diff --git a/documentation/gsl-new-features.text b/documentation/missing-features.text similarity index 57% rename from documentation/gsl-new-features.text rename to documentation/missing-features.text index 333a5e00f057f8470cac0e01bf91facaeff4b2df..420f50147e403aa59c17cb0477db2f7c41584d28 100644 --- a/documentation/gsl-new-features.text +++ b/documentation/missing-features.text @@ -1,3 +1,12 @@ +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] diff --git a/documentation/site.css b/documentation/site.css new file mode 100644 index 0000000000000000000000000000000000000000..6d3295017c1ad3af0456b6a077150ca96340b644 --- /dev/null +++ b/documentation/site.css @@ -0,0 +1,355 @@ +/* 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; +} diff --git a/documentation/status.text b/documentation/status.text new file mode 100644 index 0000000000000000000000000000000000000000..3e158ac1bab424600383dd0a8ea7369d6d5cdcbc --- /dev/null +++ b/documentation/status.text @@ -0,0 +1,41 @@ +=== 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 correct answer. + +=== Other known bugs === + + + +=== GSL questions === +gsl_stats_float_wmean gives erroneous answers; other weighted? +Query: What is _swap_rowcol supposed to do? What is its purpose? +gsl_blas_cdotu, gsl_blas_cdotc give nonsense results. +Any explanation for any of the modified Givens rotations such as +gsl_blas_drotmg? +gsl_blas_dger rank 1 update says lengths are bad? +(from Sun Nov 9 2008) diff --git a/documentation/style.css b/documentation/style.css index a6119ddfb69fad5525f0baafe24d3a4264d72a03..1ca7bf3d832b135242c7a058529c2930c0d6caac 100644 --- a/documentation/style.css +++ b/documentation/style.css @@ -1,59 +1,54 @@ -body { - font-family: sans-serif; - background-color: white; - color: black; - margin: 0; - padding: 0; -} -.header * { - color: black; - background-color: #cc4422; - margin: 0; - padding: 0.5em; +.header { + font-size: medium; + background-color:#336699; + color:#ffffff; + border-style:solid; + border-width: 5px; + border-color:#002244; + padding: 1mm 1mm 1mm 5mm; } -h1 { +.footer { + font-size: small; + font-style: italic; text-align: right; + background-color:#336699; + color:#ffffff; + border-style:solid; + border-width: 2px; + border-color:#002244; + padding: 1mm 1mm 1mm 1mm; } -.info { - text-align: left; - font-weight: bold; - line-height: 1em; +.footer a:link { + font-weight:bold; + color:#ffffff; + text-decoration:underline; } -.body { - margin: 2em 1em; +.footer a:visited { + font-weight:bold; + color:#ffffff; + text-decoration:underline; } -.level { - margin: 1em; -} +.footer a:hover { + font-weight:bold; + color:#002244; + text-decoration:underline; } -p { - margin: 1em 0em; - padding: 0em; -} +.check {font-size: x-small; + text-align:right;} -a { - color: maroon; -} +.check a:link { font-weight:bold; + color:#a0a0ff; + text-decoration:underline; } -ul { - margin: 1em; - padding: 0em; -} - -pre { - margin: 0em; - padding: 1em; - border: 1px solid; - background-color: #eeeeee; - vertical-align: baseline; -} - -img { - border: 0; -} +.check a:visited { font-weight:bold; + color:#a0a0ff; + text-decoration:underline; } +.check a:hover { font-weight:bold; + color:#000000; + text-decoration:underline; }