zerothi / sisl

Electronic structure Python package for post analysis and large scale tight-binding DFT/NEGF calculations

sisl

Copyright Nick R. Papior 2024

sisl is an open-source easy-to-use density functional theory API framework to post-analyse density functional theory codes output as well as providing tight-binding calculation capabilities. It couples to a wide range of density functional theory codes and has a high connection with LCAO codes such as Siesta. The tight-binding matrices can be used in non-equilibrium Green function calculations with TBtrans as a backend. API for creating publication ready graphs and images.

Features

• Simple command-line interface: To extract or quickly plot calculation output
• Tight-binding API: Easily create (non-) orthogonal tight-binding matrices and do electronic structure analysis
• Manipulation of sparse matrices: Extract, replace, append matrices and sub-matrices to one another
• Post analyse DFT simulations: Post-process LCAO Hamiltonians by doing (projected) density of states, inverse participation ratio and many more
• Post analyse NEGF simulations: Effectively create and post-analyse NEGF output from TBtrans
• Real-space grid analysis: Perform mathematical operations on DFT real-space grid outputs, spin-density differences and wavefunction plots
• Conversion of geometries and real-space grid: Easy conversion of geometry files and real-space grid file formats (cube, xsf, etc.)
• User contributed toolboxes: Users may contribute toolboxes for sharing methodologies
• Interoperability with other codes: ASE and pymatgen
• and many more features

Tutorials and examples

The easiest way to get started is to follow the tutorials here and the workshop material for TranSiesta here.

Documentation

Please find documentation here:

• Documentation
• API documentation
• Installation

Community support

There are different places for getting information on using sisl, here is a short list of places to search/ask for answers:

• Ask questions on the Discord page
• Ask questions on the Github issue page
• Documentation, recommended reference page
• Workshop examples showing different uses

If sisl was used to produce scientific contributions, please use this DOI for citation. We recommend to specify the version of sisl in combination of this citation:

@software{zerothi_sisl,
  author = {Papior, Nick},
  title  = {sisl: v<fill-version>},
  year   = {2024},
  doi    = {10.5281/zenodo.597181},
  url    = {https://doi.org/10.5281/zenodo.597181}
}

To get the BibTeX entry easily you may issue the following command:

sdata --cite

which fills in the version number.

Contributing

Kindly read our Contributing Guide to learn and understand about our development process, how to propose bug fixes and improvements, and how to build and test your changes to sisl.

Contributors

License

sisl © 2024, Released under the Mozilla Public License v2.0.

sisl's Issues

Square keyword for default geometries should be orthogonal

It is not correct that the returned geometry is square, rather it is orthogonal. Only for certain cells would an orthogonal lattice be square (Xcc for example)

Example of adding delta H/delta Sigma in tbtrans calculation

In this paper (Computer Physics Communications, 212, pp.8-24), there is a section regarding adding a correction term $\delta H$ in the Hamiltonian. In practice, I guess that you can generate a 'delta.nc' file and add tag 'TBT.dH delta.nc' in the input file for tbtrans.

Meanwhile, I realize this python code is capable of adding $delta H$ or $delta \Sigma$ term as well, which is nice. I assume this can be realized by defining class sisl.io.tbtrans.deltancSileTBtransare.

My question is given that I have a 'device.TBT.nc' file from a standard tbtrans calculation, how to properly generate this delta H/Sigma class, say e.g. a k-dependent E-dependent delta Sigma, such that I can further calculate the transmission based on the modified Hamiltonian. Or do I have to re-run the tbtrans code to get the transport properties of interest based on the modified Hamiltonian?

Enable sisl to generate charge grids

Currently the charge can easily be calculated by performing np.absolute(psi(...)) however, when using a density matrix it may be better to do something different.

At this instance dRho may be easy to compute, while full Rho may not be as easy. In this case the Orbital class is required to add a field called "inital charge".

Split Hamiltonian into Overlap matrix and Hamiltonian

This makes much more sense and one may use pass by reference to re-use the overlap matrix, if needed.

Then the orthogonal keyword would act as:

1. bool, create a new overlap matrix object
2. Overlap, assign the local overlap matrix

Geometry.close(...) call with keyword "idx=" specified

Revision SISL e1ec907

This code fails to run:

from future import print_function, division
import sisl
import numpy as N
xyz = [[i,0,0] for i in range(10)]
geom = sisl.Geometry(xyz)
dR = (0.1,1.1)
for ia in geom:
idx = geom.close(ia, dR=dR)
for ia in geom:
idx = geom.close(ia, dR=dR, idx=range(5))

First loop is OK, the second one fails

Error message:
Traceback (most recent call last):
File "test.py", line 17, in
idx = geom.close(ia, dR=dR, idx=range(5))
File "/scratch/thf/SOFTWARE/python/2.7.10/gcc-4.9.2/packages/sisl/e1ec907/gcc-4.9.2/lib/python2.7/site-packages/sisl/geometry.py", line 1266, in close
ret_dist=ret_dist)
File "/scratch/thf/SOFTWARE/python/2.7.10/gcc-4.9.2/packages/sisl/e1ec907/gcc-4.9.2/lib/python2.7/site-packages/sisl/geometry.py", line 1051, in close_sc
idx = idx[ix]
TypeError: only integer arrays with one element can be converted to an index

