main.doxy

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