1*bf2c3715SXin Linamespace Eigen { 2*bf2c3715SXin Li 3*bf2c3715SXin Li/** \page TopicMultiThreading Eigen and multi-threading 4*bf2c3715SXin Li 5*bf2c3715SXin Li\section TopicMultiThreading_MakingEigenMT Make Eigen run in parallel 6*bf2c3715SXin Li 7*bf2c3715SXin LiSome %Eigen's algorithms can exploit the multiple cores present in your hardware. 8*bf2c3715SXin LiTo this end, it is enough to enable OpenMP on your compiler, for instance: 9*bf2c3715SXin Li - GCC: \c -fopenmp 10*bf2c3715SXin Li - ICC: \c -openmp 11*bf2c3715SXin Li - MSVC: check the respective option in the build properties. 12*bf2c3715SXin Li 13*bf2c3715SXin LiYou can control the number of threads that will be used using either the OpenMP API or %Eigen's API using the following priority: 14*bf2c3715SXin Li\code 15*bf2c3715SXin Li OMP_NUM_THREADS=n ./my_program 16*bf2c3715SXin Li omp_set_num_threads(n); 17*bf2c3715SXin Li Eigen::setNbThreads(n); 18*bf2c3715SXin Li\endcode 19*bf2c3715SXin LiUnless `setNbThreads` has been called, %Eigen uses the number of threads specified by OpenMP. 20*bf2c3715SXin LiYou can restore this behavior by calling `setNbThreads(0);`. 21*bf2c3715SXin LiYou can query the number of threads that will be used with: 22*bf2c3715SXin Li\code 23*bf2c3715SXin Lin = Eigen::nbThreads( ); 24*bf2c3715SXin Li\endcode 25*bf2c3715SXin LiYou can disable %Eigen's multi threading at compile time by defining the \link TopicPreprocessorDirectivesPerformance EIGEN_DONT_PARALLELIZE \endlink preprocessor token. 26*bf2c3715SXin Li 27*bf2c3715SXin LiCurrently, the following algorithms can make use of multi-threading: 28*bf2c3715SXin Li - general dense matrix - matrix products 29*bf2c3715SXin Li - PartialPivLU 30*bf2c3715SXin Li - row-major-sparse * dense vector/matrix products 31*bf2c3715SXin Li - ConjugateGradient with \c Lower|Upper as the \c UpLo template parameter. 32*bf2c3715SXin Li - BiCGSTAB with a row-major sparse matrix format. 33*bf2c3715SXin Li - LeastSquaresConjugateGradient 34*bf2c3715SXin Li 35*bf2c3715SXin Li\warning On most OS it is <strong>very important</strong> to limit the number of threads to the number of physical cores, otherwise significant slowdowns are expected, especially for operations involving dense matrices. 36*bf2c3715SXin Li 37*bf2c3715SXin LiIndeed, the principle of hyper-threading is to run multiple threads (in most cases 2) on a single core in an interleaved manner. 38*bf2c3715SXin LiHowever, %Eigen's matrix-matrix product kernel is fully optimized and already exploits nearly 100% of the CPU capacity. 39*bf2c3715SXin LiConsequently, there is no room for running multiple such threads on a single core, and the performance would drops significantly because of cache pollution and other sources of overheads. 40*bf2c3715SXin LiAt this stage of reading you're probably wondering why %Eigen does not limit itself to the number of physical cores? 41*bf2c3715SXin LiThis is simply because OpenMP does not allow to know the number of physical cores, and thus %Eigen will launch as many threads as <i>cores</i> reported by OpenMP. 42*bf2c3715SXin Li 43*bf2c3715SXin Li\section TopicMultiThreading_UsingEigenWithMT Using Eigen in a multi-threaded application 44*bf2c3715SXin Li 45*bf2c3715SXin LiIn the case your own application is multithreaded, and multiple threads make calls to %Eigen, then you have to initialize %Eigen by calling the following routine \b before creating the threads: 46*bf2c3715SXin Li\code 47*bf2c3715SXin Li#include <Eigen/Core> 48*bf2c3715SXin Li 49*bf2c3715SXin Liint main(int argc, char** argv) 50*bf2c3715SXin Li{ 51*bf2c3715SXin Li Eigen::initParallel(); 52*bf2c3715SXin Li 53*bf2c3715SXin Li ... 54*bf2c3715SXin Li} 55*bf2c3715SXin Li\endcode 56*bf2c3715SXin Li 57*bf2c3715SXin Li\note With %Eigen 3.3, and a fully C++11 compliant compiler (i.e., <a href="http://en.cppreference.com/w/cpp/language/storage_duration#Static_local_variables">thread-safe static local variable initialization</a>), then calling \c initParallel() is optional. 58*bf2c3715SXin Li 59*bf2c3715SXin Li\warning Note that all functions generating random matrices are \b not re-entrant nor thread-safe. Those include DenseBase::Random(), and DenseBase::setRandom() despite a call to `Eigen::initParallel()`. This is because these functions are based on `std::rand` which is not re-entrant. 60*bf2c3715SXin LiFor thread-safe random generator, we recommend the use of c++11 random generators (\link DenseBase::NullaryExpr(Index, const CustomNullaryOp&) example \endlink) or `boost::random`. 61*bf2c3715SXin Li 62*bf2c3715SXin LiIn the case your application is parallelized with OpenMP, you might want to disable %Eigen's own parallelization as detailed in the previous section. 63*bf2c3715SXin Li 64*bf2c3715SXin Li\warning Using OpenMP with custom scalar types that might throw exceptions can lead to unexpected behaviour in the event of throwing. 65*bf2c3715SXin Li*/ 66*bf2c3715SXin Li 67*bf2c3715SXin Li} 68