Merge pull request #67 from wolfv/docs_blas

Add docs for linking LAPACK and BLAS

docs/source/index.rst

@@ -34,6 +34,7 @@ This software is licensed under the BSD-3-Clause license. See the LICENSE file f
    :maxdepth: 2
 
    installation
+   performance
 
 .. toctree::
    :caption: USAGE

docs/source/installation.rst

@@ -25,6 +25,9 @@ Although ``xtensor-blas`` is a header-only library, we provide standardized mean
 
 Besides the xtendor headers, all these methods place the `cmake` project configuration file in the right location so that third-party projects can use cmake's find_package to locate xtensor headers.
 
+.. seealso:: Read the :ref:`Performance and Linking <perf-and-link>` chapter on how to link against BLAS and improve performance
+
+
 .. image:: conda.svg
 
 Using the conda package

docs/source/performance.rst

@@ -0,0 +1,48 @@
+.. Copyright (c) 2017, Wolf Vollprecht, Johan Mabille and Sylvain Corlay
+
+   Distributed under the terms of the BSD 3-Clause License.
+
+   The full license is in the file LICENSE, distributed with this software.
+
+.. _perf-and-link:
+
+Performance and Linking
+=======================
+
+For optimal performance, the target program **has** to be linked against
+a `BLAS <https://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms>`_
+implementation. The BLAS implementation that we install by default
+with conda is ``OpenBLAS``, but other options, such as ``MKL`` are available
+on conda, too. If xtensor-blas was not installed from conda, the user has
+to manually verify that a BLAS and `LAPACK <https://en.wikipedia.org/wiki/LAPACK>`_
+implementation is available.
+Additionally, the compile time define ``-DHAVE_CBLAS`` should be enabled,
+otherwise FLENS will use the slower internal implementation.
+
+In order to link against ``OpenBLAS`` from CMake, the following lines have
+to be added to the ``CMakeLists.txt`` file.
+
+.. code:: cmake
+
+    add_definitions(-DHAVE_CBLAS=1)
+
+    if (WIN32)
+        find_package(OpenBLAS REQUIRED)
+        set(BLAS_LIBRARIES ${CMAKE_INSTALL_PREFIX}${OpenBLAS_LIBRARIES})
+    else()
+        find_package(BLAS REQUIRED)
+        find_package(LAPACK REQUIRED)
+    endif()
+
+    message(STATUS "BLAS VENDOR:    " ${BLA_VENDOR})
+    message(STATUS "BLAS LIBRARIES: " ${BLAS_LIBRARIES})
+
+    target_link_libraries(your_target_name ${BLAS_LIBRARIES} ${LAPACK_LIBRARIES})
+
+
+If CMake is not used, the flags can be passed manually to e.g. ``g++``:
+
+.. code:: bash
+
+    g++ test.cpp -o test -lblas -llapack -DHAVE_CBLAS=1
+