Download and installation¶
Here are the guidelines to install S4 and the Python API either as a Conda package or Building from source
Installing S4 and the Python API¶
Conda package¶
If you run Anaconda, S4 can be installed as a conda package. From an anaconda prompt
conda config --add channels conda-forge
conda upgrade conda
To add the channel conda-forge as one of the default channel for downloading packages and upgrade all you packages. Create a new dedicated conda environment (e.g with python 3.7:
conda create -n s4 python=3.7
Activate the environment and install the package:
conda activate s4
conda install -c paulgoulain s4
You should be able to import the S4 module in a python prompt:
import S4 as S4
Building from source¶
You can download S4 on github, however we recommend using slightly more up-to-date forks of the original code, by cloning e.g.
git clone https://github.com/phoebe-p/S4
cd S4
or
git clone https://github.com/marcus-o/S4
cd S4
Windows¶
To be added
Linux¶
Two options are proposed, depending on which optional libraries you use for the linear algebra (BLAS and Lapack), Fourier transform (FFT) and matrix factorization (CHOLMOD).
The first one makes use of the (free but proprietary) Math Kernel Library (MKL) from Intel, which largely improves performances (at least on Intel CPUs). jump
The second one uses only open-source libraries (OpenBlas, FFTW3 and CHOLMOD (SuiteSparse), at the risk of lower performances. jump
Proprietary option
The first step is to install the MKL libraries:
sudo bash
# <type your user password when prompted. this will put you in a root shell>
# cd to /tmp where this shell has write permission
cd /tmp
# now get the key:
wget https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS-2019.PUB
# now install that key
apt-key add GPG-PUB-KEY-INTEL-SW-PRODUCTS-2019.PUB
# now remove the public key file exit the root shell
rm GPG-PUB-KEY-INTEL-SW-PRODUCTS-2019.PUB
exit
# add the repository
sudo sh -c 'echo deb https://apt.repos.intel.com/mkl all main > /etc/apt/sources.list.d/intel-mkl.list'
# update the package list
sudo apt update
You can now install one of the MKL releases. Since you have to specify the component you wish to install, you can check for the version list
## exemple intel-mkl-2020.0-088
sudo apt install intel-mkl-<VERSION>.<UPDATE>-<BUILD_NUMBER>
We also need the OpenMP and suitespares-dev libraries:
# OpenMP
sudo apt install libomp-dev
# CHOLMOD
sudo apt-get install libsuitesparse-dev
The correct compilation flags have to be set in the Makefile to use the MKL libraries. Edit the following lines if necessary, the other options should work:
BLAS_LIB = -lmkl_rt
LAPACK_LIB = -lmkl_rt
FFTW3_INC =
FFTW3_LIB = -lfftw3
Then from a command prompt in the S4 folder:
make boost
make S4_pyext
Note
You might have to adapt the end of the Makefile to use the correct pip installer. pip3 is used by default, but if you want to install S4 in a particular environment, you should first activate it before running make S4_pyext.
In case an error occurs, it is most probably because the MKL libraries were installed somewhere where the compiler does not find them (e.g in /opt/). Either use the provided .sh script in the bin subdirectory of the installation directory (following this link ):
$(MKLdir)/bin/compilervars.sh
Or manually link them using (might require sudo):
ln -s $(MKLdir)/*.so /usr/lib/$(where_to_store)
i.e in my case:
sudo ln -s /opt/intel/compilers_and_libraries/linux/mkl/lib/intel64/*.so /usr/lib/x86_64-linux-gnu/
Everything should compile without any errors or warnings.
Open source option
We start by installing the OpenBlas and CHOLMOD libraries:
## linear alegra blas and lapack
sudo apt-get install libopenblas-dev
## fourier transform fftw3
sudo apt-get install libfftw3-dev
## CHOLMOD for some fourier decompositions
sudo apt-get install libsuitesparse-dev
Check that the Makefile contains the following lines (all other options should already be set):
BLAS_LIB = -lblas
LAPACK_LIB = -llapack
FFTW3_INC =
FFTW3_LIB = -lfftw3
Then compile:
make boost
make S4_pyext
Note
You might have to adapt the end of the Makefile to use the correct pip installer. pip3 is used by default, but if you want to install S4 in a particular environment, you should first activate it before running make S4_pyext.
Everything should compile without any errors or warnings.
Installing S4Utils¶
Installing S4Utils only requires pip. From a command prompt in the main S4Utils directory:
pip install ./
Should run without any trouble. The last tutorial script Tutorial 4: Dispersive Metal-Insulator-Metal grating (download script) uses some of S4Utils functions and should thus run if the installation is successful.