Spintrum

A high-performance library for spin simulations, written by Samer Afach

####purpose Spintrum creates an interface between a high-performance and low-level language (C/C++) and an easy to use and high level language (Python).

##Installation

Spintrum is supported only on Linux/Unix systems, and is primarily tested on Debian. For explanation, look at the FAQ below. If you'd like to compile Spintrum on operating systems other than debian, your efforts to do it will be minimal.

#####Prerequisites

• Linux/Unix (preferably Debian)
• OpenBLAS (read below)
• Polymath (read below)
• cmake
• Python 3.4+
• g++ 4.8+

#####In Python, the following libraries are required

• numpy
• scipy
• mpmath
• matplotlib

#####Do I need to compile OpenBLAS? This depends on the performance you're trying to achieve. OpenBLAS, when compiled, creates binaries that are processor-specific, in order to achieve the best possible performance. In order to exploit this feature, it's recommended that you compile OpenBLAS.

Don't panic, as you don't have to do this yourself from scratch. The script get_openblas.sh should do this for you. It clones the OpenBLAS repository, and changes the optimization level of the compiler settings, and does the compilation. Run it using sh get_openblas.sh.

#####What optimization level should I take for OpenBLAS? The default optimization level for OpenBLAS is -O2, which is fair. The script get_openblas.sh changes all optimization flags by default to -Ofast. This is an extreme exaggeration, and may cause problems. I recommend using O2 for tests, and going to Ofast once everything is prepared. Please read the link that explains what these optimization flags mean. Then, edit the file set_openblas_optimization.py, and change the variable target_optimization to the desired optimization level.

#####What if I don't want to compile OpenBLAS? The compilation script in the directory Spintrum expects a compiled version of OpenBLAS, either in the default directory that the script get_openblas.sh downloads and installs to, or an installed version of OpenBLAS in the operating system. Keep in mind that the default OpenBLAS in the Linux operating systems are not generally optimized for your processor.

#####Do I need Polymath? Definitely! Polymath is a C++ interface to BLAS. It was also written by Spintrum team to separate the Maths library from the programming. Use the script get_polymath.sh to clone Polymath.

#####How to install? In the directory Spintrum, there's a Makefile that will do everything for you. Simply run the command make in that directory, and then if everything runs correctly, and no error messages are issued, run make install as root/superuser to install spintrum on your Python installation.

#####How to install missing prerequisites on Debian? Simply run the following in the terminal (as superuser/root):

# apt-get install build-essential cmake g++ gcc python3
# pip3 install numpy scipy mpmath matplotlib

Note: The # means that these commands have to be executed as root. Don't literally type that # in the terminal.

#####Testing whether it works After a successful installation, simply try the examples in the examples directory. They should all work, assuming you have

#####Caveat about Jupyter Spintrum works fine on Jupyter, except that the stdout and stderr output cannot be seen on Jupyter notebooks for technical reasons. So, if there's a message from the low-level C/C++, it won't be seen. Although unlikely, but in case you have an error and you can't figure out the reason, try running the script in terminal, and see whether the C/C++ interface is reporting an error.

##FAQ

• Q: Why is spintrum not supported on Windows?
• A: Ignoring that Windows is way slower than Linux for calculations; Spintrum uses the well-known high-performance linear algebra library OpenBLAS. And since Python 3.5+ is compiled on Visual Studio 2015, and since Spintrum uses ctypes, which is the shared-library interface of Python, binary compatibility has to be achieved between Python and the compiled Spintrum library. On the other hand, OpenBLAS does not support compilation on Visual Studio with 64-bit (it supports only 32-bit), meaning that only small spin systems will be properly supported, since memory of 4+ GB cannot be used, which is not worth the effort, as too many changes have to be done to make Spintrum compatible with Windows. In the worst case, use a VMWare Workstation on your Windows Machine, and you'll get the best performance.