= WHPC release 0.19 :: http://whpc.sourceforge.net
WHPC is a software bundle which represents a self-contained environment to compile and launch high-performance numerically intensive codes on Windows. As of now it provides the capability to build and run sequential, multithreaded (PThreads- and OpenMP-aware), heterogeneous (OpenCL-aware) and distributed (MPI-aware) numeric codes.
WHPC consists of:
* Microsoft MPI implementation
* set of prebuilt numeric libraries, including but not limited to (non)linear solvers
* GNU C, C++ and FORTRAN compiler toolchains
* GNU Make utility
* PkgConfig utility
* preconfigured command-line environment
This WHPC release employs the Microsoft MPI version 8.0 which is the only maintained MPI implementation for the Windows operating system.
== Compatibility
WHPC comes in two flavors, 32- and 64-bit.
The 32-bit version can be installed on both 32- and 64-bit Windows and produces 32-bit executables. Both versions can coexist on the same system.
The 64-bit version can be installed on 64-bit Windows only and produces 64-bit executables. Note that 64-bit version is not "64-bit clean" in the sense that it still contains some 32-bit programs, notably the GNU utilities.
WHPC distributions are tested on 32-bit Windows XP SP3 and 64-bit Windows 10.
WHPC itself is meant to work on Windows XP and up. However, the Microsoft MPI versions 5.0 and up are stated not to support Windows XP, therefore the installation of bundled MS-MPI might fail on this system. However, even if MS-MPI is not installed, WHPC will still allow to build executables as it bundles all neccessary headers and import library - the executables will simply fail to start due to missing the <msmpi.dll> dynamic library.
Currently the WHPC is built against OpenCL 1.2 therefore the compiled executables are supposed to be vendor-independent.
Moreover, building the executables does not require any hardware-specific drivers to be present at compile time as WHPC bundles the OpenCL import library and the respective headers.
However, running such executables still requires the vendor-specific drivers installed in the target system, such as NVIDIA's CUDA SDK, AMD's APP SDK etc. Namely, the target system is required to have the <opencl.dll> dynamic library in path.
== Command-line operation
WHPC comes with a preconfigured Bash shell and associated utilities commonly found in Linux systems.
WHPC employs the PkgConfig tool in order to do the package configuration job.
Each bundled package has a number associated tags of the form <package-name{_package-spec}> (all lower case), where <package-name> is a name of the package and (optional) <package-spec> is the package variant, separated by underscore. For the packages which come in single variant, package-spec is omitted.
In the common case, the package variant is a three-char code XYZ, where X is library data type, Y is parallelism model and Z is build mode.
The library precision X follows the NETLIB's SDCZ convention:
* S - single precision real
* D - double precision real
* C - single precision complex
* Z - double precision complex
The parallelism model Y is one of:
* S - sequential (single-threaded) model
* T - multi-threaded shared memory model (either OpenMP or system threads)
* L - GPU-ware shared memory OpenCL model
* M - distributed memory MPI-aware model
The build mode Z is on of:
* O - optimized build
* G - debug build with debugging information
For example, the package <petsc_dmo> stands for optimized build of MPI-aware PETSc library compiled with double precision real data type.
Package descriptors alrady reference all its prerequisites.
Note that not all combiantions of the bundled libraries are shipped. In general, it is preferred to ship optimized builds of real and complex double precision versions of libraries. For actual list of bundled variants check the installation directory.
The PkgConfig tool is employed in order to retrieve the proper package-specific compilation and link options. Its basic usage is as follows:
pkg-config <package1> {<package2> ...} --cflags --libs
where <package?> are the packages of interest and <--cflags --libs> is the instruction to emit both compilation and link options. Each of these flags may be used alone, of course. This command prints the entire command-line option set which is then to be passed to compiler.
This WHPC release does not ship the MSYS package therefore the WHPC shell is the Windows native shell <cmd.exe>. As a result, the UNIX-native way of launching PkgConfig within the back quotes is not viable any more. Instead, a recommended way of building the executables is using the shipped GNU Makefile template which can be found in <share\GNUmakefile>. Copy it into the project directory and taylor it to your needs by setting the required variables, then open the WHPC shell in that directory and launch <make>. Refer to the in-makefile commentaries for more details.
In short, the required minimum is to set PROG variable to the program name, ex. <runme> and to set the SRC variable to the space-separated list of source files which need to be compiled, ex. <main.c aux.f90>. The WHPC packages which need to be queried by the PkgConfig call are specified as a space-separated list to the PKG variable, ex. <mpi lapack>.
== Shipped packages [variants]
BLAS
BOOST
EIGEN
FFTW [DSO DTO DMO]
FGSL
GMP/GMPXX
GSL
LAPACK
LIS [DSO DTO DMO ZSO ZTO ZMO]
METIS
MPC
MPFR
MPI
MUMPS [DSO DMO ZSO ZMO]
PARALUTION [DTO DLO]
PARMETIS
PETSC [DSO DMO ZSO ZMO]
RANDOM123
SPARSKIT
SCALAPACK
SLEPC [DSO DMO ZSO ZMO]
SUPERLU [DSO DTO DMO]
UMFPACK
VIENNACL [DTO DLO]
ZFP
Note that debugging versions of the packages are not shipped anymore mainly to reduce distribution size. They might be included back in later releases on demand.
== Windows Explorer integration
By default, WHPC installer performs the Explorer intergation which makes it possible to start the WHPC shell in selected directory by right-clicking on its name from within the Explorer window and selecting option "Open in WHPC* shell". Note that the 32- and 64-bit WHPC variants create separate entries making it possible for the two to coexist.
== Testing
WHPC comes with a self-check test program <share\test\whpctest.exe> which builds and runs an set of test problems for bundled packages. Run the program and examine its output for possible errors.
== Bundled packages (versions) :: references
Boost (1.63.0) :: http://www.boost.org
Eigen (3.3.4) :: http://eigen.tuxfamily.org
FGSL (1.2.0) :: http://www.lrz.de/services/software/mathematik/gsl/fortran
FFTW (3.3.6) :: http://www.fftw.org
GMP (6.1.2) :: https://gmplib.org
GSL (2.4) :: http://www.gnu.org/software/gsl
LAPACK (3.7.0) :: http://www.netlib.org/lapack
LIS (1.7.33) :: http://www.ssisc.org/lis
METIS (5.1.0) :: http://glaros.dtc.umn.edu/gkhome/metis/metis/overview
MinGW-W64 (7.1.0) :: http://mingw-w64.sourceforge.net
MPC (1.0.3) :: http://www.multiprecision.org/index.php?prog=mpc
MPFR (3.1.5) :: http://www.mpfr.org
MS-MPI (8.0) :: https://msdn.microsoft.com/en-us/library/windows/desktop/bb524831%28v=vs.85%29.aspx
MUMPS (5.1.1) :: http://graal.ens-lyon.fr/MUMPS
OpenBLAS (0.2.19) :: http://www.openblas.net
OpenCL (1.2) :: https://www.khronos.org/opencl
Paralution (1.1.0) :: http://www.paralution.com
ParMETIS (4.0.3) :: http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview
PETSc (3.7.6) :: http://www.mcs.anl.gov/petsc
Random123 (1.09) :: http://www.thesalmons.org/john/random123
SCALAPACK (2.0.2) :: http://www.netlib.org/scalapack
SLEPc (3.7.4) :: http://www.grycap.upv.es/slepc
SPARSKIT (2) :: http://www-users.cs.umn.edu/~saad/software/SPARSKIT
SuiteSparse (4.5.5) :: http://faculty.cse.tamu.edu/davis/suitesparse.html
SuperLU (5.2.1) :: http://crd-legacy.lbl.gov/~xiaoye/SuperLU
SuperLU_MT (3.1) :: http://crd-legacy.lbl.gov/~xiaoye/SuperLU
SuperLU_DIST (5.1.3) :: http://crd-legacy.lbl.gov/~xiaoye/SuperLU
ViennaCL (1.7.1) :: http://viennacl.sourceforge.net
ZFP (0.5.1) :: http://computation.llnl.gov/casc/zfp
Bundled BLAS comes in two flavors: standard Netlib BLAS and optimized OpenBLAS, a successor to GotoBLAS2.
The latter is used by default.
By default, optimized versions are built with -O3 flag.
== Caveats
* The WHPC installer requires administrator privileges to run.
* On some rare occasions the bundled Microsoft MPI distribution fails to install. In this case one should download and install it separately.
* Upon its installation the Microsoft MPI performs all neccessary Windows firewall intergation so the programs run locally do not cause the firewall to raise an alarm. However the 3rd party firewalls still unaware of it and thus will require user intervention.
* It appears that the PETSc package in its current state is not 64-bit clean. Specifically, there is an assumption throughout the code that the size of data pointer equals to that of int which holds true for 64-bit operating systems following the LP64 data model, such as modern Unices and Linux, but not for 64-bit Windows which adheres to the LLP64 data model instead. As a consequence, compiling the PETSc gives tons of warnings about lossy integer/pointer casts. Despite the warnings the produces libraries seem to work for smaller problems. However be warned that they *will* break inevitably for very large problems where the truncation errors manifest themselves.
* WHPC ships a patched version of PkgConfig which emits short path names for prefixes. This makes it possible to install WHPC in default program directory such as <c:\Program Files (x86)>. It should work in most situations, however the short names feature is optional on NTFS file systems and thus it might have been disabled causing the PkgConfig to generate wrong paths the GCC won't accept. In this case WHPC is ought to be installed in a path not containing any problematic characters, such as spaces, braces etc. A drive's root (for example <C:\>) would be then a good option.
== Legal stuff
The WHPC bundles the 3rd party packages whose copyright holders retain all the rights over them according to the respective licenses. The geniune parts of the WHPC itself are distributed under the terms of modified BSD license. Feel free to use and share.
That's all, folks. Happy number crunching!
Oleg A. Khlybov <fougas@mail.ru>