Any clue?

API for command line utilities with out-file dependent arguments

Say if one does:

sdata <Geometry> --<opts> --out test.xsf

one should be able to add forces or any other vector information. However, such option is only applicable to a subset of output files.

sids installation

Dear Nick,

As you suggested, I downloaded the package (0.4.8) via https://github.com/zerothi/sids/releases. To be honest, I am not able to install sids through pypi interface due to the restrictions applied by the supercomputer. When I tried to install sids using the following command manually,

python setup.py install --prefix=$HOME/LOCAL_APPS/SIDS

the systems echoed a fatal error, something like
"fatal: Not a git repository (or any of the parent directories): .git
/apps/python/2.7.6/lib/python2.7/distutils/dist.py:267: UserWarning: Unknown distribution option: 'test_suite'
warnings.warn(msg)"

Your kind suggestions will be appreciated. Cheers!

Jin

Progress-bar/ETA for construct function

for large scale system setups it would be nice to know the time consumption

Easy access to supercell index

There needs to be an easy way of indexing a supercell orbital to ease the creation of the Hamiltonian.

For instance this could be a good idea :

H[i, j, (0, 0, 0)] 

Where the tuple differentiates it from the orbital index.

sgrid is not working, the `nargs` keyword is probably at works

Geometry/Hamiltonian indexing should adhere to numpy standards

Currently querying standard elements from a Geometry class always returns arrays, while it should return the dimensionality as the input, scalar, -> reduced dimensionality.

This is mainly to adhere with the intrinsic numpy standard.

Allow bond-currents in the supercell picture

Currently it isn't possible to create bond-currents in the supercell picture.

Make SparseCSR take the regular sparse matrix data as __init__

Currently the SparseCSR only accepts shape as its argument, but it should also take in the data in the typical scipy-way.

Orbital class

There is currently no way of dealing with eigenvectors of eigenstates.

To be able to create real-space grids one needs some way of describing the orbital. For this an exact methodology of creating orbital classes may be required:

