[lisplab-cvs] r174 - in trunk/doc: manual www
Jørn Inge Vestgården
jivestgarden at common-lisp.net
Sat May 22 18:29:41 UTC 2010
Author: jivestgarden
Date: Sat May 22 14:29:40 2010
New Revision: 174
Log:
updated manual
Modified:
trunk/doc/manual/lisplab.texi
trunk/doc/www/index.html
Modified: trunk/doc/manual/lisplab.texi
==============================================================================
--- trunk/doc/manual/lisplab.texi (original)
+++ trunk/doc/manual/lisplab.texi Sat May 22 14:29:40 2010
@@ -3,7 +3,7 @@
@settitle Lisplab manual
@copying
-This manual is for Lisplab version 0.1, updated 10. September 2009.
+This manual is for Lisplab version 0.2, updated 10. May 2010.
Copyright @copyright{} 2009 Joern Inge Vestgaarden
@end copying
@@ -43,7 +43,7 @@
@node Introduction
@chapter Introduction
Lisplab is a mathematics/matrix library in Common Lisp. It is
-placed under the GNu General Public License (GPL) and offers
+placed under the GNU General Public License (GPL) and offers
an easy-to-use and rich programming framework for mathematics,
including Matlab-like matrix handling, linear algebra,
Fast Fourier Transform, special functions, Runge-Kutta solver,
@@ -216,12 +216,13 @@
@node Tutorial
@chapter Tutorial
-
@section Starting
-Currently Lisplab only runs on SBCL, and there is a small porting
+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*}.
+get it run on other platforms. On SBCL
+make sure that @code{lisplab.asd} is in @code{asdf:*centeral-registry*}
+and that @code{*read-default-float-format*} is @code{double-float}, as is
+requrieed when compiling Slatec.
Then type
@example
CL-USER> (require :lisplab)
@@ -240,31 +241,29 @@
to the stream example in Object-Oriented Programming in Common Lisp,
by Sonya E. Keene.
-The most common classes are @code{matrix-dge} which
-is a general, double-float matrix with any implementation
-and @code{matrix-zge} which is a
-general, complex double-float matrix with any implementation.
-
-The best way to inspect the class structure is to play
-with the low level constructor @code{make-matrix-instance},
-for example,
- at example
-LL> (make-matrix-instance '(:z :ge :any) '(2 2) 1)
-#<MATRIX-ZGE 2x2
-#C(1.0 0.0) #C(1.0 0.0)
-#C(1.0 0.0) #C(1.0 0.0)
- @{B529741@}>
- at end example
-where types are :d, :z, or :any, structure is :ge or :d,
-and implementation is :any, :lisp, :blas. Not all combinations
-have a class, since not all combinations are usefull. More types
-and structures will be added in the future.
-
-Note that with these three lines of inheritance there
-are potentially incredibly many potential class. Let's
-say we have 10 structures, 10 types and 4 implementations, giving
-400 classes. Not all of these are useful and only few are created
-by default. To add new classes in a structured way,
+Objects of the most important classes can be created by
+read macros. For double-float matrices, @code{matrix-dge},
+ at example
+LL-USER> #md((1 2) (3 4))
+#md(( 1.000 2.000 )
+ ( 3.000 4.000 ))
+ at end example
+For complex double-float matrices, @code{matrix-zge},
+ at example
+LL-USER> #mz((1 2) (#c(1 2) #c(3 4)))
+#mz((#c( 1.0 0.0 ) #c( 2.0 0.0 ))
+ (#c( 1.0 2.0 ) #c( 3.0 4.0 )))
+ at end example
+Untyped matrices, @code{matrix-ge},
+ at example
+LL-USER> #mm(('a 'b) ('c 'd))
+#mm((A B)
+ (C D))
+ at end example
+
+There are more matrix classes, but these are not exported.
+Even more matric classes can be created dynamically,
+but these capabilities are not yet fully in use.
@xref{Structure}.
@@ -273,47 +272,36 @@
the primary choice to create a matrix. Its better to use a special
constructor. Try
@example
-LL> (dnew 0 2 2)
-#<MATRIX-DGE 2x2
-0.0 0.0
-0.0 0.0
- @{AD78C91@}>
-
-LL>(drow 1 2)
-#<MATRIX-DGE 1x2
-1.0 2.0
- @{AD99AD9@}>
-
-LL> (dcol 1 2)
-#<MATRIX-DGE 2x1
-1.0
-2.0
- @{AEF4299@}>
-
-LL> (dmat (1 2) (3 4))
-#<MATRIX-DGE 2x2
-1.0 2.0
-3.0 4.0
- @{AF1F9A9@}>
- at end example
-where @code{dnew}, @code{dcol}, and @code{drow} are functions,
-while @code{dmat} is a macro. Similarly, there are
- at code{znew}, @code{zcol}, @code{zrow}, and @code{zmat}
+LL-USER> (dnew 0 2 2)
+#md(( 0.000 0.000 )
+ ( 0.000 0.000 ))
+
+LL-USER> (drow 1 2)
+#md(( 1.000 2.000 ))
+
+LL-USER> (dcol 1 2)
+#md(( 1.000 )
+ ( 2.000 ))
+
+LL-USER> (dmat '((1 2) (3 4)))
+#md(( 1.000 2.000 )
+ ( 3.000 4.000 ))
+ at end example
+Similarly, there are @code{znew}, @code{zcol}, @code{zrow}, and @code{zmat}
for double float matrices and
@code{mnew}, @code{mcol}, @code{mrow}, and @code{mmat}
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
-matrix. Then you can use @code{mcreate}. It's mainly useful when
+matrix. Then you can use @code{mcreate} and @code{mcreate*} for
+extended syntax. They are useful when
creating methods that should operate on many matrix types.
To create matrices from something else, use @code{convert}
@example
-LL> (convert '((1 2) (3 4)) '(:d :ge :any))
-#<MATRIX-DGE 2x2
-1.0 2.0
-3.0 4.0
- @{B0998B1@}>
+LL-USER> (convert '((1 2) (3 4)) '(:d :ge :any))
+#md(( 1.000 2.000 )
+ ( 3.000 4.000 ))
@end example
@code{Convert} also converts between matrix types. If the
matrix contents cannot be converted directly
@@ -321,159 +309,130 @@
use @code{copy-contents} instead.
- at section Matrix element reference (mref and vref)
-To access a matrix element use the generic function @code{mref}
+ at section Matrix element reference
+Lisplab matrices are zero-based and in column major order.
+Matrix reference is with the settable generic function @code{mref}
@example
-LL> (mref (dmat (1 2) (3 4)) 0 1)
+LL-USER> (mref #md((1 2) (3 4)) 0 1)
2.0
@end example
-Matrix references are zero based. The @code{mref} is settable.
-
-Furthermore, all matrices can also list their elements as vectors
-(similar to row-major-aref for arrays). To access a matrix as vector
-use the generic function @code{vref}
+Matrices can also list their elements as vectors
+(similar to @code{row-major-aref} for arrays). Vector access is with
+the generic function @code{vref}
@example
-LL> (vref (dmat (1 2) (3 4)) 1)
+LL-USER> (vref #md((1 2) (3 4)) 1)
3.0
@end example
-which is also settable. Note that the matrices are column major order.
+which is also settable.
- at section The dotted algebra (.+, .*, .sin, ...)
-Central in Lisplab is an algebra (in the widest possible sense of the word)
-with the functions
+ at section Elementwise operators and functions
+Lisplab introduces general mathematical operators
@code{.+}, @code{.-}, @code{.*}, @code{./}, and @code{.^}.
These are generalization of
@code{+}, @code{-}, @code{*}, @code{/}, and @code{^}.
For numbers they work the same,
@example
-LL> (.+ 1 2)
+LL-USER> (.+ 1 2)
3
@end example
-The functions @code{.+}, @code{.-}, @code{.*}, @code{./}, and @code{.^}
-are mainly wrappers that call @code{reduce} on its arguments with the
-generic functions
+But the lisplab functions have a much wider functionality since
+they are based on the binary generic functions
@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.
-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
-functions, you can write compact programs, without the slow
-single element references.
- at example
-LL> (.sin (drow 0 1))
-#<MATRIX-DGE 1x2
-0.0 0.8414709848078965
- @{BB1FE21@}>
+On matrices the all functions starting with a dot works elementwise.
+Hence
+ at example
+LL-USER> (.sin (drow 0 1))
+#md(( 0.000 0.8415 ))
@end example
-And so also for the algebraic operations
+The dotted operators ignores the internal structure of the matrices
@example
-LL> (let ((a (drow 0 1))
- (b (dcol 0.1 0.2)))
- (.+ a (.* b 2)))
-#<MATRIX-DGE 1x2
-0.2 1.4
- @{BC5AC51@}>
- at end example
-Note here that the @code{.+}, @code{.*}, etc. ignore the structure
-so that it is completely valid to add a row and a column matrix. Note
-also that the scalar is multiplied element-vise.
-
-The dotted algebra is to some extent also implemented for
-general element matrices, so that you can work with fractions and
-integers rather than floats
- at example
-LL> (.+ (row 'matrix-ge 1/2 3/2) 1)
-#<MATRIX-GE 1x2
-3/2 5/2
- @{B5AE9B9@}>
+LL-USER> (let ((a (drow 0 1))
+ (b (dcol 0.1 0.2)))
+ (.+ a (.* b 2)))
+#md((0.2000 1.400 ))
+ at end example
+The output need not have same type as the input
+ at example
+LL-USER> (.asin #md((1 2)))
+#mz((#c( 1.6 0.0 ) #c( 1.6 1.3 )))
+ at end example
+The dotted functions and operators are optimized and very fast
+for the double-float matrices, but slow for the matrices with
+arbitrary element-types.
+ at example
+LL-USER> (.+ #mm((1/2 3/2)) 1)
+#mm((3/2 5/2))
@end example
@section Linear algebra
-The linear algebra functions (unlike the dotted algebra)
+The linear algebra functions
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.
+conventions is not strictly followed. The number of linear algebra functions
+is small compared with LAPACK, but you will find matrix multiplication,
+matrix inversion, transpose, conjugate transpose, LU-decomposition and eigenvalues.
Matrix multiplication
@example
-LL>(let ((a (dmat (1 0) (0 -1)))
- (b (dcol 0.1 0.2)))
- (m* a b))
-#<MATRIX-DGE 2x1
-0.1
--0.2
- @{BD45221@}>
+LL-USER> (let ((a #md((1 0) (0 -1)))
+ (b #md((0.1) (0.2))))
+ (m* a b))
+#md((0.1000 )
+ (-.2000 ))
@end example
Matrix inversion
@example
-LL> (minv (dmat (1 2) (-2 1)))
-#<MATRIX-DGE 2x2
-0.2 -0.4
-0.4 0.2
- @{BD85161@}>
+LL-USER> (minv #md((1 2)
+ (-2 1)))
+#md((0.2000 -.4000 )
+ (0.4000 0.2000 ))
@end example
Transpose
@example
-LL> (mtp (dmat (1 2) (-2 1)))
-#<MATRIX-DGE 2x2
-1.0 -2.0
-2.0 1.0
- @{BD99B11@}>
+LL-USER> (mtp #md((1 2)
+ (-2 1)))
+#md(( 1.000 -2.000 )
+ ( 2.000 1.000 ))
@end example
Conjugate transpose
@example
-LL> (mct (zmat (1 (* 2 %i)) (-2 1)))
-#<MATRIX-ZGE 2x2
-#C(1.0 -0.0) #C(-2.0 -0.0)
-#C(0.0 -2.0) #C(1.0 -0.0)
- @{BDC1DC9@}>
+LL-USER> (mct #mz((1 (* 2 %i)) (-2 1)))
+#mz((#c( 1.0 -0.0 ) #c(-2.0 -0.0 ))
+ (#c( 0.0 -2.0 ) #c( 1.0 -0.0 )))
@end example
Eigenvalues
@example
-LL> (eigenvalues (dmat (1 2) (0 0.5)))
-#<MATRIX-DGE 2x1
-1.0
-0.5
- @{B2C5B19@}>
+LL-USER> (eigenvalues #md((1 2) (0 0.5)))
+#md(( 1.000 )
+ (0.5000 ))
@end example
Eigenvectors
@example
-LL> (eigenvectors (dmat (1 2) (0 0.5)))
-(#<MATRIX-DGE 2x1
-1.0
-0.5
- @{B3368C1@}>
- #<MATRIX-DGE 2x2
-1.0 -0.9701425001453319
-0.0 0.24253562503633297
- @{B3361A9@}>)
+LL-USER> (eigenvectors #md((1 2) (0 0.5)))
+(
+#md(( 1.000 )
+ (0.5000 ))
+
+#md(( 1.000 -.9701 )
+ ( 0.000 0.2425 )))
@end example
Some of the linear algebra functions also work for
general element matrices
@example
-LL> (let ((a (mat 'matrix-ge (1 0) (0 -1)))
- (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
-2/5 1/5
- @{BF68821@}>
+LL-USER> (let ((a #mm((1 0) (0 -1)))
+ (b #mm((1/2) (2/3))))
+ (m* a b))
+#mm((1/2)
+ (-2/3))
+
+LL-USER> (minv #mm((1 2)(-2 1)))
+#mm((1/5 -2/5)
+ (2/5 1/5))
@end example
@@ -488,19 +447,18 @@
@section Matrices without store
The class @code{function-matrix} implements matrices with
-functions and has no store.
-
-The contents can for example be given directly by a rule,
-using the macro funmat
+functions and has no store, but where the elements are given by a function
@example
-LL> (funmat '(2 2) (i j) (if (= i j) 1 0))
+LL-USER> (funmat '(2 2) (lambda (i j)
+ (if (= i j)
+ 1
+ 0)))
#<FUNCTION-MATRIX 2x2
1 0
0 1
@{AC0F489@}>
@end example
-The funmat (and its generalization @code{fmat} that creates any matrix type)
-it also useful to create grids.
+The similar macro @code{fmat} creates functions of any type by a function.
Function matrices are also used to view a part or restructured other matrix
with @code{view-matrix}, @code{view-col}, or @code{view-row}.
@@ -510,11 +468,9 @@
There are two methods for mapping of matrices: @code{mmap} and
@code{mmap-into}. For example
@example
-LL> (mmap 'matrix-dge #'realpart (zmat (1 %i) (-%i 2)))
-#<MATRIX-DGE 2x2
-1.0 0.0
-0.0 2.0
- @{A9BD489@}>
+LL-USER> (mmap 'matrix-dge #'.re #mz((1 %i) (-%i 2)))
+#md(( 1.000 0.000 )
+ ( 0.000 2.000 ))
@end example
The output matrix takes the structure from the first arguments, but
ignores in general matrix structure. If first argument @code{t} output
@@ -522,7 +478,6 @@
@section Ordinary functions
-These are:
@code{.sin}, @code{.cos}, @code{.sin}, @code{.tan},
@code{.sinh}, @code{.cosh}, @code{.sinh}, @code{.tanh},
@code{.asin}, @code{.acos}, @code{.asin}, @code{.atan},
@@ -532,7 +487,6 @@
@section Special functions
-These are:
@code{.besj}, @code{.besy},
@code{.besi}, @code{.besk},
@code{.besh1}, @code{.besh2},
@@ -540,54 +494,46 @@
@section Infix notation
-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)))
+Infix input is with the macro @code{w/infix}
+ at example
+LL-USER> (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. The infix math also works with the
+The @code{w/infix} is compatible with the Lisp
+semantics. The infix math also works with the
functions @code{+, -, *, /} and @code{^}.
@node Structure
@chapter Structure
-
@section Design principles
-Design principles for the full library
+High level principles
@itemize
+ at item Lisplab will be a @i{homogeneous platform} for mathematics.
@item Lisplab is free software.
- at item It makes a @i{homogeneous platform} for all
-kinds of mathematical calculations. (So it's a lot more
-than just a matrix library)
@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)
+ at item Lisplab will steal as much code as possible from as many as possible.
+ at end itemize
+
+General design principles
+ at itemize
@item Every common mathematical operator and 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.
- at item Error checks is primarily callers responsibility, not Lisplab's!
- at item To steal as much code as possible from as many as possible
-(I love free software).
+ at item Trust the Lisp virtual machine (Avoid use of FFIs and destructive functions).
+ at item Avoid mathematical algorithms in macros.
+ at item Error checks is primarily caller's responsibility.
@end itemize
-Design principles for the matrix part
+Design principles for the matrix code
@itemize
@item Layered structure where dependencies are
-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.
+primarily to the layer below -- not vertical within the layer.
@end itemize
@@ -604,23 +550,22 @@
where
@itemize
@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
+generic functions for mathematics.
+In this level only specialization for numbers and non-matrix objects.
+ at item @b{Level 1} defines matrices and implements
@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.)
+ at item @b{Level 2} Implements level 0 for matrices and
+defines core functionality related to matrices such as
+matrix constructors @code{dnew}, @code{dcol}, etc.
and other matrix helper functions, such as
@code{mmax}, @code{mmin}, @code{circ-shift}, etc.
+Optimizations are mainly in level 2.
@item @b{Level 3} is everything else that uses matrices,
including linear algebra, FFTs, solvers, etc.
@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 levels are unequal in size: level 0 is potentially large,
+level 1 is small, level 2 and 3 are large.
The intention with the structure are the following
@itemize
Modified: trunk/doc/www/index.html
==============================================================================
--- trunk/doc/www/index.html (original)
+++ trunk/doc/www/index.html Sat May 22 14:29:40 2010
@@ -102,9 +102,9 @@
When compiling for the first time you must have *read-default-float-format*
set to 'double-float because the generated slatec code requires it.
When started, you can for example square the elements:
- <pre> LL-USER> (.^ #md((1 2) (3 4)) 2)
- #md(( 1.000 4.000 )
- ( 9.000 16.00 ))</pre>
+ <pre>LL-USER> (.^ #md((1 2) (3 4)) 2)
+#md(( 1.000 4.000 )
+ ( 9.000 16.00 ))</pre>
The read macro #md creates double-floats matrices,
and #mz create complex double float matrices.
Untyped matrices are created with #mm.
More information about the lisplab-cvs
mailing list