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