[lisplab-cvs] r66 - doc/manual
Jørn Inge Vestgården
jivestgarden at common-lisp.net
Tue Jul 28 19:37:30 UTC 2009
Author: jivestgarden
Date: Tue Jul 28 15:37:25 2009
New Revision: 66
Log:
more on structure
Modified:
doc/manual/lisplab.texi
Modified: doc/manual/lisplab.texi
==============================================================================
--- doc/manual/lisplab.texi (original)
+++ doc/manual/lisplab.texi Tue Jul 28 15:37:25 2009
@@ -57,13 +57,21 @@
syntax on top of Common Lisp. Lisplab contains code from
Matlisp, but has also a lot of new code, refactored
code and rewritten code. Other Common Lisp matrix libraries
-are FEMLLISP and NLISP.
+are Matlisp, Femlisp and NLISP.
@node Getting started
@chapter Getting started
@section Dependencies
+In order to enjoy the full power of Lisplab you
+must install some foreign libraries. These are
+ at itemize
+ at item BLAS -- Basic Linear Algebra Subprograms. Preferably the Atlas build.
+ at item LAPACK -- Matrix library. Preferably the Atlas build.
+ at item FFTW -- The fastest Fast Fourier Transform available.
+ at end itemize
+
Lisplab has been developed with SBCL, SLIME and ASDF on Linux,
and there are yet unnecessary bindings to these platforms.
@itemize
@@ -75,20 +83,6 @@
@item The @code{*READ-DEFAULT-FLOAT-FORMAT*} must be @code{double-float}.
@end itemize
-In order to enjoy the full power of Lisplab you
-must install some foreign libraries. These are
- at itemize
- at item
-BLAS -- Basic Linear Algebra Subprograms. Preferably the Atlas build.
-
- at item
-LAPACK -- Matrix library. Preferably the Atlas build.
-
- at item
-FFTW -- The fastest Fast Fourier Transform available.
-
- at end itemize
-
@section Installing
Lisplab is ASDF installable, but before you come so far you need to
specify the location of the foreign libraries.
@@ -302,7 +296,7 @@
while @code{dmat} is a macro. Similarly, there are
@code{znew}, @code{zcol}, @code{zrow}, and @code{zmat}
for double float matrices and
- at code{mnew}, @code{mcol}, @code{mrow}, and @code{mmat}
+ at code{new}, @code{col}, @code{row}, and @code{mat}
for any matrices. The latter take matrix class as first argument.
Often you want to create a matrix of the same type as a input
@@ -318,8 +312,9 @@
@{B0998B1@}>
@end example
@code{Convert} also converts between matrix types. If the
-matrix contents cannot be converted directly (e.g., conversion
-from complex to real), use @code{copy-contents} instead.
+matrix contents cannot be converted directly
+(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}
@@ -344,7 +339,7 @@
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
-functions, you can write compact programs, without the slower
+functions, you can write compact programs, without the slow
single element references.
@example
LL> (.sin (drow 0 1))
@@ -355,8 +350,8 @@
And so also for the algebraic operations
@example
LL> (let ((a (drow 0 1))
- (b (dcol 0.1 0.2)))
- (.+ a (.* b 2)))
+ (b (dcol 0.1 0.2)))
+ (.+ a (.* b 2)))
#<MATRIX-DGE 1x2
0.2 1.4
@{BC5AC51@}>
@@ -366,7 +361,8 @@
also that the scalar is multiplied element-vise.
The dotted algebra is to some extent also implemented for
-general element matrices
+general element matrices, so that you can work with fractions and
+integers rather than floats
@example
LL> (.+ (row 'matrix-ge 1/2 3/2) 1)
#<MATRIX-GE 1x2
@@ -377,15 +373,16 @@
@section Linear algebra
The linear algebra functions (unlike the dotted algebra)
+feel and maybe also change the matrix structure.
The linear algebra functions often start with @i{m}, although this
conventions is not strictly enforced. Currently there is no a wide
spectrum of linear algebra function, but you find matrix multiplication,
matrix inversion, transpose, conjugate transpose and eigenvalues.
-Matrix multiplications
+Matrix multiplication
@example
LL>(let ((a (dmat (1 0) (0 -1)))
- (b (dcol 0.1 0.2)))
+ (b (dcol 0.1 0.2)))
(m* a b))
#<MATRIX-DGE 2x1
0.1
@@ -441,12 +438,13 @@
general element matrices
@example
LL> (let ((a (mat 'matrix-ge (1 0) (0 -1)))
- (b (col 'matrix-ge 1/2 2/3)))
+ (b (col 'matrix-ge 1/2 2/3)))
(m* a b))
#<MATRIX-GE 2x1
1/2
-2/3
@{B5DCC79@}>
+
LL> (minv (mat 'matrix-ge (1 2)(-2 1)))
#<MATRIX-GE 2x2
1/5 -2/5
@@ -489,8 +487,6 @@
@code{.conj},
@code{.realpart}, @code{.imagpart}, @code{.exp}, @code{.abs}.
-TODO: add the inverse functions.
-
@section Special functions
These are:
@code{.besj}, @code{.besy},
@@ -499,23 +495,71 @@
@code{.ai}.
@section Infix notation
-Infix input is with the macro @code{w/infix}.
- at example
-(w/infix
- (let ((x 3))
- (1 .+ 2 .* x)))
+Infix input is with the macro @code{w/infix},
+where you must have spaces before and after
+the operators
+ at example
+LL> (w/infix
+ (let ((x 3))
+ (1 .+ 2 .* x)))
+7
@end example
The @code{w/infix} messes as little as possible with the Lisp
semantics, so that if you have a lot of formulas just wrap all
-of it inside the macro.
+of it inside the macro.
@node Structure
@chapter Structure
@section Package structure
+So far, there is only one main package, called, you might guess it:
+ at i{lisplab}. Except from that there are only a few special packages
+for generated code and FFIs: slatec, blas, and FFTW.
@section The four levels, 0 -- 3.
+Lisplab has a layered structure with four levels, 0 -- 3,
+where
+ at itemize
+ at item @b{Level 0} is matrix independent and contains
+the dotted algebra generic functions,
+the dotted algebra methods specialized for numbers, and
+helper functions and macros.
+ at item @b{Level 1} defines matrices and defines and implements
+ at code{mref}, @code{vref}, at code{cols}, @code{rows}, @code{size}
+and @code{make-matrix-instance}.
+ at item @b{Level 2} defines and core functionality related
+to matrices, such as the dotted algebra methods,
+matrix constructors (@code{dnew}, @code{dcol}, etc.)
+and other matrix helper functions, such as
+ at code{mmax}, @code{mmin}, @code{circ-shift}, etc.
+ at item @b{Level 3} is everything else that uses matrices,
+including linear algebra, FFTs, solvers, etc.
+ at end itemize
+The levels are unequal in size: level 0 is fairly large,
+level 1 is extremely small, level 2 is fairly small, and
+level 3 is large and I hope it will never stop to grow.
+
+The intention with the structure are the following
+ at itemize
+ at item To minimize the work needed to add new matrices implementations.
+Actually, you need only to implement level 1,
+provided you inherit from matrix base. Otherwise you need also
+to implement level 2.
+ at item To encourage code reuse. For example, if you add
+a new type to the dotted algebra, such as polynomials, symbolic
+expressions, or arbitrary precision floats, you can immediately
+perform matrix operations on them without write one single extra line
+of code.
+ at item To manage optimizations and special implementations by
+overloading for specialized matrix types, mainly at level 2,
+but also at level 3.
+ at item To make foreign libraries available in Common Lisp.
+ at item To create a closed, constant and extensible system of operations.
+ at end itemize
+The filenames often also denote the levels. If a filename does not
+denote the level, it is most probably level 3, or outside the level system
+(non matrix code).
@section Class structure
More information about the lisplab-cvs
mailing list