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

Updated README.md

Browse Source
This commit is contained in:
Samer Afach 2017-09-02 21:14:30 +02:00
parent 787b1498dc
commit 0bbadd8a40
1 changed files with 28 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
README.md
View File

@ -1,13 +1,18 @@
# Spintrum
A high-performance library for spin simulations, written by Samer Afach
A high-performance library for spin simulations, written by Samer Afach as part of the Budker Group in University of Mainz
#### 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).
The library depends primarily on very good C/C++ programming to get fast result. No fancy physics is used in the library (so far).
#### How does it work?
As you will notice, the installation has two parts. The first one is building spintrum, which builds the shared library `libspintrum.so` and puts it in the package directory of Python, and the second part is installing that package into Python, which you can do if you wish. It is not mandatory.
## 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 (Jessie and Stretch). 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, assuming you are not trying to do it on Windows.
##### Prerequisites
- Linux/Unix (preferably Debian)
@ -20,14 +25,28 @@ Spintrum is supported only on Linux/Unix systems, and is primarily tested on Deb
##### In Python, the following libraries are required
- numpy
- mpmath
- matplotlib (for the examples only)
##### 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.
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 compiles OpenBLAS for you. If you would not like to have OpenBLAS compiled for you, then use the `Makefile` by running `make`. It 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 (whether compiled for you or installed by your system); spintrum compilation will fail.
#### How to build?
In case you choose to build this manually, follow the following steps:
- Clone the repository to some directory
- Go to that directory with your terminal
- Call `make` there.
At that point you will get a directory called `spintrum`, which is the Python package that you can use or copy.
Remember that the required software must be installed beforehand.
##### 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 simple C++ interface to BLAS. It was also written by the Spintrum team to separate the Maths library from the programming of Spintrum. The installer will get Polymath for you automatically from its repository.
##### How to install?
There are two ways:
@ -37,9 +56,9 @@ There are two ways:
# pip3 install git+https://git.afach.de/samerafach/Spintrum
```
Note: The `#` means that these commands have to be executed as root. Don't literally type that `#` in the terminal. This will install dependencies for you, too.
Note: The `#` means that these commands have to be executed as root. Don't literally type that `#` in the terminal. This command will install some of the dependencies for you, too.
- 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` to build.
##### How to install missing prerequisites on Debian?
@ -49,6 +68,8 @@ Simply run the following in the terminal (as superuser/root):
# apt-get install build-essential cmake g++ gcc gfortran python3 python3-pip
```
On Redhat versions of linux, find the equivalent package names and use `yum` or `dnf` to install the same dependencies.
##### 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`.