tutorial.hpp

来自「矩阵运算源码最新版本」· HPP 代码 · 共 1,484 行 · 第 1/4 页

<tt>File system...</tt> and chose the mtl4 main directory and do the same 
for the boost library. So this property will contain two entries.
-# "C:\cppLibs\mtl4"
-# "C:\cppLibs\boost_1_34_1"
.
\n
in my case.

Now change to the tab <tt>Build Settings</tt>. Enter an artifact name and an
extension. For windows systems this should be \c exe . For artifact name you can
take \c vector1 .\n
Under <tt>Build command</tt> you have to enter <tt>mingw32-make -k</tt>.

So we can go to the next tab \c Environment. I have installed several compiler
vor AVM microcontrollers, CYGWIN and the MinGW. This step is necessary to compile
the example successfull, even though I removed all the compiler entries in the
path variable. Don't ask me why!\n
Click on the button \c New in the configuration section. A next dialog appears.
In the field \c Name enter \c path. In \c Value appears your path and in my
case in the front of all the cygwin installation. Now remove this and all
other compilers in this path (inside the value field). The field \c Delimiter
contains the correct sign. Let's change the \c Operation to \c Replace and
click on OK. So a new user variables appears. Click on apply and than on OK.

Now you can test it if you can compile this simple example. Otherwise, please 
restart Eclipse.

P.S.: The description how to use Eclipse is contributed by Michael Schmid
      and we are very grateful for his efforts.
*/






//-----------------------------------------------------------

/*! \page tutorial Tutorial

MTL4 is still in an early state of development and it is possible that
some details may change during further implementation.
However, we will do our best that applications are minimally affected.
In particular, the topics in the tutorial are not subject to modifications.
This, of course, does not exclude backward-compatible extensions.

-# Basic Types and Operations
   -# \subpage vector_def
   -# \subpage vector_functions
   -# \subpage vector_expr 
   -# \subpage rich_vector_expr 
   -# \subpage matrix_types
   -# \subpage matrix_insertion
   -# \subpage matrix_functions
   -# \subpage matrix_expr 
   -# \subpage matrix_vector_functions 
   -# \subpage matrix_vector_expr
   .
-# Traversal of Matrices and Vectors
   -# \subpage iteration
   -# \subpage rec_intro
   .
-# Advanced Topics
   -# \subpage function_nesting
   .
-# Discussion
   -# \subpage copying
   -# \subpage peak_addiction
*/





//-----------------------------------------------------------


/*! \page vector_def Vector Definitions

To start the tutorial we want to give a very short example (we could call
it the MTL4-hello-world).

\include vector1.cpp

The <a href="http://www.boost.org">Boost library</a>
is used and must also be downloaded. See the
\ref install "installation guide" for more details.
To compile a MTL4 program you only need to include the MTL and the
boost path.
A compile command could read:\n 
<tt>g++ -I/u/peter/mtl4 -I/u/peter/boost -O2 vector1.cpp -o vector1</tt>\n
As most modern C++ software MTL4 uses intensively function inlining.
As a consequence, the performance is rather poor if compiled without
optimization.
But don't worry: despite the aggressive source code transformation at 
compile time, the compilation rarely took more than a minute, in
most cases only a few seconds.

The short program certainly does not need much explanation only some
brief comments.
The %vector in the program above is a column %vector.
The constructor in the example takes two arguments: the size and the 
initial value.

Indices always start with zero.
Earlier efforts to support one-based indices were abandoned because
code became rather complicated when mixed indexing for different
arguments of a function.
We decided that the additional development
 effort and the potential performance
penalty are not acceptable.
Extra functionality will be provided in the future if necessary for 
interoperability with Fortran libraries.

The following program defines a row %vector of 7 elements without 
(explicit) initialization.

\include vector2.cpp

Scalar values can be assigned to vectors if the type of the scalar
value is assignable to the type of the elements.
Scalar types are in MTL4 all types that are not explicitly defined
by type %traits as vectors or matrices, thus almost all types.
(Unfortunately, we needed to remove the templated assignment on MSVC 8.0
so that only the first assignment with the complex value works there.)

Proceed to \ref vector_functions "vector functions".  

*/

//-----------------------------------------------------------


/*! \page vector_functions Vector Functions


Principal MTL4 functions are all defined in namespace mtl.
Helper functions are defined in sub-namespaces to avoid
namespace pollution.

The following program shows how to compute norms:

\include vector_norm.cpp

Since this code is almost self-explanatory, we give only a few
comments here.
The definitions of the \ref one_norm, \ref two_norm, and 
\ref infinity_norm can
be found in their respective documentations.
%Vector norms are for performance reasons computed with unrolled loops.
Since we do not want to rely on the compilers' capability and 
in order to have more control over the optimization, the unrolling
is realized by meta-programming.
Specializations for certain compilers might be added later
if there is a considerable performance gain over the meta-programming
solution.

Loops in reduction %operations, like norms, are by default unrolled
to 8 statements.
The optimal unrolling depends on several factors, in particular
the number of registers and the value type of the %vector.
The last statement shows how to unroll the computation to six
statements.
The maximum for unrolling is 8 (it might be increased later).

The norms return the magnitude type of the vectors' value type, 
see Magnitude.

Similarly, the sum and the product of all vector's elements can
be computed:

\include vector_reduction.cpp

As %vector reductions base on the same implementation as norms, the
unrolling can be explicitly controlled as shown in the last
command.
The results of these reductions are the value type of the %vector.

In the same way, the maximum and minimum of vectors are computed:

\include vector_min_max.cpp

The dot product of two vectors is computed with the function \ref dot:

\include dot.cpp

As the previous computation the evaluation is unrolled, either with
a user-defined parameter or by default eight times.

The result type of \ref dot is of type of the values' product.
If MTL4 is compiled with a concept-compiler, the result type is 
taken from the concept std::Multiple and without concepts
Joel de Guzman's result type deduction from Boost is used.

The example also showed how to compute the conjugate values of all
elements.
The %vector is not changed but a view on the %vector is created
that conjugate an element when accessed.

The transposition of vectors will be implemented soon.

Return to \ref vector_def "vector definitions"
or proceed to \ref vector_expr "vector expressions".


*/

