Extend tutorial page 5: Advanced initialization.

7 files changed, 174 insertions, 13 deletions

diff --git a/doc/C05_TutorialAdvancedInitialization.dox b/doc/C05_TutorialAdvancedInitialization.dox
index 1e048d4b2..96105f6a6 100644
--- a/doc/C05_TutorialAdvancedInitialization.dox
+++ b/doc/C05_TutorialAdvancedInitialization.dox
@@ -6,26 +6,133 @@ namespace Eigen {
 \li \b Previous: \ref TutorialBlockOperations
 \li \b Next: \ref TutorialLinearAlgebra
 
-\section TutorialMatrixArithmCommaInitializer Comma initializer
+This page discusses several advanced methods for initializing matrices. It gives more details on the
+comma-initializer, which was introduced before. It also explains how to get special matrices such as the
+identity matrix and the zero matrix.
 
-Eigen offers a comma initializer syntax which allows to set all the coefficients
-of any dense objects (matrix, vector, array, block, etc.) to specific values:
-\include Tutorial_commainit_01.cpp
+\b Table \b of \b contents
+  - \ref TutorialAdvancedInitializationCommaInitializer
+  - \ref TutorialAdvancedInitializationSpecialMatrices
+  - \ref TutorialAdvancedInitializationTemporaryObjects
+
+
+\section TutorialAdvancedInitializationCommaInitializer The comma initializer
+
+Eigen offers a comma initializer syntax which allows the user to easily set all the coefficients of a matrix,
+vector or array. Simply list the coefficients, starting at the top-left corner and moving from left to right
+and from the top to the bottom. The size of the object needs to be specified beforehand. If you list too few
+or too many coefficients, Eigen will complain.
+
+<table class="tutorial_code"><tr><td>
+Example: \include Tutorial_commainit_01.cpp
+</td>
+<td>
 Output: \verbinclude Tutorial_commainit_01.out
+</td></tr></table>
+
+The comma initializer can also be used to fill block expressions such as <tt>m.row(i)</tt>. Here is a more
+complicated way to get the same result as above:
+
+<table class="tutorial_code"><tr><td>
+Example: \include Tutorial_commainit_01b.cpp
+</td>
+<td>
+Output: \verbinclude Tutorial_commainit_01b.out
+</td></tr></table>
+
+Moreover, the elements of the initialization list may themselves be matrices. Thus, we can use them to
+initialize matrices with a block structure.
+
+<table class="tutorial_code"><tr><td>
+Example: \include Tutorial_AdvancedInitialization_Block.cpp
+</td>
+<td>
+Output: \verbinclude Tutorial_AdvancedInitialization_Block.out
+</td></tr></table>
+
+
+\section TutorialAdvancedInitializationSpecialMatrices Special matrices and arrays
+
+The Matrix and Array classes have static methods like \link DenseBase::Zero() Zero()\endlink, which can be
+used to initialize all coefficients to zero. There are three variants. The first variant takes no arguments
+and can only be used for fixed-size objects. If you want to initialize a dynamic-size object to zero, you need
+to specify the size. Thus, the second variant requires one argument and can be used for one-dimensional
+dynamic-size objects, while the third variant requires two arguments and can be used for two-dimensional
+objects. All three variants are illustrated in the following example:
+
+<table class="tutorial_code"><tr><td>
+Example: \include Tutorial_AdvancedInitialization_Zero.cpp
+</td>
+<td>
+Output: \verbinclude Tutorial_AdvancedInitialization_Zero.out
+</td></tr></table>
+
+Similarly, the static method \link DenseBase::Constant() Constant\endlink(value) sets all coefficients to \c
+value. If the size of the object needs to be specified, the additional arguments go before the \c value
+argument, as in <tt>MatrixXd::Constant(rows, cols, value)</tt>. The method \link DenseBase::Random() Random()
+\endlink fills the matrix or array with random coefficients. The identity matrix can be obtained by calling
+\link MatrixBase::Identity() Identity()\endlink; this method is only available for Matrix, not for Array,
+because "identity matrix" is a linear algebra concept.  The method
+\link DenseBase::LinSpaced LinSpaced\endlink(low, high, size) is only available for vectors and
+one-dimensional arrays; it yields a vector of the specified size whose coefficients are equally spaced between
+\c low and \c high. The method \c LinSpaced() is illustrated in the following example, which prints a table
+with angles in degrees, the corresponding angle in radians, and their sine and cosine.
+
+<table class="tutorial_code"><tr><td>
+Example: \include Tutorial_AdvancedInitialization_LinSpaced.cpp
+</td>
+<td>
+Output: \verbinclude Tutorial_AdvancedInitialization_LinSpaced.out
+</td></tr></table>
+
+This example shows that objects like the ones returned by LinSpaced() can be assigned to variables (and
+expressions). Eigen defines utility functions like \link DenseBase::setZero() setZero()\endlink, 
+\link MatrixBase::setIdentity() \endlink and \link DenseBase:setLinSpaced() \endlink to do this
+conveniently. The following example contrasts three ways to construct the matrix
+\f$ J = \bigl[ \begin{smallmatrix} O & I \\ I & O \end{smallmatrix} \bigr] \f$: using static methods and
+assignment, using static methods and the comma-initializer, or using the setXxx() methods.
+
+<table class="tutorial_code"><tr><td>
+Example: \include Tutorial_AdvancedInitialization_ThreeWays.cpp
+</td>
+<td>
+Output: \verbinclude Tutorial_AdvancedInitialization_ThreeWays.out
+</td></tr></table>
+
+A summary of all pre-defined matrix, vector and array objects can be found in the \ref QuickRefPage.
+
+
+\section TutorialAdvancedInitializationTemporaryObjects Temporary matrices and arrays
+
+As shown above, static methods as Zero() and Constant() can be used to initialize to variables at the time of
+declaration or at the right-hand side of an assignment operator. You can think of these methods as returning a
+matrix or array (in fact, they return a so-called \ref TopicEigenExpressionTemplates "expression object" which
+evaluates to a matrix when needed). This matrix can also be used as a temporary object. The second example in
+the \ref GettingStarted guide, which we reproduced here, already illustrates this.
 
-Moreover, the elements of the initialization list may themselves be Eigen expressions:
-\include Tutorial_commainit_02.cpp
-Output: \verbinclude Tutorial_commainit_02.out
+<table class="tutorial_code"><tr><td>
+Example: \include QuickStart_example2_dynamic.cpp
+</td>
+<td>
+Output: \verbinclude QuickStart_example2_dynamic.out
+</td></tr></table>
 
-<span class="note">\b Side \b note: here \link CommaInitializer::finished() .finished() \endlink
-is used to get the actual matrix object once the comma initialization
-of our temporary submatrix is done. Note that despite the apparent complexity of such an expression,
-Eigen's comma initializer usually compiles to very optimized code without any overhead.</span>
+The expression <tt>m + MatrixXf::Constant(3,3,1.2)</tt> constructs the 3-by-3 matrix with all its coefficients
+equal to 1.2 and adds it to \c m ; in other words, it adds 1.2 to all the coefficients of \c m . The
+comma-initializer can also be used to construct temporary objects. The following example constructs a random
+matrix of size 2-by-3, and then multiplies this matrix on the left with 
+\f$ \bigl[ \begin{smallmatrix} 0 & 1 \\ 1 & 0 \end{smallmatrix} \bigr] \f$.
 
+<table class="tutorial_code"><tr><td>
+Example: \include Tutorial_AdvancedInitialization_CommaTemporary.cpp
+</td>
+<td>
+Output: \verbinclude Tutorial_AdvancedInitialization_CommaTemporary.out
+</td></tr></table>
 
-TODO mention using the comma initializer to fill a block xpr like m.row(i) << 1,2,3;
+The \link CommaInitializer::finished() finished() \endlink method is necessary here to get the actual matrix
+object once the comma initialization of our temporary submatrix is done.
 
-TODO add more sections about Identity(), Zero(), Constant(), Random(), LinSpaced().
 
 \li \b Next: \ref TutorialLinearAlgebra
 
diff --git a/doc/snippets/Tutorial_AdvancedInitialization_Block.cpp b/doc/snippets/Tutorial_AdvancedInitialization_Block.cpp
new file mode 100644
index 000000000..96e40acfb
--- /dev/null
+++ b/doc/snippets/Tutorial_AdvancedInitialization_Block.cpp
@@ -0,0 +1,5 @@
+MatrixXf matA(2, 2);
+matA << 1, 2, 3, 4;
+MatrixXf matB(4, 4);
+matB << matA, matA/10, matA/10, matA;
+std::cout << matB << std::endl;
diff --git a/doc/snippets/Tutorial_AdvancedInitialization_CommaTemporary.cpp b/doc/snippets/Tutorial_AdvancedInitialization_CommaTemporary.cpp
new file mode 100644
index 000000000..50cff4cb6
--- /dev/null
+++ b/doc/snippets/Tutorial_AdvancedInitialization_CommaTemporary.cpp
@@ -0,0 +1,4 @@
+MatrixXf mat = MatrixXf::Random(2, 3);
+std::cout << mat << std::endl << std::endl;
+mat = (MatrixXf(2,2) << 0, 1, 1, 0).finished() * mat;
+std::cout << mat << std::endl;
diff --git a/doc/snippets/Tutorial_AdvancedInitialization_LinSpaced.cpp b/doc/snippets/Tutorial_AdvancedInitialization_LinSpaced.cpp
new file mode 100644
index 000000000..c6a73ab8c
--- /dev/null
+++ b/doc/snippets/Tutorial_AdvancedInitialization_LinSpaced.cpp
@@ -0,0 +1,7 @@
+ArrayXXf table(10, 4);
+table.col(0) = ArrayXf::LinSpaced(10, 0, 90);
+table.col(1) = M_PI / 180 * table.col(0);
+table.col(2) = table.col(1).sin();
+table.col(3) = table.col(1).cos();
+std::cout << "  Degrees   Radians      Sine    Cosine\n";
+std::cout << table << std::endl;
diff --git a/doc/snippets/Tutorial_AdvancedInitialization_ThreeWays.cpp b/doc/snippets/Tutorial_AdvancedInitialization_ThreeWays.cpp
new file mode 100644
index 000000000..cb7457652
--- /dev/null
+++ b/doc/snippets/Tutorial_AdvancedInitialization_ThreeWays.cpp
@@ -0,0 +1,20 @@
+const int size = 6;
+MatrixXd mat1(size, size);
+mat1.topLeftCorner(size/2, size/2)     = MatrixXd::Zero(size/2, size/2);
+mat1.topRightCorner(size/2, size/2)    = MatrixXd::Identity(size/2, size/2);
+mat1.bottomLeftCorner(size/2, size/2)  = MatrixXd::Identity(size/2, size/2);
+mat1.bottomRightCorner(size/2, size/2) = MatrixXd::Zero(size/2, size/2);
+std::cout << mat1 << std::endl << std::endl;
+
+MatrixXd mat2(size, size);
+mat2.topLeftCorner(size/2, size/2).setZero();
+mat2.topRightCorner(size/2, size/2).setIdentity();
+mat2.bottomLeftCorner(size/2, size/2).setIdentity();
+mat2.bottomRightCorner(size/2, size/2).setZero();
+std::cout << mat2 << std::endl << std::endl;
+
+MatrixXd mat3(size, size);
+mat3 << MatrixXd::Zero(size/2, size/2), MatrixXd::Identity(size/2, size/2),
+        MatrixXd::Identity(size/2, size/2), MatrixXd::Zero(size/2, size/2);
+std::cout << mat3 << std::endl;
+
diff --git a/doc/snippets/Tutorial_AdvancedInitialization_Zero.cpp b/doc/snippets/Tutorial_AdvancedInitialization_Zero.cpp
new file mode 100644
index 000000000..76a36a319
--- /dev/null
+++ b/doc/snippets/Tutorial_AdvancedInitialization_Zero.cpp
@@ -0,0 +1,13 @@
+std::cout << "A fixed-size array:\n";
+Array33f a1 = Array33f::Zero();
+std::cout << a1 << "\n\n";
+
+
+std::cout << "A one-dimensional dynamic-size array:\n";
+ArrayXf a2 = ArrayXf::Zero(3);
+std::cout << a2 << "\n\n";
+
+
+std::cout << "A two-dimensional dynamic-size array:\n";
+ArrayXXf a3 = ArrayXXf::Zero(3, 4);
+std::cout << a3 << "\n";
diff --git a/doc/snippets/Tutorial_commainit_01b.cpp b/doc/snippets/Tutorial_commainit_01b.cpp
new file mode 100644
index 000000000..2adb2e213
--- /dev/null
+++ b/doc/snippets/Tutorial_commainit_01b.cpp
@@ -0,0 +1,5 @@
+Matrix3f m;
+m.row(0) << 1, 2, 3;
+m.block(1,0,2,2) << 4, 5, 7, 8;
+m.col(2).tail(2) << 6, 9;		    
+std::cout << m;