[lisplab-cvs] r93 - doc/manual
Jørn Inge Vestgården
jivestgarden at common-lisp.net
Sat Sep 12 19:29:39 UTC 2009
Author: jivestgarden
Date: Sat Sep 12 15:29:38 2009
New Revision: 93
Log:
almost finished manual
Modified:
doc/manual/lisplab.texi
Modified: doc/manual/lisplab.texi
==============================================================================
--- doc/manual/lisplab.texi (original)
+++ doc/manual/lisplab.texi Sat Sep 12 15:29:38 2009
@@ -3,14 +3,16 @@
@settitle Lisplab manual
@copying
-GPL
+This manual is for Lisplab version 0.1, updated 10. September 2009.
Copyright @copyright{} 2009 Joern Inge Vestgaarden
@end copying
@titlepage
@title Lisplab manual
-
+ at subtitle A mathematics library for Common Lisp
+ at author Joern Inge Vestgaarden
+
@page
@vskip 0pt plus 1filll
@insertcopying
@@ -19,10 +21,13 @@
@contents
@ifnottex
- at node Top
+ at node Top
+
@top Lisplab manual
@end ifnottex
+
+
@menu
* Introduction::
@@ -30,7 +35,7 @@
* Tutorial::
* Structure::
* Discussion::
-* Index::
+ at c * Index::
@end menu
@c The body
@@ -173,7 +178,7 @@
Lisplab started as a refactoring of Matlisp (To make my simulations
run on Windows for my professor), but
-I ended up by reimplementing most of it, keeping
+I (Joern Inge) ended up by reimplementing most of it, keeping
only the interfaces to Blas and Lapack. Currently,
Lisplab and Matlisp have more or less the same functionality.
Lisplab differ from Matlisp in the following ways
@@ -224,25 +229,6 @@
that uses @i{lisplab}.
- at section The dotted algebra
-Central in Lisplab is an algebra (in the widest possible sense of the word)
-with the functions
- at code{.+}, @code{.-}, @code{.*}, @code{./}, and @code{.^}.
-These are generalization of
- at code{+}, @code{-}, @code{*}, @code{/}, and @code{^}.
-For numbers they work the same,
- at example
-LL> (.+ 1 2)
-3
- at end example
-The functions @code{.+}, @code{.-}, @code{.*}, @code{./}, and @code{.^}
-are mainly wrappers that call @code{reduce} on its arguments with the
-generic functions
- at code{.add}, @code{.sub}, @code{.mul}, @code{.div}, and @code{.expt}.
-If you want to extend the algebra, e.g. with polynomials,
-you should add specializing methods to these generic functions.
-
-
@section Matrix classes
The matrix classes hierarchy has three lines of inheritance. The
first is on structure, the second is on element type, and
@@ -331,7 +317,7 @@
use @code{copy-contents} instead.
- at section Matrix element reference
+ at section Matrix element reference (mref and vref)
To access a matrix element use the generic function @code{mref}
@example
LL> (mref (dmat (1 2) (3 4)) 0 1)
@@ -349,27 +335,30 @@
which is also settable. Note that the matrices are column major order.
- at section Matrix map
-There are two methods for mapping of matrices: @code{mmap} and
- at code{mmap-into}. For example
+
+ at section The dotted algebra (.+, .*, .sin, ...)
+Central in Lisplab is an algebra (in the widest possible sense of the word)
+with the functions
+ at code{.+}, @code{.-}, @code{.*}, @code{./}, and @code{.^}.
+These are generalization of
+ at code{+}, @code{-}, @code{*}, @code{/}, and @code{^}.
+For numbers they work the same,
@example
-LL> (mmap 'matrix-dge #'realpart (zmat (1 %i) (-%i 2)))
-#<MATRIX-DGE 2x2
-1.0 0.0
-0.0 2.0
- @{A9BD489@}>
+LL> (.+ 1 2)
+3
@end example
-The output matrix takes the structure from the first arguments, but
-ignores in general matrix structure. If first argument @code{t} output
-type is same as type of first matrix argument.
-
+The functions @code{.+}, @code{.-}, @code{.*}, @code{./}, and @code{.^}
+are mainly wrappers that call @code{reduce} on its arguments with the
+generic functions
+ at code{.add}, @code{.sub}, @code{.mul}, @code{.div}, and @code{.expt}.
+If you want to extend the algebra, e.g. with polynomials,
+you should add specializing methods to these generic functions.
- at section The dotted algebra
The element-vise functions by conventions have names starting
with a dot (period). The dotted algebra works on the single elements and
is structure agnostic. The functions of the dotted algebra
-introduce a programming style
-much the same as for Matlab, and combined with the linear algebra
+introduce a programming style much the same as for Matlab,
+and combined with the linear algebra
functions, you can write compact programs, without the slow
single element references.
@example
@@ -513,6 +502,21 @@
with @code{view-matrix}, @code{view-col}, or @code{view-row}.
+ at section Matrix map
+There are two methods for mapping of matrices: @code{mmap} and
+ at code{mmap-into}. For example
+ at example
+LL> (mmap 'matrix-dge #'realpart (zmat (1 %i) (-%i 2)))
+#<MATRIX-DGE 2x2
+1.0 0.0
+0.0 2.0
+ @{A9BD489@}>
+ at end example
+The output matrix takes the structure from the first arguments, but
+ignores in general matrix structure. If first argument @code{t} output
+type is same as type of first matrix argument.
+
+
@section Ordinary functions
These are:
@code{.sin}, @code{.cos}, @code{.sin}, @code{.tan},
@@ -561,10 +565,13 @@
(There should be no need
for optimized math in FFIs or special languages like Maxima)
@item Every common mathematical operator and function
-is represented by a @i{CLOS generic function}.
+is represented by a @i{CLOS generic function}. This is called the dotted algebra.
@item Modular structure (Inspired by GSL).
+ at item Trust the Lisp system and use foreign code as little as possible.
+ at item Avoid programming mathematical algorithms in macros. Despite the
+advantages (fast and generic at the same time) it is hard to understand and debug.
@item Error checks is primarily callers responsibility, not Lisplab's!
- at item To steal as much as possible from as many as possible
+ at item To steal as much code as possible from as many as possible
(I love free software).
@end itemize
@@ -684,26 +691,40 @@
@node Discussion
@chapter Discussion
- at section Experiences with Common Lisp in high performance computing
-
@section The foreign function interfaces
+The elements of Lisplab typed matrices (double-float and complex double-float) are
+stored as 1D simple arrays, and most Lisps will then have
+a SAP inside the array pointer which is binary compatible
+with Fortran. This adds some overhead to matrix element references,
+but simplifies the garbage collections.
+
+Matlisp has an extra layer with Fortran compatibility above
+the ordinary C FFI. This layer is mainly unchanged compared
+to Matlisp, but only the SBCL FFI is in the code. The
+FFIs for other lisps could easily be added, but not without testing.
+
+The FFI for FFTW is a mock-up for SBCL, and it only is for standard
+complex transforms and inverse transforms. Of course, a lot more can
+be done, but this simple version works quite OK. In long term the SBCL
+FFI should be replaced with a general one.
+
@section Parallel execution
To request usage of more threads, call @code{init-threads}.
-Currently, only the calls to FFTW will react to this.
+Currently only the calls to FFTW will react to this.
@section Symbolic calculations
-There is some minor code for this, but it is not yet included
-in the package. Symbolic code should be developed only with
-knowledge of the generic methods of the dotted algebra (The level 0).
+There is draft code for symbolic calculations, but it is not yet included
+in the build. The symbolic code need not know anything about the rest of Lisplab,
+except for the generic methods of the dotted algebra (The level 0).
@c End stuff
- at node Index
- at unnumbered Index
+ at c @node Index
+ at c @unnumbered Index
- at printindex cp
+ at c @printindex cp
@bye
More information about the lisplab-cvs
mailing list