root/trunk/documentation/documentation.html

Revision 51, 6.9 kB (checked in by lhealy, 8 months ago)

Fix typo.
  • Property svn:keywords set to Id
Line 
1<!-- -*- mode: HTML; time-stamp-line-limit: -18; -*- -->
2<?xml version="1.0" encoding="iso-8859-1"?>
3<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
4<html xmlns="http://www.w3.org/1999/xhtml">
5  <head>
6    <link rel="stylesheet" href="style.css" type="text/css"/>
7       <title>GSLL Documentation</title>
8  </head>
9  <body>
10    <div class="body">
11
12 <div class="header">
13  <h1>GSLL Documentation</h1>
14  <h2>GSLL Documentation</h2>
15 </div>
16
17 <h3>General Advice</h3>
18 <div class="content">
19
20 <p>There is little separate documentation for GSLL.  Instead, the
21 following techniques for using the API are advised:</p>
22 <ul>
23 <li>Find the appropriate function(s) in the <a
24 href="http://www.gnu.org/software/gsl/manual/">GSL
25 documentation</a>.</li>
26 <li>Use the GSLL function <code>gsl-lookup</code>
27  to find the equivalent GSLL function, for example
28<pre>
29(gsl-lookup "gsl_sf_elljac_e")
30JACOBIAN-ELLIPTIC-FUNCTIONS
31T
32</pre>
33to find that the Lisp function name is <code>#'jacobian-elliptic-functions</code>. 
34  </li>
35 <li>Look at the documentation for that Lisp function, e.g.
36   <pre>(documentation #'jacobian-elliptic-functions 'function)
37"The Jacobian elliptic functions sn(u|m),
38  cn(u|m), dn(u|m) computed by descending Landen transformations."
39   </pre>
40   to get an explanation of the arguments etc.
41 </li>
42 <li>Look at the end of the Lisp source file, or in an "example" file
43 in the same directory, for examples.  Often, the examples are placed
44 in a <code>make-tests</code> form (which will be commented out with
45 a #| |# block).  If the
46 <a href="http://www.gnu.org/software/gsl/manual/">GSL documentation</a>
47 provides an example, there will usually be the same or similar
48 example provided in GSLL.</li>
49 </ul>
50 It is advisable to look at the examples first for calculations that
51 require more complex setup (generally, the later chapters in the GSL
52 manual).
53 </div>
54
55 <h3>GSL objects and letm </h3>
56There are a number of GSL structures available that must be manually
57allocated, possibly set, and freed.  In
58order to make this as convenient as possible, the macro
59<code>letm</code> is provided.  This macro acts as a
60<code><a
61href="http://www.lispworks.com/documentation/HyperSpec/Body/s_let_l.htm#letST">let*</a></code>,
62with the additional feature that if the init-form is one of GSL objects
63
64<pre>
65acceleration basis-spline block-complex block-double-float block-fixnum
66block-single-float chebyshev combination complex-workspace
67discrete-random eigen-herm eigen-hermv eigen-symm eigen-symmv
68fdfsolver fit-workspace fminimizer fsolver hankel histogram
69integration-workspace interpolation levin levin-truncated
70matrix-complex matrix-double-float matrix-fixnum
71matrix-single-float mfdfminimizer mfdfsolver mfminimizer mfsolver
72monte-carlo-miser monte-carlo-plain monte-carlo-vegas
73nonlinear-fdffit nonlinear-ffit permutation
74quasi-random-number-generator random-number-generator spline
75vector-complex vector-double-float vector-fixnum
76vector-single-float wavelet wavelet-workspace
77</pre>
78the appropriate object will be allocated and bound to the variable,
79optionally set, and then freed when the body of the let is exited.
80For Lisp environments with arglist prompting (such as SLIME), these
81are functions whose symbols are exported so that an arglist prompt
82will be visible; however, the function should not be used outside a
83<code>letm</code> binding.
84
85 <h3>Data: vectors, matrices, etc.</h3>
86 <div class="content">
87 <p>
88 Collectively, vectors, matrices, histograms and the like are called
89 <i>data</i>.  There are many different types of vectors and matrices
90 supported by GSL, but GSLL has implemented only a few of these:
91 complex, double-float, single-float, and fixnum, because those types
92 are defined by the Common Lisp standard.
93 <p>Vectors and matrices can be converted to and from their Lisp
94 counterparts with <code>data</code> and <code>(setf data)</code>.
95 Setting the GSL value to a Lisp value at initialization
96 can be done within the <code>letm</code> by giving the Lisp value as
97 the first argument after the type, for example
98<pre>
99(letm ((vec (vector-double-float #(-3.21d0 1.0d0 12.8d0))))
100   (data vec))
101</pre>
102 Individual elements of data may be accessed with <code>maref</code>,
103 either directly or in a <code>setf</code>.
104
105 <h3>Status</h3>
106 <div class="content">
107 Consistent with the <a href="development.html">development</a>
108 philosophy, most of the interface to the library is done.  Notes
109 on particular chapters:
110<ul>
111<base href="http://www.gnu.org/software/gsl/manual/html_node/">
112<li><a href="Vectors-and-Matrices.html">Vectors and Matrices</a>
113        are done for integer, real, double, complex.
114         Subvectors and views don't work.  Other element types may be
115        difficult to port due to lack of CL definition.
116<li>Functions that provide file input and output to files are not tested and
117 likely will need other definitions (perhaps in C) to function
118 properly, unless CFFI and the CL platform provide C stream
119 compatibility.
120<li><a href="BLAS-Support.html">BLAS</a> is completed, but with only very
121 limited testing.
122 <li><a href="Fast-Fourier-Transforms.html">FFTs</a> have not been done
123 because GSL does not supply an example and it is not clear how it is
124 used.  Contributions welcome.
125<li><a href="Simulated-Annealing.html">Simulated Annealing</a> is
126 known to have problems in GSL and a replacement <a
127 href="https://gna.org/projects/annealing">is being redesigned</a>;
128 the version distributed has been ported in GSLL but does not work.
129<li><a href="Wavelet-Transforms.html">Wavelet Transforms</a> has been
130 done but the results of the example do not agree with the GSL manual.
131<li><a href="Discrete-Hankel-Transforms.html">Discrete Hankel
132 Transforms</a> has been done but there is no example given in the GSL
133 manual.
134<li><a href="Basis-Splines.html">Basis splines</a> example runs, but
135 the GSL documentation does not provide the result for comparison.
136</ul>
137<p>
138There are failures observed in the regression tests
139<code>(lisp-unit:run-tests)</code>:
140<ul>
141<li>CLISP shows three "foreign callout errors." Remedy unknown.
142<li>There are several regression failures that are apparently due to
143changes in GSL between versions 1.8 and 1.10.  These are:
144beta, chi-squared, dirichlet, elliptic-functions, fdist,
145gamma-randist, negative-binomial.
146</ul>
147
148 <div class="footer">
149    <hr>
150    <address><a href="mailto:gsll-devel@common-lisp.net">Liam Healy</a></address>
151<!-- hhmts start -->
152    <small>
153       Time-stamp: <2008-04-11 11:47:28EDT documentation.html>
154       </small>
155<!-- hhmts end -->
156 </div>
157<script type="text/javascript">
158var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
159document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
160</script>
161<script type="text/javascript">
162var pageTracker = _gat._getTracker("UA-3669275-1");
163pageTracker._initData();
164pageTracker._trackPageview();
165</script>
166 </body>
167</html>
Note: See TracBrowser for help on using the browser.