HOWTO LAPACK/CLAPACK for Windows
Posted: Tue Aug 11, 2009 2:25 pmThis is the first attempt of a HOWTO that I'm writing on using LAPACK with Visual Studio. In doing so, I've made the assumption that the reader, although probably an expert in some other discipline that requires a linear equation solver, is a novice when it comes to LAPACK -- just as I was when I started. For this reason, I've tried to explain the whys rather than dispense instructions.
Thanks to Evgenii Rudnyi and Mark Hoemmen at http://groups.google.com/group/matrixprogramming their early suggestions and the reading the draft of this HOWTO. Any inaccuracies in this document are mine. Use with care.
###########################################
Part 1: Compiling GotoBLAS
(Cygwin required -- http://cygwin.org/ )
###########################################
Preamble
LAPACK [http://www.netlib.org/lapack/] is designed as a two-tiered Fortran library, comprising higher level subroutines and "lower-level Basic Linear Algebra Subprograms (BLAS) in order to effectively exploit the caches on modern cache-based architectures" [http://en.wikipedia.org/wiki/LAPACK]. For reference purposes, the LAPACK installation provides a(n untuned) version of the BLAS which is not optimized for any architecture. This reference BLAS implementation may be orders of magnitude slower than optimized implementations, for matrix factorizations and other computationally intensive matrix operations. Optimized implementations the BLAS are available from a number of vendors and projects such as: Intel (commercial), AMD, and ATLAS, but my favorite is GotoBLAS because it is:
- currently the fastest BLAS implementation
[see research report "Choosing the optimal BLAS and LAPACK library" at http://tinyurl.com/m6lmqs ]
- trivial to compile
- is free (available without cost) for research/academic use.
You can read about sole author of this library Kazushige Goto (pronounced "Goat toe") at http://en.wikipedia.org/wiki/Kazushige_Goto
[Links to other BLAS implementations]
MKL - http://software.intel.com/en-us/intel-mkl/
AMD (AMCL) -- http://developer.amd.com/cpu/Libraries/ ... fault.aspx
ATLAS -- http://math-atlas.sourceforge.net/ (I was unable to build this library. I found the instructions too lengthy, complicated, and often ambiguous. Nevertheless, the goal of the ATLAS project is an admirable one. It aims to, by self-discovery, automatically generate an optimized BLAS library. However, its performance trails that of other libraries http://en.wikipedia.org/wiki/Automatica ... a_Software )
Compiling GotoBLAS
The GotoBLAS source is available from http://www.tacc.utexas.edu/resources/software/#blas (there's short registration
form to fill), and can be compiled for Windows with Cygwin. No changes need to be made to GotoBLAS' config file
Makefile.rule, unless a particular compiler is preferred. Happily, the config file automatically enables multithreading if more than one processor is available.
1. Download and extract the GotoBLAS source to any directory of choice, and make any desired changes to the config file (the default option should also work well).
2. In Cygwin, "cd" to the top-level directory containing the source, and type "make"
3. The result of this process should be a file libgoto_<processor_class>-r<gotoblas_version_number>.a, and a (symbolic) link libgoto.a pointing to this file. (For example, libgoto_banias-r1.26.a)
4. [Edit:] Now for the final part, building a Windows library (*.lib) and dll for GotoBLAS. This is best done in what's called the "Visual Studio command prompt". The Visual Studio command prompt is basically a version of of the command prompt (cmd) that knows the locations of all the Visual Studio tools e.g. compiler, linker.
- Add the path to the Cygwin binaries to your Windows PATH variable. (On my machine, this path is C:\cygwin\bin).
(Refer to the section "Adding or Editing Environment Variables" of the following page http://vlaurie.com/computers2/Articles/environment.htm for help on how to do this.)
- Launch the Visual Studio command prompt from:
Start Menu -> Programs -> Microsoft Visual Studio -> Visual Studio Tools -> Visual Studio Command prompt
- In the Visual Studio command prompt, change directory to the "exports" subdirectory of GotoBLAS and run the command "make dll". The result should be something like: libgoto_<processor_class>-r<gotoblas_version_number>.lib and libgoto_<processor_class>-r<gotoblas_version_number>.dll . For example: libgoto_banias-r1.26.dll, or libgoto_northwood-r1.26.dll
Final note:
* Windows needs to be told where to find this dll, else you will get a serious error when you try to run your program. There are several ways to do accomplish this. One, is to add the location of the dll to the PATH environment variable. Another is to simply copy the dll to the Windows\system32 folder. I did the later.
For more information, refer to Microsoft guidelines on Search Path Used by Windows to Locate a DLL
###########################################
Part 2: Using LAPACK subroutines in a Visual (Studio) C/C++ Project -- Part 1
###########################################
1. Download the LAPACK source or precompiled binaries from http://icl.cs.utk.edu/lapack-for-windows/ . Sources have been and can be can be compiled into debug and release versions. File names of the precomputed debug libraries end with the letter "d" e.g. BLASd.lib and lapackd.lib (in comparison to the release versions BLAS.lib and lapack.lib).
2. If you chose to compile LAPACK, you will require a Fortran compiler and libraries. I recommend the Intel Fortran compiler (distributed with libraries) [http://software.intel.com/en-us/articles/intel-software-evaluation-center/].
3. Obtain a tuned version of BLAS for your machine (refer to "Compiling GotoBLAS").
4. Create a Visual Studio project with the following sample C program:
http://www.cs.rochester.edu/~bh/cs400/using_lapack.html
5. rename the prototypes in the above program to
void dgesv_( )
void dgels_( )
to
extern "C" void dgesv_( )
extern "C" void dgels_( )
6. Add the following libraries to the Visual Studio project settings, under Linker -> Input -> Additional Dependencies. For example, on my laptop:
libgoto_banias-r1.26.lib
lapack.lib
Note: because BLAS libraries commonly provide faster versions of some LAPACK subroutines, the BLAS library must be listed before before LAPACK library.
Note: the make sure that the gotoBLAS dll is on your system path e.g. in the WINDOWS\system32 folder, else binary won't run.
7. Compile the project and run the resulting executable. You should get the output:
The solution is -0.661082 9.456125 -16.014625
Prologue:
Part 3 of this HOWTO will briefly explain what "dgesv" means and how to call it and other LAPACK subroutines with the appropriate arguments.
###########################################
Part 3: More about LAPACK subroutines (example: dgesv)
###########################################
(Note: this is the first draft of this section.)
In the previous section, I explained how to call a LAPACK subroutine e.g. dgesv_ from a C or C++ program, but I did not explain what the dgesv meant as well as its arguments. This is the purpose of this part of the HOWTO. In doing so, I will refer to the LAPACK documentation and hopefully show how easy it is to find an appropriate LAPACK subroutine and create the corresponding C/C++ function prototype for it.
Understanding dgesv
Prefix -- "dge"
From the LAPACK naming scheme -- http://www.netlib.org/lapack/lug/node24.html, it is plain to see that:
- d in "dgesv" means: double precsion data
- ge in "dgesv" means: general as in unsymmetric matrix
As such we can deduce that "dge" refers to the sort of matrix we have -- a general/unymmetric matrix containing double precision data
Suffix -- "sv"
This refers to the type of driver routine (solver in lay speak) to be used to solve the linear system. There are two kinds on drivers: simple drivers (suffixed with "sv") and "expert" drivers (suffixed with "svx"). Refer to http://www.netlib.org/lapack/lug/node26.html .
Therefore dgesv is simple driver routine for a general/unymmetric matrix containing double precision data.
Subroutine arguments
From the page http://www.netlib.org/lapack/double/dgesv.f , we can see that the subroutine dgesv has 8 arguments.
- The first argument is N, an integer. This is marked as an input (meaning argument will not be modified, as opposed to an input argument or an input/output argument) in the documentation. In C/C++ speak we can therefore refer to argument 1 as a constant integer i.e. "const int". However, because in Fortran all ALL arguments, *without exception* are passed by address, the type of N in C/C++ is: const *int . (Same goes for argument 2.)
- Argument 3, marked in the documentation as an input/output double precision array. In C/C++ terms input/output means NOT-constant. Therefore, because arguments are passed by reference, the type of argument 3 is: double * .
- Argument 5, marked in the documentation as an output integer array. In C/C++ terms this means the argument is not a const. Therefore argument 5 is of type int* . Same goes for argument 8, even though the argument is not an array (remember, all Fortran arguments are passed by address).
It should now be clear why the C/C++ prototype for dgesv is
Prologue:
A pattern for using directly LAPACK subroutines should now be clear.
- First find the appropriate subroutine from the list of available drivers http://www.netlib.org/lapack/lug/node25.html .
- Look up the driver in the index of routines http://www.netlib.org/lapack/explore-html/
- Create a the appropriate C/C++ prototype for the driver.
###########################################
Part 4: SEND US FEEDBACK!
[b]###########################################
We are working hard to improve the LAPACK/CLAPACK Windows support but it seems that users still have problems.
In case of success or failure, please let us know. We would like to know how we are doing, and how we could further help you.
Your post on the forum will be appreciated.
Enjoy.
graphicsRat & Julie
[Next, using CLAPACK in Visual Studio]
Thanks to Evgenii Rudnyi and Mark Hoemmen at http://groups.google.com/group/matrixprogramming their early suggestions and the reading the draft of this HOWTO. Any inaccuracies in this document are mine. Use with care.
###########################################
Part 1: Compiling GotoBLAS
(Cygwin required -- http://cygwin.org/ )
###########################################
Preamble
LAPACK [http://www.netlib.org/lapack/] is designed as a two-tiered Fortran library, comprising higher level subroutines and "lower-level Basic Linear Algebra Subprograms (BLAS) in order to effectively exploit the caches on modern cache-based architectures" [http://en.wikipedia.org/wiki/LAPACK]. For reference purposes, the LAPACK installation provides a(n untuned) version of the BLAS which is not optimized for any architecture. This reference BLAS implementation may be orders of magnitude slower than optimized implementations, for matrix factorizations and other computationally intensive matrix operations. Optimized implementations the BLAS are available from a number of vendors and projects such as: Intel (commercial), AMD, and ATLAS, but my favorite is GotoBLAS because it is:
- currently the fastest BLAS implementation
[see research report "Choosing the optimal BLAS and LAPACK library" at http://tinyurl.com/m6lmqs ]
- trivial to compile
- is free (available without cost) for research/academic use.
You can read about sole author of this library Kazushige Goto (pronounced "Goat toe") at http://en.wikipedia.org/wiki/Kazushige_Goto
[Links to other BLAS implementations]
MKL - http://software.intel.com/en-us/intel-mkl/
AMD (AMCL) -- http://developer.amd.com/cpu/Libraries/ ... fault.aspx
ATLAS -- http://math-atlas.sourceforge.net/ (I was unable to build this library. I found the instructions too lengthy, complicated, and often ambiguous. Nevertheless, the goal of the ATLAS project is an admirable one. It aims to, by self-discovery, automatically generate an optimized BLAS library. However, its performance trails that of other libraries http://en.wikipedia.org/wiki/Automatica ... a_Software )
Compiling GotoBLAS
The GotoBLAS source is available from http://www.tacc.utexas.edu/resources/software/#blas (there's short registration
form to fill), and can be compiled for Windows with Cygwin. No changes need to be made to GotoBLAS' config file
Makefile.rule, unless a particular compiler is preferred. Happily, the config file automatically enables multithreading if more than one processor is available.
1. Download and extract the GotoBLAS source to any directory of choice, and make any desired changes to the config file (the default option should also work well).
2. In Cygwin, "cd" to the top-level directory containing the source, and type "make"
3. The result of this process should be a file libgoto_<processor_class>-r<gotoblas_version_number>.a, and a (symbolic) link libgoto.a pointing to this file. (For example, libgoto_banias-r1.26.a)
4. [Edit:] Now for the final part, building a Windows library (*.lib) and dll for GotoBLAS. This is best done in what's called the "Visual Studio command prompt". The Visual Studio command prompt is basically a version of of the command prompt (cmd) that knows the locations of all the Visual Studio tools e.g. compiler, linker.
- Add the path to the Cygwin binaries to your Windows PATH variable. (On my machine, this path is C:\cygwin\bin).
(Refer to the section "Adding or Editing Environment Variables" of the following page http://vlaurie.com/computers2/Articles/environment.htm for help on how to do this.)
- Launch the Visual Studio command prompt from:
Start Menu -> Programs -> Microsoft Visual Studio -> Visual Studio Tools -> Visual Studio Command prompt
- In the Visual Studio command prompt, change directory to the "exports" subdirectory of GotoBLAS and run the command "make dll". The result should be something like: libgoto_<processor_class>-r<gotoblas_version_number>.lib and libgoto_<processor_class>-r<gotoblas_version_number>.dll . For example: libgoto_banias-r1.26.dll, or libgoto_northwood-r1.26.dll
Final note:
* Windows needs to be told where to find this dll, else you will get a serious error when you try to run your program. There are several ways to do accomplish this. One, is to add the location of the dll to the PATH environment variable. Another is to simply copy the dll to the Windows\system32 folder. I did the later.
For more information, refer to Microsoft guidelines on Search Path Used by Windows to Locate a DLL
###########################################
Part 2: Using LAPACK subroutines in a Visual (Studio) C/C++ Project -- Part 1
###########################################
1. Download the LAPACK source or precompiled binaries from http://icl.cs.utk.edu/lapack-for-windows/ . Sources have been and can be can be compiled into debug and release versions. File names of the precomputed debug libraries end with the letter "d" e.g. BLASd.lib and lapackd.lib (in comparison to the release versions BLAS.lib and lapack.lib).
2. If you chose to compile LAPACK, you will require a Fortran compiler and libraries. I recommend the Intel Fortran compiler (distributed with libraries) [http://software.intel.com/en-us/articles/intel-software-evaluation-center/].
3. Obtain a tuned version of BLAS for your machine (refer to "Compiling GotoBLAS").
4. Create a Visual Studio project with the following sample C program:
http://www.cs.rochester.edu/~bh/cs400/using_lapack.html
5. rename the prototypes in the above program to
void dgesv_( )
void dgels_( )
to
extern "C" void dgesv_( )
extern "C" void dgels_( )
6. Add the following libraries to the Visual Studio project settings, under Linker -> Input -> Additional Dependencies. For example, on my laptop:
libgoto_banias-r1.26.lib
lapack.lib
Note: because BLAS libraries commonly provide faster versions of some LAPACK subroutines, the BLAS library must be listed before before LAPACK library.
Note: the make sure that the gotoBLAS dll is on your system path e.g. in the WINDOWS\system32 folder, else binary won't run.
7. Compile the project and run the resulting executable. You should get the output:
The solution is -0.661082 9.456125 -16.014625
Prologue:
Part 3 of this HOWTO will briefly explain what "dgesv" means and how to call it and other LAPACK subroutines with the appropriate arguments.
###########################################
Part 3: More about LAPACK subroutines (example: dgesv)
###########################################
(Note: this is the first draft of this section.)
In the previous section, I explained how to call a LAPACK subroutine e.g. dgesv_ from a C or C++ program, but I did not explain what the dgesv meant as well as its arguments. This is the purpose of this part of the HOWTO. In doing so, I will refer to the LAPACK documentation and hopefully show how easy it is to find an appropriate LAPACK subroutine and create the corresponding C/C++ function prototype for it.
Understanding dgesv
Prefix -- "dge"
From the LAPACK naming scheme -- http://www.netlib.org/lapack/lug/node24.html, it is plain to see that:
- d in "dgesv" means: double precsion data
- ge in "dgesv" means: general as in unsymmetric matrix
As such we can deduce that "dge" refers to the sort of matrix we have -- a general/unymmetric matrix containing double precision data
Suffix -- "sv"
This refers to the type of driver routine (solver in lay speak) to be used to solve the linear system. There are two kinds on drivers: simple drivers (suffixed with "sv") and "expert" drivers (suffixed with "svx"). Refer to http://www.netlib.org/lapack/lug/node26.html .
Therefore dgesv is simple driver routine for a general/unymmetric matrix containing double precision data.
Subroutine arguments
From the page http://www.netlib.org/lapack/double/dgesv.f , we can see that the subroutine dgesv has 8 arguments.
- The first argument is N, an integer. This is marked as an input (meaning argument will not be modified, as opposed to an input argument or an input/output argument) in the documentation. In C/C++ speak we can therefore refer to argument 1 as a constant integer i.e. "const int". However, because in Fortran all ALL arguments, *without exception* are passed by address, the type of N in C/C++ is: const *int . (Same goes for argument 2.)
- Argument 3, marked in the documentation as an input/output double precision array. In C/C++ terms input/output means NOT-constant. Therefore, because arguments are passed by reference, the type of argument 3 is: double * .
- Argument 5, marked in the documentation as an output integer array. In C/C++ terms this means the argument is not a const. Therefore argument 5 is of type int* . Same goes for argument 8, even though the argument is not an array (remember, all Fortran arguments are passed by address).
It should now be clear why the C/C++ prototype for dgesv is
- Code: Select all
extern "C" void dgesv_( const int * , const int * , double * , const int * , int * , double * , const int * , int * );
Prologue:
A pattern for using directly LAPACK subroutines should now be clear.
- First find the appropriate subroutine from the list of available drivers http://www.netlib.org/lapack/lug/node25.html .
- Look up the driver in the index of routines http://www.netlib.org/lapack/explore-html/
- Create a the appropriate C/C++ prototype for the driver.
###########################################
Part 4: SEND US FEEDBACK!
[b]###########################################
We are working hard to improve the LAPACK/CLAPACK Windows support but it seems that users still have problems.
In case of success or failure, please let us know. We would like to know how we are doing, and how we could further help you.
Your post on the forum will be appreciated.
Enjoy.
graphicsRat & Julie
[Next, using CLAPACK in Visual Studio]