SyTen
Installation

Please read all sections of this file carefully, unless you are certain they do not apply to you. Only after having read all of them attempt to run any commands, installation procedures etc. pp. By now, most issues are covered here or in the FAQ.

Overall Idea

Configuration takes place via the make.inc file. This file is included by the Makefile file which in turn defines the possible targets. You can either write the make.inc file by hand (not supported) or execute the setup.sh script. If you want to write the make.inc file yourself, have a look at setup.sh to find all the required entries. Note that the setup.sh script will also compile some libraries which are bundled with the toolkit under ext/.

Once you have a working make.inc file, you can easily add additional configuration options (e.g. regarding the compile-time switches below).

Prerequisites and `make.inc`

Detailed Requirements

Required Libraries and other tools

  • Either LAPACKE and BLAS or the Intel MKL. If you use the Intel compiler, it is very easy to use the MKL. If you have the MKL available, it is also highly suggested to use the MKL, examples of linking lines are given in the setup.sh script. Otherwise, you should install LAPACK, LAPACKE and BLAS.
  • Boost is used for serialisation and deserialisation, argument parsing and multiprecision floating point values. Version 1.67 works, but earlier versions (starting from ~1.60) may also work if you can handle compiler warnings etc.
  • Doxygen can be used to generate documentation. Version 1.8.11 works flawlessly, 1.8.6 behaves a bit weirdly.
  • tcmalloc can and should be used with the toolkit if possible.
  • liblz4 is used for compression. A version comes bundled with the toolkit, but it is also possible to use the system-provided version.
  • For Python bindings, Python3 development headers are required, e.g. in the libpython3-dev package on Debian.

Suitable Compilers

  • GCC versions 8.2 and up should work seamlessly. Earlier GCC versions are not supported any more, the last "working" commits are tagged as pre-C++17 (for GCC < 7.2) and pre-C++20 (for GCC < 8.2) respectively. Hence, if you have an older compiler, use one of these commits: $ git checkout pre-C++17.
  • Clang is currently untested, but should work provided there is a sufficiently new standard library (e.g. from G++ 8.2). Use the --gcc-toolchain= option to specify the path of that library.
  • The Intel ICC compiler is currently untested.

Boost Installation

Regardless of version used, the installation of the Boost libraries always proceeds in the same way: Once you downloaded and unpacked the boost archive, the following two lines first configure and then install Boost.

$ ./bootstrap.sh --prefix=BOOST_BASE_DIRECTORY --with-libraries=serialization,program_options,date_time,iostreams
$ ./b2 -j8 [cxxflags=-D_GLIBCXX_USE_CXX11_ABI=0] install

where you of course have to adapt your BOOST_BASE_DIRECTORY. Make sure that the version of the STL used here matches the version used later! If you want to use ICC or Clang later, include the cxxflags option, otherwise, remove it.

When using version 1.61, you may encounter warnings similar to

…/include/boost/type_traits/detail/template_arity_spec.hpp:13:84: note: #pragma message: NOTE: Use of this header (template_arity_spec.hpp) is deprecated
 # pragma message("NOTE: Use of this header (template_arity_spec.hpp) is deprecated")

These are harmless, if they annoy you too much, you can simply comment them out in the specified header file.

tcmalloc Installation

tcmalloc is a very fast allocator; using it can speed up especially small calculations by 10-20%. However, it is not a strict requirement, using the standard allocator works equally well, just slower.

If it is already installed on your system, you can just add the following line to your make.inc file (see below):

LDFLAGS_EXTRA+=-ltcmalloc_minimal

Otherwise, you will need to manually download and extract the .so file, e.g. on Debian/Ubuntu, apt-get download libtcmalloc-minimal4 can be used to acquire the package, which can be extracted with dpkg -x. You then only have to copy the file from (e.g.) ./usr/lib/libtcmalloc_minimal.so.4.1.2 to LIBLZ4_LIB_DIR/libtcmalloc_minimal.so.

liblz4 Installation

