]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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<T></tt> and <tt>matrix<T></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<T></tt> and <tt>matrix<T></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<double> -------------------------------------------------------------------- | |
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 (©) 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> |