From ba100998bfab8fcf325451be050cabb52f641f46 Mon Sep 17 00:00:00 2001
From: Gael Guennebaud <g.gael@free.fr>
Date: Sun, 24 Aug 2008 15:15:32 +0000
Subject: * split Meta.h to Meta.h (generic meta programming) and XprHelper.h
 (relates to eigen mechanism) * added a meta.cpp unit test *
 EIGEN_TUNE_FOR_L2_CACHE_SIZE now represents L2 block size in Bytes (whence
 the ei_meta_sqrt...) * added a CustomizeEigen.dox page * added a TOC to
 QuickStartGuide.dox

---
 doc/CustomizingEigen.dox | 77 ++++++++++++++++++++++++++++++++++++++++++++++++
 doc/QuickStartGuide.dox  | 55 +++++++++++++++++++++++-----------
 2 files changed, 114 insertions(+), 18 deletions(-)
 create mode 100644 doc/CustomizingEigen.dox

(limited to 'doc')

diff --git a/doc/CustomizingEigen.dox b/doc/CustomizingEigen.dox
new file mode 100644
index 000000000..74108c999
--- /dev/null
+++ b/doc/CustomizingEigen.dox
@@ -0,0 +1,77 @@
+namespace Eigen {
+
+/** \page CustomizingEigen
+
+<h1>Customizing Eigen</h1>
+
+Eigen2 can be extended in several way, for instance, by defining global methods, \link ExtendingMatrixBase by adding custom methods to MatrixBase \endlink, etc.
+
+\section ExtendingMatrixBase Extending MatrixBase
+
+In this section we will see how to add custom methods to MatrixBase. Since all expressions and matrix types inherit MatrixBase, adding a method to MatrixBase make it immediately available to all expressions ! A typical use case is, for instance, to make Eigen compatible with another API.
+
+You certainly know that in C++ it is not possible to add methods to an extending class. So how that's possible ? Here the trick is to include in the declaration of MatrixBase a file defined by the preprocessor token \c EIGEN_MATRIXBASE_PLUGIN:
+\code
+class MatrixBase {
+  // ...
+  #ifdef EIGEN_MATRIXBASE_PLUGIN
+  #include EIGEN_MATRIXBASE_PLUGIN
+  #endif
+};
+\endcode
+Therefore to extend MatrixBase with you own methods you just have to create a file with your method declaration and define EIGEN_MATRIXBASE_PLUGIN before you include any Eigen's header file.
+
+Here is an example of such an extension file: \n
+\b MatrixBaseAddons.h
+\code
+inline Scalar at(uint i, uint j) const { return this->operator()(i,j); }
+inline Scalar& at(uint i, uint j) { return this->operator()(i,j); }
+inline Scalar at(uint i) const { return this->operator[](i); }
+inline Scalar& at(uint i) { return this->operator[](i); }
+
+inline RealScalar squaredLength() const { return norm2(); }
+inline RealScalar length() const { return norm(); }
+inline RealScalar invLength(void) const { return fast_inv_sqrt(norm2()); }
+
+template<typename OtherDerived>
+inline Scalar squaredDistanceTo(const MatrixBase<OtherDerived>& other) const
+{ return (derived() - other.derived()).norm2(); }
+
+template<typename OtherDerived>
+inline RealScalar distanceTo(const MatrixBase<OtherDerived>& other) const
+{ return ei_sqrt(derived().squaredDistanceTo(other)); }
+
+inline void scaleTo(RealScalar l) { RealScalar vl = norm(); if (vl>1e-9) derived() *= (l/vl); }
+
+inline Transpose<Derived> transposed() {return transpose();}
+inline const Transpose<Derived> transposed() const {return transpose();}
+
+inline uint minComponentId(void) const  { int i; minCoeff(&i); return i; }
+inline uint maxComponentId(void) const  { int i; maxCoeff(&i); return i; }
+
+template<typename OtherDerived>
+void makeFloor(const MatrixBase<OtherDerived>& other) { derived() = derived().cwise().min(other.derived()); }
+template<typename OtherDerived>
+void makeCeil(const MatrixBase<OtherDerived>& other) { derived() = derived().cwise().max(other.derived()); }
+
+const typename Cwise<Derived>::ScalarAddReturnType
+operator+(const Scalar& scalar) const { return cwise() + scalar }
+
+friend const typename Cwise<Derived>::ScalarAddReturnType
+operator+(const Scalar& scalar, const MatrixBase<Derived>& mat) { return mat + scalar; }
+\endcode
+
+Then one can the following declaration in the config.h or whatever prerequisites header file of his project:
+\code
+#define EIGEN_MATRIXBASE_PLUGIN "MatrixBaseAddons.h"
+\endcode
+
+\section PreprocessorDirectives Preprocessor directives
+
+ - \b EIGEN_DONT_VECTORIZE disables explicit vectorization when defined.
+ - \b EIGEN_UNROLLING_LIMIT defines the maximal instruction counts to enable meta unrolling of loops. Set it to zero to disable unrolling. The default is 100.
+ - \b EIGEN_TUNE_FOR_L2_CACHE_SIZE represents the maximal size in Bytes of L2 blocks. Since several blocks have to stay concurently in L2 cache, this value should correspond to at most 1/4 of the size of L2 cache.
+
+*/
+
+}
diff --git a/doc/QuickStartGuide.dox b/doc/QuickStartGuide.dox
index 86405a705..aa505b91d 100644
--- a/doc/QuickStartGuide.dox
+++ b/doc/QuickStartGuide.dox
@@ -4,7 +4,25 @@ namespace Eigen {
 
 <h1>Quick start guide</h1>
 
-<h2>Simple example with fixed-size matrices and vectors</h2>
+\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
+
+\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).
 