liblz4 is used for compression. You can either use the version that comes bundled with the toolkit or an already-installed version. If the library is not installed on your computer, you can compile and install the bundled version from within the setup.sh script.

HPTT and TCL Installation

HPTT and TCL are support libraries which can optionally be enabled using environment variables. They’re automatically installed into the writable library directory by the setup.sh script.

setup.sh

setup.sh is a little script that will guide you through the process of creating a make.inc configuration file. This configuration file tells SyTen where to find Boost, the liblz4 library, LAPACKE and BLAS etc. It also tells it which compiler to use and with what flags. If you would like to use multiple compilers (e.g., for testing), you can run setup.sh multiple times writing to different output files.

The script will also create a file envvars.source. Sourcing this file from your terminal will set up the necessary environment variables to allow you to execute the SyTen binaries.

Compile-Time Switches

A number of compile-time switches allow adapting the library to specific usecases, such as real-valued calculations, reduced floating point accuracy etc.

SYTEN_MAX_SYM and SYTEN_MAX_DEG

For performance reason, the data structures used to store the labels of an irrep and those used to store the irreps on a specific tensor length have a compile-time fixed length. This improves data locality and space usage. However, it means that if you want to use more symmetries or groups with a higher degree, you have to recompile the tools/binaries you want to use.

Per default, SYTEN_MAX_SYM is set to 3, i.e. tools can by default handle three symmetries (e.g. two different charges and one spin). If you want to use more symmetries, say 5, in your calculation, pass -DSYTEN_MAX_SYM=5 during compilation. You can do this with e.g. the line CPPFLAGS_EXTRA+=-DSYTEN_MAX_SYM=5 in your make.inc file. Tools compiled with a setting different from those used to build a lattice/state/DMRG file will complain when you attempt to load such a file.

SYTEN_MAX_DEG is set to 2 by default. This means that each irrep can have up to two labels. That is enough for \( \mathrm{U}(1) \), \( \mathrm{SU}(2) \) and \( \mathrm{SU}(3) \) symmetries as well as (due to an implementation quirk) \( Z_k \). Again, this is a compile-time constant, a binary compiled for at most one label cannot read a file created with another binary compiled for two labels. If you wish to use a lower setting, you can do this by e.g. adding the line CPPFLAGS_EXTRA+=-DSYTEN_MAX_DEG=1 in your make.inc file.

SYTEN_COMPLEX_SCALAR

Similar to SYTEN_MAX_SYM and SYTEN_MAX_DEG, SYTEN_COMPLEX_SCALAR allows you to define whether the scalar type used in the dense sub-blocks of tensors is real or complex. By default, it is complex, but if the operators of the problem in question can be written down in purely real terms and you do not wish to do real-time evolution, you can add CPPFLAGS_EXTRA+=-DSYTEN_COMPLEX_SCALAR=0 to your make.inc file. This is again a compile-time constant, you cannot read a complex wavefunction with a tool that is compiled for real numbers.

When this define is set to false (i.e. only real numbers are allowed) some tools will behave differently; e.g. while normally you have to pass in a \( \delta t = -10^{-3} \mathbb{i} \) to do imaginary time evolution with step-size \( 10^{-3} \), you will now have to use a value \( \delta t = 10^{-3} \) to achieve the same result. You can check whether a tool was compiled for real or complex numbers using the --version switch, the default tensor type is given as Standard scalar type.

SYTEN_SDEF_TYPE and SYTEN_SRDEF_TYPE

Again similar to the above, SYTEN_SDEF_TYPE and SYTEN_SRDEF_TYPE allow you define the types of standard dense tensor values. If you only set SYTEN_SRDEF_TYPE (using -DSYTEN_SRDEF_TYPE=float), the base numeric type will be floats. Tensors will then be complex floats (unless you set SYTEN_COMPLEX_SCALAR to a false value). If you also set SYTEN_SDEF_TYPE, that type will be used directly, but you will then also have to tell the toolkit whether it is a complex type or a real type by also defining SYTEN_COMPLEX_SCALAR.

