TooN 2.0.0-beta8
doc/documentation.h
00001 /*
00002     Copyright (c) 2005 Paul Smith, 2009 Edward Rosten
00003 
00004     Permission is granted to copy, distribute and/or modify this document under
00005     the terms of the GNU Free Documentation License, Version 1.2 or any later
00006     version published by the Free Software Foundation; with no Invariant
00007     Sections, no Front-Cover Texts, and no Back-Cover Texts.
00008 
00009     You should have received a copy of the GNU Free Documentation License
00010     License along with this library; if not, write to the Free Software
00011     Foundation, Inc.
00012     51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
00013 
00014 */
00015 ///////////////////////////////////////////////////////
00016 // General Doxygen documentation
00017 ///////////////////////////////////////////////////////
00018 
00019 ///////////////////////////////////////////////////////
00020 // The main title page
00021 /**
00022 @mainpage
00023 
00024 \section sIntro Introduction
00025 
00026 The %TooN library is a set of C++ header files which provide basic numerics facilities:
00027     - @link TooN::Vector Vectors@endlink, @link TooN::Matrix matrices@endlink and @link gLinAlg etc @endlink
00028     - @link gDecomps Matrix decompositions@endlink
00029     - @link gOptimize Function optimization@endlink
00030     - @link gTransforms Parameterized matrices (eg transformations)@endlink 
00031     - @link gEquations linear equations@endlink
00032     - @link gFunctions Functions (eg numerical derivatives) @endlink
00033 
00034 It provides classes for statically- (known at compile time) and dynamically-
00035 (unknown at compile time) sized vectors and matrices and it can delegate
00036 advanced functions (like large SVD or multiplication of large matrices) to
00037 LAPACK and BLAS (this means you will need libblas and liblapack).
00038 
00039 The library makes substantial internal use of templates to achieve run-time
00040 speed efficiency whilst retaining a clear programming syntax.
00041 
00042 Why use this library?
00043  - Because it supports statically sized vectors and matrices very efficiently.
00044  - Because it provides extensive type safety for statically sized vectors and matrices (you can't attempt to multiply a 3x4 matrix and a 2-vector).
00045  - Because it supports transposition, subscripting and slicing of matrices (to obtain a vector) very efficiently.
00046  - Because it interfaces well to other libraries.
00047  - Because it exploits LAPACK and BLAS (for which optimised versions exist on many platforms).
00048  - Because it is fast, \link sCramerIsBad but not at the expense of numerical stability. \endlink
00049 
00050 \section sUsage How to use TooN
00051 This section is arranged as a FAQ. Most answers include code fragments. Assume
00052 <code>using namespace TooN;</code>.
00053 
00054  - \ref sDownload
00055  - \ref sStart
00056  - \ref sWindowsErrors
00057  - \ref sCreateVector
00058  - \ref sCreateMatrix
00059  - \ref sFunctionVector
00060  - \ref sGenericCode
00061  - \ref sConst
00062  - \ref sElemOps
00063  - \ref sInitialize
00064  - \ref sScalars
00065  - \ref ssExamples
00066  - \ref sSTL
00067  - \ref sResize
00068  - \ref sDebug
00069  - \ref sSlices
00070  - \ref sFuncSlices
00071  - \ref sPrecision
00072  - \ref sSolveLinear
00073  - \ref sOtherStuff
00074  - \ref sHandyFuncs
00075  - \ref sNoInplace
00076  - \ref sColMajor
00077  - \ref sWrap
00078  - \ref sWrap "How do I interface to other libraries?"
00079  - \ref sImplementation
00080 
00081     \subsection sDownload Getting the code and installing
00082     
00083     To get the code from cvs use:
00084 
00085     cvs -z3 -d:pserver:anoncvs@cvs.savannah.nongnu.org:/cvsroot/toon co TooN
00086 
00087     The home page for the library with a version of this documentation is at:
00088 
00089     http://mi.eng.cam.ac.uk/~er258/cvd/toon.html
00090 
00091     The code will work as-is, and comes with a default configuration, which
00092     should work on any system.
00093 
00094     On a unix system, <code>./configure && make install </code> will  install
00095     TooN to the correct place.  Note there is no code to be compiled, but the
00096     configure script performs some basic checks.
00097 
00098     On non-unix systems, e.g. Windows and embedded systems, you may wish to 
00099     configure the library manually. See \ref sManualConfiguration.
00100 
00101     \subsection sStart Getting started
00102 
00103         To begin, just in include the right file:
00104 
00105         @code
00106         #include <TooN/TooN.h>
00107         @endcode
00108 
00109         Everything lives in the <code>TooN</code> namespace.
00110 
00111         Then, make sure the directory containing TooN is in your compiler's
00112         search path. If you use any decompositions, you will need to link
00113         against LAPACK, BLAS and any required support libraries. On a modern
00114         unix system, linking against LAPACK will do this automatically.
00115 
00116     \subsection sWindowsErrors Comilation errors on Win32 involving TOON_TYPEOF
00117     
00118         If you get errors compiling code that uses TooN, look for the macro TOON_TYPEOF 
00119         in the messages. Most likely the file <code>internal/config.hh</code> is clobbered. 
00120         Open it and remove all the defines present there. 
00121         
00122         Also see @ref sManualConfiguration for more details on configuring TooN, 
00123         and @ref sConfigLapack, if you want to use LAPACK and BLAS. Define the macro
00124         in <code>internal/config.hh</code>.
00125 
00126     \subsection sCreateVector How do I create a vector?
00127 
00128         Vectors can be statically sized or dynamically sized.
00129 
00130         @code
00131             Vector<3> v1;    //Create a static sized vector of size 3
00132             Vector<>  v2(4); //Create a dynamically sized vector of size 4
00133             Vector<Dynamic>  v2(4); //Create a dynamically sized vector of size 4
00134         @endcode
00135 
00136         See also \ref sPrecision.
00137 
00138 
00139     \subsection sCreateMatrix How do I create a matrix?
00140 
00141         Matrices can be statically sized or dynamically sized.
00142 
00143         @code
00144             Matrix<3> m;              //A 3x3 matrix (statically sized)
00145             Matrix<3,2>  m;           //A 3x2 matrix (statically sized)
00146             Matrix<>  m(5,6);         //A 5x6 matrix (dynamically sized)
00147             Matrix<3,Dynamic> m(3,6); //A 3x6 matrix with a dynamic number of columns and static number of rows.
00148             Matrix<Dynamic,2> m(3,2); //A 2x3 matrix with a dynamic number of rows and static number of columns.
00149         @endcode
00150 
00151         See also \ref sPrecision.
00152 
00153 
00154     \subsection sFunctionVector How do I write a function taking a vector?
00155     
00156         To write a function taking a local copy of a vector:
00157         @code
00158             template<int Size> void func(Vector<Size> v);
00159         @endcode
00160 
00161         To write a function taking any type of vector by reference:
00162         @code
00163         template<int Size, typename Precision, typename Base> void func(const Vector<Size, Precision, Base>& v);
00164         @endcode
00165         See also \ref sPrecision, \ref sGenericCode and \ref sNoInplace
00166 
00167 
00168         Slices are strange types. If you want to write a function which
00169         uniformly accepts <code>const</code> whole objects as well as slices,
00170         you need to template on the precision.
00171 
00172         Note that constness in C++ is tricky (see \ref sConst). If you write
00173         the function to accept <code> Vector<3, double, B>& </code>, then you
00174         will not be able to pass it slices from <code> const Vector</code>s.
00175         If, however you write it to accept <code> Vector<3, const double, B>&
00176         </code>, then the only way to pass in a <code>Vector<3></code> is to
00177         use the <code>.as_slice()</code> method.
00178 
00179         See also \ref sGenericCode
00180 
00181     \subsection sConst What is wrong with constness?
00182 
00183         In TooN, the behaviour of a Vector or Matrix is controlled by the third
00184         template parameter. With one parameter, it owns the data, with another
00185         parameter, it is a slice. A static sized object uses the variable:
00186         @code
00187              double my_data[3];
00188         @endcode
00189         to hold the data. A slice object uses:
00190         @code
00191              double* my_data;
00192         @endcode
00193         When a Vector is made <code>const</code>, C++ inserts <code>const</code> in
00194         to those types.  The <code>const</code> it inserts it top level, so these
00195         become (respectively):
00196         @code
00197              const double my_data[3];
00198              double * const my_data;
00199         @endcode
00200         Now the types behave very differently. In the first case
00201         <code>my_data[0]</code> is immutable. In the second case,
00202         <code>my_data</code> is immutable, but
00203         <code>my_data[0]</code> is mutable.
00204         
00205         Therefore a slice <code>const Vector</code> behaves like an immutable
00206         pointer to mutable data. TooN attempts to make <code>const</code>
00207         objects behave as much like pointers to \e immutable data as possible.
00208 
00209         The semantics that TooN tries to enforce can be bypassed with 
00210         sufficient steps:
00211         @code
00212             //Make v look immutable
00213             template<class P, class B> void fake_immutable(const Vector<2, P, B>& v)
00214             {
00215                 Vector<2, P, B> nonconst_v(v);
00216                 nonconst_v[0] = 0; //Effectively mutate v
00217             }
00218 
00219             void bar()
00220             {
00221                 Vector<3> v;
00222                 ...
00223                 fake_immutable(v.slice<0,2>());
00224                 //Now v is mutated
00225             }
00226 
00227         @endcode
00228 
00229         See also \ref sFunctionVector
00230 
00231 
00232 
00233     \subsection sElemOps What elementary operations are supported?
00234         
00235         Assignments are performed using <code>=</code>. See also 
00236         \ref sNoResize.
00237 
00238         These operators apply to vectors or matrices and scalars. 
00239         The operator is applied to every element with the scalar.
00240         @code
00241         *=, /=, *, / 
00242         @endcode
00243         
00244         Vector and vectors or matrices and matrices:
00245         @code
00246         +, -, +=, -= 
00247         @endcode
00248         
00249         Dot product:
00250         @code
00251         Vector * Vector
00252         @endcode
00253 
00254         Matrix multiply:
00255         @code
00256         Matrix * Matrix
00257         @endcode
00258 
00259         Matrix multiplying a column vector:
00260         @code
00261         Matrix * Vector
00262         @endcode
00263 
00264         Row vector multiplying a matrix:
00265         @code
00266         Vector * Matrix
00267         @endcode
00268         
00269         3x3 Vector cross product:
00270         @code
00271         Vector<3> ^ Vector<3> 
00272         @endcode
00273 
00274         All the functions listed below return slices. The slices 
00275         are simply references to the original data and can be used as lvalues.
00276 
00277         Getting the transpose of a matrix:
00278         @code
00279             Matrix.T()
00280         @endcode
00281         
00282         Accessing elements:
00283         @code
00284         Vector[i]     //get element i
00285         Matrix(i,j)   //get element i,j
00286         Matrix[i]     //get row i as a vector
00287         Matrix[i][j]  //get element i,j
00288         @endcode
00289         
00290         Turning vectors in to matrices:
00291         @code
00292         Vector.as_row() //vector as a 1xN matrix
00293         Vector.as_col() //vector as a Nx1 matrix
00294         @endcode
00295 
00296         Slicing with a start position and size:
00297         
00298         @code
00299         Vector.slice<Start, Length>();                         //Static slice
00300         Vector.slice(start, length);                           //Dynamic slice
00301         Matrix.slice<RowStart, ColStart, NumRows, NumCols>();  //Static slice
00302         Matrix.slice(rowstart, colstart, numrows, numcols);    //Dynamic slice
00303         @endcode
00304         
00305         Slicing diagonals:
00306         @code
00307         Matrix.diagonal_slice();                               //Get the leading diagonal as a vector.
00308         Vector.as_diagonal();                                  //Represent a Vector as a DiagonalMatrix
00309         @endcode
00310         
00311         Like other features of TooN, mixed static/dynamic slicing is allowed.
00312         For example:
00313 
00314         @code
00315         Vector.slice<Dynamic, 2>(3, 2);   //Slice starting at index 3, of length 2.
00316         @endcode
00317 
00318         See also \ref sSlices
00319 
00320     \subsection sInitialize How I initialize a vector/matrix?
00321 
00322         Vectors and matrices start off uninitialized (filled with random garbage).
00323         They can be easily filled with zeros, or ones (see also TooN::Ones):
00324         @code
00325             Vector<3> v = Zeros;
00326             Matrix<3> m = Zeros
00327             Vector<>  v2 = Zeros(2); //Note in they dynamic case, the size must be specified
00328             Matrix<>  m2 = Zeros(2,2); //Note in they dynamic case, the size must be specified
00329         @endcode
00330 
00331         Vectors can be filled with makeVector:
00332         @code
00333             Vector<> v = makeVector(2,3,4,5,6);
00334         @endcode
00335         
00336         Matrices can be initialized to the identity matrix:
00337         @code
00338             Matrix<2> m = Idendity;
00339             Matrix<> m2 = Identity(3);
00340         @endcode
00341         note that you need to specify the size in the dynamic case.
00342 
00343         Matrices can be filled from data in row-major order:
00344         @code
00345             Matrix<3> m = Data(1, 2, 3, 
00346                                4, 5, 6, 
00347                                7, 8, 9);
00348         @endcode
00349 
00350         A less general, but visually more pleasing syntax can also be used:
00351         @code
00352             Vector<5> v;
00353             Fill(v) = 1,2,3,4,5; 
00354 
00355             Matrix<3,3> m;
00356             Fill(m) = 1, 2, 3, 
00357                       4, 5, 6, 
00358                       7, 8, 9;
00359         @endcode
00360         Note that underfilling is a run-time check, since it can not be detected
00361         at compile time.
00362 
00363         They can also be initialized with data from another source. See also \ref  sWrap.
00364 
00365 
00366 
00367 
00368 
00369     \subsection sScalars How do I add a scalar to every element of a vector/matrix? 
00370         
00371         Addition to every element is not an elementary operation in the same way
00372         as multiplication by a scalar. It is supported throught the ::Ones
00373         object:
00374         
00375         @code
00376             Vector<3> a, b;
00377             ...
00378             b = a + Ones*3;       // b_i = a_i + 3
00379             a+= Ones * 3;         // a_i <- a_i + 3
00380         @endcode
00381 
00382         It is supported the same way on Matrix and slices.
00383 
00384     \subsection sNoResize Why does assigning mismatched dynamic vectors fail?
00385     
00386     Vectors are not generic containers, and dynamic vectors have been designed
00387     to have the same semantics as static vectors where possible. Therefore
00388     trying to assign a vector of length 2 to a vector of length 3 is an error,
00389     so it fails. See also \ref sResize
00390 
00391     \subsection sSTL How do I store Dynamic vectors in STL containers.
00392 
00393     As C++ does not yet support move semantics, you can only safely store
00394     static and resizable Vectors in STL containers.
00395 
00396     \subsection sResize How do I resize a dynamic vector/matrix?
00397 
00398     Do you really want to? If you do, then you have to declare it:
00399 
00400     @code
00401          Vector<Resizable> v;
00402          v.resize(3);
00403          v = makeVector(1, 2, 3);
00404 
00405          v = makeVector(1, 2); //resize
00406          v = Ones(5); //resize
00407          v = Zeros; // no resize
00408     @endcode
00409 
00410     The policy behind the design of TooN is that it is a linear algebra
00411     library, not a generic container library, so resizable Vectors are only
00412     created on request. They provide fewer guarantees than other vectors, so
00413     errors are likely to be more subtle and harder to track down.  One of the
00414     main purposes is to be able to store Dynamic vectors of various sizes in
00415     STL containers.
00416 
00417     Assigning vectors of mismatched sizes will cause an automatic resize. Likewise
00418     assigning from entities like Ones with a size specified will cause a resize.
00419     Assigning from an entities like Ones with no size specified will not cause
00420     a resize.
00421 
00422     They can also be resized with an explicit call to .resize().
00423     Resizing is efficient since it is implemented internally with
00424     <code>std::vector</code>.  Note that upon resize, existing data elements
00425     are retained but new data elements are uninitialized.
00426 
00427     Currently, resizable matrices are unimplemented.  If you want a resizable
00428     matrix, you may consider using a <code>std::vector</code>, and accessing it
00429     as a TooN object when appropriate. See \ref sWrap. Also, the speed and
00430     complexity of resizable matrices depends on the memory layout, so you may
00431     wish to use column major matrices as opposed to the default row major
00432     layout.
00433 
00434     \subsection sDebug What debugging options are there?
00435 
00436     By default, everything which is checked at compile time in the static case
00437     is checked at run-time in the dynamic case (with some additions). Checks can
00438     be disabled with various macros. Note that the optimizer will usually
00439     remove run-time checks on static objects if the test passes.
00440     
00441     Bounds are not checked by default. Bounds checking can be enabled by
00442     defining the macro \c TOON_CHECK_BOUNDS. None of these macros change the
00443     interface, so debugging code can be freely mixed with optimized code.
00444 
00445     The debugging checks can be disabled by defining either of the following macros:
00446         - \c TOON_NDEBUG
00447         - \c NDEBUG 
00448 
00449     Additionally, individual checks can be disabled with the following macros:
00450         - Static/Dynamic mismatch
00451             - Statically determined functions accept and ignore dynamically specified
00452               sizes. Nevertheless, it is an error if they do not match.
00453             - Disable with \c TOON_NDEBUG_MISMATCH
00454         - Slices
00455             - Disable with \c TOON_NDEBUG_SLICE
00456         - Size checks (for assignment)
00457             - Disable with \c TOON_NDEBUG_SIZE
00458         - overfilling using Fill 
00459             - Disable with \c TOON_NDEBUG_FILL
00460         - underfilling using Fill (run-time check)
00461             - Disable with \c TOON_NDEBUG_FILL
00462     
00463 
00464 
00465 
00466     Errors are manifested to a call to <code>std::abort()</code>.
00467 
00468     TooN does not initialize data in a Vector or Matrix.  For debugging purposes
00469     the following macros can be defined:
00470     - \c TOON_INITIALIZE_QNAN or \c TOON_INITIALIZE_NAN Sets every element of newly defined Vectors or
00471       Matrixs to quiet NaN, if it exists, and 0 otherwise. Your code will not compile
00472       if you have made a Vector or Matrix of a type which cannot be constructed
00473       from a number.
00474     - \c TOON_INITIALIZE_SNAN Sets every element of newly defined Vectors or
00475       Matrixs to signalling NaN, if it exists, and 0 otherwise. 
00476     - \c TOON_INITIALIZE_VAL Sets every element of newly defined Vectors or
00477       Matrixs to the expansion of this macro.
00478     - \c TOON_INITIALIZE_RANDOM Fills up newly defined Vectors and Matrixs with
00479       random bytes, to trigger non repeatable behaviour. The random number
00480       generator is automatically seeded with a granularity of 1 second. Your
00481       code will not compile if you have a Vector or Matrix of a non-POD type.
00482 
00483     \subsection sSlices What are slices?
00484 
00485     Slices are references to data belonging to another vector or matrix. Modifying
00486     the data in a slice modifies the original object. Likewise, if the original 
00487     object changes, the change will be reflected in the slice. Slices can be
00488     used as lvalues. For example:
00489 
00490     @code
00491         Matrix<3> m = Identity;
00492 
00493         m.slice<0,0,2,2>() *= 3; //Multiply the top-left 2x2 submatrix of m by 3.
00494 
00495         m[2] /=10; //Divide the third row of M by 10.
00496 
00497         m.T()[2] +=2; //Add 2 to every element of the second column of M.
00498 
00499         m[1].slice<1,2>() = makeVector(3,4); //Set m_1,1 to 3 and m_1,2 to 4
00500         
00501         m[0][0]=6;
00502     @endcode
00503 
00504     Slices are usually strange types. See \ref sFunctionVector
00505 
00506     See also \sFuncSlices
00507 
00508     \subsection sPrecision Can I have a precision other than double?
00509 
00510     Yes!
00511     @code
00512         Vector<3, float> v;          //Static sized vector of floats
00513         Vector<Dynamic, float> v(4); //Dynamic sized vector of floats
00514         Vector<Dynamic, std::complex<double> > v(4); //Dynamic sized vector of complex numbers
00515     @endcode
00516 
00517     Likewise for matrix. By default, TooN supports all builtin types
00518     and std::complex. Using custom types requires some work. If the 
00519     custom type understands +,-,*,/ with builtin types, then specialize
00520     TooN::IsField on the types.
00521 
00522     If the type only understands +,-,*,/ with itself, then specialize
00523     TooN::Field on the type.
00524 
00525     Note that this is required so that TooN can follow the C++ promotion 
00526     rules. The result of multiplying a <code>Matrix<double></code> by a 
00527     <code>Vector<float></code> is a <code>Vector<double></code>.
00528 
00529 
00530     \subsection sFuncSlices How do I return a slice from a function?
00531 
00532     Each vector has a <code>SliceBase</code> type indicating the type of a slice.
00533 
00534     They can be slightly tricky to use:
00535     @code
00536         Vector<2, double, Vector<4>::SliceBase> sliceof(Vector<4>& v)
00537         {
00538             return v.slice<1,2>();
00539         }
00540 
00541         template<int S, class P, class B>
00542         Vector<2, P, Vector<S, P, B>::SliceBase> sliceof(Vector<S, P, B>& v)
00543         {
00544             return v.template slice<1,2>();
00545         }
00546 
00547         template<int S, class P, class B>
00548         const Vector<2, const P, typename Vector<S, P, B>::ConstSliceBase > foo(const Vector<S, P, B>& v)
00549         {
00550             return v.template slice<1,2>();
00551         }
00552     @endcode
00553 
00554     \subsection sSolveLinear How do I invert a matrix / solve linear equations?
00555     
00556     You use the decomposition objects (see \ref sDecompos "below"), for example to solve Ax=b:
00557 
00558     @code
00559     Matrix<3> A;
00560     A[0]=makeVector(1,2,3);
00561     A[1]=makeVector(3,2,1);
00562     A[2]=makeVector(1,0,1);
00563 
00564     Vector<3> b = makeVector (2,3,4);
00565 
00566     // solve Ax=b using LU
00567     LU<3> luA(A);
00568     Vector<3> x1 = luA.backsub(b);
00569 
00570     // solve Ax=b using SVD
00571     SVD<3> svdA(A);
00572     Vector<3> x2 = svdA.backsub(b);
00573     @endcode
00574     
00575     Similarly for the other \ref sDecompos "decomposition objects"
00576 
00577     \subsection sDecompos  Which decomposisions are there?
00578 
00579     For general size matrices (not necessarily square) there are:
00580     @link TooN::LU LU @endlink, @link TooN::SVD SVD @endlink and gauss_jordan()
00581 
00582     For square symmetric matrices there are:
00583     @link TooN::SymEigen SymEigen @endlink and @link TooN::Cholesky Cholesky @endlink
00584 
00585     If all you want to do is solve a single Ax=b then you may want gaussian_elimination()
00586 
00587     \subsection sOtherStuff What other stuff is there:
00588     
00589     Look at the @link modules modules @endlink.
00590 
00591     \subsection sHandyFuncs What handy functions are there (normalize, identity, fill, etc...)?
00592 
00593     See @link gLinAlg here @endlink.
00594 
00595 
00596     \subsection sNoInplace Why don't functions work in place?
00597 
00598     Consider the function:
00599     @code
00600         void func(Vector<3>& v);
00601     @endcode
00602     It can accept a <code>Vector<3></code> by reference, and operate on it 
00603     in place. A <code>Vector<3></code> is a type which allocates memory on the
00604     stack. A slice merely references memory, and is a subtly different type. To
00605     write a function taking any kind of vector (including slices) you can write:
00606 
00607     @code
00608         template<class Base> void func(Vector<3, double, Base>& v);
00609     @endcode
00610 
00611     A slice is a
00612     temporary object, and according to the rules of C++, you can't pass a
00613     temporary to a function as a non-const reference. TooN provides the
00614     <code>.ref()</code> method to escape from this restriction, by returning a
00615     reference as a non-temporary. You would then have to write:
00616     @code
00617         Vector<4> v;
00618         ...
00619         func(v.slice<0,3>().ref());
00620     @endcode
00621     to get func to accept the slice.
00622 
00623     You may also wish to consider writing functions that do not modify structures in
00624     place. The \c unit function of TooN computes a unit vector given an input
00625     vector. In the following context, the code:
00626     @code
00627         //There is some Vector, which may be a slice, etc called v;
00628         v = unit(v);
00629     @endcode
00630     produces exactly the same compiler output as the hypothetical
00631     <code>Normalize(v)</code> which operates in place (for static vectors). Consult the ChangeLog 
00632     entries dated ``Wed 25 Mar, 2009 20:18:16'' and ``Wed  1 Apr, 2009 16:48:45''
00633     for further discussion.
00634     
00635 
00636     \subsection sColMajor Can I have a column major matrix?
00637 
00638     Yes!
00639     @code
00640         Matrix<3, 3, double, ColMajor> m;          //3x3 Column major matrix
00641     @endcode
00642 
00643     \subsection sWrap I have a pointer to a bunch of data. How do I turn it in to a vector/matrix without copying?
00644 
00645     To create a vector use:
00646     @code
00647     double d[]={1,2,3,4};
00648     Vector<4,double,Reference> v1(d);
00649     Vector<Dynamic,double,Reference> v2(d,4);
00650     @endcode
00651     Or, a functional form can be used:
00652     @code
00653     double d[]={1,2,3,4};
00654 
00655     wrapVector<4>(d);         //Returns a Vector<4>
00656     wrapVector<4,double>(d);  //Returns a Vector<4>
00657     
00658     wrapVector(d,3);          //Return a Vector<Dynamic> of size 3
00659     wrapVector<Double>(d,3);  //Return a Vector<Dynamic> of size 3
00660     @endcode
00661 
00662     To crate a matrix use
00663     @code
00664     double d[]={1,2,3,4,5,6};
00665     Matrix<2,3,double,Reference::RowMajor> m1(d);
00666     Matrix<2,3,double,Reference::ColMajor> m2(d);
00667     Matrix<Dynamic, Dynamic, double, Reference::RowMajor> m3(d, 2, 3);
00668     Matrix<Dynamic, 3, double, Reference::RowMajor> m4(d, 2, 3); // note two size arguments are required for semi-dynamic matrices
00669     @endcode
00670 
00671     See also wrapVector() and wrapMatrix().
00672 
00673     \subsection sGenericCode How do I write generic code?
00674     
00675     The constructors for TooN objects are very permissive in that they 
00676     accept run-time size arguments for statically sized objects, and then 
00677     discard the values, This allows you to easily write generic code which 
00678     works for both static and dynamic inputs.
00679 
00680     Here is a function which mixes up a vector with a random matrix:
00681     @code
00682     template<int Size, class Precision, class Base> Vector<Size, Precision> mixup(const Vector<Size, Precision, Base>& v)
00683     {
00684         //Create a square matrix, of the same size as v. If v is of dynamic
00685         //size, then Size == Dynamic, and so Matrix will also be dynamic. In
00686         //this case, TooN will use the constructor arguments to select the
00687         //matrix size. If Size is a real size, then TooN will simply ighore
00688         //the constructor values.
00689 
00690         Matrix<Size, Size, Precision> m(v.size(), v.size());
00691         
00692         //Fill the matrix with random values that sum up to 1.
00693         Precision sum=0;
00694         for(int i=0; i < v.size(); i++)
00695             for(int j=0; j < v.size(); j++)
00696                 sum += (m[i][j] = rand());
00697         
00698         m/= sum;
00699 
00700         return m * v;
00701     }
00702     @endcode
00703 
00704     Writing functions which safely accept multiple objects requires assertions
00705     on the sizes since they may be either static or dynamic. TooN's built in
00706     size check will fail at compile time if mismatched static sizes are given,
00707     and at run-time if mismatched dynamic sizes are given:
00708     
00709     @code
00710     template<int S1, class B1, int S2, class B2> void func_of_2_vectors(const Vector<S1, double, B1>& v1, const Vector<S2, double, B2>& v2)
00711     {
00712         //Ensure that vectors are the same size
00713         SizeMismatch<S1, S2>::test(v1.num_rows(), v2.num_rows());
00714 
00715 
00716     }
00717     @endcode
00718 
00719     For issues relating to constness, see \sFunctionVector and \sConst
00720 
00721 
00722 \subsection ssExamples Are there any examples?
00723 
00724 Create two vectors and work out their inner (dot), outer and cross products
00725 @code
00726 // Initialise the vectors
00727 Vector<3> a = makeVector(3,5,0);
00728 Vector<3> b = makeVector(4,1,3);
00729 
00730 // Now work out the products
00731 double dot = a*b;                            // Dot product
00732 Matrix<3,3> outer = a.as_col() * b.as_row(); // Outer product
00733 Vector<3> cross = a ^ b;                     // Cross product
00734 
00735 cout << "a:" << endl << a << endl;
00736 cout << "b:" << endl << b << endl;
00737 cout << "Outer:" << endl << outer << endl;
00738 cout << "Cross:" << endl << cross << endl;
00739 @endcode
00740 
00741 Create a vector and a matrix and multiply the two together
00742 @code
00743 // Initialise a vector
00744 Vector<3> v = makeVector(1,2,3);
00745 
00746 // Initialise a matrix
00747 Matrix<2,3> M(d);
00748 M[0] = makeVector(2,4,5);
00749 M[1] = makeVector(6,8,9);
00750 
00751 // Now perform calculations
00752 Vector<2> v2 = M*v;  // OK - answer is a static 2D vector
00753 Vector<> v3 = M*v;   // OK - vector is determined to be 2D at runtime
00754 Vector<> v4 = v*M;   // Compile error - dimensions of matrix and vector incompatible
00755 @endcode
00756 
00757 
00758 \subsection sImplementation How is it implemented
00759 
00760 \subsubsection ssStatic Static-sized vectors and matrices
00761 
00762 One aspect that makes this library efficient is that when you declare a
00763 3-vector, all you get are 3 doubles - there's no metadata. So
00764 <code>sizeof(Vector<3>)</code> is 24. This means that when you write
00765 <code>Vector<3> v;</code> the data for <code>v</code> is allocated on the stack
00766 and hence <code>new</code>/<code>delete</code>
00767 (<code>malloc</code>/<code>free</code>) overhead is avoided. However, for large
00768 vectors and matrices, this would be a Bad Thing since <code>Vector<1000000>
00769 v;</code> would result in an object of 8 megabytes being allocated on the stack and
00770 potentially overflowing it. %TooN gets around
00771 that problem by having a cutoff at which statically sized vectors are allocated
00772 on the heap. This is completely transparent to the programmer, the objects'
00773 behaviour is unchanged and you still get the type safety offered by statically
00774 sized vectors and matrices. The cutoff size at which the library changes the
00775 representation is defined in <code>TooN.h</code> as the <code>const int
00776 TooN::Internal::max_bytes_on_stack=1000;</code>.
00777 
00778 When you apply the subscript operator to a <code>Matrix<3,3></code> and the
00779 function simply returns a vector which points to the the apropriate hunk of memory as a reference
00780 (i.e. it basically does no work apart from moving around a pointer). This avoids
00781 copying and also allows the resulting vector to be used as an l-value. Similarly
00782 the transpose operation applied to a matrix returns a matrix which referes to the 
00783 same memory but with the opposite layout which also means
00784 the transpose can be used as an l-value so <code>M1 = M2.T();</code> and
00785 <code>M1.T() = M2;</code> do exactly the same thing.
00786 
00787 <b> Warning: This also means that <code>M = M.T();</code> does the wrong thing.</b>
00788 However, since .T() essentially costs nothing, it should be very rare that you need to do this.
00789 
00790 \subsubsection ssDynamic Dynamic sized vectors and matrices
00791 
00792 These are implemented in the obvious way using metadata with the rule that the
00793 object that allocated on the heap also deallocates. Other objects may reference
00794 the data (e.g. when you subscript a matrix and get a vector).
00795 
00796 \subsection ssLazy Return value optimisation vs Lazy evaluation
00797 
00798 When you write <code>v1 = M * v2;</code> a naive implementation will compute
00799 <code>M * v2</code> and store the result in a temporary object. It will then
00800 copy this temporary object into <code>v1</code>. A method often advanced to
00801 avoid this is to have <code>M * v2</code> simply return an special object
00802 <code>O</code> which contains references to <code>M</code> and <code>v2</code>.
00803 When the compiler then resolves <code>v1 = O</code>, the special object computes
00804 <code>M*v2</code> directly into <code>v1</code>. This approach is often called
00805 lazy evaluation and the special objects lazy vectors or lazy matrices.
00806 Stroustrup (The C++ programming language Chapter 22) refers to them as
00807 composition closure objects or compositors.
00808 
00809 
00810 The killer is this: <b>What if v1 is just another name for v2?</b> i.e. you
00811 write something like <code>v = M * v;</code>. In this case the semantics have
00812 been broken because the values of <code>v</code> are being overwritten as the
00813 computation progresses and then the remainder of the computation is using the
00814 new values. In this library <code>v1</code> in the expression could equally well
00815 alias part of <code>M</code>, thus you can't even solve the problem by having a
00816 clever check for aliasing between <code>v1</code> and <code>v2</code>. This
00817 aliasing problem means that the only time the compiler can assume it's safe to
00818 omit the temporary is when <code>v1</code> is being constructed (and thus cannot
00819 alias anything else) i.e. <code>Vector<3> v1 = M * v2;</code>.
00820 
00821 %TooN provides this optimisation by providing the compiler with the opportunity
00822 to use a return value optimisation. It does this by making <code>M * v2</code>
00823 call a special constructor for <code>Vector<3></code> with <code>M</code> and
00824 <code>v2</code> as arguments. Since nothing is happening between the
00825 construction of the temporary and the copy construction of <code>v1</code> from
00826 the temporary (which is then destroyed), the compiler is permitted to optimise
00827 the construction of the return value directly into <code>v1</code>.
00828 
00829 Because a naive implemenation of this strategy would result in the vector and
00830 matrix classes having a very large number of constructors, these classes are
00831 provided with template constructors that take a standard form. The code that
00832 does this, declared in the header of class <code>Vector</code> is: 
00833 
00834 @code
00835     template <class Op>
00836     inline Vector(const Operator<Op>& op)
00837         : Base::template VLayout<Size, Precision> (op)
00838     {
00839         op.eval(*this);
00840     }
00841 @endcode
00842 
00843 \subsubsection ssHow How it all really works
00844 
00845 This documentation is generated from a cleaned-up version of the interface, hiding the implementation 
00846 that allows all of the magic to work. If you want to know more and can understand idioms like:
00847 @code
00848 
00849 template<int, typename, int, typename> struct GenericVBase;
00850 template<int, typename> struct VectorAlloc;
00851 
00852 struct VBase {
00853     template<int Size, class Precision>
00854     struct VLayout : public GenericVBase<Size, Precision, 1, VectorAlloc<Size, Precision> > {
00855         ...
00856     };
00857 };
00858 
00859 template <int Size, class Precision, class Base=VBase>
00860 class Vector: public Base::template VLayout<Size, Precision> {
00861    ...
00862 };
00863 @endcode
00864 
00865 then take a look at the source code ... 
00866 
00867 
00868 \section sManualConfiguration Manual configuration
00869     
00870 Configuration is controlled by <code>internal/config.hh</code>. If this file is empty
00871 then the default configuration will be used and TooN will work. There are several options.
00872 
00873 \subsection stypeof Typeof
00874 
00875 TooN needs a mechanism to determine the type of the result of an expression. One of the following
00876 macros can be defined to control the behaviour:
00877 - \c TOON_TYPEOF_DECLTYPE
00878   - Use the C++0x decltype operator.
00879 - \c TOON_TYPEOF_TYPEOF
00880   - Use GCC's \c typeof extension. Only works with GCC and will fail with -pedantic
00881 - \c TOON_TYPEOF___TYPEOF__
00882   - Use GCC's \c __typeof__ extension. Only works with GCC and will work with -pedantic
00883 - \c TOON_TYPEOF_BOOST
00884   - Use the \link http://www.boost.org/doc/html/typeof.html Boost.Typeof\endlink system.
00885     This will work with Visual Studio if Boost is installed.
00886 - \c TOON_TYPEOF_BUILTIN
00887   - The default option (does not need to be defined)
00888   - Only works for the standard builtin integral types and <code>std::complex<float></code> and <code>std::complex<double></code>.
00889 
00890 Under Win32, the builtin typeof needs to be used. Comment out all the TOON_TYPEOF_ defines to use it.
00891 
00892 \subsection sConfigLapack Functions using LAPACK
00893 
00894 Some functions use internal implementations for small sizes and may switch over
00895 to LAPACK for larger sizes. In all cases, an equivalent method is used in terms
00896 of accuracy (eg Gaussian elimination versus LU decomposition). If the following 
00897 macro is defined:
00898 - \c TOON_USE_LAPACK
00899 then LAPACK will be used for large systems, where optional.
00900 The individual functions are:
00901 - TooN::determinant is controlled by \c TOON_DETERMINANT_LAPACK
00902   -  If the macro is undefined as or defined as -1, then LAPACK will never be
00903      used. Otherwise it indicated which the size at which LAPACK should be 
00904      used.
00905 
00906 Note that these macros do not affect classes that are currently only wrappers
00907 around LAPACK.
00908 
00909 **/
00910 
00911 ///////////////////////////////////////////////////////
00912 // Modules classifying classes and functions
00913 
00914 /// @defgroup gLinAlg Linear Algebra
00915 /// \link TooN::Vector Vector\endlink  and \link TooN::Matrix Matrix \endlink classes, and helpers.
00916 
00917 /// @defgroup gDecomps Matrix decompositions
00918 /// Classes to perform matrix decompositions, used to solve 
00919 /// linear equations and provide information about matrices. These are wrappers for functionality
00920 /// provided by the LAPACK library.
00921 
00922 /// @defgroup gTransforms Transformation matrices
00923 /// Classes to represent particular types of transformation matrix.
00924 
00925 /// @defgroup gEquations Linear equation solvers
00926 /// Classes to solve linear equations.
00927 
00928 /// @defgroup gFunctions Evaluation of functions.
00929 /// Evaluation of useful functions.
00930 /** 
00931 
00932 @defgroup gOptimize Function optimization
00933 
00934 Classes and functions to perform function optimization.
00935 
00936 @section gOneDim One dimensional function optimization
00937 
00938 The following functions find the minimum of a 1-D function:
00939  - golden_section_search()
00940  - brent_line_search()
00941 
00942 @section gMultiDim Multidimensional dimensional function optimization
00943 
00944 The following classes perform multidimensional function minimization:
00945  - TooN::DownhillSimplex
00946  - TooN::ConjugateGradient
00947 
00948 The mode of operation is to set up a mutable class, then repeatedly call an
00949 iterate function. This allows different sub algorithms (such as termination
00950 conditions) to be substituted in if need be.
00951 
00952 @internal
00953 @defgroup gInternal TooN internals
00954 
00955 */