[lisplab-cvs] r92 - doc/manual
Jørn Inge Vestgården
jivestgarden at common-lisp.net
Thu Sep 10 19:18:53 UTC 2009
Author: jivestgarden
Date: Thu Sep 10 15:18:53 2009
New Revision: 92
Log:
more writing
Modified:
doc/manual/lisplab.texi
Modified: doc/manual/lisplab.texi
==============================================================================
--- doc/manual/lisplab.texi (original)
+++ doc/manual/lisplab.texi Thu Sep 10 15:18:53 2009
@@ -5,7 +5,7 @@
@copying
GPL
-Copyright @copyright{} 2009 Jorn Inge Vestgaarden
+Copyright @copyright{} 2009 Joern Inge Vestgaarden
@end copying
@titlepage
@@ -29,6 +29,7 @@
* Getting started::
* Tutorial::
* Structure::
+* Discussion::
* Index::
@end menu
@@ -84,6 +85,9 @@
@item The @code{*READ-DEFAULT-FLOAT-FORMAT*} must be @code{double-float}.
@end itemize
+Except from this, Lisplab should be self-contained and not depend on
+any other projects.
+
@section Installing
Lisplab is ASDF installable, but before you come so far you need to
specify the location of the foreign libraries.
@@ -203,15 +207,21 @@
@node Tutorial
@chapter Tutorial
+
@section Starting
-To test Lisplab open Emacs and Slime in the lisplab directory.
+Currently Lisplab only runs on SBCL, and there is a small porting
+job (mainly the FFIs and a few uses of SB-EXT package) to
+get it run on other platforms. If you have SBCL you must
+make sure that @code{lisplab.asd} is (or pointed to) in @code{asdf:*centeral-registry*}.
+Then type
@example
-CL-USER> (load "start.lisp")
+CL-USER> (require :lisplab)
CL-USER> (in-package :ll)
@end example
The main package of Lisplab is @i{lisplab}, with nickname @i{ll}.
The tutorial assues that you are in the @i{lisplab} package or
-use it.
+use it. There is also a package @i{lisplab-user}, with nickname @i{ll-user}
+that uses @i{lisplab}.
@section The dotted algebra
@@ -232,6 +242,7 @@
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
@@ -266,6 +277,7 @@
by default. To add new classes in a structured way,
@xref{Structure}.
+
@section Matrix construction
The constructor @code{make-matrix-instance} is not
the primary choice to create a matrix. Its better to use a special
@@ -318,6 +330,7 @@
(e.g., conversion from complex to real),
use @code{copy-contents} instead.
+
@section Matrix element reference
To access a matrix element use the generic function @code{mref}
@example
@@ -335,6 +348,22 @@
@end example
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 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 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
@@ -463,6 +492,7 @@
Note that the IO functions are currently in a poor state.
+
@section Matrices without store
The class @code{function-matrix} implements matrices with
functions and has no store.
@@ -482,6 +512,7 @@
Function matrices are also used to view a part or restructured other matrix
with @code{view-matrix}, @code{view-col}, or @code{view-row}.
+
@section Ordinary functions
These are:
@code{.sin}, @code{.cos}, @code{.sin}, @code{.tan},
@@ -491,6 +522,7 @@
@code{.conj},
@code{.realpart}, @code{.imagpart}, @code{.exp}, @code{.abs}.
+
@section Special functions
These are:
@code{.besj}, @code{.besy},
@@ -498,6 +530,7 @@
@code{.besh1}, @code{.besh2},
@code{.ai}, @code{.gamma}.
+
@section Infix notation
Infix input is with the macro @code{w/infix},
where you must have spaces before and after
@@ -516,6 +549,7 @@
@node Structure
@chapter Structure
+
@section Design principles
Design principles for the full library
@itemize
@@ -523,15 +557,13 @@
@item It makes a @i{homogeneous platform} for all
kinds of mathematical calculations. (So it's a lot more
than just a matrix library)
- at item User applications need only to stay in Common Lisp.
+ at item User applications should need to stay only in Common Lisp.
(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}. (By convention
-the names of the operators start with a dot and is called
-the dotted algebra, where algebra is used in the widest possible sense
-of the word).
+is represented by a @i{CLOS generic function}.
@item Modular structure (Inspired by GSL).
+ at item Error checks is primarily callers responsibility, not Lisplab's!
@item To steal as much as possible from as many as possible
(I love free software).
@end itemize
@@ -539,21 +571,22 @@
Design principles for the matrix part
@itemize
@item Layered structure where dependencies are
-primarily on the layer below -- not vertical in the layer.
- at item The layers get larger upwards. Combined with the previous
-principle it ensures a modular structure!
+primarily on the layer below -- not vertical within the layer.
+ at item Layer 0 is mainly interfaces and generic functions, not implementations.
+Level 1 and 2 are small. This structure should encourage modularity.
@end itemize
-
-
@section Package structure
So far, there is only one main package, called, you might guess it:
@i{lisplab}. Except from that there are only a few special packages
-for generated code and FFIs: Slatec, Blas, and FFTW.
+for generated code and FFIs: Slatec, Blas, and FFTW. There is also
+a package @i{lisplab-user} for test code and applications.
+
@section The four levels, 0 -- 3.
-Lisplab has a layered structure with four levels, 0 -- 3,
+The Lisplab matrix and linear algebra code
+has a layered structure with four levels, 0 -- 3,
where
@itemize
@item @b{Level 0} is matrix independent and contains
@@ -596,7 +629,12 @@
denote the level, it is most probably level 3, or outside the level system
(non matrix code).
+
@section Matrix class hierarchy
+All matrices are subclasses of @code{matrix-base}, and as
+far as possible the generic functions specialize
+on one or many of its subclasses.
+
The matrix class hierarchy has three independent
lines of inheritance
@itemize
@@ -605,12 +643,60 @@
@item On implementation
@end itemize
The structure is inspired by the stream example in
-Object-Oriented Programming in Common Lisp,
-by Sonya E. Keene.
+Object-Oriented Programming in Common Lisp, by Sonya E. Keene.
+
+
+ at subsection The structure
+The structure tells what kind of symmetries or other
+special properties the matrix has.
+Two matrix classes
+ at itemize
+ at item @code{matrix-structure-general}, where the matrix
+has no known symmetries.
+ at item @code{matrix-structure-diagonal}, where only
+diagonal elements are non-zero.
+ at end itemize
+
+ at subsection The element type
+The element type classes has no other purpose than to be
+represents a Common Lisp types..
+ at itemize
+ at item @code{matrix-element-base}, represents @code{t}
+ at item @code{matrix-element-double-float}, represents @code{double-float}
+ at item @code{matrix-element-complex-double-float}, represents @code{complex double-float}
+ at end itemize
+
+ at subsection The implementation
+Since Lisplab has many competing implementation of the same
+generic functions, the implementation class structure tells which
+one too choose. There are currently four classes in a straight
+line of inheritance
+ at itemize
+ at item matrix-implementation-base
+ at item matrix-implementation-lisp, use native Common Lisp if possible.
+ at item matrix-implementation-blas, use foreign libraries if possible.
+ at end itemize
+This standard method dispatch ensures foreign library methods
+are chosen before native lisp. @i{It is the responsibility of the
+methods to call next method if the library is not loaded}.
+
+
+ at node Discussion
+ at chapter Discussion
+
+ at section Experiences with Common Lisp in high performance computing
+ at section The foreign function interfaces
+ at section Parallel execution
+To request usage of more threads, call @code{init-threads}.
+Currently, only the calls to FFTW will react to this.
+ at 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).
@c End stuff
More information about the lisplab-cvs
mailing list