Turn MKL off by default. Add section on performance to INSTALL.md

CMakeLists.txt

@@ -61,8 +61,8 @@ option(GTSAM_POSE3_EXPMAP 			 	 "Enable/Disable using Pose3::EXPMAP as the defau
 option(GTSAM_ROT3_EXPMAP 			 	 "Ignore if GTSAM_USE_QUATERNIONS is OFF (Rot3::EXPMAP by default). Otherwise, enable Rot3::EXPMAP, or if disabled, use Rot3::CAYLEY." OFF)
 option(GTSAM_ENABLE_CONSISTENCY_CHECKS   "Enable/Disable expensive consistency checks"       OFF)
 option(GTSAM_WITH_TBB                    "Use Intel Threaded Building Blocks (TBB) if available" ON)
-option(GTSAM_WITH_EIGEN_MKL              "Eigen will use Intel MKL if available" ON)
+option(GTSAM_WITH_EIGEN_MKL              "Eigen will use Intel MKL if available" OFF)
-option(GTSAM_WITH_EIGEN_MKL_OPENMP       "Eigen, when using Intel MKL, will also use OpenMP for multithreading if available" ON)
+option(GTSAM_WITH_EIGEN_MKL_OPENMP       "Eigen, when using Intel MKL, will also use OpenMP for multithreading if available" OFF)
 option(GTSAM_THROW_CHEIRALITY_EXCEPTION "Throw exception when a triangulated point is behind a camera" ON)
 option(GTSAM_BUILD_PYTHON                "Enable/Disable building & installation of Python module" OFF)
 option(GTSAM_ALLOW_DEPRECATED_SINCE_V4   "Allow use of methods/functions deprecated in GTSAM 4" ON)
@@ -563,12 +563,6 @@ message(STATUS "==============================================================="
 if(GTSAM_WITH_TBB AND NOT TBB_FOUND)
 	message(WARNING "TBB was not found - this is ok, but note that GTSAM parallelization will be disabled.  Set GTSAM_WITH_TBB to 'Off' to avoid this warning.")
 endif()
-if(GTSAM_WITH_EIGEN_MKL AND NOT MKL_FOUND)
-	message(WARNING "MKL was not found - this is ok, but note that MKL yields better performance.  Set GTSAM_WITH_EIGEN_MKL to 'Off' to disable this warning.")
-endif()
-if(GTSAM_WITH_EIGEN_MKL_OPENMP AND NOT OPENMP_FOUND AND MKL_FOUND)
-	message(WARNING "Your compiler does not support OpenMP - this is ok, but performance may be improved with OpenMP.  Set GTSAM_WITH_EIGEN_MKL_OPENMP to 'Off' to avoid this warning.")
-endif()
 if(GTSAM_BUILD_PYTHON AND GTSAM_PYTHON_WARNINGS)
 	message(WARNING "${GTSAM_PYTHON_WARNINGS}")
 endif()

INSTALL.md

@@ -23,18 +23,22 @@ $ make install
        disable the CMake flag GTSAM_WITH_TBB (enabled by default).  On Ubuntu, TBB
        may be installed from the Ubuntu repositories, and for other platforms it
        may be downloaded from https://www.threadingbuildingblocks.org/
+     - GTSAM may be configured to use MKL by toggling `GTSAM_WITH_EIGEN_MKL` and
+       `GTSAM_WITH_EIGEN_MKL_OPENMP` to `ON`; however, best performance is usually
+       achieved with MKL disabled. We therefore advise you to benchmark your problem 
+       before using MKL.
 
     Tested compilers:
 
-    - GCC 4.2-4.7
+    - GCC 4.2-7.3
-    - OSX Clang 2.9-5.0
+    - OS X Clang 2.9-10.0
-    - OSX GCC 4.2
+    - OS X GCC 4.2
-    - MSVC 2010, 2012
+    - MSVC 2010, 2012, 2017
 
     Tested systems:
 
-    - Ubuntu 11.04 - 18.04
+    - Ubuntu 16.04 - 18.04
-    - MacOS 10.6 - 10.9
+    - MacOS 10.6 - 10.14
     - Windows 7, 8, 8.1, 10
 
     Known issues:
@@ -134,6 +138,27 @@ MEX_COMMAND: Path to the mex compiler. Defaults to assume the path is included i
 
 $MATLABROOT can be found by executing the command `matlabroot` in MATLAB
 
+## Performance
+
+Here are some tips to get the best possible performance out of GTSAM.
+
+1. Build in `Release` mode. GTSAM will run up to 10x faster compared to `Debug` mode.
+2. Enable TBB. On modern processors with multiple cores, this can easily speed up
+    optimization by 30-50%. Please note that this may not be true for very small 
+    problems where the overhead of dispatching work to multiple threads outweighs
+    the benefit. We recommend that you benchmark your problem with/without TBB.
+3. Add `-march=native` to `GTSAM_CMAKE_CXX_FLAGS`. A performance gain of
+    25-30% can be expected on modern processors. Note that this affects the portability
+    of your executable. It may not run when copied to another system with older/different
+    processor architecture.
+    Also note that all dependent projects *must* be compiled with the same flag, or
+    seg-faults and other undefined behavior may result.
+4. Enable MKL. Please note that our benchmarks have shown that this helps only
+    in very limited cases, and actually hurts performance in the usual case. We therefore
+    recommend that you do *not* enable MKL, unless you have benchmarked it on
+    your problem and have verified that it improves performance.
+
+
 ## Debugging tips
 
 Another useful debugging symbol is _GLIBCXX_DEBUG, which enables debug checks and safe containers in the standard C++ library and makes problems much easier to find.