How to install the toolkit
These instructions refer to installing the new version of the toolkit from the git repository. if you are installing the old version from subversion, refer to InstallingOld.
Firstly, download the toolkit from the git repository. For details see the Download section, but briefly, the commands are:
git clone https://github.com/mptoolkit/mptoolkit.git
cd mptoolkit
./fix-timestamp.sh
(the fix-timestamp.sh program updates some timestamps on files which 'git' doesn't preserve properly; this prevents the build system from getting confused and thinking that files are out of date when they are not.)
Dependencies
The toolkit depends on having the following software libraries installed. These are all standard packages which modern Linux distributions will include (either by default or as an optional package).
- C++14 Compiler, a recent compiler from GNU (>= GCC-4.9), Intel (>= 17.0), or Clang (>= 3.4) should all work. See CompilerSupport page for more details.
- Boost software library headers, and the
libboost_program_options library.
- BLAS libary. Recommend a high performance library such as MKL (supplied by Intel), FLAME (supplied by AMD), OpenBLAS, etc.
- LAPACK libary. Generally high-performance libraries such as MKL include both BLAS and LAPACK.
- ARPACK library. Modern Linux distributions often install this by default or have a package for it, it is unlikely that you will need to install it manually. If for some reason you do need to compile it from source, you probably want arpack-ng.
- GNU GMP library. This is also very common nowdays, your distribution is sure to have a package for it. Any version from 3 onwards will work.
- EXPOKIT is included in the source code repository, you do not need to separately install.
For a stock Ubuntu installation, the additional packages required are libgmp-dev, gfortran, libopenblas-base (or some alternative BLAS/LAPACK library), libboost-all-dev, libarpack2.
Optional dependencies
Optionally, the toolkit will use, if available,
The toolkit uses GNU Autoconf for the build system, and supports many of the standard options if you are familiar with this system.
It is recommend that you use a different directory for compiling the toolkit, rather than compiling the programs from inside the source mptoolkit directory. This avoids mixing temporary .o files and executable files with the source files, and also allows having multiple copies of the toolkit simultaneously (eg, with and without OpenMP threading, or with debugging versus optimized compiler flags).
So, firstly, make a new directory build, and change directory into it. This is normally at the same level as the mptoolkit directory (ie, don't make it a sub-directory of mptoolkit), but if you want to put it somewhere else, that is OK too. From the build directory, run the configure script. You will need to specify the path back to the source directory.
|
Note In older versions of the toolkit, it was necessary to set the CXXFLAGS compiler flags prior to running the configure script. This is no longer necessary, and the default flags are set for a high level of compiler optimizations.
|
mkdir build
cd build
../mptoolkit/configure
On most recent Linux distributions, the configure script will run successfully without any additional effort. If it does not, then there are some unmet dependencies that need to be fixed before trying again (eg, by installing an appropriate package).
|
Higher performance To get more performance out of the toolkit, it is most important to use an optimized
BLAS library such as MKL or ACML. Most Linux distributions have the 'reference' version of BLAS installed by default, which will work but will be much slower (perhaps a factor 4 or more) than an optimized BLAS library. See ConfigureCustomization to find out how to configure an optimized BLAS library. NOTE Ensure that your BLAS library is compatible with ARPACK. On Linux distributions, ARPACK uses the Fortran calling convention for returning complex values from functions, which is different from the usual C/C++ calling convention. If you are using MKL, this means that you need to use the _gf_ variants of the MKL libraries, not the _intel_ variants.
|
After the configure script has successfully run, you can compile the toolkit with
make
At this point, the tools will be compiled and you can run them from the build directory, eg with ./mp-info. If you want to install them, then
make install
This copies the executable programs to the install directory, specified by the configure script. The default location is $HOME/bin. If you want to install them somewhere else, see ConfigureCustomization.
The tools alone are not very useful without the ability to construct a particular model. A model is a short C++ program that constructs a 'lattice file'', which contains information about a particular model such as the Hilbert space and operators. The lattice file is then used as an input to various tools, for example to construct a wavefunction. The toolkit comes with many different model files, and it is quite easy to construct new ones. The core group of models (which are intended to be good examples that you can use to build your own models) are in the mptoolkit/models directory, and you can compile them with
make models
And also install them, if you want, with make install-models.
There are also some other model files in mptoolkit/models/contrib, which have been added for some purpose, but are more specialized and are not compiled by default. You can compile these models individually, with make <model>, or, if you want to compile all of the contrib/ models, you can use
make all-models
There is also a corresponding make install-all-models, if you want to install all of the models.
Walkthrough installs for specific systems
- getafix system at The University of Queensland
- MacOSX It is a bit complicated process, but it is possible.
- Weiner GPU system at the Uniersity of Queensland
- gowonda HPC system at Griffith University
- newton HPC system at Max Planck Institute (Germany)
Troubleshooting
- If you get an error similar to "
configure.ac:31: error: Autoconf version X.XX or higher is required" after updating the toolkit with git pull, then rerun the fix-timestamps script. This is caused by some files used by the build system (eg the configure script) changing, and since git doesn't track timestamps this can confuse the make program.
- If you get errors similar to "Illegal instruction" when running programs, then it means that you are running the program on a different (probably older) CPU than it was compiled on. The default compiler options include
-match=native, which instructs the compiler to produce code that is targeted at the CPU of the machine that the compiler is running on. This is usually what you want, as it will use optimized instructions if available (for example, AVX extensions). However if you want to then run the tools on a different machine (eg on a cluster with a mix of architectures) then this is a bad idea. To resolve this, you need to specify an architecture by hand. See ConfigureCustomization for how to do this.
- When using MKL, make sure that you use the version of the library that is compatible with other components of the system, specifically ARPACK. ARPACK is usually compiled using gfortran, which means that you must use the mkl_gf_lp64 version of MKL, rather than mkl_intel_lp64. If you get this wrong, you will probably get segmentation errors inside MKL when it calls the zdotc function, since this function uses a different calling convention in the GNU compiler versus Intel. This probably means that if you use the Intel compiler then you also need to obtain (or compile from source) a version of ARPACK compiled with the Intel compiler.
Debugging
The --enable-debug option to the configure script enables various debugging options and adds additional assertions and checks to the code. In addition, on the GNU compiler you can add additional standard library checks by configuring using
configure --enable-debug CXXFLAGS="-std=c++14 -g -O0 -DGLIBCXX_DEBUG -D_GLIBCXX_DEBUG_BACKTRACE" LDFLAGS="-lbacktrace"
