ceph/src/boost/libs/numeric/ublas/doc/options.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" >
   4 <head>
   5 <meta name="generator" content="HTML Tidy for Linux (vers 6 November 2007), see www.w3.org" />
   6 <!-- tidy options: -w 120 -asxhtml -clean - - vertical-space yes -f index.html.err -m index.html -->
   7 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
   8 <link rel="stylesheet" href="../../../../boost.css" type="text/css"/>
   9 <link rel="stylesheet" href="ublas.css" type="text/css" />
  10 <script type="text/javascript" src="js/jquery-1.3.2.min.js" async="async" ></script>
  11 <script type="text/javascript" src="js/jquery.toc-gw.js" async="async" ></script>
  12 <title>Boost Basic Linear Algebra - Configuration Options</title>
  13 </head>
  14 <body>
  15 <h1><img src="../../../../boost.png" align="middle" alt="logo"/>Boost Basic Linear Algebra - Configuration Options</h1>
  16 <div class="toc" id="toc"></div>
  17
  18 <div class="navigation">
  19 <a href="index.html">back to uBLAS home</a>
  20 </div>
  21
  22 <h2>NDEBUG</h2>
  23
  24 <p><strong>Make sure you define NDEBUG</strong> The only way uBLAS
  25 knows you want a release configuration is to check if you have defined
  26 NDEBUG. If you don't it assumes you want a debug configuration and
  27 adds a lot of very useful runtime check. However these are very slow!
  28 </p>
  29
  30
  31 <h2>BOOST_UBLAS_MOVE_SEMANTICS</h2>
  32
  33 <p class="credit">The patch and description was provided by Nasos Iliopoulos.</p>
  34
  35 <p>An immediate effect of this option is the elimination of the need
  36 for noalias in types <tt>vector&lt;T&gt;</tt> and <tt>matrix&lt;T&gt;</tt>,
  37 when assigned to the same type. This option doesn't have an effect on
  38 bounded and c types. Although it is rare, not all compilers support copy
  39 elision (that allows for move semantics), so a test must be performed to
  40 make sure that there is a benefit when it is enabled. A small
  41 demonstration and test can be found in
  42 <a href="../test/manual/test_move_semantics.cpp"><tt>test_move_semantics.cpp</tt></a></p>
  43
  44 <p>
  45 In the <a href="../test/manual/test_move_semantics.cpp">test
  46 example</a> two tests are defined, one for vectors and one for
  47 matrices. The aim of this example is to print the pointers of the
  48 storage of each of the containers, before and after the assignment to
  49 a temporary object. When move semantics are enabled, the
  50 <tt>vector&lt;T&gt;</tt> and <tt>matrix&lt;T&gt;</tt> storage is moved
  51 from the temporary and no copy is performed.
  52 </p>
  53
  54 <p>
  55 If move semantics are supported by your compiler you will get an output like the following:
  56 </p>
  57 <pre class="screen">
  58 matrix&lt;double&gt; --------------------------------------------------------------------
  59 Temporary pointer r: 0x94790c0
  60 Pointer (must be equal to temp. pointer if move semantics are enabled) : 0x94790c0
  61 </pre>
  62
  63 <p>Notes:</p>
  64 <ul>
  65 <li>It should be no surprise to see matrices and vectors been passed
  66 by VALUE, the compiler takes care and either moves (if the underlying
  67 code does not modify the object), or copies (if the underlying code
  68 modifies the object).
  69 </li>
  70 <li>There might be some space for some improvements (like clearing the
  71 data, before swaping)
  72 </li>
  73 <li>Move semantics don't eliminate temporaries. They rather move their
  74 storage around so no copies are performed.
  75 </li>
  76 <li>MSVC does no implement Named Return Value Optimization in debug
  77 mode. So if you build in debug with this compiler you might get <a
  78 href="https://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=483229"
  79 target="_blank">different behaviour</a> than a release build.
  80 </li>
  81 <li>Enabling move semantics is done via #define BOOST_UBLAS_MOVE_SEMANTICS.
  82 </li>
  83 <li>There is plenty of room for optimizations when c++0x standard is
  84 out, taking advantage of rvalue references. (I have a sweet vector
  85 implementation using that).
  86 </li>
  87 <li>If you enable move semantics and your compiler does not support
  88 them, the operation will just be as passing by const reference.
  89 </li>
  90 </ul>
  91
  92 <p>Interesting links</p>
  93 <ul>
  94 <li> <a href="http://cpp-next.com/archive/2009/08/want-speed-pass-by-value/" target="_blank">Want Speed? Pass by Value.</a>
  95 </li>
  96 <li> <a href="http://blogs.msdn.com/vcblog/archive/2009/02/03/rvalue-references-c-0x-features-in-vc10-part-2.aspx" target="_blank">Rvalue References: C++0x Features in VC10, Part 2</a>
  97 </li>
  98 <li> <a href="http://cpp-next.com/archive/2009/09/move-it-with-rvalue-references/" target="_blank">Move It With Rvalue References</a>
  99 </li>
 100 </ul>
 101
 102 <h2>BOOST_UBLAS_CHECK_ENABLE</h2>
 103
 104 <p>When BOOST_UBLAS_CHECK_ENABLE is defined then all index and
 105 parameter checks are enabled. This is enabled in debug mode and
 106 disabled in release mode.
 107 </p>
 108
 109 <h2>BOOST_UBLAS_TYPE_CHECK</h2>
 110
 111 <p>When BOOST_UBLAS_TYPE_CHECK is enabled then all possibly expensive
 112 structure checks are enabled. If this is not desireable then use
 113 <tt>#define BOOST_UBLAS_TYPE_CHECK 0</tt> before including any uBLAS
 114 header. The define BOOST_UBLAS_TYPE_CHECK_EPSILON can be used to
 115 control the acceptable tolerance, see
 116 <tt>detail/matrix_assign.hpp</tt> for implementation details of this
 117 check.
 118 </p>
 119
 120 <h2>BOOST_UBLAS_USE_LONG_DOUBLE</h2>
 121
 122 <p>Enable uBLAS expressions that involve containers of 'long double'</p>
 123
 124 <h2>BOOST_UBLAS_USE_INTERVAL</h2>
 125
 126 <p>Enable uBLAS expressions that involve containers of 'boost::numeric::interval' types</p>
 127
 128 <h2>Configuring uBLAS with Macros</h2>
 129
 130 <p>Many macro's appear in ublas/config.hpp and elsewhere. Hopefully in the future some of these will disappear!
 131 They fall into 4 groups:
 132 </p>
 133 <ul>
 134 <li> Automatically set by 'boost/numeric/ublas/config.hpp' based on
 135 NDEBUG. Makes the distinction between debug (safe) and release (fast)
 136 mode. Similar to STLport
 137 <ul>
 138 <li> <i>Release</i> mode (NDEBUG defined)
 139 <ul>
 140 <li> BOOST_UBLAS_INLINE <i>Compiler dependant definition to control
 141 function inlining.</i> </li><li> BOOST_UBLAS_USE_FAST_SAME </li></ul>
 142 </li><li> <i>Debug</i> mode
 143 <ul>
 144 <li> BOOST_UBLAS_CHECK_ENABLE <i>Enable checking of indexs, iterators
 145 and parameters. Prevents out of bound access etc.</i> </li><li>
 146 BOOST_UBLAS_TYPE_CHECK <i>Enable additional checks for the results of
 147 expressions using non dense types. Picks up runtime error such as the
 148 assignment of a numerically non-symmetric matrix to
 149 symmertic_matrix. Use <tt>#define BOOST_UBLAS_TYPE_CHECK 0</tt> to
 150 disable expensive numeric type checks.</i> (Note: "structure check"
 151 would be a much better name.)  </li><li>
 152 BOOST_UBLAS_TYPE_CHECK_EPSILON <i>default: sqrt(epsilon), controls how
 153 large the difference between the expected result and the computed
 154 result may become. Increase this value if you are going to use near
 155 singular or badly scaled matrices. Please, refer to
 156 <tt>detail/matrix_assign.hpp</tt> for implementation of these type
 157 checks.</i> </li></ul> </li></ul>
 158 </li>
 159 <li> Automatically set by 'boost/numeric/ublas/config.hpp' based on
 160 compiler and boost/config.hpp macro's. Augments the compiler
 161 deficiency workarounds already supplied by boost/config.hpp
 162 <ul>
 163 <li> BOOST_UBLAS_NO_NESTED_CLASS_RELATION <i>A particularly nasty
 164 problem with VC7.1 Requires that uBLAS and the user use begin(it)
 165 rather then it.begin()</i> </li><li> BOOST_UBLAS_NO_SMART_PROXIES
 166 <i>Disable the automatic propagation of 'constantness' to
 167 proxies. Smart proxies automatically determine if the underling
 168 container they reference is constant or not. They adjust there
 169 definition of iterators and container access to reflect this
 170 constantness.</i> </li></ul>
 171 </li>
 172 <li> For use by uBLAS authors to test implementation methods. Preset
 173 in config.hpp
 174 <ul>
 175 <li> BOOST_UBLAS_USE_INVARIANT_HOISTING </li><li>
 176 BOOST_UBLAS_USE_INDEXING </li><li> BOOST_UBLAS_USE_INDEXED_ITERATOR
 177 </li><li> BOOST_UBLAS_NON_CONFORMANT_PROXIES <i>Gappy containers may
 178 be non-conformant, that is contain elements at different
 179 indices. Assigning between proxies (vector ranges for example) of
 180 these containers is difficult as the LHS may need insert new
 181 elements. This is slow.</i> </li><li> BOOST_UBLAS_USE_DUFF_DEVICE
 182 <i>Near useless on all platforms (see GCC's -funroll-loops)</i>
 183
 184 </li></ul>
 185 </li>
 186 <li> User options. Can be predefined by user before including any
 187 uBLAS headers. They may also be automatically defined for some
 188 compilers to work around compile bugs.
 189 <ul>
 190 <li> BOOST_UBLAS_USE_LONG_DOUBLE <i>Enable uBLAS expressions that
 191 involve containers of 'long double'</i> </li><li>
 192 BOOST_UBLAS_USE_INTERVAL <i>Enable uBLAS expressions that involve
 193 containers of 'boost::numeric::interval' types</i> </li><li>
 194 BOOST_UBLAS_SIMPLE_ET_DEBUG <i>In order to simplify debugging is is
 195 possible to simplify expression templateso they are restricted to a
 196 single operation</i>
 197
 198 </li><li> BOOST_UBLAS_ENABLE_PROXY_SHORTCUTS <i> enable automatic
 199 conversion from proxy class to matrix expression </i> </li><li>
 200 BOOST_UBLAS_NO_ELEMENT_PROXIES <i>Disables the use of element proxies
 201 for gappy types.</i> </li><li> <i>The Gappy types (sparse, coordinate,
 202 compressed) store non-zero elements in their own containers. When new
 203 non-zero elements are assigned they must rearrange these
 204 containers. This invalidates references, iterators or pointers to
 205 these elements. This can happen at some surprising times such as the
 206 expression "a [1] = a [0] = 1;". Element proxies guarantee all such
 207 expressions will work as expected. However they bring their own
 208 restrictions and efficiency problems. For example as of Boost 1.30.0
 209 they prevent the assignment of elements between different types.</i>
 210 </li>
 211 <li> BOOST_UBLAS_REFERENCE_CONST_MEMBER <i>Enable to allow refernces
 212 to be returned to fixed (zero or one) elements of triangular or banded
 213 matrices</i>
 214
 215 </li><li> BOOST_UBLAS_NO_EXCEPTIONS <i>Disable the use exceptions of
 216 uBLAS internal checks and error conditions. BOOST_NO_EXCEPTIONS has
 217 same effect.</i>
 218 </li>
 219 <li> BOOST_UBLAS_SINGULAR_CHECK <i>Check the for singularity in triangular solve() functions</i></li>
 220 </ul>
 221 </li>
 222 </ul>
 223
 224 <hr />
 225 <div id="copyright">
 226  <p>Copyright (&copy;) 2000-2009 Joerg Walter, Mathias Koch, Gunter Winkler<br />
 227    Use, modification and distribution are subject to the Boost Software License, Version 1.0.
 228    (See accompanying file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
 229       http://www.boost.org/LICENSE_1_0.txt
 230    </a>).
 231  </p>
 232 </div>
 233 <div id="revision">
 234 <p>
 235 <!-- Created: Wed Sep 16 21:19:20 CEST 2009 -->
 236 <!-- hhmts start -->
 237 Last modified: Wed Sep 16 23:16:45 CEST 2009
 238 <!-- hhmts end -->
 239 </p>
 240 </div>
 241 <script type="text/javascript">
 242 (function($) {
 243     $('#toc').toc();
 244 })(jQuery);
 245 </script>
 246 </body>
 247 </html>