From 6f305cd5fd9e027bd06d321d1c80759004855cc9 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 11 Jun 2021 07:06:29 -0400 Subject: Find{BLAS,LAPACK}: Factor out vendor documentation Move the list of vendors to a dedicated section shared by both modules. Format it as a definition list. --- Modules/FindBLAS.cmake | 160 +++++++++++++++++++++++++++++------------------ Modules/FindLAPACK.cmake | 54 +--------------- 2 files changed, 100 insertions(+), 114 deletions(-) diff --git a/Modules/FindBLAS.cmake b/Modules/FindBLAS.cmake index 826a9c21d0..74d8bf0a84 100644 --- a/Modules/FindBLAS.cmake +++ b/Modules/FindBLAS.cmake @@ -23,68 +23,8 @@ The following variables may be set to influence this module's behavior: if ``ON`` use static linkage ``BLA_VENDOR`` - If set, checks only the specified vendor, if not set checks all the - possibilities. List of vendors valid in this module: - - * ``Goto`` - * ``FlexiBLAS`` - * ``OpenBLAS`` - * ``FLAME`` - * ``ATLAS PhiPACK`` - * ``CXML`` - * ``DXML`` - * ``SunPerf`` - * ``SCSL`` - * ``SGIMATH`` - * ``IBMESSL`` - * ``Intel10_32`` (intel mkl v10 32 bit, threaded code) - * ``Intel10_64lp`` (intel mkl v10+ 64 bit, threaded code, lp64 model) - * ``Intel10_64lp_seq`` (intel mkl v10+ 64 bit, sequential code, lp64 model) - * ``Intel10_64ilp`` (intel mkl v10+ 64 bit, threaded code, ilp64 model) - * ``Intel10_64ilp_seq`` (intel mkl v10+ 64 bit, sequential code, ilp64 model) - * ``Intel10_64_dyn`` (intel mkl v10+ 64 bit, single dynamic library) - * ``Intel`` (obsolete versions of mkl 32 and 64 bit) - * ``ACML`` - * ``ACML_MP`` - * ``ACML_GPU`` - * ``Apple`` - * ``NAS`` - * ``Arm`` - * ``Arm_mp`` - * ``Arm_ilp64`` - * ``Arm_ilp64_mp`` - * ``EML`` - * ``EML_mt`` - * ``Fujitsu_SSL2`` (Fujitsu serial blas / lapack) - * ``Fujitsu_SSL2BLAMP`` (Fujitsu parallel blas / lapack) - * ``NVHPC`` - * ``Generic`` - - .. versionadded:: 3.6 - ``OpenBLAS`` support. - - .. versionadded:: 3.11 - ``FLAME`` support. - - .. versionadded:: 3.13 - Added ILP64 MKL variants (``Intel10_64ilp``, ``Intel10_64ilp_seq``). - - .. versionadded:: 3.17 - Added single dynamic library MKL variant (``Intel10_64_dyn``). - - .. versionadded:: 3.18 - Arm Performance Libraries support (``Arm``, ``Arm_mp``, ``Arm_ilp64``, - ``Arm_ilp64_mp``). - - .. versionadded:: 3.19 - ``FlexiBLAS`` support. - - .. versionadded:: 3.20 - Elbrus Math Library support (``EML``, ``EML_mt``). - Fujitsu SSL2 Library support (``Fujitsu_SSL2``, ``Fujitsu_SSL2BLAMP``) - - .. versionadded:: 3.21 - NVHPC support + Set to one of the :ref:`BLAS/LAPACK Vendors` to search for BLAS only + from the specified vendor. If not set, all vendors are considered. ``BLA_F95`` if ``ON`` tries to find the BLAS95 interfaces @@ -136,6 +76,102 @@ This module defines the following variables: set(BLA_VENDOR Intel10_64lp) find_package(BLAS) +.. _`BLAS/LAPACK Vendors`: + +BLAS/LAPACK Vendors +^^^^^^^^^^^^^^^^^^^ + +``Generic`` + Generic reference implementation + +``ACML``, ``ACML_MP``, ``ACML_GPU`` + AMD Core Math Library + +``Apple``, ``NAS`` + Apple BLAS (Accelerate), and Apple NAS (vecLib) + +``Arm``, ``Arm_mp``, ``Arm_ilp64``, ``Arm_ilp64_mp`` + .. versionadded:: 3.18 + + Arm Performance Libraries + +``ATLAS`` + Automatically Tuned Linear Algebra Software + +``CXML``, ``DXML`` + Compaq/Digital Extended Math Library + +``EML``, ``EML_mt`` + .. versionadded:: 3.20 + + Elbrus Math Library + +``FLAME`` + .. versionadded:: 3.11 + + BLIS Framework + +``FlexiBLAS`` + .. versionadded:: 3.19 + +``Fujitsu_SSL2``, ``Fujitsu_SSL2BLAMP`` + .. versionadded:: 3.20 + + Fujitsu SSL2 serial and parallel blas/lapack + +``Goto`` + GotoBLAS + +``IBMESSL`` + IBM Engineering and Scientific Subroutine Library + +``Intel`` + Intel MKL 32 bit and 64 bit obsolete versions + +``Intel10_32`` + Intel MKL v10 32 bit, threaded code + +``Intel10_64lp`` + Intel MKL v10+ 64 bit, threaded code, lp64 model + +``Intel10_64lp_seq`` + Intel MKL v10+ 64 bit, sequential code, lp64 model + +``Intel10_64ilp`` + .. versionadded:: 3.13 + + Intel MKL v10+ 64 bit, threaded code, ilp64 model + +``Intel10_64ilp_seq`` + .. versionadded:: 3.13 + + Intel MKL v10+ 64 bit, sequential code, ilp64 model + +``Intel10_64_dyn`` + .. versionadded:: 3.17 + + Intel MKL v10+ 64 bit, single dynamic library + +``NVHPC`` + .. versionadded:: 3.21 + + NVIDIA HPC SDK + +``OpenBLAS`` + .. versionadded:: 3.6 + +``PhiPACK`` + Portable High Performance ANSI C (PHiPAC) + +``SCSL`` + Scientific Computing Software Library + +``SGIMATH`` + SGI Scientific Mathematical Library + +``SunPerf`` + Sun Performance Library + Hints ^^^^^ diff --git a/Modules/FindLAPACK.cmake b/Modules/FindLAPACK.cmake index fa2300d6b0..593b5e8380 100644 --- a/Modules/FindLAPACK.cmake +++ b/Modules/FindLAPACK.cmake @@ -23,58 +23,8 @@ The following variables may be set to influence this module's behavior: if ``ON`` use static linkage ``BLA_VENDOR`` - If set, checks only the specified vendor, if not set checks all the - possibilities. List of vendors valid in this module: - - * ``FlexiBLAS`` - * ``OpenBLAS`` - * ``FLAME`` - * ``Intel10_32`` (intel mkl v10 32 bit, threaded code) - * ``Intel10_64lp`` (intel mkl v10+ 64 bit, threaded code, lp64 model) - * ``Intel10_64lp_seq`` (intel mkl v10+ 64 bit, sequential code, lp64 model) - * ``Intel10_64ilp`` (intel mkl v10+ 64 bit, threaded code, ilp64 model) - * ``Intel10_64ilp_seq`` (intel mkl v10+ 64 bit, sequential code, ilp64 model) - * ``Intel10_64_dyn`` (intel mkl v10+ 64 bit, single dynamic library) - * ``Intel`` (obsolete versions of mkl 32 and 64 bit) - * ``ACML`` - * ``Apple`` - * ``NAS`` - * ``Arm`` - * ``Arm_mp`` - * ``Arm_ilp64`` - * ``Arm_ilp64_mp`` - * ``EML`` - * ``EML_mt`` - * ``Fujitsu_SSL2`` (Fujitsu serial blas / lapack) - * ``Fujitsu_SSL2BLAMP`` (Fujitsu parallel blas / lapack) - * ``NVHPC`` - * ``Generic`` - - .. versionadded:: 3.6 - ``OpenBLAS`` support. - - .. versionadded:: 3.11 - ``FLAME`` support. - - .. versionadded:: 3.13 - Added ILP64 MKL variants (``Intel10_64ilp``, ``Intel10_64ilp_seq``). - - .. versionadded:: 3.17 - Added single dynamic library MKL variant (``Intel10_64_dyn``). - - .. versionadded:: 3.18 - Arm Performance Libraries support (``Arm``, ``Arm_mp``, ``Arm_ilp64``, - ``Arm_ilp64_mp``). - - .. versionadded:: 3.19 - ``FlexiBLAS`` support. - - .. versionadded:: 3.20 - Elbrus Math Library support (``EML``, ``EML_mt``). - Fujitsu SSL2 Library support (``Fujitsu_SSL2``, ``Fujitsu_SSL2BLAMP``) - - .. versionadded:: 3.21 - NVHPC support + Set to one of the :ref:`BLAS/LAPACK Vendors` to search for BLAS only + from the specified vendor. If not set, all vendors are considered. ``BLA_F95`` if ``ON`` tries to find the BLAS95/LAPACK95 interfaces -- cgit v1.2.1 From 3beac78a133a6bc23a77530490cffe978d9f1311 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 11 Jun 2021 07:58:15 -0400 Subject: Find{BLAS,LAPACK}: Revise imported targets documentation layout --- Modules/FindBLAS.cmake | 7 +++---- Modules/FindLAPACK.cmake | 6 +++--- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/Modules/FindBLAS.cmake b/Modules/FindBLAS.cmake index 74d8bf0a84..f0778140a9 100644 --- a/Modules/FindBLAS.cmake +++ b/Modules/FindBLAS.cmake @@ -38,13 +38,12 @@ The following variables may be set to influence this module's behavior: Imported targets ^^^^^^^^^^^^^^^^ -.. versionadded:: 3.18 - -This module defines the following :prop_tgt:`IMPORTED` target: +This module defines the following :prop_tgt:`IMPORTED` targets: ``BLAS::BLAS`` - The libraries to use for BLAS, if found. + .. versionadded:: 3.18 + The libraries to use for BLAS, if found. Result Variables ^^^^^^^^^^^^^^^^ diff --git a/Modules/FindLAPACK.cmake b/Modules/FindLAPACK.cmake index 593b5e8380..3eeb4b2998 100644 --- a/Modules/FindLAPACK.cmake +++ b/Modules/FindLAPACK.cmake @@ -38,11 +38,11 @@ The following variables may be set to influence this module's behavior: Imported targets ^^^^^^^^^^^^^^^^ -.. versionadded:: 3.18 - -This module defines the following :prop_tgt:`IMPORTED` target: +This module defines the following :prop_tgt:`IMPORTED` targets: ``LAPACK::LAPACK`` + .. versionadded:: 3.18 + The libraries to use for LAPACK, if found. Result Variables -- cgit v1.2.1 From 43b581367d71ce45bb36ef0fc3bf77bfbea98af2 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 11 Jun 2021 08:00:22 -0400 Subject: Find{BLAS,LAPACK}: Move implementation note from docs to comments --- Modules/FindBLAS.cmake | 7 +++---- Modules/FindLAPACK.cmake | 7 +++---- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/Modules/FindBLAS.cmake b/Modules/FindBLAS.cmake index f0778140a9..ae4f779fe3 100644 --- a/Modules/FindBLAS.cmake +++ b/Modules/FindBLAS.cmake @@ -10,10 +10,6 @@ Find Basic Linear Algebra Subprograms (BLAS) library This module finds an installed Fortran library that implements the BLAS linear-algebra interface (see http://www.netlib.org/blas/). -The approach follows that taken for the ``autoconf`` macro file, -``acx_blas.m4`` (distributed at -http://ac-archive.sourceforge.net/ac-archive/acx_blas.html). - Input Variables ^^^^^^^^^^^^^^^ @@ -184,6 +180,9 @@ Hints #]=======================================================================] +# The approach follows that of the ``autoconf`` macro file, ``acx_blas.m4`` +# (distributed at http://ac-archive.sourceforge.net/ac-archive/acx_blas.html). + # Check the language being used if(NOT (CMAKE_C_COMPILER_LOADED OR CMAKE_CXX_COMPILER_LOADED OR CMAKE_Fortran_COMPILER_LOADED)) if(BLAS_FIND_REQUIRED) diff --git a/Modules/FindLAPACK.cmake b/Modules/FindLAPACK.cmake index 3eeb4b2998..7026f1112a 100644 --- a/Modules/FindLAPACK.cmake +++ b/Modules/FindLAPACK.cmake @@ -10,10 +10,6 @@ Find Linear Algebra PACKage (LAPACK) library This module finds an installed Fortran library that implements the LAPACK linear-algebra interface (see http://www.netlib.org/lapack/). -The approach follows that taken for the ``autoconf`` macro file, -``acx_lapack.m4`` (distributed at -http://ac-archive.sourceforge.net/ac-archive/acx_lapack.html). - Input Variables ^^^^^^^^^^^^^^^ @@ -76,6 +72,9 @@ This module defines the following variables: find_package(LAPACK) #]=======================================================================] +# The approach follows that of the ``autoconf`` macro file, ``acx_lapack.m4`` +# (distributed at http://ac-archive.sourceforge.net/ac-archive/acx_lapack.html). + if(CMAKE_Fortran_COMPILER_LOADED) include(${CMAKE_CURRENT_LIST_DIR}/CheckFortranFunctionExists.cmake) else() -- cgit v1.2.1 From 6a7c055f96c02587d36c57a33f5e37cb95c53fac Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 11 Jun 2021 08:02:59 -0400 Subject: Find{BLAS,LAPACK}: Revise formatting of intro docs --- Modules/FindBLAS.cmake | 4 +++- Modules/FindLAPACK.cmake | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/Modules/FindBLAS.cmake b/Modules/FindBLAS.cmake index ae4f779fe3..00ce946792 100644 --- a/Modules/FindBLAS.cmake +++ b/Modules/FindBLAS.cmake @@ -8,7 +8,9 @@ FindBLAS Find Basic Linear Algebra Subprograms (BLAS) library This module finds an installed Fortran library that implements the -BLAS linear-algebra interface (see http://www.netlib.org/blas/). +`BLAS linear-algebra interface`_. + +.. _`BLAS linear-algebra interface`: http://www.netlib.org/blas/ Input Variables ^^^^^^^^^^^^^^^ diff --git a/Modules/FindLAPACK.cmake b/Modules/FindLAPACK.cmake index 7026f1112a..2d396d1d74 100644 --- a/Modules/FindLAPACK.cmake +++ b/Modules/FindLAPACK.cmake @@ -8,7 +8,9 @@ FindLAPACK Find Linear Algebra PACKage (LAPACK) library This module finds an installed Fortran library that implements the -LAPACK linear-algebra interface (see http://www.netlib.org/lapack/). +`LAPACK linear-algebra interface`_. + +.. _`LAPACK linear-algebra interface`: http://www.netlib.org/lapack/ Input Variables ^^^^^^^^^^^^^^^ -- cgit v1.2.1 From 8585a12bd94241a6527cee22e840c430a45fead3 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 11 Jun 2021 08:40:37 -0400 Subject: Find{BLAS,LAPACK}: Move enabled language requirement to top of documentation --- Modules/FindBLAS.cmake | 3 ++- Modules/FindLAPACK.cmake | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/Modules/FindBLAS.cmake b/Modules/FindBLAS.cmake index 00ce946792..ed816faa67 100644 --- a/Modules/FindBLAS.cmake +++ b/Modules/FindBLAS.cmake @@ -10,6 +10,8 @@ Find Basic Linear Algebra Subprograms (BLAS) library This module finds an installed Fortran library that implements the `BLAS linear-algebra interface`_. +At least one of the ``C``, ``CXX``, or ``Fortran`` languages must be enabled. + .. _`BLAS linear-algebra interface`: http://www.netlib.org/blas/ Input Variables @@ -63,7 +65,6 @@ This module defines the following variables: .. note:: - C, CXX or Fortran must be enabled to detect a BLAS library. C or CXX must be enabled to use Intel Math Kernel Library (MKL). For example, to use Intel MKL libraries and/or Intel compiler: diff --git a/Modules/FindLAPACK.cmake b/Modules/FindLAPACK.cmake index 2d396d1d74..740dc28feb 100644 --- a/Modules/FindLAPACK.cmake +++ b/Modules/FindLAPACK.cmake @@ -10,6 +10,8 @@ Find Linear Algebra PACKage (LAPACK) library This module finds an installed Fortran library that implements the `LAPACK linear-algebra interface`_. +At least one of the ``C``, ``CXX``, or ``Fortran`` languages must be enabled. + .. _`LAPACK linear-algebra interface`: http://www.netlib.org/lapack/ Input Variables @@ -63,7 +65,6 @@ This module defines the following variables: .. note:: - C, CXX or Fortran must be enabled to detect a BLAS/LAPACK library. C or CXX must be enabled to use Intel Math Kernel Library (MKL). For example, to use Intel MKL libraries and/or Intel compiler: -- cgit v1.2.1 From 5bf16514525eabc179b826d3caa5114afb51d9ad Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 11 Jun 2021 08:41:25 -0400 Subject: Find{BLAS,LAPACK}: Revise and extend Intel MKL usage documentation Fixes: #22295 --- Modules/FindBLAS.cmake | 77 ++++++++++++++++++++++++++++++++++++------------ Modules/FindLAPACK.cmake | 19 ++++++++---- 2 files changed, 71 insertions(+), 25 deletions(-) diff --git a/Modules/FindBLAS.cmake b/Modules/FindBLAS.cmake index ed816faa67..7c36f128a6 100644 --- a/Modules/FindBLAS.cmake +++ b/Modules/FindBLAS.cmake @@ -63,17 +63,6 @@ This module defines the following variables: ``BLAS95_FOUND`` library implementing the BLAS95 interface is found -.. note:: - - C or CXX must be enabled to use Intel Math Kernel Library (MKL). - - For example, to use Intel MKL libraries and/or Intel compiler: - - .. code-block:: cmake - - set(BLA_VENDOR Intel10_64lp) - find_package(BLAS) - .. _`BLAS/LAPACK Vendors`: BLAS/LAPACK Vendors @@ -170,16 +159,66 @@ BLAS/LAPACK Vendors ``SunPerf`` Sun Performance Library -Hints -^^^^^ +.. _`Intel MKL`: + +Intel MKL +^^^^^^^^^ + +To use the Intel MKL implementation of BLAS, a project must enable at least +one of the ``C`` or ``CXX`` languages. Set ``BLA_VENDOR`` to an Intel MKL +variant either on the command-line as ``-DBLA_VENDOR=Intel10_64lp`` or in +project code: + +.. code-block:: cmake + + set(BLA_VENDOR Intel10_64lp) + find_package(BLAS) + +In order to build a project using Intel MKL, and end user must first +establish an Intel MKL environment: + +Intel oneAPI + Source the full Intel environment script: + + .. code-block:: shell + + . /opt/intel/oneapi/setvars.sh + + Or, source the MKL component environment script: + + .. code-block:: shell + + . /opt/intel/oneapi/mkl/latest/env/vars.sh + +Intel Classic + Source the full Intel environment script: + + .. code-block:: shell + + . /opt/intel/bin/compilervars.sh intel64 + + Or, source the MKL component environment script: + + .. code-block:: shell + + . /opt/intel/mkl/bin/mklvars.sh intel64 + +The above environment scripts set the ``MKLROOT`` environment variable +to the top of the MKL installation. They also add the location of the +runtime libraries to the dynamic library loader environment variable for +your platform (e.g. ``LD_LIBRARY_PATH``). This is necessary for programs +linked against MKL to run. + +.. note:: + + As of Intel oneAPI 2021.2, loading only the MKL component does not + make all of its dependencies available. In particular, the ``iomp5`` + library must be available separately, or provided by also loading + the compiler component environment: -``MKLROOT`` - .. versionadded:: 3.15 + .. code-block:: shell - Set this environment variable to a directory that contains an MKL - installation, or add the directory to the dynamic library loader environment - variable for your platform (``LIB``, ``DYLD_LIBRARY_PATH`` or - ``LD_LIBRARY_PATH``). + . /opt/intel/oneapi/compiler/latest/env/vars.sh #]=======================================================================] diff --git a/Modules/FindLAPACK.cmake b/Modules/FindLAPACK.cmake index 740dc28feb..725a70cefc 100644 --- a/Modules/FindLAPACK.cmake +++ b/Modules/FindLAPACK.cmake @@ -63,16 +63,23 @@ This module defines the following variables: ``LAPACK95_FOUND`` library implementing the LAPACK95 interface is found -.. note:: +Intel MKL +^^^^^^^^^ - C or CXX must be enabled to use Intel Math Kernel Library (MKL). +To use the Intel MKL implementation of LAPACK, a project must enable at least +one of the ``C`` or ``CXX`` languages. Set ``BLA_VENDOR`` to an Intel MKL +variant either on the command-line as ``-DBLA_VENDOR=Intel10_64lp`` or in +project code: - For example, to use Intel MKL libraries and/or Intel compiler: +.. code-block:: cmake - .. code-block:: cmake + set(BLA_VENDOR Intel10_64lp) + find_package(LAPACK) + +In order to build a project using Intel MKL, and end user must first +establish an Intel MKL environment. See the :module:`FindBLAS` module +section on :ref:`Intel MKL` for details. - set(BLA_VENDOR Intel10_64lp) - find_package(LAPACK) #]=======================================================================] # The approach follows that of the ``autoconf`` macro file, ``acx_lapack.m4`` -- cgit v1.2.1