sisl is easy to install using any of your preferred methods.
Running sisl requires these versions:
Python 3.7 or above
numpy (1.13 or later)
scipy (0.18 or later)
pyparsing (1.5.7 or later)
pytest (for running the test suite)
pathos (for parallel BrillouinZone calculations)
tqdm (for displaying progress-bars)
xarray (for advanced table data structures in certain methods)
plotly (for advanced visualization)
sisl implements certain methods in Cython which speeds up the execution. Cython is required if one wishes to re-generate the C-sources with a different Cython version. Note that this is not a necessary step and should typically only be considered by developers of Cython modules.
Installing sisl using PyPi can be done using
python3 -m pip install sisl # for better analysis python3 -m pip install sisl[analysis] # for advanced plotting functionality python3 -m pip install sisl[viz]
pip will automatically install the required dependencies. The optional dependencies
will be used if later installed.
The latter installations call also installs dependent packages which are part of extended analysis methods. These are not required and may be installed later if their usage is desired.
When wanting to pass options to
pip simply use the following
python3 -m pip install --install-option="--compiler=intelem" --install-option="--fcompiler-intelem" sisl
note that options are accummulated.
It is recommended to install sisl in a separate environment to decouple its dependencies from other packages that may be installed. To find more information about the conda-forge enabled versions please see here.
conda is a somewhat fragile environment when users want to update/upgrade packages. Therefore when conda installations fails, or when it will not update to a more recent version it is advisable to create a new environment (starting from scratch) to ensure that your currently installed packages are not limiting the upgrading of other packages.
For sisl there are two options, whether one wants to use a stable sisl release, or be able to install the latest development version from here.
Installing the stable sisl release in conda all that is needed is:
conda create -n sisl conda activate sisl conda config --add channels conda-forge conda install -c conda-forge python=3.9 scipy matplotlib plotly netcdf4 sisl
which will install all dependencies including the graphical visualization capabilities of sisl.
Installing the development version of sisl requires some other basic packages
while also using
pip to install sisl, the procedure would be:
conda create -n sisl-dev conda activate sisl-dev conda config --add channels conda-forge conda install -c conda-forge fortran-compiler c-compiler python=3.9 conda install -c conda-forge scipy netcdf4 cftime plotly matplotlib
Subsequent installation of sisl in your conda enviroment would follow Development version.
pip codes may be used to install git clones or downloaded
python3 -m pip install . --prefix=<prefix>
sisl on Windows one will require a specification of
the compilers used. Typically one may do
python3 -m pip install . --prefix=<prefix> --install-option='--fcompiler=gfortran' --install-option='--compiler=mingw32'
setuptools does not intercept the flags in the build process.
To remedy this please ensure
%HOME%\pydistutils.cfg contains the build options:
[build] compiler = mingw32 fcompiler = gfortran
Testing your installation
After installation (by either of the above listed methods) you are encouraged to perform the shipped tests to ensure everything got installed correctly.
Note that pytest needs to be installed to run the tests. Testing the installation may be done by:
pytest --pyargs sisl
The above will run the default test-suite which covers most of the
Additional tests may be runned by cloning the sisl-files
and setting the environment variable SISL_FILES_TESTS as the
tests path to the repository.
A basic procedure would be:
git clone https://github.com/zerothi/sisl-files.git SISL_FILES_TESTS=$(pwd)/sisl-files/tests pytest --pyargs sisl
For source/development installations some basic packages are required:
To install the development version using
pip you may use the URL command:
python3 -m pip install -U git+https://github.com/zerothi/sisl.git
Otherwise follow the manual installation by cloning the git repository.
Remark that the
git+https protocol is buggy (as of pip v19.0.3) because you cannot pass compiler
setuptools. If you want to install the development version with e.g.
the Intel compilers you should do:
git clone git+https://github.com/zerothi/sisl.git cd sisl python3 -m pip install . -U --build-option="--compiler=intelem" --build-option="--fcompiler=intelem" .
which will pass the correct options to the build system.
The -U flag ensures that prior installations are overwritten.