add a Transposition section in page 2

CMakeLists.txt

@@ -220,6 +220,17 @@ else()
   )
 endif()
 
+# similar to set_target_properties but append the property instead of overwriting it
+macro(ei_add_target_property target prop value)
+
+  get_target_property(previous ${target} ${prop})
+  # if the property wasn't previously set, ${previous} is now "previous-NOTFOUND" which cmake allows catching with plain if()
+  if(NOT previous)
+    set(previous "")
+  endif(NOT previous)
+  set_target_properties(${target} PROPERTIES ${prop} "${previous} ${value}")
+endmacro(ei_add_target_property)
+
 install(FILES
   signature_of_eigen3_matrix_library
   DESTINATION ${INCLUDE_INSTALL_DIR} COMPONENT Devel

cmake/EigenTesting.cmake

@@ -1,17 +1,6 @@
 option(EIGEN_NO_ASSERTION_CHECKING "Disable checking of assertions using exceptions" OFF)
 option(EIGEN_DEBUG_ASSERTS "Enable advanced debuging of assertions" OFF)
 
-# similar to set_target_properties but append the property instead of overwriting it
-macro(ei_add_target_property target prop value)
-
-  get_target_property(previous ${target} ${prop})
-  # if the property wasn't previously set, ${previous} is now "previous-NOTFOUND" which cmake allows catching with plain if()
-  if(NOT previous)
-    set(previous "")
-  endif(NOT previous)
-  set_target_properties(${target} PROPERTIES ${prop} "${previous} ${value}")
-endmacro(ei_add_target_property)
-
 macro(ei_add_property prop value)
   get_property(previous GLOBAL PROPERTY ${prop})
   set_property(GLOBAL PROPERTY ${prop} "${previous} ${value}")

doc/C02_TutorialMatrixArithmetic.dox

@@ -15,6 +15,7 @@ between matrices, vectors and scalars with Eigen.
   - \ref TutorialArithmeticAddSub
   - \ref TutorialArithmeticScalarMulDiv
   - \ref TutorialArithmeticMentionXprTemplates
+  - \ref TutorialArithmeticTranspose
   - \ref TutorialArithmeticMatrixMul
   - \ref TutorialArithmeticDotAndCross
   - \ref TutorialArithmeticRedux
@@ -84,6 +85,35 @@ for(int i = 0; i < 50; ++i)
 Thus, you should not be afraid of using relatively large arithmetic expressions with Eigen: it only gives Eigen
 more opportunities for optimization.
 
+\section TutorialArithmeticTranspose Transposition and conjugation
+
+The \c transpose \f$ a^T \f$, \c conjugate \f$ \bar{a} \f$, and the \c adjoint (i.e., conjugate transpose) of the matrix or vector \f$ a \f$, are simply obtained by the functions of the same names.
+
+<table class="tutorial_code"><tr><td>
+Example: \include tut_arithmetic_transpose_conjugate.cpp
+</td>
+<td>
+Output: \include tut_arithmetic_transpose_conjugate.out
+</td></tr></table>
+
+For real matrices, \c conjugate() is a no-operation, and so \c adjoint() is 100% equivalent to \c transpose().
+
+As for basic arithmetic operators, \c transpose and \c adjoint simply return a proxy object without doing the actual transposition. Therefore, <tt>a=a.transpose()</tt> leads to an unexpected result:
+<table class="tutorial_code"><tr><td>
+Example: \include tut_arithmetic_transpose_aliasing.cpp
+</td>
+<td>
+Output: \include tut_arithmetic_transpose_aliasing.out
+</td></tr></table>
+In "debug mode", i.e., when assertions have not been disabled, such common pitfalls are automatically detected. For \em in-place transposition, simply use the transposeInPlace() function:
+<table class="tutorial_code"><tr><td>
+Example: \include tut_arithmetic_transpose_inplace.cpp
+</td>
+<td>
+Output: \include tut_arithmetic_transpose_inplace.out
+</td></tr></table>
+There is also the adjointInPlace() function for complex matrix.
+
 \section TutorialArithmeticMatrixMul Matrix-matrix and matrix-vector multiplication
 
 Matrix-matrix multiplication is again done with \c operator*. Since vectors are a special

doc/snippets/CMakeLists.txt

@@ -26,3 +26,5 @@ foreach(snippet_src ${snippets_SRCS})
   set_source_files_properties(${CMAKE_CURRENT_BINARY_DIR}/${compile_snippet_src}
                               PROPERTIES OBJECT_DEPENDS ${snippet_src})
 endforeach(snippet_src)
+
+ei_add_target_property(compile_tut_arithmetic_transpose_aliasing COMPILE_FLAGS -DEIGEN_NO_DEBUG)

doc/snippets/tut_arithmetic_transpose_aliasing.cpp

@@ -0,0 +1,4 @@
+Matrix2i a; a << 1, 2, 3, 4;
+cout << "Here is the matrix a:\n" << a << endl;
+a = a.transpose(); // fails
+cout << "and the aliasing effect:\n" << a << endl;

doc/snippets/tut_arithmetic_transpose_conjugate.cpp

@@ -0,0 +1,12 @@
+MatrixXcf a = MatrixXcf::Random(2,2);
+cout << "Here is the matrix a\n" << a << endl;
+
+cout << "Here is the matrix a^T\n" << a.transpose() << endl;
+
+
+cout << "Here is the conjugate of a\n" << a.conjugate() << endl;
+
+
+cout << "Here is the matrix a^*\n" << a.adjoint() << endl;
+
+

doc/snippets/tut_arithmetic_transpose_inplace.cpp

@@ -0,0 +1,4 @@
+MatrixXf a(2,3); a << 1, 2, 3, 4, 5, 6;
+cout << "Here is the initial matrix a:\n" << a << endl;
+a.transposeInPlace();
+cout << "and after being transposed:\n" << a << endl;

doc/snippets/tut_matrix_assignmnet_resizing.cpp

@@ -1,5 +0,0 @@
-MatrixXf a(2,2);
-cout << "a is of size " << a.rows() << "x" << a.cols() << std::endl;
-MatrixXf b(3,3);
-a = b;
-cout << "a is now of size " << a.rows() << "x" << a.cols() << std::endl;