TooN: doc/documentation.h Source File

TooN 2.0.0-beta8

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- File List

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 */