samerafach/Spintrum
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fix README.md heads

Browse Source
This commit is contained in:
Samer Afach 2017-01-14 12:33:01 +01:00
parent d5225ddc0a
commit 7a07d2c8c8
1 changed files with 11 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
README.md
View File

@ -2,14 +2,14 @@
A high-performance library for spin simulations, written by Samer Afach A high-performance library for spin simulations, written by Samer Afach
####purpose #### 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). 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 ## 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. 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 ##### Prerequisites
- Linux/Unix (preferably Debian) - Linux/Unix (preferably Debian)
- OpenBLAS (read below) - OpenBLAS (read below)
- Polymath (read below) - Polymath (read below)
@ -17,19 +17,19 @@ Spintrum is supported only on Linux/Unix systems, and is primarily tested on Deb
- Python 3.4+ - Python 3.4+
- g++ 4.8+ - g++ 4.8+
#####In Python, the following libraries are required ##### In Python, the following libraries are required
- numpy - numpy
- mpmath - mpmath
#####Do I need to compile OpenBLAS? ##### 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. 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.
The installer automatically installs OpenBLAS for you. If you would not like to have OpenBLAS compiled for you, then use the `Makefile` script through calling `make`, which will ask whether you want to have OpenBLAS compiled for you. Then, you're free to use the directory `spintrum` independently as a package, or copy it yourself to your Python installation. You have to have OpenBLAS installed on your system to have this work; otherwise, the compilation will fail. The installer automatically installs OpenBLAS for you. If you would not like to have OpenBLAS compiled for you, then use the `Makefile` script through calling `make`, which will ask whether you want to have OpenBLAS compiled for you. Then, you're free to use the directory `spintrum` independently as a package, or copy it yourself to your Python installation. You have to have OpenBLAS installed on your system to have this work; otherwise, the compilation will fail.
#####Do I need Polymath? ##### Do I need Polymath?
Definitely! Polymath is a C++ interface to BLAS. It was also written by the Spintrum team to separate the Maths library from the programming. The installer will get Polymath for you automatically from its repository. Definitely! Polymath is a C++ interface to BLAS. It was also written by the Spintrum team to separate the Maths library from the programming. The installer will get Polymath for you automatically from its repository.
#####How to install? ##### How to install?
There are two ways: There are two ways:
- Use `pip` to do the installation for you with the command: - Use `pip` to do the installation for you with the command:
@ -42,22 +42,22 @@ Note: The `#` means that these commands have to be executed as root. Don't liter
- Or, you can use Spintrum as an independent package, by cloning the repository `https://git.afach.de/samerafach/Spintrum` yourself, and running `make`. - Or, you can use Spintrum as an independent package, by cloning the repository `https://git.afach.de/samerafach/Spintrum` yourself, and running `make`.
#####How to install missing prerequisites on Debian? ##### How to install missing prerequisites on Debian?
Simply run the following in the terminal (as superuser/root): Simply run the following in the terminal (as superuser/root):
```sh ```sh
# apt-get install build-essential cmake g++ gcc gfortran python3 python3-pip # apt-get install build-essential cmake g++ gcc gfortran python3 python3-pip
``` ```
#####Testing whether it works ##### Testing whether it works
After a successful installation, simply try the examples in the `examples` directory. They should all work, assuming you have everything installed correctly. The dependencies of the examples are different than Spintrum itself. For example, the examples use Matplotlib, which plots signals and spectra. You have to install this yourself. On Debian, you can `sudo apt-get install python3-matplotlib` to do that. Also for fitting scripts, the package `scipy` is used, which you can install using `sudo pip3 install scipy`. After a successful installation, simply try the examples in the `examples` directory. They should all work, assuming you have everything installed correctly. The dependencies of the examples are different than Spintrum itself. For example, the examples use Matplotlib, which plots signals and spectra. You have to install this yourself. On Debian, you can `sudo apt-get install python3-matplotlib` to do that. Also for fitting scripts, the package `scipy` is used, which you can install using `sudo pip3 install scipy`.
#####Caveat about Jupyter ##### 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. 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 ## FAQ
- **Q:** Why is spintrum not supported on Windows? - **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 Virtual Machine on your Windows Machine, and you'll get the best performance. - **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 Virtual Machine on your Windows Machine, and you'll get the best performance.