i.e. (see e.g. wiki: https://en.wikipedia.org/wiki/Atomic_orbital)

• Hydrogen like orbital
• Slater-type orbital
• Gaussian type orbital

conda build does not work, their API changed using the __conda_version__ file

We need to fix this for the next release.

k-point class

A k-point class is needed for constructing k-points on paths

Create fast lapack functions

Instead of using solve, dot etc we may speed things up by simplifying some of the routines, e.g. eigh and solve.

Add vector object to abstract geometry and forces into a similar feature

Instead of having a geometry object with similar features, it would be nice to have a vector object which takes into account the basic routines for duplicating stuff, etc.

I.e. the geometry should inherit the vector class.

ImportError: No module named sids

Dear Nick,

Many thanks for your response!

Although the system echoed the error message, it seemed that the installation proceeded all right. After the installation, two files, e.g. sgeom and sgrid, were generated in the /bin folder. When I ran either of these two bin files at the terminal,

sgrid

I got the following rror message,

File "sgrid", line 15, in
import sids
ImportError: No module named sids

May I have your suggestions? Cheers!

Jin

Overload math operators on SparseCSR and Hamiltonian object

Currently it is very difficult to perform similar transformations on all sparse data in the SparseCSR and Hamiltonian objects.

We need 2 things:

1. an attribute which returns a handle to _D in SparseCSR
2. Overload __*__ operators in SparseCSR in addition to an overload mechanism for propagating overloads easily.

VESTA file-formats

Allow VESTA file-formats for better compatibility.

Add F90 files for reading siesta files

The siesta IO files cannot be read as the F90 files are not part of sisl.

ex_03.py in sisl/examples could not finish normally.

Dear Nick,

Drawing on your advice, I firstly installed 4.1-b3 of Siesta.
Next, I obtained an execution file of "phtrans" by just typing "make phtrans",
at "siesta-4.1-b3/Util/TS/TBtrans/" .

So I tried to run ex_03.py in sisl/examples, but I could not finish it normally.

What I did so far are followings:
(1) python ex_03.py
=> obtained {zz.gin, ZZ.fdf}.
(2) gulp < zz.gin >zz.gout
=> seems to be finished normally.
(3) python ex_03.py
=> obtained {ELEC_zz.nc, DEVICE_zz.nc}
(4) phtrans <ZZ.fdf >ZZ.out
=>obtained the following message:
forrtl: severe (24): end-of-file during read, unit 12, file /home/satoru/work/sisl.test/DEVICE_zz.nc

ZZ.out

PHtrans Version: siesta-4.1--736
Architecture : x86_64-unknown-linux-gnu--unknown
Compiler flags: mpif90 -g
PP flags : -DMPI -DFC_HAVE_FLUSH -DFC_HAVE_ABORT -DTBTRANS -DTBT_PHONON
Libraries : -lmkl_scalapack_lp64 -lmkl_blacs_openmpi_lp64 -lmkl_lapack95_lp64 -lmkl_blas95_lp64 -lmkl_intel_lp64 -lmkl_sequential -lmkl_core -lpthread
PARALLEL version

• Running in serial mode with MPI

Start of run: 2-JAN-2018 17:27:19

                       ************************
                       *  WELCOME TO PHtrans  *
                       ************************

reinit: Reading from standard input
************************** Dump of input data file ****************************
SystemLabel ZZ
TBT.DOS.Gf T
TBT.k [51 1 1]
TBT.HS DEVICE_zz.nc
%block TBT.Contour.line
part line
from 0. eV to .23 eV
points 400
method mid-rule
%endblock TBT.Contour.line
%block TBT.Elec.Left
HS ELEC_zz.nc
semi-inf-direction -a2
electrode-position 1
%endblock
%block TBT.Elec.Right
HS ELEC_zz.nc
semi-inf-direction +a2
electrode-position end -1
%endblock
************************** End of input data file *****************************

reinit: -----------------------------------------------------------------------
reinit: System Name:
reinit: -----------------------------------------------------------------------
reinit: System Label: ZZ
reinit: -----------------------------------------------------------------------

sdata not generating output file in the latest revision.

Hi, after update, I couldn't get an output file anymore, here is the command I use with the output file from siesta.
sdata graphene.TBT.AV.nc --atom 1 --dos --ados Left -o test.dat

Here are the updating information.
wang10@h2ologin2:~/temp> pip install --user sisl --upgrade
Collecting sisl
Downloading sisl-0.8.2.tar.gz (161kB)
100% |\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 163kB 1.6MB/s
Requirement already up-to-date: six in /mnt/a/sw/xe_xk_cle5.2UP02_pe2.3.0/bwpy/0.3.0/python-single/usr/lib/python2.7/site-packages (from sisl)
Collecting setuptools (from sisl)
Downloading setuptools-34.3.3-py2.py3-none-any.whl (389kB)
100% |\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 399kB 1.4MB/s
Collecting numpy>=1.9 (from sisl)
Downloading numpy-1.12.1-cp27-cp27mu-manylinux1_x86_64.whl (16.5MB)
100% |\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 16.5MB 42kB/s
Collecting scipy (from sisl)
Downloading scipy-0.19.0-cp27-cp27mu-manylinux1_x86_64.whl (45.0MB)
100% |\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 45.0MB 15kB/s
Collecting netCDF4 (from sisl)
Downloading netCDF4-1.2.7-cp27-cp27mu-manylinux1_x86_64.whl (5.7MB)
100% |\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 5.7MB 109kB/s
Collecting packaging>=16.8 (from setuptools->sisl)
Downloading packaging-16.8-py2.py3-none-any.whl
Collecting appdirs>=1.4.0 (from setuptools->sisl)
Downloading appdirs-1.4.3-py2.py3-none-any.whl
Collecting pyparsing (from packaging>=16.8->setuptools->sisl)
Downloading pyparsing-2.2.0-py2.py3-none-any.whl (56kB)
100% |\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 61kB 835kB/s
Building wheels for collected packages: sisl
Running setup.py bdist_wheel for sisl ... done
Stored in directory: /u/sciteam/wang10/.cache/pip/wheels/99/c1/11/a73a78c9975980be20a832e0614f04ba36c6723c762977a126
Successfully built sisl
Installing collected packages: pyparsing, packaging, appdirs, setuptools, numpy, scipy, netCDF4, sisl
Found existing installation: sisl 0.8.1
Uninstalling sisl-0.8.1:
Successfully uninstalled sisl-0.8.1
Successfully installed appdirs-1.4.3 netCDF4-1.2.7 numpy-1.12.1 packaging-16.8 pyparsing-2.2.0 scipy-0.19.0 setuptools-34.3.3 sisl-0.8.2

Parallelization of "construct"

For very large systems this would be really useful.

pip install sisl fails if numpy is not installed

Using pip install sisl requires numpy to be installed prior to installation.

This is because the numpy.distutils subpackage is used in sisl setup.py.

Try and circumvent this by backfalling to setuptools. However, can we ensure numpy.distutils after requirements has been meet?

Change to pytest, from nose

The current testing platform (nose) has some deficiencies.

Secondly pytest has a lot more traction.

Spin-polarized Hamiltonians

The spin-polarized Hamiltonians should be possible using sisl, however, there are mistakes.

Currently this is easy to bypass as one simply creates two Hamiltonians (spin-polarizations are independent)

Cut the supercell from GULP

Following the advice you provided in last issue, I tried to generate a supercell with x and y periodicity and then cut it twice by
el = el.cut(3,1,seg=1) el = el.cut(3,0,seg=1)
But I find that the positions out of this is totally messed up. How should one set the position of supercell initially to make the later cut work perfectly? Also, do we have to add optimization tag in GULP?
For the device region, should I also add x and y periodicity?

Fdf reading and consistencies

When reading geometries from the fdf file there are a few inconsistencies:

• if a keyword is in comments in the file it can read erroneously
• reading a geometry should be based on XV file, if present or the nc files. It should reflect what the other output files contain. I. E. a DM file contains the latest coordinates.
• possibility of reading specific output from fdf
• add warnings when reading incomplete data, DM etc.
• read supercell information from ORB_INDX file or other.

Allow Cython objects by shipping Cython compiled source-code

This enables the use of faster objects for faster execution and also paves the way for creating SIESTA I/O with binaries.

Finalize conda setup

We need to add sisl to conda

Add COOP/COHP analysis to TBt.nc file

Since today TBtrans can calculate COOP/COHP curves and we may evaluate these rather similar to the bond-currents.

We simply need to add interfaces for this in the tbt.py file.

Move __init__ docstrings to end of class docstring to have documentation of parameters

Cut

I construct a supercell and try to generate the matrix needed for phtrans calculation. When I try to cut the structure for the electrode from a BBB structure into just B, I met this problem and cannot get rid of it by all possible means. I hope you can offer some suggestions to correct this. Thanks.

File "ex48.py", line 418, in
el = dyn1.cut(3,2,seg=1)
File "/home/qichen/.local/lib/python2.7/site-packages/sisl-0.9.2+389-py2.7-linux-x86_64.egg/sisl/sparse_geometry.py", line 1378, in cut
if issubclass(w[-1].category, SislWarning):
NameError: global name 'SislWarning' is not defined

Shapes require major rewriting

All shapes are in dire need for a complete rewrite.

We need these details

• Adding two shapes + (inclusion), - (subtraction)
• ensure the basic shapes have vectors such that skewed shapes can be used
• enable Grid.index to accept shapes (extremely convenient for skewed shapes)
• Convert any shape into a maximum sphere which is ensured to contain all points in the parent shape. I.e. a sphere with a radius equal to the farthest point
• when using & operator and converting to a sphere one can easily reduce the actual sphere by performing some simple arithmetic measures.

MonkhorstPack grid is not Gamma centered

Add link to transiesta+tbtrans+sisl tutorial

Use grid in `iter_block` to create explicit blocks

Currently the iter_block is non-deterministic and it randomly selects atoms.
The algorithm may greatly be improved by creating blocks and looping the centers of the blocks.

I think we can easily implement this using the Grid class with offset, and min/max of atomic coordinates.
Then we loop on all corners of the grid and do the selection there. This should limit the iter_block greatly and further speed up construct.

SuperCell.origo has no unique function

Currently the origo attribute of SuperCell and their children does not have a conforming usage.

I.e. should all atomic coordinates be shifted according to the origo, or should they be relative?
It is easier relative, but it may not be what people expect?

Create an IPython siesta analysis tutorial

• molecule analysis
• non polarised (k)
• polarised (k)
• non-colinear (k)
• spin-orbit (k)
• grid handling
• wavefunctions
• integration of stuff

How to run ex_03.py in sisl/examples ?

Hello Developers,

I would like to know how to run ex_03.py in sisl/examples.

What I did so far are followings:
(1) python ex_03.py
=> obtained {zz.gin, ZZ.fdf}.
(2) gulp < zz.gin >zz.gout
=> seems to be finished normally.
(3) python ex_03.py
=> obtained {ELEC_zz.nc, DEVICE_zz.nc}
(4) tbtrans <ZZ.fdf >ZZ.out
=> could not finish normally.
In the tail of ZZ.out, "Must specify k-points with Monkhorst_Pack".

Thanks much,
satoru

Tests for io stuff

There is very little tests of the io routines. We should try and have more of these!

Create Hk in Cython

This should drastically speed up BrillouinZone average calculations

Add sisl to conda-forge

fork conda-forge to create a new feedstock

The atoms object is duplicated for each atom

This makes the geometry object heavy. Instead we should make it a property to set get an indexed atom list such that no duplication is made.

Thiswill make it easier to host the orbital classes with full real-space data.

Move scripts to entry_points for easier testing and maintenance

The entry_points segment is really useful for creating scripts interfaced directly in the code.

See for instance this entry which has the required information for the implementation:
http://stackoverflow.com/questions/774824/explain-python-entry-points

Add TBT.SE.nc file

Move io.*.* to io.*._* to reduce cluttered documentations

Currently all submodules are listed in the respective software headers, instead we should make the software header module contain all documentation and provide the given documentation for the total doc.

This should reduce the length of the .io. documentation and make it more manageable from a users perspective.

Geometry.close(...,idx=...) behaves strangely

Revision sisl/6a25a7a

Test code
from future import print_function, division
import sisl

xyz = [[i,0,0] for i in range(10)]
geom = sisl.Geometry(xyz)
dR = (0.1,1.1)

r1 = range(5)
r2 = range(5,10)

for ia in r1:
idx = geom.close(ia, dR=dR, idx=r2)
print(idx)

for ia in r2:
idx = geom.close(ia, dR=dR, idx=r1)
print(idx)

Observations
The arrays idx returned in first and second loop are structurally inequivalent

The above test script returns:
python test.py
[]
[]
[]
[]
[array([], dtype=int32), array([5], dtype=int32)]
[array([], dtype=int32), array([4], dtype=int32)]
[[], []]
[[], []]
[[], []]
[[], []]

i.e., why is "[]" returned in the first loop, and "[[],[]]" in the second?