//-----------------------------------------------------------


/*! \page vector_expr Vector Expressions

The following program illustrates the usage of basic %vector
expressions.

\include vector_expr.cpp

The mathematical definition of %vector spaces requires that
vectors can be added, multiplied with scalar values
and the results can be assigned to vectors.
In MTL4, the vectors must have the same algebraic shape, 
see \ref ashape,
 for addition
and assignment, i.e. column vectors cannot be assigned to row vectors.
If the elements of the vectors are vectors themselves or matrices
then the elements must also be of the same algebraic shape.

Products of scalars and vectors are
 implemented by a view, see \ref vector::scaled_view,
and %vector elements are multiplied with the factor when
accessing an element of the view.
Please notice that the scaling factor's type is not required to be
identical with the vector's value type.
Furthermore, the value type of the view can be different from
the vector's value type if necessary to represent the products.
The command is an example for it: multiplying a double %vector
with a complex number requires a complex %vector view to 
guarantee the correctness of the results.

Traditional definitions of operators perform computations
in temporary variables that are returned at the end of the
calculation.
The presence of multiple operators, say n, in a single expression
(which is always the case except for an assignment without numerics)
requires then the execution of n loops (possibly more to copy
the temporaries on the stack).
If the vectors are too large for the cache, values must be loaded
repeatedly from slower memories.
Expression templates circumvent this repeated loading of %vector
elements by
performing only one loop.


Return to \ref vector_functions "vector functions"
or proceed to \ref rich_vector_expr "rich vector expressions".

*/

//-----------------------------------------------------------


/*! \page rich_vector_expr Rich Vector Expressions

As discussed in the previous chapter, 
%vector operation can be accelerated by improving
their cache locality via expression templates.
Cache locality can be further improved in applications
when subsequent %vector expressions are evaluated
in one loop, data dependencies allowing.
Unfortunately, this so-called loop fusion cannot be 
realized with expression templates.
At least not when the loops are performed in the assignment.

In collaboration with Karl Meerbergen, we developed expression
templates that can be nested, called rich expression templates.
The following program shows some examples of rich expression
templates:

\include rich_vector_expr.cpp

The first example shows the combination of an incremental
assignment with a %vector addition.
The second statement fuses four %vector expressions:
-# The value 2 is assigned to every element of x;
-# w is scaled in-place with 3;
-# v is incremented by the sum of both %vector; and
-# u is incremented by the new value of v.

Again, all these %operations are performed in one loop and each %vector
element is accessed exactly once.


Return to \ref vector_expr "vector expressions"
or proceed to \ref matrix_types "matrix types".

*/

//-----------------------------------------------------------


/*! \page matrix_types Matrix Types

Right now, MTL4 provides three %matrix types:
- \ref dense2D;
- \ref morton_dense; and
- \ref compressed.

The type \ref dense2D defines regular 
row-major and column-major matrices:

\include dense2D.cpp

If no %matrix parameters are defined, dense matrices are
by default row-major.
There are more %matrix parameters besides the orientation.
As they are not yet fully supported we refrain from discussing
them.

%Matrix elements can be accessed by a(i, j) or in the more
familiar form a[i][j].
The second form is internally transformed into the first
one at compile time so that the run-time performance is not
affected (unless the compiler does not inline completely
which we never observed so far).
Also, the compile time is not conceivably increased by this
transformation.

Please notice that overwriting single %matrix elements is only
defined for dense %matrix types. 
For a generic way to modify matrices see \ref matrix_insertion.

Assigning a scalar value to a %matrix stores a multiple of
the identity %matrix, i.e. the scalar is assigned to all
diagonal elements and all off-diagonal elements are 0.
If the %matrix is not square this assignment throws an exception.
This operation is generic (i.e. applicable to
all %matrix types including sparse).

Just in case you wonder why the %scalar value is only assigned to the diagonal
elements of the %matrix not to all entries, this becomes quite clear
when you think of a %matrix as a linear operator (from one %vector space
to another one).
For instance, consider the multiplication of %vector x with the scalar alpha:
\code
    y= alpha * x;
\endcode
where y is a %vector too.
This %operation is equivalent to assigning alpha to the %matrix A and multiplying x with 
A:
\code
    A= alpha;
    y= A * x;
\endcode
In other words, the %matrix A has the same impact on x as the scalar alpha itself.

Assigning the %scalar value to the diagonal requires of course that the %matrix is 
square.
In the special case that the %scalar value is 0 (more precisely the multiplicative
identity element of the %matrix's value_type) the %matrix can be non-square.
This is consistent with the linear operator characteristic: applying the zero operator
on some %vector results in the zero %vector with the dimension of the operators image.
From a more pragmatic prospective 
\code
    A= 0; 
\endcode
can be used to clear any %matrix, square or rectangular, sparse and dense. 

Dense matrices with a recursively designed memory layout
can be defined with the type \ref morton_dense:

\include morton_dense.cpp