TooN 2.0.0-beta8
|
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 */