For single-precision real calculations, use either -DSYTEN_COMPLEX_SCALAR=0 -DSYTEN_SRDEF_TYPE=float or -DSYTEN_SDEF_TYPE=float -DSYTEN_SRDEF_TYPE=float -DSYTEN_COMPLEX_SCALAR=0.

For single-precision complex calculations, use -DSYTEN_COMPLEX_SCALAR=1 -DSYTEN_SRDEF_TYPE=float or -DSYTEN_SRDEF_TYPE=float or -DSYTEN_SDEF_TYPE=std::complex<float> -DSYTEN_SRDEF_TYPE=float.

For double-precision real calculations, use either -DSYTEN_COMPLEX_SCALAR=0 -DSYTEN_SRDEF_TYPE=double or -DSYTEN_COMPLEX_SCALAR=0 or -DSYTEN_SDEF_TYPE=double -DSYTEN_SRDEF_TYPE=double -DSYTEN_COMPLEX_SCALAR=0.

Double-precision complex calculations are the default.

SYTEN_STENSOR

To use the new ‘smart’ tensor class, you need to define the SYTEN_STENSOR macro together with the SYTEN_STENSOR_MAX_RANK and SYTEN_STENSOR_RANKS macros. As this class is still work-in-progress, the setup.sh script will not ask you for details about it. To e.g. use smart tensors up to rank 5, define -DSYTEN_STENSOR -DSYTEN_STENSOR_MAX_RANK=5 -DSYTEN_STENSOR_RANKS="0, 1, 2, 3, 4, 5"

Available Targets

The Makefile defines the following targets:

  • make doc: to generate the documentation
  • make copy: to compile and install all executable binaries
  • make pyten-copy: to compile and install the Python module and all Python scripts
  • make copy-all: to compile and install all executable binaries, the Python module and all Python scripts
  • make bin/syten-dmrg--copy: (example) to compile and copy the syten-dmrg binary

Specific Installation Instructions

Installation on Debian

Debian Testing comes with nearly all packages necessary to successfully compile SyTen. As such, if you have root access on the machine, it is very easy to set up. Note that while here we use OpenBLAS, it is highly advisable to use the MKL if you have it.

First, install the necessary packages:

# apt install rsync make git g++ libboost-all-dev liblz4-1 liblz4-dev libopenblas-dev libopenblas-base liblapack3 liblapack-dev liblapacke liblapacke-dev libtcmalloc-minimal4 libgoogle-perftools-dev libpython3-dev ipython3

On a bare system this will take about one gigabyte of hard disk space, but in practice most of these packages are already installed.

The following two caveats apply:

  • OpenBLAS in version 0.2.20 mixes up complex and double pointers. Possible solutions:
    • install OpenBLAS from unstable: apt install -t unstable libopenblas-dev
    • install the Netlib BLAS (apt install libblas-dev) and point the symlink /etc/alternatives/cblas.h-x86_64-linux-gnu at /usr/include/x86_64-linux-gnu/cblas-netlib.h instead of /usr/include/x86_64-linux-gnu/cblas-openblas.h
  • You may see ‘strange’ linking errors complaining about missing symbols such as __zgesvd_stage2 or similar. In this case, you can either
    • install OpenBLAS from unstable as above
    • downgrade liblapacke to version 3.7 from version 3.8

Then, switch back to the user account and run through setup.sh. Select the system-installed Boost and liblz4 libraries as well as g++. No special compiler options are needed to find BLAS and LAPACKE, but make sure to pass -lblas -llapack -llapcke as the linker options. Finally, answer n to using the pre-C++11 ABI and y to using libtcmalloc. No further flags should be necessary.

To compile, execute

$ make copy -jN

where you replace N by the number of processors available on your system or the number of gigabytes of RAM available (each g++ instance takes roughly 1GB peak RAM). After a while, everything should be compiled and copied into place. If the external binary directory is already in your path, you should then be able to execute e.g. syten-add without problems. Otherwise, source envvars.source to add the directory to your PATH variable. To compile the Python binding, say

$ make pyten-copy -jN

You will likely have to source envvars.source then in order to set up the PYTHONPATH environment variable.