sisl: tight-binding and DFT interface library¶

The Python library sisl was born out of a need to handle(create and read), manipulate and analyse output from DFT programs. It was initially developed by Nick Papior (co-developer of Siesta) as a side-project to TranSiesta and TBtrans to efficiently analyse TBtrans output for N-electrode calculations. Since then it has expanded to accommodate a rich set of DFT code input/outputs such as (but not limited to) VASP, OpenMX, BigDFT, Wannier90.

A great deal of codes are implementing, roughly, the same thing. However, every code implements their own analysis and post-processing utilities which typically turns out to be equivalent utilities only having the interface differently.

sisl tries to solve some of the analysis issues by creating a unified scripting approach in Python which does analysis using the same interface, regardless of code being used. For instance one may read the Kohn-Sham eigenvalue spectrum from various codes and return them in a consistent manner so the post-processing is the same, regardless of code being used.

sisl is also part of the training material for a series of workshops hosted here.

In some regards it has overlap with ASE and sisl also interfaces with ASE.

First time use¶

Here we show 2 examples of using sisl together with Siesta.

To read in a Hamiltonian from a Siesta calculation and calculate the DOS for a given Monkhorst-Pack grid one would do:

import sisl
import numpy as np
H = sisl.get_sile('RUN.fdf').read_hamiltonian()
mp = sisl.MonkhorstPack(H, [13, 13, 13])
E = np.linspace(-4, 4, 500)
DOS = mp.asaverage().DOS(E)
from matplotlib import pyplot as plt
plt.plot(E, DOS)

Which calculates the DOS for a 13x13x13 Monkhorst-Pack grid.

Another common analysis is real-space charge analysis, the following command line subtracts two real-space charge grids and writes them to a CUBE file:

sgrid reference/Rho.grid.nc --diff Rho.grid.nc --geometry RUN.fdf --out diff.cube

which may be analysed using VMD, XCrySDen or other tools.

Every use of sisl¶

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

This page for the documentation!
Workshop examples showing different uses, see workshop
Ask questions on its use on the Github issue page here
Ask questions on the Gitter page here

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:

@misc{zerothi_sisl,
  author       = {Papior, Nick},
  title        = {sisl: v<fill-version>},
  year         = {2020},
  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.

Introduction¶

sisl has a number of features which makes it easy to jump right into and perform a large variation of tasks.

Easy creation of geometries. Similar to ASE sisl provides an easy scripting engine to create and manipulate geometries. The goal of sisl is not specifically DFT-related software which typically only targets a limited number of atoms. One of the main features of sisl is the enourmously fast creation and manipulation of very large geometries such as attaching two geometries together, rotating atoms, removing atoms, changing bond-lengths etc. Everything is optimized for extremely large scale systems >1,000,000 atoms such that creating geometries for tight-binding models becomes a breeze.
Easy creation of tight-binding Hamiltonians via intrinsic and very fast algorithms for creating sparse matrices. One of the key-points is that the Hamiltonian is treated as a matrix. I.e. one may easily specify couplings without using routine calls. For large systems, >10,000 atoms, it becomes advantegeous to iterate on sub-grids of atoms to speed up the creation by orders of magnitudes. sisl intrinsically implements such algorithms.
Post-processing of data from DFT software. One may easily add additional post-processing tools to use sisl on non-implemented data-files.

Package¶

sisl is mainly a Python package with many intrinsic capabilities.

Follow these instructions for installing sisl.

DFT¶

Many intrinsic DFT program files are handled by sisl and extraction of the necessary physical quantities are easily performed.

Its main focus has been Siesta which thus has the largest amount of implemented output files.

Geometry manipulation¶

Geometries can easily be generated from basic routines and enables easy repetitions, additions, removal etc. of different atoms/geometries, for instance to generate a graphene flake one can use this small snippet:

>>> import sisl
>>> graphene = sisl.geom.graphene(1.42).repeat(100, 0).repeat(100, 1)

which generates a graphene flake of \(2 \cdot 100 \cdot 100 = 20000\) atoms.

Command line usage¶

The functionality of sisl is also extended to command line utilities for easy manipulation of data from DFT programs. There are a variety of commands to manipulate generic data (sdata), geometries (sgeom) or grid-related quantities (sgrid).

Contributing¶

The sisl code is open-source, and thus we encourage external users to contribute back to the code base.

Any size of contribution is extremely welcome!

If you’ve ideas of missing features
If you’ve ideas for improving documentation
If you’ve found a bug
If you’ve found a documentation error
If you’ve created a tutorial

Then please share them here.

Contribute external code¶

External toolbox codes may be contributed here, then press “Issue” and select Contribute toolbox.

There are two cases of external contributions:

If the code is directly integratable into sisl it will be merged into the sisl source.
If the code is showing how to use sisl to calculate some physical quantity but is not a general implementation, it will be placed in toolbox directory.

Either way, any contribution is very welcome.

Other resources¶

One of sisl goals is an easy interaction between a variety of DFT simulations, much like ASE with a high emphasis on Siesta, while simultaneously providing the tools necessary to perform tight-binding calculations.

However, sisl is far from the only Python package that implements simplistic tight-binding calculations. We are currently aware of 3 established tight-binding methods used in litterature (in random order):

sisl’s philosophy is drastically different in the sense that the Hamiltonian (and other physical quantities described via matrices) is defined in matrix form. As for kwant and pybinding the model is descriptive as shapes define the geometries. Secondly, both kwant and pybinding are self-contained packages where all physics is handled by the scripts them-selves, while sisl can calculate band-structures, but transport properties should be off-loaded to TBtrans.

Citing sisl¶

sisl is an open-source software package intended for the scientific community. It is released under the LGPL-3 license.

You are encouraged to cite sisl you use it to produce scientific contributions.

The sisl citation can be found through Zenodo:

By citing sisl you are encouraging development and expoosing the software package.

Citing basic usage¶

If you are only using sisl as a post-processing tool and/or tight-binding calculations you should cite this (Zenodo DOI):

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

The sgeom, sgrid or sdata commands all print-out the above information in a suitable format:

sgeom --cite
sgrid --cite
sdata --cite

which fill in the version for you, all yield the same output.

Citing transport backend¶

When using sisl as tight-binding setup for Hamiltonians and dynamical matrices for TBtrans and PHtrans you should cite these two DOI’s:

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

@article{Papior2017,
  author = {Papior, Nick and Lorente, Nicol{\'{a}}s and Frederiksen, Thomas and Garc{\'{i}}a, Alberto and Brandbyge, Mads},
  doi = {10.1016/j.cpc.2016.09.022},
  issn = {00104655},
  journal = {Computer Physics Communications},
  month = {mar},
  number = {July},
  pages = {8--24},
  title = {{Improvements on non-equilibrium and transport Green function techniques: The next-generation transiesta}},
  volume = {212},
  year = {2017}
}

Publications using sisl¶

The sisl tool-suite has been used one way or the other in the listed publications below.

Please help maintaining the list complete via a pull request or by writing an email to nickpapior@gmail.com.

S. Sanz, P. Brandimarte, G. Giedke, D. Sanchez-Portal, T. Frederiksen, Crossed graphene nanoribbons as beam splitters and mirrorsfor electron quantum optics, arXiv 2005.11391
J. Li, S. Sanz, J. Castro-Esteban, M. Vilas-Varela, N. Friedrich, T. Frederiksen, D. Pena, J.I. Pascual, Uncovering the Triplet Ground State of Triangular Graphene Nanoflakes Engineeredwith Atomic Precision on a Metal Surface, Physical Review Letters 124, 177201 (2020)
T. Schmitt, S. Bourelle, N. Tye, G. Soavi, A.D. Bond, S. Feldmann, T. Boubacar, C. Katan, J. Even, S.E. Dutton, F. Deschler, Control of Crystal Symmetry Breaking with Halogen-Substituted Benzylammonium in Layered Hybrid Metal-Halide Perovskites, Journal of the American Chemical Society 142, 11 (2020)
J. Brand, S. Leitherer, N. Papior, N. Neel, Y. Lei, M. Brandbyge and J. Kroger, Nonequilibrium Bond Forces in Single-Molecule Junctions, Nano Letters (2019)
G. Singh, K. Kumar, R. K. Moudgil, Alloying-induced Spin Seebeck Effect and Spin Figure of Merit in Pt-based Bimetallic Atomic Wires of Noble Metals, Physical Chemistry Chemical Physics (2019)
L. Oroszlány, J. Ferrer, A. Deak, L. Udvardi and L. Szunyogh, Exchange interactions from a nonorthogonal basis set: From bulk ferromagnetsto the magnetism in low-dimensional graphene systems, Physical Review B 99, 224412 (2019)
G. Calogero, I. Alcon, N. Papior, A-P Jauho, M. Brandbyge, Quantum interference engineering of nanoporous graphene for carbon nanocircuitry, Journal of the American Chemical Society 141 (2019)
S. Leitherer, N. Papior, M. Brandbyge, Current-induced atomic forces in gated graphene nanoconstrictions, Physical Review B 100, 035415 (2019)
G. Singh, K. Kumar, B. Singh, R.K. Moudgil, Ballistic phonon thermal transport across nano-junctions on aluminum and platinum nanowires, AIP Conference Proceedings 2093, 020029 (2019)
G. Calogero, N. Papior, M. Koleini, M. H. L. Larsen and M. Brandbyge, Multi-scale approach to first-principles electron transport beyond 100 nm, Nanoscale 11, 6153 (2019)
G. Singh, K. Kumar and R.K. Moudgil, On topology-tuned thermoelectric properties of noble metal atomic wires, Physica E: Low-dimensional Systems and Nanostructures 109, 114 (2019)
J. Li, S. Sanz, M. Corso, D.J. Choi, D. Pena, T. Frederiksen and J.I. Pascual, Single spin localization and manipulation in graphene open-shell nanostructures, Nature Communications 10, 200 (2019)
G. Calogero, N. Papior, B. Kretz, A. Garcia-Lekue, T. Frederiksen and M. Brandbyge, Electron Transport in Nanoporous Graphene: Probing the Talbot Effect, Nano Letters 19, 1 (2019)
D. Perera and J. Rohrer, Structure sensitivity of electronic transport across graphene grain boundaries, Physical Review B 98, 155432 (2018)
Z. Nourbakhsh and R. Asgari, Phosphorene as nanoelectromechanical material, Physical Review B 98, 125427 (2018)
G. Calogero, N. Papior, P. Bøggild and M. Brandbyge, Large-scale tight-binding simulations of quantum transport in ballistic graphene, Journal of Physics: Condensed Matter, 36, 36 (2018)
B. Fülöp, Z. Tajkov, J. Pető, P. Kun, J. Koltai, L. Oroszlány, E. Tóvári, H. Murakawa, Y. Tokura, S. Bordács, L. Tapasztó and S. Csonka, Exfoliation of single layer BiTeI flakes, 2D Materials 5, 3 (2018).
Z. Nourbakhsh and R. Asgari, Charge transport in doped zigzag phosphorene nanoribbons, Physical Review B 97, 235406 (2018)
N. Papior, G. Calogero and M. Brandbyge, Simple and efficient LCAO basis sets for the diffuse states in carbon nanostructures, Journal of Physics: Condensed Matter 30, 25 (2018)
C. Moreno, M. Vila-Varela, B. Kretz, A. Garcia-Lekue, M.V. Costache, M. Paradinas, M. Panighel, G. Ceballos, S.O. Valenzuela, D. Pena and A.M. Mugarza, Bottom-up synthesis of multifunctional nanoporous graphene, Science 360, 6385 (2018)
P. Bøggild, J.M. Caridad, C. Stampfer, G. Calogero, N.R. Papior and M. Brandbyge, A two-dimensional Dirac fermion microscope, Nature Communications 8, 15783 (2017)
P. Brandimarte, M. Engelund, N. Papior, A. Garcia-Lekue, T. Frederiksen and D. Sanchez-Portal, A tunable electronic beam splitter realized with crossed graphene nanoribbons, Journal of Chemical Physics 146, 092318 (2017)
V. Obersteiner, G. Huhs, N. Papior and E. Zojer, Unconventional Current Scaling and Edge Effects for Charge Transport through Molecular Clusters, Nano Letters 17, 12 (2017)
T. Groizard, N.R. Papior, B. Le Guennic, V. Robert and M. Kepenekian, Enhanced Cooperativity in Supported Spin-Crossover Metal-Organic Frameworks, Journal of Physical Chemistry Letters 8, 3415 (2017)
N. Papior, N. Lorente, T. Frederiksen, A. Garcia and M. Brandbyge, Improvements on non-equilibrium and transport Green function techniques: The next-generation TranSiesta, Computer Physics Communications 212, 8 (2017)

arXiv publications¶

These publications are as far as we know in the review process.

N. Papior, G. Calogero, S. Leitherer, M. Brandbyge, Removing all periodic boundary conditions: Efficient non-equilibrium Green function calculations 1905.11113
D. Weckbecker, M. Fleischmann, R. Gupta, W. Landgraf, S. Leitherer, O. Pankratov, S. Sharma, V. Meded, S. Shallcross, Moiré ordered current loops in the graphene twist bilayer, 1901.04712

Installation¶

sisl is easy to install using any of your preferred methods.

Required dependencies¶

Python 3.5 or above
setuptools
numpy (1.13 or later)
scipy (0.18 or later)
netCDF4-python
pyparsing (1.5.7 or later)
A C- and fortran-compiler

Optional dependencies:

pytest (for running the test suite)
matplotlib
tqdm (for displaying progress-bars)
xarray (for advanced table data structures in certain methods)

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.

pip3¶

Installing sisl using PyPi can be done using

pip3 install sisl
# or
pip3 install sisl[analysis]

pip3 will automatically install the required dependencies. The optional dependencies will be used if later installed.

The latter installation call also installs tqdm and xarray 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 pip3 simply use the following

pip3 install --install-option="--compiler=intelem" --install-option="--fcompiler-intelem" sisl

note that options are accummulated.

conda¶

Installing sisl using conda can be done by

conda config --add channels conda-forge
conda install sisl

To find more information about the conda-forge installation please see here.

Manual installation¶

sisl may be installed using the regular setup.py script. Ensure the required dependencies are installed before proceeding with the manual installation (without numpy installed a spurious error message will appear). The dependencies may be installed using this pip3 command:

pip3 install -r requirements.txt

Simply download the release tar from this page, or clone the git repository for the latest developments

python3 setup.py install --prefix=<prefix>

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

Development version¶

To install the development version using pip3 you may use the URL command:

pip3 install 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 options to setup.py. 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
pip3 install --global-option="build" --global-option="--compiler=intelem" --global-option="--fcompiler=intelem" .

which will pass the correct options to the build system.

Tutorials¶

sisl is shipped with these tutorials which introduces the basics.

All examples are assumed to have this in the header:

import numpy as np
from sisl import *

to enable numpy and sisl.

Below is a list of the current tutorials:

Siesta/TranSiesta support¶

sisl was initiated around the Siesta/TranSiesta code. And it may be very educational to look at the sisl+TBtrans+TranSiesta tutorial located here.

If you plan on using sisl as an analyzation tool for Siesta you are highly recommended to follow these tutorials:

Deprecated tutorials¶

Once everything has been moved to the IPython notebook notation, these tutorials will be removed. Until that happens they are located here for consistency:

Geometry creation – part 1¶

To create a Geometry one needs to define a set of attributes. The only required information is the atomic coordinates:

>>> single_hydrogen = Geometry([[0., 0., 0.]])
>>> print(single_hydrogen)
{na: 1, no: 1, species:
 {Atoms(1):
    (1) == [H, Z: 1, orbs: 1, mass(au): 1.00794, maxR: -1.00000],
 },
 nsc: [1, 1, 1], maxR: -1.0
}

this will create a Geometry object with 1 Hydrogen atom with a single orbital (default if not specified), and a supercell of 10 A in each Cartesian direction. When printing a Geometry object a list of information is printed in an XML-like fashion. na corresponds to the total number of atoms in the geometry, while no refers to the total number of orbitals. The species are printed in a sub-tree and Atoms(1) means that there is one distinct atomic specie in the geometry. That atom is a Hydrogen, with mass listed in atomic-units. maxR refers to the maximum range of all the orbitals associated with that atom. A negative number means that there is no specified range. Lastly nsc refers to the number of neighbouring super-cells that is represented by the object. In this case [1, 1, 1] means that it is a molecule and there are no super-cells (only the unit-cell).

To specify the atomic specie one may do:

>>> single_carbon = Geometry([[0., 0., 0.]], Atom('C'))

which changes the Hydrogen to a Carbon atom. See <link to atom_01.rst> on how to create different atoms.

To create a geometry with two different atomic species, for instance a chain of alternating Natrium an Chloride atoms, separated by 1.6 A one may do:

>>> chain = Geometry([[0. , 0., 0.],
                      [1.6, 0., 0.]], [Atom('Na'), Atom('Cl')],
                      [3.2, 10., 10.])

note the last argument which specifies the Cartesian lattice vectors. sisl is clever enough to repeat atomic species if the number of atomic coordinates is a multiple of the number of passed atoms, i.e.:

>>> chainx2 = Geometry([[0. , 0., 0.],
                        [1.6, 0., 0.],
                        [3.2, 0., 0.],
                        [4.8, 0., 0.]]], [Atom('Na'), Atom('Cl')],
                        [6.4, 10., 10.])

which is twice the length of the first chain with alternating Natrium and Chloride atoms, but otherwise identical.

This is the most basic form of creating geometries in sisl and is the starting point of almost anything related to sisl.

Geometry creation – part 2¶

Many geometries are intrinsically enabled via the sisl.geom submodule.

Here we list the currently default geometries:

honeycomb (graphene unit-cell):

hBN = geom.honeycomb(1.5, [Atom('B'), Atom('N')])

graphene (equivalent to honeycomb with Carbon atoms):
```
graphene = geom.graphene(1.42)
```

Simple-, body- and face-centered cubic as well as HCP All have the same interface:

sc = geom.sc(2.5)
bcc = geom.bcc(2.5)
fcc = geom.fcc(2.5)
hcp = geom.hcp(2.5)

Nanotubes with different chirality:

ntb = geom.nanotube(1.54, chirality=(n, m))

Diamond:
```
d = geom.diamond(3.57)
```

Specifying super-cell information¶

An important thing when dealing with geometries in how the super-cell is used. First, recall that the number of supercells can be retrieved by:

>>> geometry = Geometry([[0, 0, 0]])
>>> print(geometry)
{na: 1, no: 1, species:
 {Atoms(1):
    (1) == [H, Z: 1, orbs: 1, mass(au): 1.00794, maxR: -1.00000],
 },
 nsc: [1, 1, 1], maxR: -1.0
}
>>> geometry.nsc # or geometry.sc.nsc
array([1, 1, 1], dtype=int32)

where nsc is the specific super-cell information. In the default case only the unit-cell is taken into consideration (nsc: [1, 1, 1]). However when using the Geometry.close or Geometry.within functions one may retrieve neighbouring atoms depending on the size of the supercell.

Specifying the number of super-cells may be done when creating the geometry, or after it has been created:

>>> geometry = Geometry([[0, 0, 0]], sc=SuperCell(5, [3, 3, 3]))
>>> geometry.nsc
array([3, 3, 3], dtype=int32)
>>> geometry.set_nsc([3, 1, 5])
>>> geometry.nsc
array([3, 1, 5], dtype=int32)

The final geometry enables intrinsic routines to interact with the 2 closest neighbouring cells along the first lattice vector (1 + 2 == 3), and the 4 closest neighbouring cells along the third lattice vector (1 + 2 + 2 == 5). Note that the number of neighbouring supercells is always an uneven number because if it connects in the positive direction it also connects in the negative, hence the primary unit-cell plus 2 per neighbouring cell.

Example – square¶

Here we show a square 2D lattice with one atom in the unit-cell and a supercell which extends 2 cells along the Cartesian \(x\) lattice vector (5 in total) and 1 cell along the Cartesian \(y\) lattice vector (3 in total):

>>> square = Geometry([[0.5,0.5,0]], sc=SuperCell([1,1,10], [5, 3, 1]))

which results in this underlying geometry:

With this setup, sisl, can handle couplings that are within the defined supercell structure, see green, full arrow. Any other couplings that reach farther than the specified supercell cannot be defined (and will thus always be zero), see the red, dashed arrow.

Note that even though the geometry is purely 2D, sisl requires the last non-used dimension. For 2D cases the non-used direction should always have a supercell of 1.

Example – graphene¶

A commonly encountered example is the graphene unit-cell. In a tight-binding picture one may suffice with a nearest-neighbour coupling.

Here we create the simple graphene 2D lattice with 2 atoms per unit-cell and a supercell of [3, 3, 1] to account for nearest neighbour couplings.

>>> graphene = geom.graphene()

which results in this underlying geometry:

The couplings from each unit-cell atom is highlighted by green (first atom) and blue (second atom) arrows. When dealing with Hamiltonians the supercell is extremely important to obtain the correct electronic structure. If one wishes to use the 3rd nearest neighbour couplings one is forced to use a supercell of [5, 5, 1] (please try and convince yourself of this).

Electronic structure setup – part 1¶

A Hamiltonian is an extension of a Geometry. From the Geometry it reads the number of orbitals, the supercell information.

Hamiltonians are matrices, and in sisl all Hamiltonians are treated as sparse matrices, i.e. matrices where there are an overweight of zeroes in the full matrix. As the Hamiltonian is treated as a matrix one can do regular assignments of the matrix elements, and basic math operations as well.

Here we create a square lattice and from this a Hamiltonian:

>>> geometry = Geometry([[0, 0, 0]])
>>> H = Hamiltonian(geometry)
>>> print(H)
{spin: 1, non-zero: 0
 {na: 1, no: 1, species:
  {Atoms(1):
    (1) == [H, Z: 1, orbs: 1, mass(au): 1.00794, maxR: -1.00000],
  },
 nsc: [1, 1, 1], maxR: -1.0
 }
}

which informs that the Hamiltonian currently only has 1 spin-component, is a matrix with complete zeroes (non-zero is 0). The geometry is a basic geometry with only one orbital per atom as \(na = no\).

This geometry and Hamiltonian represents a lone atom with one orbital with zero on-site energy, a rather un-interesting case.

The examples here will be re-performed in Electronic structure setup – part 2 by highlighting how the Hamiltonian can be setup in a more easy way.

Example – square¶

Let us try and continue from Geometry creation – part 1 and create a square 2D lattice with one atom in the unit-cell and a supercell which couples only to nearest neighbour atoms.

>>> square = Geometry([[0.5,0.5,0]], sc=SuperCell([1, 1, 10], [3, 3, 1]))
>>> H = Hamiltonian(square)

Now we have a periodic structure with couplings allowed only to nearest neighbour atoms. Note, that it still only has 1 orbital. In the following we setup the on-site and the 4 nearest neighbour couplings to, \(-4\) and \(1\), respectively:

>>> H[0, 0] = -4
>>> H[0, 0, (1, 0)] = 1
>>> H[0, 0, (-1, 0)] = 1
>>> H[0, 0, (0, 1)] = 1
>>> H[0, 0, (0, -1)] = 1
>>> print(H)
{spin: 1, non-zero: 5
 {na: 1, no: 1, species:
  {Atoms(1):
    (1) == [H, Z: 1, orbs: 1, mass(au): 1.00794, maxR: -1.00000],
  },
  nsc: [3, 3, 1], maxR: -1.0
 }
}

There are a couple of things going on here (the items corresponds to lines in the above snippet):

Specifies the on-site energy of the orbital. Note that we assign as would do in a normal matrix.
Sets the coupling element from the first orbital in the primary unit-cell to the first orbital in the unit-cell neighbouring in the \(x\) direction, hence (1, 0).
Sets the coupling element from the first orbital in the primary unit-cell to the first orbital in the unit-cell neighbouring in the \(-x\) direction, hence (-1, 0).
Sets the coupling element from the first orbital in the primary unit-cell to the first orbital in the unit-cell neighbouring in the \(y\) direction, hence (0, 1).
Sets the coupling element from the first orbital in the primary unit-cell to the first orbital in the unit-cell neighbouring in the \(-y\) direction, hence (0, -1).

sisl does not intrinsically enforce symmetry, that is the responsibility of the user. This completes the Hamiltonian for nearest neighbour interaction and enables the calculation of the band-structure of the system.

In the below figure we plot the band-structure going from the \(\Gamma\) point to the band-edge along \(x\), to the corner and back.

The complete code for this example (plus the band-structure) can be found here.

Example – graphene¶

A commonly encountered example is the graphene unit-cell. In a tight-binding picture one may suffice with a nearest-neighbour coupling.

Here we create the simple graphene 2D lattice with 2 atoms per unit-cell and a supercell of [3, 3, 1] to account for nearest neighbour couplings.

>>> graphene = geom.graphene()
>>> H = Hamiltonian(graphene)

The nearest neighbour tight-binding model for graphene uses 0 onsite energy and \(2.7\) as the hopping parameter. These are specified as this:

>>> H[0, 1] = 2.7
>>> H[0, 1, (-1, 0)] = 2.7
>>> H[0, 1, (0, -1)] = 2.7
>>> H[1, 0] = 2.7
>>> H[1, 0, (1, 0)] = 2.7
>>> H[1, 0, (0, 1)] = 2.7

The complete code for this example (plus the band-structure) can be found here.

Electronic structure setup – part 2¶

Following part 1 we focus on how to generalize the specification of the hopping parameters in a more generic way.

First, we re-create the square geometry (with one orbital per atom). However, to generalize the specification of the hopping parameters it is essential that we specify how long range the orbitals interact. In the following we set the atomic specie to be a Hydrogen atom with a single orbital with a range of \(1\,Å\)

>>> Hydrogen = Atom(1, R=1.)
>>> square = Geometry([[0.5, 0.5, 0]], Hydrogen,
                      sc=SuperCell([1, 1, 10], [3, 3, 1]))
>>> H = Hamiltonian(square)
>>> print(H)
{spin: 1, non-zero: 0
 {na: 1, no: 1, species:
  {Atoms(1):
    (1) == [H, Z: 1, orbs: 1, mass(au): 1.00794, maxR: 1.00000],
  },
  nsc: [3, 3, 1], maxR: 1.0
 }
}

Note how the maxR variable has changed from -1.0 to 1.0. This corresponds to the maximal orbital range in the geometry. Here there is only one type of orbital, but for geometries with several different orbitals, there may be different orbital ranges.

Now one can assign the generalized parameters:

>>> for ia in square: # loop atomic indices (here equivalent to the orbital indices)
...     idx_a = square.close(ia, R=[0.1, 1.1])
...     H[ia, idx_a[0]] = -4.
...     H[ia, idx_a[1]] = 1.

The Geometry.close function is a convenience function to return atomic indices of atoms within a certain radius. For instance close(0, R=1.) returns all atomic indices within a spherical radius of \(1\,Å\) from the first atom in the geometry, including it-self. close([0., 0., 1.], R=1.) will return all atomic indices within \(1\,Å\) of the coordinate [0., 0., 1.]. If one specifies a list of R it will return the atomic indices in the sphere within the first element; and for the later values it will return the atomic indices in the spherical shell between the corresponding radii and the previous radii.

The above code is the preferred method of creating a Hamiltonian. It is safe because it ensures that all parameters are set, and symmetrized.

For very large geometries (larger than 50,000 atoms) the above code will be extremely slow. Hence, the preferred method to setup the Hamiltonian for these large geometries is:

>>> for ias, idxs in square.iter_block():
...    for ia in ias:
...        idx_a = square.close(ia, R=[0.1, 1.1], idx=idxs)
...        H[ia, idx_a[0]] = -4.
...        H[ia, idx_a[1]] = 1.

The code above is the preferred method of specifying the Hamiltonian parameters.

The complete code for this example (plus the band-structure) can be found here.

Examples¶

sisl is shipped with these examples which describes a large variation of use cases.

All examples are assumed to have this in the header:

import numpy as np
from sisl import *

to enable numpy and sisl.

Graphene tight-binding model¶

This example creates a minimal graphene unit-cell of two atoms. The Carbon atoms are described with a single orbital per atom and with a cutoff radius of 1.42 Å.

The Hamiltonian H is an object which may be treated as a sparse matrix. The for loop below loops over all atoms (ia) in the graphene unit-cell. The close function returns a list of length len(R) with elements where all neighbouring atoms within the radius defined in R are listed. Comments in the below example clarifies each of the steps carefully.

# This example creates the tight-binding Hamiltonian
# for graphene with on-site energy 0, and hopping energy
# -2.7 eV.

import sisl

bond = 1.42
# Construct the atom with the appropriate orbital range
# Note the 0.01 which is for numerical accuracy.
C = sisl.Atom(6, R = bond + 0.01)
# Create graphene unit-cell
gr = sisl.geom.graphene(bond, C)

# Create the tight-binding Hamiltonian
H = sisl.Hamiltonian(gr)
R = [0.1 * bond, bond + 0.01]

for ia in gr:
    idx_a = gr.close(ia, R)
    # On-site
    H[ia, idx_a[0]] = 0.
    # Nearest neighbour hopping
    H[ia, idx_a[1]] = -2.7

# Calculate eigenvalues at K-point
print(H.eigh([2./3, 1./3, 0.]))

Scripts¶

sisl implements a set of command-line utitilies that enables easy interaction with all the data files compatible with sisl.

sdata¶

The sdata executable is a tool for reading and performing actions on all sisl file formats applicable.

Essentially it performs operations dependent on the file that is being processed. If for instance the file contains any kind of Geometry it allows the same operations as sgeom.

For a short help description of the possible uses do:

sdata <in> --help

which shows a help dependent on which kind of file <in> is.

As the options for this utility depends on the input file, it is not completely documented.

Files with Geometry¶

If a file contains a Geometry one gets all the options like sgeom. I.e. sdata is a generic form of the sgeom script.

Files with Grid¶

If the file contains a Grid one gets all the options like sgrid. I.e. sdata is a generic form of the sgrid script.

sgeom¶

The sgeom executable is a tool for reading and transforming general coordinate formats to other formats, or alter them.

For a short help description of the possible uses do:

sgeom --help

Here we list a few of the most frequent used commands.

Conversion¶

The simplest usage is transforming from one format to another format. sgeom takes at least two mandatory arguments, the first being the input file format, and the second (and any third + argumets) the output file formats

sgeom <in> <out> [<out2>] [[<out3>] ...]

Hence to convert from an fdf Siesta input file to an xyz file for plotting in a GUI program one can do this:

sgeom RUN.fdf RUN.xyz

and the RUN.xyz file will be created.

Remark that the input file must be the first argument of sgeom.

Available formats¶

A great deal of different file formats are available. For details please see sisl.io for a list of all implemented data-files. Any file that implements the read_geometry/write_geometry methods will be usable by sgeom.

Advanced Features¶

More advanced features are represented here.

The sgeom utility enables highly advanced creation of several geometry structures by invocing the arguments in order.

I.e. if one performs:

sgeom <in> --repeat 3 x repx3.xyz --repeat 3 y repx3_repy3.xyz

will read <in>, repeat the geometry 3 times along the first unit-cell vector, store the resulting geometry in repx3.xyz. Subsequently it will repeat the already repeated structure 3 times along the second unit-cell vector and store the now 3x3 repeated structure as repx3_repy3.xyz.

Repeating/Tiling structures¶

One may use periodicity to create larger structures from a simpler structure. This is useful for creating larger bulk structures. To repeat a structure do

sgeom <in> --repeat <int> [ax|yb|zc] <out>

which repeats the structure one atom at a time, <int> times, in the corresponding direction. Note that x and a correspond to the same cell direction (the first).

To repeat the structure in chunks one can use the --tile option:

sgeom <in> --tile <int> [ax|yb|zc] <out>

which results in the same structure as --repeat however with different atomic ordering.

Both tiling and repeating have the shorter variants:

sgeom <in> -t[xyz] <int> -r[xyz] <int>

to ease the commands.

To repeat a structure 4 times along the x cell direction:

sgeom RUN.fdf --repeat 4 x RUN4x.fdf
sgeom RUN.fdf --repeat-x 4 RUN4x.fdf
sgeom RUN.fdf --tile 4 x RUN4x.fdf
sgeom RUN.fdf --tile-x 4 RUN4x.fdf

where all the above yields the same structure, albeit with different orderings.

Rotating structure¶

To rotate the structure around certain cell directions one can do:

sgeom <in> --rotate <angle> [ax|yb|zc] <out>

which rotates the structure around the origo with a normal vector along the specified cell direction. The input angle is in degrees and not in radians. If one wish to use radians append an r in the angle specification.

Again there are shorthand commands:

sgeom <in> -R[xyz] <angle>

Combining command line arguments¶

All command line options may be used together. However, one should be aware that the order of the command lines determine the order of operations.

If one starts by repeating the structure, then rotate it, then shift the structure, it will be different from, shift the structure, then rotate, then repeat.

Be also aware that outputting structures are done at the time in the command line order. This means one can store the intermediate steps while performing the entire operation:

sgeom <in> --rotate <angle> --out <rotated> -tx 2 --out <rotate-tile-x> --ty 2 --out <rotate-tile-y>

sgrid¶

The sgrid executable is a tool for manipulating a simulation grid and transforming it into CUBE format for plotting 3D data in, e.g. VMD or XCrySDen.

Any Sile which implements a read_grid method can be used to post-process data.

For a short help description of the possible uses do:

sgrid --help

Here we list a few of the most frequent used commands. Note that all commands are available via Python scripts and the Grid class.

Creating CUBE files¶

The simplest usage is converting a grid file to CUBE file using

sgrid Rho.grid.nc Rho.cube

which converts a Siesta grid file of the electron density into a corresponding CUBE file. The CUBE file writeout is implemented in Cube.

Conveniently CUBE files can accomodate geometries and species for inclusion in the 3D plot and this can be added to the file via the --geometry flag, any geometry format implemented in sisl are also compatible with sgrid.

sgrid Rho.grid.nc --geometry RUN.fdf Rho.cube

the shorthand flag for -geometry is -G.

Grid differences¶

To easily obtain differences between two grids one may use the --diff flag which takes one additional grid file for the difference. I.e.

sgrid Rho.grid.nc{0} -G RUN.fdf --diff Rho.grid.nc{1} diff_up-down.cube

which takes the difference between the spin up and spin down in the same Rho.grid.nc file. The spin (index) specification takes either a single integer or a list of floating point values, as can be seen in the below and shorter equivalent syntax:

sgrid "Rho.grid.nc{1.,-1.}" -G RUN.fdf diff_up-down.cube

The bracketed specification is an array of the fractions for each spin-component, so here we take the first spin-component and subtract the second spin-component. The quotation marks are typically required due to Python’s argparse module.

Note that these spin specifications only work for files that contain all spin relevant quantities.

The above is largely equivalent to this small snippet:

geom = sisl.get_sile('RUN.fdf').read_geometry()
diff = sisl.get_sile('Rho.grid.nc').read_grid(index=[1, -1])
diff.set_geometry(geom)
diff.write('diff_up-down.cube')

Reducing grid sizes¶

Often grids are far too large in that only a small part of the full cell is needed to be studied. One can remove certain parts of the grid after reading, before writing. This will greatly decrease the output file and greatly speed-up the process as writing huge ASCII files is extremely time consuming. There are two methods for reducing grids:

sgrid <file> --sub <pos|<frac>f> x
sgrid <file> --remove [+-]<pos|<frac>f> x

This needs an example, say the unit cell is an orthogonal unit-cell with side lengths 10x10x20 Angstrom. To reduce the cell to a middle square of 5x5x5 Angstrom you can do:

sgrid Rho.grid.nc --sub 2.5:7.5 x --sub 2.5:7.5 y --sub 7.5:12.5 z 5x5x5.cube

note that the order of the reductions are made in the order of appearence. So two subsequent sub/remove commands with the same direction will not yield the same final grid. The individual commands can be understood via

--sub 2.5:7.5 x: keep the grid along the first cell direction above 2.5 Å and below 5 Å.

--sub 2.5:7.5 y: keep the grid along the second cell direction above 2.5 Å and below 5 Å.

--sub 7.5:12.5 z: keep the grid along the third cell direction above 7.5 Å and below 12.5 Å.

When one is dealing with fractional coordinates is can be convenient to use fractional grid operations. The length unit for the position is always in Ångstrøm, unless an optional f is appended which forces the unit to be in fractional position (must be between 0 and 1).

Averaging and summing¶

Sometimes it is convenient to average or sum grids along cell directions:

sgrid Rho.grid.nc --average x meanx.cube
sgrid Rho.grid.nc --sum x sumx.cube

which takes the average or the sum along the first cell direction, respectively. Note that this results in the number of partitions along that direction to be 1 (not all 3D software is capable of reading such a CUBE file).

Advanced features¶

The above operations are not the limited use of the sisl library. However, to accomblish more complex things you need to manually script the actions using the Grid class and the methods available for that method. For inspiration you can check the sgrid executable to see how the commands are used in the script.

Visualization¶

sisl’s strength lies in its post-processing capabilities of DFT outputs and/or manipulating geometries.

However, quite frequently one is in need for good looking graphics. This document tries to explain and show how one may use sisl and related tools for showing publication ready images.

ASE¶

A sisl Geometry object may easily be converted to ASE objects and thus directly plotted.

import sisl import ase.visualize.view as view

geom = sisl.geom.graphene() view(geom.toASE())

will open a new window showing the atoms.

File formats¶

sisl implements a generic interface for interacting with many different file formats. When using the command line utilities all these files are accepted as input for, especially sdata while only those which contains geometries (Geometry) may be used with sgeom.

In sisl any file is named a Sile to allow * imports.

Please see External code in/out put supported for the list of available files.

API documentation¶

The sisl package consists of a variety of sub packages enabling different routines for electronic structure calculations.

sisl (`sisl`)¶

sisl is an electronic structure package which may interact with tight-binding and DFT matrices alike.

The full sisl package consistent of a large variety of classes and methods which enables large-scale tight-binding calculations as well as post-processing DFT calculations.

Below a set of classes that are the basis of everything in sisl is present.

Generic classes¶

`PeriodicTable`	Periodic table for creating an `Atom`, or retrieval of atomic information via atomic numbers
`Orbital`(R[, q0, tag])	Base class for orbital information.
`SphericalOrbital`(l, rf_or_func[, q0, tag])	An arbitrary orbital class where \(\phi(\mathbf r)=f(\|\mathbf r\|)Y_l^m(\theta,\varphi)\)
`AtomicOrbital`(args, *kwargs)	A projected atomic orbital consisting of real harmonics
`Atom`(Z[, orbitals, mass, tag])	Atomic information, mass, name number of orbitals and ranges
`Atoms`([atoms, na])	A list-like object to contain a list of different atoms with minimum data duplication.
`Geometry`(xyz[, atoms, sc, names])	Holds atomic information, coordinates, species, lattice vectors
`SuperCell`(cell[, nsc, origo])	A cell class to retain lattice vectors and a supercell structure
`Grid`(shape[, bc, sc, dtype, geometry])	Real-space grid information with associated geometry.

Below are a group of advanced classes rarely needed. A lot of the sub-classes extend these classes, or use them intrinsically. However, they are not necessarily intended for users use.

Advanced classes¶

`Quaternion`([angle, v, rad])	Quaternion object to enable easy rotational quantities.
`SparseCSR`(arg1[, dim, dtype, nnzpr, nnz])	A compressed sparse row matrix, slightly different than `csr_matrix`.
`SparseAtom`(geometry[, dim, dtype, nnzpr])	Sparse object with number of rows equal to the total number of atoms in the `Geometry`
`SparseOrbital`(geometry[, dim, dtype, nnzpr])	Sparse object with number of rows equal to the total number of orbitals in the `Geometry`
`Selector`([routines, ordered])	Base class for implementing a selector of class routines

Common geometries (`sisl.geom`)¶

A variety of default geometries.

Basic
1D materials
2D materials
Others

Basic ¶

sisl.geom.sc(alat, atom)

Simple cubic lattice with 1 atom

Parameters

alat (float) – lattice parameter
atom (Atom) – the atom in the SC lattice

sisl.geom.bcc(alat, atoms, orthogonal=False)

Body centered cubic lattice with 1 (non-orthogonal) or 2 atoms (orthogonal)

Parameters

alat (float) – lattice parameter
atoms (Atom) – the atom(s) in the BCC lattice
orthogonal (bool, optional) – whether the lattice is orthogonal (2 atoms)

sisl.geom.fcc(alat, atoms, orthogonal=False)

Face centered cubic lattice with 1 (non-orthogonal) or 4 atoms (orthogonal)

Parameters

alat (float) – lattice parameter
atoms (Atom) – the atom(s) in the FCC lattice
orthogonal (bool, optional) – whether the lattice is orthogonal (4 atoms)

sisl.geom.hcp(a, atoms, coa=1.63333, orthogonal=False)

Hexagonal closed packed lattice with 2 (non-orthogonal) or 4 atoms (orthogonal)

Parameters

a (float) – lattice parameter for 1st and 2nd lattice vectors
atoms (Atom) – the atom(s) in the HCP lattice
coa (float, optional) – c over a parameter where c is the 3rd lattice vector length
orthogonal (bool, optional) – whether the lattice is orthogonal (4 atoms)

1D materials ¶

sisl.geom.nanoribbon(bond, atoms, width, kind='armchair')

Construction of a nanoribbon unit cell of type armchair or zigzag.

The geometry is oriented along the \(x\) axis.

Parameters

bond (float) – bond length between atoms in the honeycomb lattice
atoms (Atom) – atom (or atoms) in the honeycomb lattice
width (int) – number of atoms in the transverse direction
kind ({'armchair', 'zigzag'}) – type of ribbon

See also

honeycomb: honeycomb lattices
graphene: graphene geometry
graphene_nanoribbon: graphene nanoribbon
agnr: armchair graphene nanoribbon
zgnr: zigzag graphene nanoribbon

sisl.geom.graphene_nanoribbon(width, bond=1.42, atoms=None, kind='armchair')

Construction of a graphene nanoribbon

Parameters

width (int) – number of atoms in the transverse direction
bond (float, optional) – C-C bond length. Defaults to 1.42
atoms (Atom, optional) – atom (or atoms) in the honeycomb lattice. Defaults to Atom(6)
kind ({'armchair', 'zigzag'}) – type of ribbon

See also

honeycomb: honeycomb lattices
graphene: graphene geometry
nanoribbon: honeycomb nanoribbon (used for this method)
agnr: armchair graphene nanoribbon
zgnr: zigzag graphene nanoribbon

sisl.geom.agnr(width, bond=1.42, atoms=None)

Construction of an armchair graphene nanoribbon

Parameters

width (int) – number of atoms in the transverse direction
bond (float, optional) – C-C bond length. Defaults to 1.42
atoms (Atom, optional) – atom (or atoms) in the honeycomb lattice. Defaults to Atom(6)

See also

honeycomb: honeycomb lattices
graphene: graphene geometry
nanoribbon: honeycomb nanoribbon
graphene_nanoribbon: graphene nanoribbon
zgnr: zigzag graphene nanoribbon

sisl.geom.zgnr(width, bond=1.42, atoms=None)

Construction of a zigzag graphene nanoribbon

Parameters

width (int) – number of atoms in the transverse direction
bond (float, optional) – C-C bond length. Defaults to 1.42
atoms (Atom, optional) – atom (or atoms) in the honeycomb lattice. Defaults to Atom(6)

See also

honeycomb: honeycomb lattices
graphene: graphene geometry
nanoribbon: honeycomb nanoribbon
graphene_nanoribbon: graphene nanoribbon
agnr: armchair graphene nanoribbon

sisl.geom.nanotube(bond, atoms=None, chirality=1, 1)

Nanotube with user-defined chirality.

This routine is implemented as in ASE with some cosmetic changes.

Parameters

bond (float) – length between atoms in nano-tube
atoms (Atom(6)) – nanotube atoms
chirality ((int, int)) – chirality of nanotube (n, m)

2D materials ¶

sisl.geom.honeycomb(bond, atoms, orthogonal=False)

Honeycomb lattice with 2 or 4 atoms per unit-cell, latter orthogonal cell

This enables creating BN lattices with ease, or graphene lattices.

Parameters

bond (float) – bond length between atoms (not lattice constant)
atoms (Atom) – the atom (or atoms) that the honeycomb lattice consists of
orthogonal (bool, optional) – if True returns an orthogonal lattice

See also

graphene: the equivalent of this, but with default of Carbon atoms
bilayer: create bilayer honeycomb lattices

sisl.geom.graphene(bond=1.42, atoms=None, orthogonal=False)[source]

Graphene lattice with 2 or 4 atoms per unit-cell, latter orthogonal cell

Parameters

bond (float) – bond length between atoms (not lattice constant)
atom (Atom, optional) – the atom (or atoms) that the honeycomb lattice consists of. Default to Carbon atom.
orthogonal (bool, optional) – if True returns an orthogonal lattice

See also

honeycomb: the equivalent of this, but with non-default atoms
bilayer: create bilayer honeycomb lattices

sisl.geom.bilayer(bond=1.42, bottom_atoms=None, top_atoms=None, stacking='AB', twist=0, 0, separation=3.35, ret_angle=False, layer='both')

Commensurate unit cell of a hexagonal bilayer structure, possibly with a twist angle.

This routine follows the prescription of twisted bilayer graphene found in 1.

Notes

This routine may change in the future to force some of the arguments.

Parameters

bond (float, optional) – bond length between atoms in the honeycomb lattice
bottom_atoms (Atom, optional) – atom (or atoms) in the bottom layer. Defaults to Atom(6)
top_atoms (Atom, optional) – atom (or atoms) in the top layer, defaults to bottom_atom
stacking ({'AB', 'AA', 'BA'}) – stacking sequence of the bilayer, where XY means that site X in bottom layer coincides with site Y in top layer
twist (tuple of int, optional) – integer coordinates (m, n) defining a commensurate twist angle
separation (float, optional) – distance between the two layers
ret_angle (bool, optional) – return the twist angle (in degrees) in addition to the geometry instance
layer ({'both', 'bottom', 'top'}) – control which layer(s) to return

See also

honeycomb: honeycomb lattices
graphene: graphene geometry

References

1

Trambly de Laissardiere, D. Mayou, L. Magaud, “Localization of Dirac Electrons in Rotated Graphene Bilayers”, Nano Letts. 10, 804-808 (2010)

Others ¶

sisl.geom.diamond(alat=3.57, atoms=None)

Diamond lattice with 2 atoms in the unitcell

Parameters

alat (float) – the lattice constant for the diamond
atoms (Atom, optional) – atom in the lattice, may be one or two atoms. Default is Carbon

Physical objects (`sisl.physics`)¶

Implementations of various DFT and tight-binding related quantities are defined. The implementations range from simple Brillouin zone perspectives to self-energy calculations from Hamiltonians.

In sisl the general usage of physical matrices are considering sparse matrices. Hence Hamiltonians, density matrices, etc. are considered sparse. There are exceptions, but it is generally advisable to have this in mind.

Brillouin zone (`brillouinzone`)¶

`BrillouinZone`(parent[, k, weight])	A class to construct Brillouin zone related quantities
`MonkhorstPack`(parent, nkpt[, displacement, …])	Create a Monkhorst-Pack grid for the Brillouin zone
`BandStructure`(parent, point, division[, name])	Create a path in the Brillouin zone for plotting band-structures etc.

Spin configuration¶

Spin([kind, dtype])

Spin class to determine configurations and spin components.

Physical quantites¶

`EnergyDensityMatrix`(geometry[, dim, dtype, …])	Sparse energy density matrix object
`DensityMatrix`(geometry[, dim, dtype, nnzpr])	Sparse density matrix object
`Hamiltonian`(geometry[, dim, dtype, nnzpr])	Sparse Hamiltonian matrix object
`DynamicalMatrix`(geometry[, dim, dtype, nnzpr])	Dynamical matrix of a geometry
`Overlap`(geometry[, dim, dtype, nnzpr])	Sparse overlap matrix object
`SelfEnergy`(args, *kwargs)	Self-energy object able to calculate the dense self-energy for a given sparse matrix
`SemiInfinite`(spgeom, infinite[, eta])	Self-energy object able to calculate the dense self-energy for a given SparseGeometry in a semi-infinite chain.
`RecursiveSI`(spgeom, infinite[, eta])	Self-energy object using the Lopez-Sancho Lopez-Sancho algorithm
`RealSpaceSE`(parent, semi_axis, k_axes[, unfold])	Bulk real-space self-energy (or Green function) for a given physical object with periodicity
`RealSpaceSI`(semi, surface, k_axes[, unfold])	Surface real-space self-energy (or Green function) for a given physical object with limited periodicity

Electrons (`electron`)¶

`DOS`(E, eig[, distribution])	Calculate the density of states (DOS) for a set of energies, E, with a distribution function
`PDOS`(E, eig, state[, S, distribution, spin])	Calculate the projected density of states (PDOS) for a set of energies, E, with a distribution function
`velocity`(state, dHk[, energy, dSk, degenerate])	Calculate the velocity of a set of states
`velocity_matrix`(state, dHk[, energy, dSk, …])	Calculate the velocity matrix of a set of states
`berry_phase`(contour[, sub, eigvals, closed, …])	Calculate the Berry-phase on a loop using a predefined path
`berry_curvature`(state, energy, dHk[, dSk, …])	Calculate the Berry curvature matrix for a set of states (using Kubo)
`conductivity`(bz[, distribution, method, complex])	Electronic conductivity for a given `BrillouinZone` integral
`wavefunction`(v, grid[, geometry, k, spinor, …])	Add the wave-function (Orbital.psi) component of each orbital to the grid
`spin_moment`(state[, S])	Calculate the spin magnetic moment (also known as spin texture)
`spin_orbital_moment`(state[, S])	Calculate the spin magnetic moment per orbital site (equivalent to spin-moment per orbital)
`spin_squared`(state_alpha, state_beta[, S])	Calculate the spin squared expectation value between two spin states
`EigenvalueElectron`(c[, parent])	Eigenvalues of electronic states, no eigenvectors retained
`EigenvectorElectron`(state[, parent])	Eigenvectors of electronic states, no eigenvalues retained
`EigenstateElectron`(state, c[, parent])	Eigen states of electrons with eigenvectors and eigenvalues.

Phonons (`phonon`)¶

`DOS`(E, hw[, distribution])	Calculate the density of modes (DOS) for a set of energies, E, with a distribution function
`PDOS`(E, mode, hw[, distribution])	Calculate the projected density of modes (PDOS) onto each each atom and direction for a set of energies, E, with a distribution function
`velocity`(mode, hw, dDk[, degenerate])	Calculate the velocity of a set of modes
`displacement`(mode, hw, mass)	Calculate real-space displacements for a given mode (in units of the characteristic length)
`EigenvaluePhonon`(c[, parent])	Eigenvalues of phonon modes, no eigenmodes retained
`EigenvectorPhonon`(state[, parent])	Eigenvectors of phonon modes, no eigenvalues retained
`EigenmodePhonon`(state, c[, parent])	Eigenmodes of phonons with eigenvectors and eigenvalues.

Bloch’s theorem (`bloch`)¶

Bloch(*bloch)

Bloch’s theorem object containing unfolding factors and unfolding algorithms

Distribution functions (`distribution`)¶

`get_distribution`(method[, smearing, x0])	Create a distribution function, Gaussian, Lorentzian etc.
`gaussian`(x[, sigma, x0])	Gaussian distribution function
`lorentzian`(x[, gamma, x0])	Lorentzian distribution function
`fermi_dirac`(E[, kT, mu])	Fermi-Dirac distribution function
`bose_einstein`(E[, kT, mu])	Bose-Einstein distribution function
`cold`(E[, kT, mu])	Cold smearing function, Marzari-Vanderbilt, PRL 82, 16, 1999
`step_function`(x[, x0])	Step function, also known as \(1 - H(x)\)
`heaviside`(x[, x0])	Heaviside step function

Low level objects¶

The low level objects are the driving objects for a majority of the physical objects found here. They are rarely (if ever) required to be used, but they may be important for developers wishing to extend the functionality of sisl using generic class-structures. For instance the Hamiltonian inherits the SparseOrbitalBZSpin class and EigenvalueElectron inherits from Coefficient.

States¶

`Coefficient`(c[, parent])	An object holding coefficients for a parent with info
`State`(state[, parent])	An object handling a set of vectors describing a given state
`StateC`(state, c[, parent])	An object handling a set of vectors describing a given state with associated coefficients c

Sparse matrices¶

`SparseOrbitalBZ`(geometry[, dim, dtype, nnzpr])	Sparse object containing the orbital connections in a Brillouin zone
`SparseOrbitalBZSpin`(geometry[, dim, dtype, …])	Sparse object containing the orbital connections in a Brillouin zone with possible spin-components

Input/Output (`sisl.io`)¶

Available files for reading/writing

sisl handles a large variety of input/output files from a large selection of DFT software and other post-processing tools.

Since sisl may be used with many other packages all files are name siles to distinguish them from files from other packages.

Basic IO methods/classes¶

`add_sile`(suffix, cls[, case, gzip])	Add files to the global lookup table
`get_sile`(file, args, *kwargs)	Retrieve an object from the global lookup table via filename and the extension
`SileError`(value[, obj])	Define an error object related to the Sile objects

External code in/out put supported¶

List the relevant codes that sisl can interact with. If there are files you think are missing, please create an issue here.

Generic files
BigDFT (bigdft)
GULP (gulp)
OpenMX (openmx)
ScaleUp (scaleup)
Siesta (siesta)
TranSiesta (siesta)
TBtrans (tbtrans)
VASP (vasp)
Wannier90 (wannier90)

Generic files¶

Files not specificly related to any code.

`tableSile`(filename[, mode, comment])	ASCII tabular formatted data
`xyzSile`(filename[, mode, comment])	XYZ file object
`pdbSile`(filename[, mode, comment])	PDB file object
`cubeSile`(filename[, mode, comment])	CUBE file object
`moldenSile`(filename[, mode, comment])	Molden file object
`xsfSile`(filename[, mode, comment])	XSF file for XCrySDen

BigDFT (`bigdft`)¶

asciiSileBigDFT(filename[, mode, comment])

ASCII file object for BigDFT

GULP (`gulp`)¶

`gotSileGULP`(filename[, mode, comment])	GULP output file object
`fcSileGULP`(filename[, mode, comment])	GULP output file object

OpenMX (`openmx`)¶

omxSileOpenMX(filename[, mode, comment])

OpenMX-input file

ScaleUp (`scaleup`)¶

`orboccSileScaleUp`(filename[, mode, comment])	orbocc file object for ScaleUp
`refSileScaleUp`(filename[, mode, comment])	REF file object for ScaleUp
`rhamSileScaleUp`(filename[, mode, comment])	rham file object for ScaleUp

Siesta (`siesta`)¶

`fdfSileSiesta`(filename[, mode, comment])	FDF-input file
`outSileSiesta`(filename[, mode, comment])	Output file from Siesta
`xvSileSiesta`(filename[, mode, comment])	Geometry file
`bandsSileSiesta`(filename[, mode, comment])	Bandstructure information
`eigSileSiesta`(filename[, mode, comment])	Eigenvalues as calculated in the SCF loop, easy plots using sdata
`pdosSileSiesta`(filename[, mode, comment])	Projected DOS file with orbital information
`gridSileSiesta`(filename[, mode])	Binary real-space grid file
`gridncSileSiesta`(filename[, mode, lvl, access])	NetCDF real-space grid file
`onlysSileSiesta`(filename[, mode])	Geometry and overlap matrix
`dmSileSiesta`(filename[, mode])	Density matrix file
`hsxSileSiesta`(filename[, mode])	Hamiltonian and overlap matrix file
`wfsxSileSiesta`(filename[, mode])	Binary WFSX file reader for Siesta
`ncSileSiesta`(filename[, mode, lvl, access])	Generic NetCDF output file containing a large variety of information
`ionxmlSileSiesta`(filename[, mode, comment])	Basis set information in xml format
`ionncSileSiesta`(filename[, mode, lvl, access])	Basis set information in NetCDF files
`orbindxSileSiesta`(filename[, mode, comment])	Orbital information file
`faSileSiesta`(filename[, mode, comment])	Forces file
`fcSileSiesta`(filename[, mode, comment])	Force constant file
`kpSileSiesta`(filename[, mode, comment])	k-points file in 1/Bohr units
`rkpSileSiesta`(filename[, mode, comment])	Special k-point file with units in reciprocal lattice vectors

TranSiesta (`siesta`)¶

`tshsSileSiesta`(filename[, mode])	Geometry, Hamiltonian and overlap matrix file
`tsdeSileSiesta`(filename[, mode])	Non-equilibrium density matrix and energy density matrix file
`tsgfSileSiesta`(filename[, mode])	Surface Green function file containing, Hamiltonian, overlap matrix and self-energies
`tsvncSileSiesta`(filename[, mode, lvl, access])	TranSiesta potential input Grid file object

TBtrans (`tbtrans`)¶

`tbtncSileTBtrans`(filename[, mode, lvl, access])	TBtrans output file object
`deltancSileTBtrans`(filename[, mode, lvl, access])	TBtrans \(\delta\) file object
`tbtgfSileTBtrans`(filename[, mode])	Surface Green function file containing, Hamiltonian, overlap matrix and self-energies
`tbtsencSileTBtrans`(filename[, mode, lvl, access])	TBtrans self-energy file object with downfolded self-energies to the device region
`tbtavncSileTBtrans`(filename[, mode, lvl, access])	TBtrans average file object
`tbtprojncSileTBtrans`(filename[, mode, lvl, …])	TBtrans projection file object

Additionally the PHtrans code also has these files

`phtncSilePHtrans`(filename[, mode, lvl, access])	PHtrans file object
`phtsencSilePHtrans`(filename[, mode, lvl, access])	PHtrans file object
`phtavncSilePHtrans`(filename[, mode, lvl, access])	PHtrans file object
`phtprojncSilePHtrans`(filename[, mode, lvl, …])	PHtrans projection file object

VASP (`vasp`)¶

`carSileVASP`(filename[, mode, comment])	*CAR VASP files for defining geomtries
`doscarSileVASP`(filename[, mode, comment])	Density of states output
`eigenvalSileVASP`(filename[, mode, comment])	Kohn-Sham eigenvalues
`chgSileVASP`(filename[, mode, comment])	Charge density plus geometry
`locpotSileVASP`(filename[, mode, comment])	Electrostatic (or total) potential plus geometry

Wannier90 (`wannier90`)¶

winSileWannier90(filename[, mode, comment])

Wannier seedname input file object

Low level methods/classes¶

Classes and methods generically only used internally. If you wish to create your own Sile you should inherit either of Sile (ASCII), SileCDF (NetCDF) or SileBin (binary), then subsequently add it using add_sile which enables its generic use in all routines etc.

`get_siles`([attrs])	Retrieve all files with specific attributes or methods
`get_sile_class`(filename, args, *kwargs)	Retrieve a class from the global lookup table via filename and the extension
`BaseSile`	Base class for all sisl files
`Sile`(filename[, mode, comment])	Base class for ASCII files
`SileCDF`(filename[, mode, lvl, access])	Creates/Opens a SileCDF
`SileBin`(filename[, mode])	Creates/Opens a SileBin

Physical constants (`sisl.constant`)¶

Module containing a pre-set set of physical constants. The SI units are following the new convention that takes effect on 20 May 2019.

The currently stored constants are (all are given in SI units):

`PhysicalConstant`	Class to create a physical constant with unit-conversion capability, works exactly like a float.
`q`	Unit of charge [C], or [A s]
`c`	Speed of light [m/s]
`h`	Plancks constant [J s]
`hbar`	Reduced Plancks constant [J s]
`m_e`	Mass of electron [kg]
`m_p`	Mass of proton [kg]
`G0`	Conductance quantum [S], or [m^2/s^2]
`G`	Gravitational constant [m^3/kg/s^2]

All constants may be used like an ordinary float (which converts it to a float):

>>> c
299792458.0 m/s
>>> c * 2
599584916

while one can just as easily convert the units (which ensures thay stay like another PhysicalConstant):

>>> c('Ang/ps')
2997924.58 Ang/ps

Unit conversion (`sisl.unit`)¶

Generic conversion utility between different units.

All different codes unit conversion routines should adhere to the same routine names for consistency and readability. This package should supply a subpackage for each code where specific unit conversions are required. I.e. if the codes unit conversion are not the same as the sisl defaults.

Default unit conversion utilities¶

`unit_group`(unit[, tbl])	The group of units that unit belong to
`unit_convert`(fr, to[, opts, tbl])	Factor that takes ‘fr’ to the units of ‘to’.
`unit_default`(group[, tbl])	The default unit of the unit group group.
`units`	Object for converting between units for a set of unit-tables.

All subsequent subpackages also exposes the above 4 methods. If a subpackage method is used, the unit conversion corresponds to the units defined in the respective code.

The units object is by far the easiest version to use since it handles complex units (Ry/kg/Bohr N) while unit_convert is the basic unit-conversion table that only converts simple units. E.g. Ry to eV etc.

Siesta units (`sisl.unit.siesta`)¶

This subpackage implements the unit conversions used in Siesta.

To use the unit conversion from Siesta, simply import units as:

>>> from sisl.unit import units
>>> from sisl.unit.siesta import units as siesta_units

in which case units will refer to default unit conversions and siesta_units will use the unit definitions in Siesta.

Shapes (`sisl.shape`)¶

A variety of default shapes.

All shapes inherit the Shape class.

All shapes in sisl allows one to perform arithmetic on them. I.e. one may add two shapes to accomblish what would be equivalent to an & operation. The resulting shape will be a CompositeShape which implements the necessary routines to ensure correct operation.

Currently these mathematical/boolean operators are implemented:

A & B: intersection of shapes
A | B or A + B: union of shapes
A ^ B: the disjunction union
A - B: complementary shape

`Shape`(center)	Baseclass for all shapes.
`Cuboid`(v[, center])	A cuboid/rectangular prism (P4)
`Cube`(side[, center])	3D Cube with equal sides
`Ellipsoid`(v[, center])	3D Ellipsoid shape
`Sphere`(radius[, center])	3D Sphere
`NullShape`(args, *kwargs)	A unique shape which has no well-defined spatial volume or center

Utility routines (`sisl.utils`)¶

Several utility functions are used throughout sisl.

Range routines¶

`array_arange`(start[, end, n, dtype])	Creates a single array from a sequence of `numpy.arange`
`strmap`(func, s[, start, end, sep])	Parse a string as though it was a slice and map all entries using `func`.
`strseq`(cast, s[, start, end])	Accept a string and return the casted tuples of content based on ranges.
`lstranges`(lst[, cast, end])	Convert a `strmap` list into expanded ranges
`erange`(start, step[, end])	Returns the range with both ends includede
`list2str`(lst)	Convert a list of elements into a string of ranges
`fileindex`(f[, cast])	Parses a filename string into the filename and the indices.

Miscellaneous routines¶

`str_spec`(name)	Split into a tuple of name and specifier, delimited by `{...}`.
`direction`(d)	Return the index coordinate index corresponding to the Cartesian coordinate system.
`angle`(s[, rad, in_rad])	Convert the input string to an angle, either radians or degrees.
`iter_shape`(shape)	Generator for iterating a shape by returning consecutive slices
`math_eval`(expr)	Evaluate a mathematical expression using a safe evaluation method

A table of contents for all methods may be found here while a table of contents for the sub-modules may be found here.

sisl: tight-binding and DFT interface library¶

First time use¶

Every use of sisl¶

Introduction¶

Package¶

DFT¶

Geometry manipulation¶

Command line usage¶

Contributing¶

Contribute external code¶

Other resources¶

Citing sisl¶

Citing basic usage¶

Citing transport backend¶

Publications using sisl¶

arXiv publications¶

Installation¶

Required dependencies¶

pip3¶

conda¶

Manual installation¶

Testing your installation¶

Development version¶

Tutorials¶

Siesta/TranSiesta support¶

Deprecated tutorials¶

Geometry creation – part 1¶

Geometry creation – part 2¶

Specifying super-cell information¶

Example – square¶

Example – graphene¶

Electronic structure setup – part 1¶

Example – square¶

Example – graphene¶

Electronic structure setup – part 2¶

Examples¶

Graphene tight-binding model¶

Scripts¶

sdata¶

Files with Geometry¶

Files with Grid¶

sgeom¶

Conversion¶

Available formats¶

Advanced Features¶

Repeating/Tiling structures¶

Rotating structure¶

Combining command line arguments¶

sgrid¶

Creating CUBE files¶

Grid differences¶

Reducing grid sizes¶

Averaging and summing¶

Advanced features¶

Visualization¶

ASE¶

File formats¶

API documentation¶

sisl (sisl)¶

Generic classes¶

Advanced classes¶

Common geometries (sisl.geom)¶

Basic¶

1D materials¶

2D materials¶

Others¶

Physical objects (sisl.physics)¶

Brillouin zone (brillouinzone)¶

Spin configuration¶

Physical quantites¶

Electrons (electron)¶

Phonons (phonon)¶

Bloch’s theorem (bloch)¶

Distribution functions (distribution)¶

Low level objects¶

States¶

Sparse matrices¶

Input/Output (sisl.io)¶

Basic IO methods/classes¶

External code in/out put supported¶

sisl (`sisl`)¶

Common geometries (`sisl.geom`)¶

Basic ¶

1D materials ¶

2D materials ¶

Others ¶

Physical objects (`sisl.physics`)¶

Brillouin zone (`brillouinzone`)¶

Electrons (`electron`)¶

Phonons (`phonon`)¶

Bloch’s theorem (`bloch`)¶

Distribution functions (`distribution`)¶

Input/Output (`sisl.io`)¶

BigDFT (`bigdft`)¶

GULP (`gulp`)¶

OpenMX (`openmx`)¶

ScaleUp (`scaleup`)¶

Siesta (`siesta`)¶

TranSiesta (`siesta`)¶

TBtrans (`tbtrans`)¶

VASP (`vasp`)¶

Wannier90 (`wannier90`)¶

Physical constants (`sisl.constant`)¶

Unit conversion (`sisl.unit`)¶

Siesta units (`sisl.unit.siesta`)¶

Shapes (`sisl.shape`)¶

Utility routines (`sisl.utils`)¶