[lisplab-cvs] r56 - doc/manual
Jørn Inge Vestgården
jivestgarden at common-lisp.net
Fri Jul 10 19:31:26 UTC 2009
Author: jivestgarden
Date: Fri Jul 10 15:31:25 2009
New Revision: 56
Log:
A lot more writing on the manual
Modified:
doc/manual/lisplab.texi
Modified: doc/manual/lisplab.texi
==============================================================================
--- doc/manual/lisplab.texi (original)
+++ doc/manual/lisplab.texi Fri Jul 10 15:31:25 2009
@@ -27,8 +27,7 @@
@menu
* Introduction::
-* Dependencies::
-* Installing::
+* Getting started::
* Tutorial::
* Structure::
* Index::
@@ -38,98 +37,93 @@
@node Introduction
@chapter Introduction
-Lisplab is a mathematics library in Common Lisp. Common Lisp
-is a general purpose programming. The purpose
-of Lisplab is to specialize Common Lisp towards mathematics.
+Lisplab is a mathematics library in Common Lisp and offers
+an easy-to-use and rich programming framework with linear algebra,
+Fast Fourier Transform, Special functions, Runge-Kutta solver,
+infix notation, and general matrix utility functions.
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. Contrary to Matlab, Lisplab can do a
-lot other than just matrix manipulation because Lisplab is
+lot more than just matrix manipulation because Lisplab is
based on Common Lisp. Hence, you get all
-the benefits of programming in a lexically scoped, dynamic, and fast
-general purpose programming language, not bound to the idiom
-of @i{everything's a matrix}.
+the benefits of lexical scope, dynamic scope, macros, 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
+to the matrices: functions, hash tables, structures,
+classes, arbitrary precision
+integers, rationals, and lists.
Note that Lisplab is not unique in building Matlab-like
-syntax on top of Common Lisp. Lisplab contains much code from
+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 libraries of similar nature
+code and rewritten code. Other Common Lisp matrix libraries
are FEMLLISP and NLISP.
- at node Dependencies
- at chapter Dependencies
+ at node Getting started
+ at chapter Getting started
+
+ at section Dependencies
Lisplab has been developed with SBCL, SLIME and ASDF on Linux,
and there are yet unnecessary bindings to these platforms.
@enumerate
- at item
-Some of the optimized lisp code uses the SBCL macro
- at code{truly-the}. This must be dealt with.
-
- at item
-The FFTW FFI is only for SBCL.
-
- at item
-The Matlisp FFI should be portable to other lisps and
+ at item Some of the optimized lisp code uses the
+SBCL macro @code{truly-the}. This must be dealt with.
+ at item The FFTW FFI is only for SBCL.
+ at item The Matlisp FFI should be portable to other lisps and
Windows, but it has not been tested.
-
+ at item The @code{*READ-DEFAULT-FLOAT-FORMAT*} must be @code{double-float}.
@end enumerate
In order to enjoy the full power of Lisplab you
must install some foreign libraries. These are
@enumerate
@item
-BLAS -- Basic Linear Algebra Subprograms. Preferably the Atlas build
+BLAS -- Basic Linear Algebra Subprograms. Preferably the Atlas build.
@item
-LAPACK -- Matrix library. Preferably the Atlas build
-
+LAPACK -- Matrix library. Preferably the Atlas build.
@item
FFTW -- The fastest Fast Fourier Transform available.
@end enumerate
+ at section Installing
+Lisplab is ASDF installable, but before you come so far you need to
+specify the location of the foreign libraries.
+You specify these in three special variables,
+ at itemize
+ at item *lisplab-libblas-path*
+ at item *lisplab-liblapack-path*
+ at item *lisplab-libfftw-path*
+ at end itemize
+that live their lives 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}.
- at node Installing
- at chapter Installing
-Lisplab is ASDF installable, but the installations is
-more complicated than most Common Lisp libraries because of
-the external dependencies. Lisplab has of the following
-ASDF systems
- at enumerate
+ASDF sub-systems
+ at itemize
@item @emph{Lisplab} --
the full Lisplab installation.
-
@item @emph{Lisplab-base} --
-the part of Lisplab without external dependencies. It should run
-on all platforms.
-
+the part of Lisplab without external dependencies.
@item @emph{Lisplab-matlisp} --
FFIs to BLAS and LAPACK. These are modified version from Matlisp.
-
@item @emph{Lisplab-fftw} --
FFI to FFTW for Fast Fourier Transform.
-
@item Slatec --
special functions, generated from Fortran by f2cl.
Originally made for Maxima.
-
@item Quadpack --
integration routines, generated from Fortran by f2cl.
- at end enumerate
+ at end itemize
-The simplest way to install Lisplab is to load @code{start.lisp}.
+The simplest way to test Lisplab is to load @code{start.lisp}.
If you have problems loading, first look at @code{start.lisp}
-and see if you can hack it.
-The foreign libraries are also loaded by ASDF and it takes
-the file pathnames from the file @code{libs.lisp}.
+and see if you can hack it. Then look at @code{lisplab.asd}.
- at node Tutorial
- at chapter Tutorial
-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.
@section Naming conventions
The matrix classes and constructors follow the naming convention
@@ -145,21 +139,193 @@
@xref{Structure}, for more about the naming conventions
of matrix structure. There you also see the naming conventions for
-files.
+files, with level0 to level3.
+
+
+ at section Status - past and future
+The purpose of Lisplab
+is to provide a complete mathematics programming environment,
+not just linear algebra. Currently it contains a fairly
+large matrix manipulation basis and linear algebra,
+as well as fast Fourier transform and special functions.
+It lacks special matrices, such as diagonal, tridiagonal,
+and sparse matrices.
+
+Lisplab started as a refactoring of Matlisp, but
+I 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
+ at itemize
+ at item Layered structure (@xref{Structure}.)
+ at item Shorter names.
+ at item Using the standard Lapack and Blas libraries, not a special build.
+ at item Native Common Lisp linear algebra implementations.
+ at end itemize
+
+The future I will mainly do minor changes and bug-fixes,
+since it now covers my basic needs. I will only add new
+modules when needed.
+
+
+However, there are many exiting extensions that can be made,
+such as
+ at itemize
+ at item Parallel computation, e.g. using MPI.
+ at item More native linear algebra routines, e.g. with eigenvalues.
+ at item New non-matrix algebra items, e.g. quaternions, polynomes or
+arbitrary precision floats.
+ at item Symbolic manipulation. Could make something like
+ at i{ginac} in @code{c++}.
+ at item Other Common Lisp libraries, e.g. image processing libraries.
+ at end itemize
+
+Please contact if you want to contribute.
+
+
+ at node Tutorial
+ at chapter Tutorial
+
+ at section Starting
+To test Lisplab open Emacs and Slime in the lisplab directory.
+ at example
+CL-USER> (load "start.lisp")
+CL-USER> (in-package :ll)
+ at 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.
+
+
@section Basic algebra
+Central in Lisplab is an algebra 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
+the third is on implementation. This hierarchy is similar
+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 not all are created
+by default. To add new classes in a structured way,
+ at xref{Structure}.
@section Matrix construction
-Lisplab offers a very many ways to create a matrix.
-
+The constructor @code{make-matrix-instance} is not
+the primary choice to create a matrix. Its better to use a special
+constructor. Try
+ at 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}
+for double float matrices and
+ at 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
+creating methods that should operate on many matrix types.
+
+To create matrices from something else, use @code{convert}
+ at example
+LL> (convert '((1 2) (3 4)) '(:d :ge :any))
+#<MATRIX-DGE 2x2
+1.0 2.0
+3.0 4.0
+ @{B0998B1@}>
+ at end example
+ at 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.
+
+ at section Matrix element reference
+To access a matrix element use the generic function @code{mref}
+ at example
+LL> (mref (dmat (1 2) (3 4)) 0 1)
+2.0
+ at 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}
+ at example
+LL> (vref (dmat (1 2) (3 4)) 1)
+3.0
+ at end example
+whcih is also settable. Note that the matrices are column major order.
@section Matrix manipulation
+ at section Matrices without store
+
@section Ordinary functions
@section Special functions
+ at section Infix notation
+
@node Structure
@chapter Structure
More information about the lisplab-cvs
mailing list