1*bf2c3715SXin Linamespace Eigen { 2*bf2c3715SXin Li 3*bf2c3715SXin Li/** \page GettingStarted Getting started 4*bf2c3715SXin Li 5*bf2c3715SXin Li\eigenAutoToc 6*bf2c3715SXin Li 7*bf2c3715SXin LiThis is a very short guide on how to get started with Eigen. It has a dual purpose. It serves as a minimal introduction to the Eigen library for people who want to start coding as soon as possible. You can also read this page as the first part of the Tutorial, which explains the library in more detail; in this case you will continue with \ref TutorialMatrixClass. 8*bf2c3715SXin Li 9*bf2c3715SXin Li\section GettingStartedInstallation How to "install" Eigen? 10*bf2c3715SXin Li 11*bf2c3715SXin LiIn order to use Eigen, you just need to download and extract Eigen's source code (see <a href="http://eigen.tuxfamily.org/index.php?title=Main_Page#Download">the wiki</a> for download instructions). In fact, the header files in the \c Eigen subdirectory are the only files required to compile programs using Eigen. The header files are the same for all platforms. It is not necessary to use CMake or install anything. 12*bf2c3715SXin Li 13*bf2c3715SXin Li 14*bf2c3715SXin Li\section GettingStartedFirstProgram A simple first program 15*bf2c3715SXin Li 16*bf2c3715SXin LiHere is a rather simple program to get you started. 17*bf2c3715SXin Li 18*bf2c3715SXin Li\include QuickStart_example.cpp 19*bf2c3715SXin Li 20*bf2c3715SXin LiWe will explain the program after telling you how to compile it. 21*bf2c3715SXin Li 22*bf2c3715SXin Li 23*bf2c3715SXin Li\section GettingStartedCompiling Compiling and running your first program 24*bf2c3715SXin Li 25*bf2c3715SXin LiThere is no library to link to. The only thing that you need to keep in mind when compiling the above program is that the compiler must be able to find the Eigen header files. The directory in which you placed Eigen's source code must be in the include path. With GCC you use the -I option to achieve this, so you can compile the program with a command like this: 26*bf2c3715SXin Li 27*bf2c3715SXin Li\code g++ -I /path/to/eigen/ my_program.cpp -o my_program \endcode 28*bf2c3715SXin Li 29*bf2c3715SXin LiOn Linux or Mac OS X, another option is to symlink or copy the Eigen folder into /usr/local/include/. This way, you can compile the program with: 30*bf2c3715SXin Li 31*bf2c3715SXin Li\code g++ my_program.cpp -o my_program \endcode 32*bf2c3715SXin Li 33*bf2c3715SXin LiWhen you run the program, it produces the following output: 34*bf2c3715SXin Li 35*bf2c3715SXin Li\include QuickStart_example.out 36*bf2c3715SXin Li 37*bf2c3715SXin Li 38*bf2c3715SXin Li\section GettingStartedExplanation Explanation of the first program 39*bf2c3715SXin Li 40*bf2c3715SXin LiThe Eigen header files define many types, but for simple applications it may be enough to use only the \c MatrixXd type. This represents a matrix of arbitrary size (hence the \c X in \c MatrixXd), in which every entry is a \c double (hence the \c d in \c MatrixXd). See the \ref QuickRef_Types "quick reference guide" for an overview of the different types you can use to represent a matrix. 41*bf2c3715SXin Li 42*bf2c3715SXin LiThe \c Eigen/Dense header file defines all member functions for the MatrixXd type and related types (see also the \ref QuickRef_Headers "table of header files"). All classes and functions defined in this header file (and other Eigen header files) are in the \c Eigen namespace. 43*bf2c3715SXin Li 44*bf2c3715SXin LiThe first line of the \c main function declares a variable of type \c MatrixXd and specifies that it is a matrix with 2 rows and 2 columns (the entries are not initialized). The statement <tt>m(0,0) = 3</tt> sets the entry in the top-left corner to 3. You need to use round parentheses to refer to entries in the matrix. As usual in computer science, the index of the first index is 0, as opposed to the convention in mathematics that the first index is 1. 45*bf2c3715SXin Li 46*bf2c3715SXin LiThe following three statements sets the other three entries. The final line outputs the matrix \c m to the standard output stream. 47*bf2c3715SXin Li 48*bf2c3715SXin Li 49*bf2c3715SXin Li\section GettingStartedExample2 Example 2: Matrices and vectors 50*bf2c3715SXin Li 51*bf2c3715SXin LiHere is another example, which combines matrices with vectors. Concentrate on the left-hand program for now; we will talk about the right-hand program later. 52*bf2c3715SXin Li 53*bf2c3715SXin Li<table class="manual"> 54*bf2c3715SXin Li<tr><th>Size set at run time:</th><th>Size set at compile time:</th></tr> 55*bf2c3715SXin Li<tr><td> 56*bf2c3715SXin Li\include QuickStart_example2_dynamic.cpp 57*bf2c3715SXin Li</td> 58*bf2c3715SXin Li<td> 59*bf2c3715SXin Li\include QuickStart_example2_fixed.cpp 60*bf2c3715SXin Li</td></tr></table> 61*bf2c3715SXin Li 62*bf2c3715SXin LiThe output is as follows: 63*bf2c3715SXin Li 64*bf2c3715SXin Li\include QuickStart_example2_dynamic.out 65*bf2c3715SXin Li 66*bf2c3715SXin Li 67*bf2c3715SXin Li\section GettingStartedExplanation2 Explanation of the second example 68*bf2c3715SXin Li 69*bf2c3715SXin LiThe second example starts by declaring a 3-by-3 matrix \c m which is initialized using the \link DenseBase::Random(Index,Index) Random() \endlink method with random values between -1 and 1. The next line applies a linear mapping such that the values are between 10 and 110. The function call \link DenseBase::Constant(Index,Index,const Scalar&) MatrixXd::Constant\endlink(3,3,1.2) returns a 3-by-3 matrix expression having all coefficients equal to 1.2. The rest is standard arithmetic. 70*bf2c3715SXin Li 71*bf2c3715SXin LiThe next line of the \c main function introduces a new type: \c VectorXd. This represents a (column) vector of arbitrary size. Here, the vector \c v is created to contain \c 3 coefficients which are left uninitialized. The one but last line uses the so-called comma-initializer, explained in \ref TutorialAdvancedInitialization, to set all coefficients of the vector \c v to be as follows: 72*bf2c3715SXin Li 73*bf2c3715SXin Li\f[ 74*bf2c3715SXin Liv = 75*bf2c3715SXin Li\begin{bmatrix} 76*bf2c3715SXin Li 1 \\ 77*bf2c3715SXin Li 2 \\ 78*bf2c3715SXin Li 3 79*bf2c3715SXin Li\end{bmatrix}. 80*bf2c3715SXin Li\f] 81*bf2c3715SXin Li 82*bf2c3715SXin LiThe final line of the program multiplies the matrix \c m with the vector \c v and outputs the result. 83*bf2c3715SXin Li 84*bf2c3715SXin LiNow look back at the second example program. We presented two versions of it. In the version in the left column, the matrix is of type \c MatrixXd which represents matrices of arbitrary size. The version in the right column is similar, except that the matrix is of type \c Matrix3d, which represents matrices of a fixed size (here 3-by-3). Because the type already encodes the size of the matrix, it is not necessary to specify the size in the constructor; compare <tt>MatrixXd m(3,3)</tt> with <tt>Matrix3d m</tt>. Similarly, we have \c VectorXd on the left (arbitrary size) versus \c Vector3d on the right (fixed size). Note that here the coefficients of vector \c v are directly set in the constructor, though the same syntax of the left example could be used too. 85*bf2c3715SXin Li 86*bf2c3715SXin LiThe use of fixed-size matrices and vectors has two advantages. The compiler emits better (faster) code because it knows the size of the matrices and vectors. Specifying the size in the type also allows for more rigorous checking at compile-time. For instance, the compiler will complain if you try to multiply a \c Matrix4d (a 4-by-4 matrix) with a \c Vector3d (a vector of size 3). However, the use of many types increases compilation time and the size of the executable. The size of the matrix may also not be known at compile-time. A rule of thumb is to use fixed-size matrices for size 4-by-4 and smaller. 87*bf2c3715SXin Li 88*bf2c3715SXin Li 89*bf2c3715SXin Li\section GettingStartedConclusion Where to go from here? 90*bf2c3715SXin Li 91*bf2c3715SXin LiIt's worth taking the time to read the \ref TutorialMatrixClass "long tutorial". 92*bf2c3715SXin Li 93*bf2c3715SXin LiHowever if you think you don't need it, you can directly use the classes documentation and our \ref QuickRefPage. 94*bf2c3715SXin Li 95*bf2c3715SXin Li\li \b Next: \ref TutorialMatrixClass 96*bf2c3715SXin Li 97*bf2c3715SXin Li*/ 98*bf2c3715SXin Li 99*bf2c3715SXin Li} 100*bf2c3715SXin Li 101