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