path: root/doc/QuickStartGuide.dox

namespace Eigen {

/** \page QuickStartGuide
<a name="top"></a>

<h1>Quick start guide</h1>

\b Table \b of \b contents
 - \ref SimpleExampleFixedSize
 - \ref SimpleExampleDynamicSize
 - \ref MatrixTypes
 - \ref MatrixInitialization
 - \ref BasicLinearAlgebra
 - \ref Reductions
 - \ref SubMatrix
 - \ref MatrixTransformations
 - \ref Geometry
 - \ref Performance
 - \ref AdvancedLinearAlgebra
   - \ref LinearSolvers
   - \ref LU
   - \ref Cholesky
   - \ref QR
   - \ref EigenProblems

</br>
<hr>


\section SimpleExampleFixedSize Simple example with fixed-size matrices and vectors

By fixed-size, we mean that the number of rows and columns are known at compile-time. In this case, Eigen avoids dynamic memory allocation and unroll loops. This is useful for very small sizes (typically up to 4x4).

<table><tr><td>
\include Tutorial_simple_example_fixed_size.cpp
</td>
<td>
output:
\include Tutorial_simple_example_fixed_size.out
</td></tr></table>

<a href="#" class="top">top</a>\section SimpleExampleDynamicSize Simple example with dynamic-size matrices and vectors

Dynamic-size means that the number of rows and columns are not known at compile-time. In this case, they are stored as runtime variables and the arrays are dynamically allocated.

<table><tr><td>
\include Tutorial_simple_example_dynamic_size.cpp
</td>
<td>
output:
\include Tutorial_simple_example_dynamic_size.out
</td></tr></table>






<a href="#" class="top">top</a>\section MatrixTypes Matrix and vector types

In Eigen, all kinds of dense matrices and vectors are represented by the template class Matrix. In most cases you can simply use one of the several convenient typedefs (\ref matrixtypedefs).

The template class Matrix takes a number of template parameters, but for now it is enough to understand the 3 first ones (and the others can then be left unspecified):

\code Matrix<Scalar, RowsAtCompileTime, ColsAtCompileTime> \endcode

\li \c Scalar is the scalar type, i.e. the type of the coefficients. That is, if you want a vector of floats, choose \c float here.
\li \c RowsAtCompileTime and \c ColsAtCompileTime are the number of rows and columns of the matrix as known at compile-time. 

For example, \c Vector3d is a typedef for \code Matrix<double, 3, 1> \endcode

What if the matrix has dynamic-size i.e. the number of rows or cols isn't known at compile-time? Then use the special value Eigen::Dynamic. For example, \c VectorXd is a typedef for \code Matrix<double, Dynamic, 1> \endcode





<a href="#" class="top">top</a>\section MatrixInitialization Matrix and vector creation and initialization

To get a matrix with all coefficients equals to a given value you can use the Matrix::Constant() function, e.g.:
<table><tr><td>
\code
int rows=2, cols=3;
cout << MatrixXf::Constant(rows, cols, sqrt(2));
\endcode
</td>
<td>
output:
\code
1.41 1.41 1.41
1.41 1.41 1.41
\endcode
</td></tr></table>

To set all the coefficients of a matrix you can also use the setConstant() variant:
\code
MatrixXf m(rows, cols);
m.setConstant(rows, cols, value);
\endcode

Eigen also offers variants of these functions for vector types and fixed-size matrices or vectors, as well as similar functions to create matrices with all coefficients equal to zero or one, to create the identity matrix and matrices with random coefficients:

<table>
<tr>
  <td>Fixed-size matrix or vector</td>
  <td>Dynamic-size matrix</td>
  <td>Dynamic-size vector</td>
</tr>
<tr>
  <td>
\code
Matrix3f x;

x = Matrix3f::Zero();
x = Matrix3f::Ones();
x = Matrix3f::Constant(6);
x = Matrix3f::Identity();
x = Matrix3f::Random();

x.setZero();
x.setOnes();
x.setIdentity();
x.setConstant(6);
x.setRandom();
\endcode
  </td>
  <td>
\code
MatrixXf x;

x = MatrixXf::Zero(rows, cols);
x = MatrixXf::Ones(rows, cols);
x = MatrixXf::Constant(rows, cols, 6);
x = MatrixXf::Identity(rows, cols);
x = MatrixXf::Random(rows, cols);

x.setZero(rows, cols);
x.setOnes(rows, cols);
x.setConstant(rows, cols, 6);
x.setIdentity(rows, cols);
x.setRandom(rows, cols);
\endcode
  </td>
  <td>
\code
VectorXf x;

x = VectorXf::Zero(size);
x = VectorXf::Ones(size);
x = VectorXf::Constant(size, 6);
x = VectorXf::Identity(size);
x = VectorXf::Random(size);

x.setZero(size);
x.setOnes(size);
x.setConstant(size, 6);
x.setIdentity(size);
x.setRandom(size);
\endcode
  </td>
</tr>
</table>

Finally, all the coefficients of a matrix can be set to specific values using the comma initializer syntax:
<table><tr><td>
\include Tutorial_commainit_01.cpp
</td>
<td>
output:
\verbinclude Tutorial_commainit_01.out
</td></tr></table>

Eigen's comma initializer also allows you to set the matrix per block:
<table><tr><td>
\include Tutorial_commainit_02.cpp
</td>
<td>
output:
\verbinclude Tutorial_commainit_02.out
</td></tr></table>

Here .finished() is used to get the actual matrix object once the comma initialization
of our temporary submatrix is done. Note that despite the appearant complexity of such an expression
Eigen's comma initializer usually yields to very optimized code without any overhead.






<a href="#" class="top">top</a>\section BasicLinearAlgebra Basic Linear Algebra

In short all mathematically well defined operators can be used right away as in the following example:
\code
mat4 -= mat1*1.5 + mat2 * mat3/4;
\endcode
which includes two matrix scalar products ("mat1*1.5" and "mat3/4"), a matrix-matrix product ("mat2 * mat3/4"),
a matrix addition ("+") and substraction with assignment ("-=").

<table>
<tr><td>
matrix/vector product</td><td>\code
col2 = mat1 * col1;
row2 = row1 * mat1;     row1 *= mat1;
mat3 = mat1 * mat2;     mat3 *= mat1; \endcode
</td></tr>
<tr><td>
add/subtract</td><td>\code
mat3 = mat1 + mat2;      mat3 += mat1;
mat3 = mat1 - mat2;      mat3 -= mat1;\endcode
</td></tr>
<tr><td>
scalar product</td><td>\code
mat3 = mat1 * s1;   mat3 = s1 * mat1;   mat3 *= s1;
mat3 = mat1 / s1;   mat3 /= s1;\endcode
</td></tr>
<tr><td>
\link MatrixBase::dot() dot product \endlink (inner product)</td><td>\code
scalar = vec1.dot(vec2);\endcode
</td></tr>
<tr><td>
outer product</td><td>\code
mat = vec1 * vec2.transpose();\endcode
</td></tr>
<tr><td>
\link MatrixBase::cross() cross product \endcode</td><td>\code
#include <Eigen/Geometry>
vec3 = vec1.cross(vec2);\endcode</td></tr>
</table>


In Eigen only mathematically well defined operators can be used right away,
but don't worry, thanks to the \link Cwise .cwise() \endlink operator prefix,
Eigen's matrices also provide a very powerful numerical container supporting
most common coefficient wise operators:

<table>

<tr><td>Coefficient wise product</td>
<td>\code mat3 = mat1.cwise() * mat2; \endcode
</td></tr>
<tr><td>
Add a scalar to all coefficients</td><td>\code
mat3 = mat1.cwise() + scalar;
mat3.cwise() += scalar;
mat3.cwise() -= scalar;
\endcode
</td></tr>
<tr><td>
Coefficient wise division</td><td>\code
mat3 = mat1.cwise() / mat2; \endcode
</td></tr>
<tr><td>
Coefficient wise reciprocal</td><td>\code
mat3 = mat1.cwise().inverse(); \endcode
</td></tr>
<tr><td>
Coefficient wise comparisons \n
(support all operators)</td><td>\code
mat3 = mat1.cwise() < mat2;
mat3 = mat1.cwise() <= mat2;
mat3 = mat1.cwise() > mat2;
etc.
\endcode
</td></tr>
<tr><td>
Trigo:\n sin, cos, tan</td><td>\code
mat3 = mat1.cwise().sin();
etc.
\endcode
</td></tr>
<tr><td>
Power:\n pow, square, cube, sqrt, exp, log</td><td>\code
mat3 = mat1.cwise().square();
mat3 = mat1.cwise().pow(5);
mat3 = mat1.cwise().log();
etc.
\endcode
</td></tr>
<tr><td>
min, max, absolute value</td><td>\code
mat3 = mat1.cwise().min(mat2);
mat3 = mat1.cwise().max(mat2);
mat3 = mat1.cwise().abs(mat2);
mat3 = mat1.cwise().abs2(mat2);
\endcode</td></tr>
</table>






<a href="#" class="top">top</a>\section Reductions Reductions

Reductions can be done matrix-wise,
\link MatrixBase::colwise() column-wise \endlink or
\link MatrixBase::rowwise() row-wise \endlink, e.g.:
<table>
<tr><td>\code mat \endcode
</td><td>\code
5 3 1
2 7 8
9 4 6
\endcode
</td></tr>

<tr><td>\code mat.minCoeff(); \endcode</td><td>\code 1 \endcode</td><td></td>
    <td>\code mat.maxCoeff(); \endcode</td><td>\code 9 \endcode</td></tr>
<tr><td>\code mat.colwise().minCoeff(); \endcode</td><td>\code 2 3 1 \endcode</td><td></td>
    <td>\code mat.colwise().maxCoeff(); \endcode</td><td>\code 9 7 8 \endcode</td></tr>
<tr><td>\code mat.rowwise().minCoeff(); \endcode</td><td>\code
1
2
4
\endcode</td><td></td>
   <td>\code mat.rowwise().maxCoeff(); \endcode</td><td>\code
5
8
9
\endcode</td></tr>
</table>

Eigen provides several other reduction methods such as \link Cwise::sum() sum() \endlink,
\link Cwise::norm() norm() \endlink, \link Cwise::norm2() norm2() \endlink,
\link Cwise::all() all() \endlink, and \link Cwise::any() any() \endlink.
The all() and any() functions are especially useful in combinaison with coeff-wise comparison operators.





<a href="#" class="top">top</a>\section SubMatrix Sub matrices

Read-write access to a \link MatrixBase::col(int) column \endlink
or a \link MatrixBase::row(int) row \endlink of a matrix:
\code
mat1.row(i) = mat2.col(j);
mat1.col(j1).swap(mat1.col(j2));
\endcode

Read-write access to sub-vector:
<table>
<tr>
<td>Default versions</td>
<td>Optimized versions when the size is known at compile time</td></tr>
<td></td>

<tr><td>\code vec1.start(n)\endcode</td><td>\code vec1.start<n>()\endcode</td><td>the first \c n coeffs </td></tr>
<tr><td>\code vec1.end(n)\endcode</td><td>\code vec1.end<n>()\endcode</td><td>the last \c n coeffs </td></tr>
<tr><td>\code vec1.block(pos,n)\endcode</td><td>\code vec1.block<n>(pos)\endcode</td>
    <td>the \c size coeffs in the range [\c pos : \c pos + \c n [</td></tr>
</table>

Read-write access to sub-matrices:
<table>
<tr><td>Default versions</td>
<td>Optimized versions when the size is known at compile time</td><td></td></tr>

<tr>
  <td>\code mat1.block(i,j,rows,cols)\endcode
      \link MatrixBase::block(int,int,int,int) (more) \endlink</td>
  <td>\code mat1.block<rows,cols>(i,j)\endcode
      \link MatrixBase::block(int,int) (more) \endlink</td>
  <td>the \c rows x \c cols sub-matrix starting from position (\c i,\c j) </td>
</tr>
<tr>
 <td>\code
 mat1.corner(TopLeft,rows,cols)
 mat1.corner(TopRight,rows,cols)
 mat1.corner(BottomLeft,rows,cols)
 mat1.corner(BottomRight,rows,cols)\endcode
 \link MatrixBase::corner(CornerType,int,int) (more) \endlink</td>
 <td>\code
 mat1.corner<rows,cols>(TopLeft)
 mat1.corner<rows,cols>(TopRight)
 mat1.corner<rows,cols>(BottomLeft)
 mat1.corner<rows,cols>(BottomRight)\endcode
 \link MatrixBase::corner(CornerType) (more) \endlink</td>
 <td>the \c rows x \c cols sub-matrix \n taken in one of the four corners</td></tr>
</table>





<a href="#" class="top">top</a>\section MatrixTransformations Matrix transformations

transpose, adjoint, etc...





<a href="#" class="top">top</a>\section Geometry Geometry features

maybe a second tutorial for that





<a href="#" class="top">top</a>\section Performance Notes on performances


<a href="#" class="top">top</a>\section AdvancedLinearAlgebra Advanced Linear Algebra

\subsection LinearSolvers Solving linear problems
\subsection LU LU
\subsection Cholesky Cholesky
\subsection QR QR
\subsection EigenProblems Eigen value problems

*/

}