Installation

Alexander Gaenko edited this page Jul 9, 2018 · 54 revisions

Table of Contents

Prerequisites

To install ALPSCore, the following is needed:

  1. C++ compiler: g++ >= 4.2 OR Intel >= 10.0 OR Clang >= 3.2
  2. CMake >= 3.1 (NOTE: CMake 3.6.0 on Mac has a known problem)
  3. HDF5 library 1.8.x (NOTE: HDF5 1.10 has a known problem)
  4. Boost >= 1.56.0
  5. Eigen 3.3.4 (can be requested to be downloaded automatically)

Optional requirements:

  1. An MPI library and headers for compiling multi-cpu versions of the libraries.
  2. Doxygen for creating low-level documentation.

Obtaining ALPSCore

From package managers

Mac OS

macports
    $ sudo port install alpscore
homebrew
    $ brew tap homebrew/science
    $ brew install alpscore

See https://github.com/ALPSCore/packaging/blob/master/homebrew/ for details

Gentoo Linux

See https://github.com/ALPSCore/packaging/blob/master/gentoo/ for details

For other systems: please file an issue to let us know your system and we will try to add package files.

Manual source installation

The ALPSCore package can be obtained by following methods:

  • Clone Git repository at https://github.com/ALPSCore/ALPSCore.git:

      $ git clone https://github.com/ALPSCore/ALPSCore.git
      $ cd ALPSCore
    
  • From release tarball:

    1. Download a release tarball from https://github.com/ALPSCore/ALPSCore/releases.

    2. Rename the downloaded tarball to ALPSCore.tar.gz (or ALPSCore.zip, if you chose the zip version), unpack it and change into the created directory:

        $ tar -xzf ALPSCore.tar.gz
        $ cd ALPSCore*/
      

Compilation and installation procedure

The ALPSCore library uses CMake as its build system.

  1. Create a build directory and change to it:

     $ mkdir build
     $ cd build
    
  2. Next, generate the ALPSCore build. The simplest build with reasonable defaults is generated by:

     $ cmake .. -DCMAKE_INSTALL_PREFIX=/where/to/install/ALPSCore
    

    You can also have a look at the build.jenkins.sh file in the directory common/build. This outlines some of the common options used by our automatic build system.

    NOTE: You must compile the ALPSCore libraries and all your codes which depend on the ALPScore libraries with the same C++ standard for ABI compatibility. At the very least, do not mix C++03 and C++11 code.

    Since version 2.1.0, the new CMake flag "ALPS_CXX_STD" allows to choose C++ standard to compile ALPSCore with. This flag can be set to either c++11, c++14 or custom (e.g. -DALPS_CXX_STD=c++11), with the default being c++11 since version 2.2.1. (Version 2.1.0 supported c++03 also, which was the default to that version.) If a compiler is "known" to CMake, CMake will set appropriate compiler flags. Normally, the standard-setting flags propagate to the build of your code, so there is no need to set them in your project's CMake files.

    If CMake failed to set an appropriate flag, you can set a compilation flag manually via -DALPS_CXX_STD=custom -DCMAKE_CXX_FLAGS='-std=c++14'. In this case, you will also have to make sure that your project is build with the same version of C++ standard, by manually setting CMAKE_CXX_FLAGS when configuring your project.

    More detailed information about setting C++ standard version is available on Choice of C++ standard page.

    For advanced users: If you do not wish to install all ALPSCore components, please refer to Selecting ALPSCore components.

    Troubleshooting:

    a. If your build generation seems to pick up the wrong Boost library, the following may help (note the mixed-case Boost_ in some of the arguments!):

       $ cmake .. -DBOOST_ROOT=/path/to/boost \
                  -DBoost_NO_SYSTEM_PATHS=ON \
                  -DBoost_NO_BOOST_CMAKE=ON
    

    b. To point CMake to the correct location of HDF5 library, set environment variable HDF5_ROOT=/path/to/hdf5 prior to CMake invocation.

    c. If your CMake run fails with a message In source builds are disabled. Please use a separate build directory, first make sure that you are not indeed attempting to build in the source directory. The error may be a lasting effect of a previous attempt at an in-source build, see CMake FAQ.

    You should remove CMake-generated files from the source directory and redo the build. For example, this way (from the build directory):

    $ mv ../CMakeLists.txt ../save_CMakeLists.txt
    $ rm -rf ../CMake*
    $ mv ../save_CMakeLists.txt ../CMakeLists.txt
    

    d. On most high performance computers with non-standard environments, e.g. crays/blue genes, you will get the best results by using the wrapper compilers and enabling static linking (see ALPS_BUILD_TYPE in CMake and environment variables affecting ALPSCore build.

    e. See also a page listing known problems.

    For more information, see CMake and environment variables affecting ALPSCore build.

  3. Once the build tree successfully generated, perform the build:

     $ make
    

    on multicore machines with enough memory you can also run

     $ make -j njobs
    

    with njobs the number of parallel jobs to run the compilation in parallel.

  4. Run the testing:

     $ make test
    
  5. and install ALPSCore:

     $ make install
    

The ALPScore will be installed in the directory specified in step 3 (/where/to/install/ALPSCore in this example).

Build your project with ALPSCore

To use ALPSCore, your project must utilize CMake build system. Add the following lines to your project's CMakeLists.txt:

    # Not strictly necessary, but will create executables that are
    # aware of ALPSCore location
    SET(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
    
    # Request the ALPSCore package:
    find_package(ALPSCore)
    # (optionally, components can be also listed, like this:) 
    # find_package(ALPSCore accumulators params)
    
    # Use ALPSCore_LIBRARIES variable to link to ALPSCore 
    target_link_libraries(your_project_target ${ALPSCore_LIBRARIES})

You can see a CMakeLists.txt in an example project at https://github.com/ALPSCore/ALPSCore/tree/master/tutorials/mc/ising_mc . To build the project:

    $ mkdir ~/alpscore-tutorial
    $ cd ~/alpscore-tutorial
    $ env ALPSCore_DIR=/where/to/install/ALPSCore cmake /path/to/the/tutorials/mc/ising_mc
    $ make