00001 /*! 00002 \mainpage 00003 00004 \htmlonly 00005 00006 <br> 00007 <p> 00008 <li> 00009 This is the technical documentation -- the <a href="../docs_user/index.html" target="_top">user documentation is over here</a> 00010 </li> 00011 <br> 00012 <li> 00013 For a quick tutorial see <i>examples/example1.cpp</i> 00014 </li> 00015 </p> 00016 <br> 00017 <hr> 00018 <br> 00019 00020 <table style="text-align: left;" border="0" cellpadding="2" cellspacing="2"> 00021 <tbody> 00022 <tr> 00023 <td style="vertical-align: top;"> 00024 <b>Main class hierarchies:</b> 00025 <ul> 00026 <li>Base <- Mat</li> 00027 <li>Base <- Mat <- Col</li> 00028 <li>Base <- Mat <- Row</li> 00029 <li>Base <- Glue</li> 00030 <li>Base <- Op</li> 00031 <li>Base <- subview</li> 00032 <li>Base <- subview <- subview_col</li> 00033 <li>Base <- subview <- subview_row</li> 00034 <li>Base <- diagview</li> 00035 <li>field</li> 00036 <li>field <- subview_field</li> 00037 </ul> 00038 </td> 00039 <td style="vertical-align: top;"> 00040 00041 <br> 00042 </td> 00043 <td style="vertical-align: top;"> 00044 <b>Main helper classes:</b> 00045 <ul> 00046 <li>diskio</li> 00047 <li>glue_div</li> 00048 <li>glue_minus</li> 00049 <li>glue_plus</li> 00050 <li>glue_schur</li> 00051 <li>glue_times</li> 00052 <li>unwrap</li> 00053 <li>unwrap_check</li> 00054 </ul> 00055 </td> 00056 </tr> 00057 </tbody> 00058 </table> 00059 00060 <br> 00061 <p> 00062 <b>Matrix and vector types:</b> 00063 00064 <ul> 00065 00066 <li> 00067 'Mat' is the templated matrix class, with column-major ordering of data (i.e. column by column). 00068 </li> 00069 <br> 00070 00071 <li> 00072 'Col' and 'Row' are the templated column vector and row vector classes, respectively. 00073 The vector classes are derived from the 'Mat' class. 00074 An instance of a 'Row' is effectively treated as a 'Mat' comprised of one row. 00075 Similarly, 'Col' is treated as 'Mat' comprised of one column. 00076 Functions which expect 'Mat' as an input can also use 'Row' and 'Col', where it mathematically makes sense -- 00077 an error at run-time is given where incorrect usage is detected. 00078 </li> 00079 <br> 00080 00081 <li> 00082 'Mat<double>' has been typedefed as 'mat'. 00083 'Col<double>' has been typedefed as 'vec' and 'colvec'. 00084 'Row<double>' has been typedefed as 'rowvec'. 00085 See <i>include/armadillo_bits/typedef.hpp</i> for more typedefs. 00086 </li> 00087 00088 <br> 00089 00090 <li> 00091 A scalar is treated as a 1x1 matrix during assignment. 00092 Hence <b>mat X(5,10); X = 20;</b> will result in <b>X</b> having a size of 1x1, rather than 5x10. 00093 This is the same as what happens in Matlab/Octave. 00094 </li> 00095 <br> 00096 </ul> 00097 </p> 00098 00099 <p> 00100 <b>In order to have ease of use and a straightforward user interface, 00101 some trade-offs between verbosity, speed and memory efficiency are present:</b> 00102 <ul> 00103 <li> 00104 To dramatically speed up handling of small vectors and matrices, 00105 while at the same time allowing dynamic re-sizing (e.g. to load matrices of unknown size from disk), 00106 each matrix has a certain amount of memory pre-allocated directly in the definition of the 'Mat' class. 00107 The 'new' operator is called only if the required size of the matrix does not fit into the pre-allocated memory. 00108 The pre-allocation technique was used instead of requiring the user to hard-code matrix sizes. 00109 </li> 00110 <br> 00111 <li> 00112 Accessors for simple data, such as the number of rows and columns, are not used, e.g. <b>X.rows()</b>. 00113 Instead, read-only publically accessible members are provided, e.g. <b>X.n_rows</b>. 00114 This was done with the aim of improving readbility of user code with many loops. 00115 (As a sidenote, <b>X.rows(...)</b> is used to access sub-matrices of <b>X</b>). 00116 </li> 00117 <br> 00118 <li> 00119 Unsigned integers are used (of type 'u32') for loops and the storage of sizes. 00120 This avoids the need to account for negative values during bounds checks. 00121 </li> 00122 <br> 00123 </ul> 00124 </p> 00125 00126 <p> 00127 <b>Debugging:</b> 00128 <ul> 00129 <li> 00130 <b>Bounds and other checks are enabled by default</b>. 00131 They can be turned off by defining <b>ARMA_NO_DEBUG</b> prior to including <i>armadillo</i> 00132 (preferably in the Makefile file or the command line, e.g. g++ -DARMA_NO_DEBUG ...). 00133 The reasoning here is that bounds checks should be turned off <b>only</b> when the user is satisfied that their code is working correctly 00134 (i.e. thoroughly debugged). 00135 </li> 00136 <br> 00137 00138 <li> 00139 <b>Low level library debugging</b> can be aided by defining <b>ARMA_EXTRA_DEBUG</b> prior to including <i>armadillo</i>. 00140 Note that defining ARMA_NO_DEBUG will automatically undefine ARMA_EXTRA_DEBUG (see <i>armadillo_bits/debug.hpp</i>). 00141 </li> 00142 <br> 00143 </ul> 00144 </p> 00145 00146 <p> 00147 <b>External libraries:</b> 00148 <ul> 00149 <li> 00150 To avoid reinventing a few wheels, Armadillo can leverage ATLAS, LAPACK, BLAS and Boost libraries. 00151 While the presence of these libraries is not mandatory, the functionality of Armadillo will be reduced without them. 00152 Operations such as matrix multiplication will still work, 00153 however more involved operations such as matrix inversion of eigenvalue decomposition require ATLAS or LAPACK. 00154 </li> 00155 <br> 00156 </ul> 00157 </p> 00158 00159 00160 <p> 00161 <b>Delayed evaluation via expression templates:</b> 00162 00163 <ul> 00164 <li> 00165 Many operations (invoked through unary or binary operators) are not immediately executed, allowing more operations to be queued. 00166 The queued operations are executed (possibly by combining several operations) when the 'Mat' 00167 constructor or assignment operator is invoked. This is done at compile time. 00168 <ul> 00169 <p> 00170 As an example, when the compiler evaluates the line 00171 <b>mat Z = A + B + C</b>, 00172 the line is converted, at compile time, to be 00173 <b>mat Z = X</b>, 00174 where <b>X</b> is of type <b>Glue< Glue<mat, mat, glue_plus>, mat, glue_plus></b>. 00175 The constructor for the 'Mat' class then uses the last template argument to call 00176 <b>glue_plus::apply(*this, X)</b>, 00177 which sets the size of <b>Z</b> and evaluates <b>A + B + C</b> in one loop (i.e. no temporary matrices are created). 00178 </p> 00179 <p> 00180 The recursive template type <b>Glue< glue_data<mat, mat, glue_plus>, mat, glue_plus></b> 00181 is constructed via repeated invocations of <b>operator+()</b>. 00182 First, <b>operator+(mat,mat)</b> is called, which returns an object of type <b>Glue<mat, mat, glue_plus></b>. 00183 This object is then fed to <b>operator+(Glue<T1,T2,glue_type>, mat)</b> which returns an object of type 00184 <b>Glue< Glue<mat, mat, glue_plus>, mat, glue_plus></b>. 00185 </p> 00186 <p>Note that the compiler can optimise away the temporary object <b>X</b> as well as the intermediate object resulting 00187 from calling <b>operator+()</b> the first time. 00188 Furthermore, the single loop which evaluates <b>A + B + C</b> can be inlined. 00189 </p> 00190 </ul> 00191 </li> 00192 <br> 00193 <li> 00194 Other types of delayed operation are queued unary operations. 00195 One example is <b>max Z = inv(diagmat(A))</b>, which has a temporary object of type 00196 <b>Op< Op<mat, op_diagmat>, op_inv></b>. 00197 </li> 00198 <br> 00199 <li> 00200 Operations types can be mixed. A contrived example is <b>mat Z = trans( diagmat(A * B) + inv(C) )</b>, 00201 which has a temporary object with the rather convoluted type of 00202 <font size=-1> 00203 <b>Op< Glue< Op< Glue<mat, mat, glue_times>, op_diagmat>, Op<mat, op_inv>, glue_plus>, op_trans></b>. 00204 </font> 00205 </li> 00206 <br> 00207 <li> 00208 The degree to which operations are optimised is dependent on code being present to handle particular combinations. 00209 </li> 00210 <br> 00211 <li> 00212 The 'unwrap' class is used internally by many functions to create a 'Mat' object out of 'Op' or 'Glue' objects. 00213 If a 'Mat' object is fed to 'unwrap', no copying is done. 00214 </li> 00215 <br> 00216 <li> 00217 The 'Base' class is used for type-safe downcasting in functions that restrict their input(s) to be classes that are derived from 'Base'. 00218 This includes 'Mat', 'Op' 'Glue', 'diagview' and 'subview' classes. 00219 </li> 00220 <br> 00221 </ul> 00222 </p> 00223 00224 \endhtmlonly 00225 */