[lisplab-cvs] r192 - trunk/doc/manual
Jørn Inge Vestgården
jivestgarden at common-lisp.net
Sun Oct 24 12:59:57 UTC 2010
Author: jivestgarden
Date: Sun Oct 24 08:59:56 2010
New Revision: 192
Log:
fixed doc
Modified:
trunk/doc/manual/lisplab.texi
Modified: trunk/doc/manual/lisplab.texi
==============================================================================
--- trunk/doc/manual/lisplab.texi (original)
+++ trunk/doc/manual/lisplab.texi Sun Oct 24 08:59:56 2010
@@ -50,19 +50,20 @@
infix notation, and interfaces to BLAS, LAPACK, FFTW, SLATEC and
QUADPACK.
-The name Lisplab is inspired by Matlab and Lisplab offers
-much of the same kind of programming-style as Matlab, with high level
-manipulation of matrices, but contrary to Matlab, Lisplab
-benefits from being a part of Common Lisp. Hence, you have
+The name Lisplab is inspired by Matlab and a purpose of Lisplab
+is to add the Matlab programming style to Common Lisp.
+Hence you can do high level manipulation of matrices, while
+still benefitting from being a part of Common Lisp, with
lexical scope, dynamic scope, macros, first class
-functions, iterations, CLOS, fast execution,
-and working in an free general purpose programming language. And
-best of all: you can enjoy you favorite data-types in addition
+functions, iterations, CLOS, fast execution,
+and fast open source implementations. And
+best of all, you can enjoy you favorite Common Lisp
+data types in addition
to the matrices: functions, hash tables, structures,
classes, arbitrary precision integers, rationals, and lists.
Lisplab is not unique in building Matlab-like
-syntax on top of Common Lisp. Other similar framweorks are
+syntax on top of Common Lisp, please consults also
Matlisp, Femlisp, NLISP and GSLL. Lisplab itself was
started as a branch of Matlisp, but there is now only
little of the original code left.
@@ -90,14 +91,14 @@
@item The Matlisp FFI should in theory be portable to other lisps and
Windows, but it has not yet been tested.
@item The @code{*READ-DEFAULT-FLOAT-FORMAT*} must be @code{double-float}
-when compiling Slatec. This is a minor problem.
+when compiling Slatec. (This should be is a minor problem.)
@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
+Lisplab is installed by ASDF, but before you come so far you need to
specify the location of the foreign libraries.
You specify these in three special variables,
@itemize
@@ -105,7 +106,7 @@
@item @code{*lisplab-liblapack-path*}
@item @code{*lisplab-libfftw-path*}
@end itemize
-that live their lives in the Common-Lisp-User package.
+living in the Common-Lisp-User package.
You can either assign them on the top-level, in you Common Lisp
installation file, in @code{start.lisp}, or
probably the easiest: directly in @code{lisplab.asd}.
@@ -131,9 +132,9 @@
If you have problems loading, first look at @code{start.lisp}
and see if you can hack it. Then look at @code{lisplab.asd}.
-To install BLAS, LAPACK, and FFTW, if you are too lazy to do a custom build,
-and is lucky enough to administer a Debian or Ubuntu machine,
-you typically write
+If you are too lazy to do a custom build,
+and lucky enough to administer a Debian or Ubuntu machine,
+you typically install BLAS, LAPACK and FFTW as
@example
# aptitude install libatlas3gf-base
# aptitude install libfftw3-3
@@ -142,25 +143,23 @@
@section Naming conventions
@itemize
@item
-The matrix classes and constructors follow the naming convention
-from BLAS where you give names based on element type and
-matrix structure.
+Matrix names follow the BLAS naming convention of
+(element type, matrix structure).
The most used types are @i{f - float}, @i{d - double},
- at i{c - complex float}, @i{z - complex double float},
-while for matrix structure @i{ge - general}, @i{di - diagonal},
-and many more. So @i{matrix-dge} is a general matrix
+ at i{c - complex float}, @i{z - complex double float}.
+The most used matrix structures are @i{ge - general} and @i{di - diagonal}.
+For example, @i{matrix-dge} is a general matrix
with double float elements, while @i{matrix-zge} is a
general matrix with complex double float elements.
@item
-The generic functions of the basic algebra start with a dot:
+Functions starting with @code{.} act elementwise on matrices.
+For example
@code{.+}, @code{.-}, @code{.*}, @code{./}, @code{.^}, @code{.sin}
@code{.cos}, @code{.tan}, @code{.besj}, @code{.re}, etc.
-On numbers these functions work as the non-dotted Common Lisp functions
-and on matrices they work elementwise.
@item
Linear algebra functions tend to start with @i{m}:
@code{m*}, @code{minv}, @code{mmax}, @code{mtp}, etc.,
-but this conventions is not strictly followed.
+(This conventions is not followed strictly.)
@item
The naming convention of files follow the layered structure of
Lisplab, with level0 to level3.
@@ -201,14 +200,18 @@
Hence, the list in this section must be read as non-systematic gathering
of problem features.
@itemize
- at item Lisplab runs only on SBCL.
+ at item
+Lisplab runs only on SBCL.
Lisplab is mainly ANSI Common Lisp, so just minor changes
in the build-system should make it
run on other lisps, but the problem is that it will most
probably be slow. It should be fast on CMUCL, though.
- at item Lacks a formal spec.
- at item Poorly tested.
- at item Lacks error checks (but these should not be made before a spec!)
+ at item
+Lacks a formal spec.
+ at item
+Poorly tested.
+ at item
+Lacks error checks (but these should not be made before a spec!)
@end itemize
@@ -469,6 +472,9 @@
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.
+If type is @code{t} the output matrix has type equals the
+first matrix argument,
+if it is @code{nil} nothing is returned.
@section Ordinary functions
@@ -506,28 +512,41 @@
@section Design principles
High level principles
@itemize
- at item Lisplab will be a @i{homogeneous platform} for mathematics.
- at item Lisplab is free software.
- at item User applications should need to stay only in Common Lisp.
+ at item
+Lisplab is free software.
+ at item
+Lisplab is a high-level homogeneous platform for mathematics.
+ 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)
- at item Lisplab will steal as much code as possible from as many as possible.
+ at item
+Lisplab steals as much code as possible from as many as possible.
@end itemize
General design principles
@itemize
- at item Every common mathematical operator and function
+ at item
+Every common mathematical operator and function
is represented by a @i{CLOS generic function}.
- at item Modular structure (Inspired by GSL).
- 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.
+ at item
+Modular structure (Inspired by GSL).
+ at item
+Trust the Lisp virtual machine
+(E.g. avoid manual memory management 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 code
@itemize
- at item Layered structure where dependencies are
+ at item
+Layered structure where dependencies are
primarily to the layer below -- not vertical within the layer.
+ at item
+All matrix optimization should be in level 2.
@end itemize
@@ -543,19 +562,23 @@
has a layered structure with four levels, 0 -- 3,
where
@itemize
- at item @b{Level 0} is matrix independent and contains
+ at item
+ at b{Level 0} is matrix independent and contains
generic functions for mathematics.
In this level only specialization for numbers and non-matrix objects.
- at item @b{Level 1} defines matrices and implements
+ at item
+ at 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} Implements level 0 for matrices and
+ at item
+ at 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.
- at item @b{Level 3} is everything else that uses matrices,
+ at item
+ at 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 potentially large,
@@ -563,27 +586,34 @@
The intention with the structure are the following
@itemize
- at item To minimize the work needed to add new matrices implementations.
+ 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
+ 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
+ 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 item
+To make foreign libraries available in Common Lisp.
+ at item
+To create a closed, constant and extensible system of operations.
@end itemize
-The filenames often also denote the levels. If a filename does not
+The filenames often 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).
+(utilities or non matrix code).
@section Matrix class hierarchy
+Note first that all matrices are also vectors and have a 1D store.
+
All matrices are subclasses of @code{matrix-base}, and as
far as possible the generic functions specialize
on one or many of its subclasses.
@@ -604,9 +634,9 @@
special properties the matrix has.
Two matrix classes
@itemize
- at item @code{matrix-structure-general}, where the matrix
+ at item @code{structure-general}, where the matrix
has no known symmetries.
- at item @code{matrix-structure-diagonal}, where only
+ at item @code{structure-diagonal}, where only
diagonal elements are non-zero.
@item Other types to come.
@end itemize
@@ -615,9 +645,9 @@
The element type classes has no other purpose than to be
represents a Common Lisp types.
@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 item @code{element-base}, represents @code{t}
+ at item @code{element-double-float}, represents @code{double-float}
+ at item @code{element-complex-double-float}, represents @code{complex double-float}
@end itemize
@@ -627,9 +657,9 @@
one too choose. There are currently four classes in a straight
line of inheritance
@itemize
- at item @code{matrix-implementation-base}
- at item @code{matrix-implementation-lisp}, use native Common Lisp if possible.
- at item @code{matrix-implementation-blas}, use foreign libraries if possible.
+ at item @code{implementation-base}
+ at item @code{implementation-lisp}, use native Common Lisp if possible.
+ at item @code{implementation-blas}, use foreign libraries if possible.
@end itemize
This standard method dispatch ensures foreign library methods
are chosen before native lisp. @i{It is the responsibility of the
More information about the lisplab-cvs
mailing list