@@ -16,7 +34,7 @@ output:
 \include Tutorial_simple_example_fixed_size.out
 </td></tr></table>
 
-<h2>Simple example with dynamic-size matrices and vectors</h2>
+\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.
 
@@ -28,7 +46,7 @@ output:
 \include Tutorial_simple_example_dynamic_size.out
 </td></tr></table>
 
-<h2>Matrix and vector types</h2>
+\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).
 
@@ -39,11 +57,11 @@ The template class Matrix takes a number of template parameters, but for now it
 \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.
+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.
+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
 
-<h2>Matrix and vector creation and initialization</h2>
+\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>
@@ -151,7 +169,7 @@ Here .finished() is used to get the actual matrix object once the comma initiali
 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.
 
-<h2>Basic Linear Algebra</h2>
+\section BasicLinearAlgebra Basic Linear Algebra
 
 In short all mathematically well defined operators can be used right away as in the following example:
 \code
@@ -249,7 +267,7 @@ mat3 = mat1.cwise().abs2(mat2);
 \endcode</td></tr>
 </table>
 
-<h2>Reductions</h2>
+\section Reductions Reductions
 
 Reductions can be done matrix-wise,
 \link MatrixBase::colwise() column-wise \endlink or
@@ -285,7 +303,7 @@ The all() and any() functions are especially useful in combinaison with coeff-wi
 
 
 
-<h2>Sub matrices</h2>
+\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:
@@ -336,24 +354,25 @@ Read-write access to sub-matrices:
 </table>
 
 
-<h2>Transformations</h2>
+\section MatrixTransformations Matrix transformations
 
 transpose, adjoint, etc...
 
 
-<h2>Geometry features</h2>
+\section Geometry Geometry features
 
+maybe a second tutorial for that
 
-<h2>Notes on performances</h2>
+\section Performance Notes on performances
 
 
-<h2>Advanced Linear Algebra</h2>
+\section AdvancedLinearAlgebra Advanced Linear Algebra
 
-<h3>Solving linear problems</h3>
-<h3>LU</h3>
-<h3>Cholesky</h3>
-<h3>QR</h3>
-<h3>Eigen value problems</h3>
+\subsection LinearSolvers Solving linear problems
+\subsection LU LU
+\subsection Cholesky Cholesky
+\subsection QR QR
+\subsection EigenProblems Eigen value problems
 
 */
 
-- 
cgit v1.2.3