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