It is important to read the tutorials before looking at the questions. This FAQ
is aimed to add complementary explainations that are not in the tutorials. The `Kwant paper <https://downloads.kwant-project.org/doc/kwant-paper.pdf>`_ also digs deeper into Kwant's structure.
This FAQ complements the regular Kwant tutorials and thus does not cover
questions that are discussed there. The `Kwant paper
<https://downloads.kwant-project.org/doc/kwant-paper.pdf>`_ also digs deeper
into Kwant's structure.
What is a system, and what is a builder?
========================================
A Kwant system represents a tight-binding model. It contains a graph of edges
and vertices that are assigned values, and which is used to construct
the Hamiltonian for the model being simulated.
In Kwant the specification of the tight-binding model is separated from the use
of the model in numerical calculations. The `~kwant.builder.Builder` is used
when specifying/constructing the model, then the
`~kwant.builder.Builder.finalize` method is called, which produces a so-called
low-level `~kwant.system.System` that can be used by Kwant's solvers.
In the documentation and in mailing list discussions, the term general term
"system" can be used to refer either to a ``Builder`` or to a low-level
A Kwant system represents a particular tight-binding model. It contains a graph
whose edges and vertices are assigned values, and that corresponds to the
Hamiltonian matrix of the model being simulated.
In Kwant the creation of the system is separated from its use in numerical
calculations. First an instance of the `~kwant.builder.Builder` class is used
to construct the model, then the `~kwant.builder.Builder.finalize` method is
called, which produces a so-called low-level `~kwant.system.System` that can be
used by Kwant's solvers.
The interface of builders mimics Python mappings (e.g. dictionaries). The
familiar square-bracket syntax allows to set, get and delete items that
correspond to elements of the system graph, e.g. ``syst[key] = value``. An
item consists of a key and an associated value. Keys are `sites <What is a
site?_>`_ and `hoppings <What is a hopping?_>`_. Values can be numbers, arrays
of numbers, or functions that return numbers or arrays.
Finalizing a builder returns a copy of the system with the graph *structure*
frozen. (This can be equivalently seen as freezing the system geometry or the
sparsity structure of the Hamiltonian.) The associated *values* are taken over
verbatim. Note that finalizing does not freeze the Hamiltonian matrix: only
its structure is fixed, values that are functions may depend on an arbitrary
number of parameters.
In the documentation and in mailing list discussions, the general term
"system" can refer either to a ``Builder`` or to a low-level
``System``, and the context will determine which specific class is being
referred to. The terms "builder" and "low-level system" (or "finalized system")
refer respectively to ``Builder`` and ``System``.
...
...
@@ -27,9 +42,9 @@ refer respectively to ``Builder`` and ``System``.
What is a site?
===============
Kwant is a tool for working with tight-binding models, which can be viewed as a
graph composed of edges and vertices. Site objects are Kwant’s abstraction for
the vertices. Sites have two attributes: a **family** and a **tag** . The
combination of family and tag uniquely define a site.
graph composed of edges and vertices. Sites are Kwant’s labels for the
vertices. Sites have two attributes: a *family* and a *tag*. The
combination of family and tag uniquely defines a site.
For example let us create an empty tight binding system and add two sites:
...
...
@@ -39,14 +54,57 @@ For example let us create an empty tight binding system and add two sites:
.. image:: ../images/faq_site.*
In the above snippet we added 2 sites: ``lat(1,0)`` and ``lat(0, 1)``. Both
In the above snippet we added 2 sites: ``lat(1,0)`` and ``lat(0, 1)``. Both
of these sites belong to the same family, ``lat``, but have different tags:
``(1, 0)`` and ``(0, 1)`` respectively.
Both sites were given the value 4 which means that the above system corresponds
to the Hamiltonian matrix
.. math::
H = \left(
\begin{array}{cc}
4 & 0 \\
0 & 4
\end{array}
\right).
What is a hopping?
==================
A hopping is simply a tuple of two of sites, which defines an edge of the graph
that makes up a tight-binding model. Other sequences of sites that are not
tuples, for example lists, are not treated as hoppings.
Starting from the example code from `What is a site?`_, we can add a hopping
to our system in the following way:
.. literalinclude:: faq.py
:start-after: #HIDDEN_BEGIN_hopping
:end-before: #HIDDEN_END_hopping
.. image:: ../images/faq_hopping.*
Visually, a hopping is represented as a line that joins two sites.
The Hamiltonian matrix is now
.. math::
H = \left(
\begin{array}{cc}
4 & i \\
-i & 4
\end{array}
\right).
Note how adding ``(site_a, site_b)`` to a system and assigning it a value
``v``, implicitly adds the hopping ``(site_b, site_a)`` with the Hermitian
conjugate of ``v`` as value.
What is a site family, and what is a tag?
=========================================
a site family "groups" related sites together, and a tag serves as a unique
A site family groups related sites together, and a tag serves as a unique
identifier for a site within a given family.
In the previous example we saw a family that was suggestively called ``lat``,
...
...
@@ -63,48 +121,53 @@ are tagged by letters of the alphabet.
What is a lattice?
==================
Kwant allows users to define and use Bravais lattices for dealing with
collections of regularly placed sites. They know about things like which sites
on the lattice are neighbors, and how to fill a region of realspace with sites.
``Monatomic`` lattices have a single site in their basis, while ``Polyatomic``
have more than one site in their basis.
``Monatomic`` lattices in Kwant *are also site families*, with sites that are
tagged with tuples of integers: the site's coordinates in the basis of
primitive vectors of the lattice. ``Polyatomic`` lattices, however, are *not*
site families, as lattice coordinates are not enough information to uniquely
identify a site if there is more than one site in the basis. ``Polyatomic``
Kwant allows to define and use Bravais lattices for dealing with collections of
regularly placed sites. They know about things like what sites are
neighbors, or what sites belong to a given region of realspace.
`~kwant.lattice.Monatomic` lattices have a single site in their basis, while
`~kwant.lattice.Polyatomic` lattices have more than one site in their basis.
Monatomic lattices in Kwant *are also site families*, with sites that are
tagged by tuples of integers: the site's coordinates in the basis of
primitive vectors of the lattice. Polyatomic lattices, however, are *not*
site families, since lattice coordinates are not enough information to uniquely
identify a site if there is more than one site in the basis. Polyatomic
lattices do, however, have an attribute ``sublattices`` that is a list of
``Monatomic`` lattices that together make up the whole ``Polyatomic`` lattice.
monatomic lattices that together make up the whole polyatomic lattice.
For example:
Let's create two monatomic lattices (``lat_a`` and ``lat_b``). ``(1, 0)``
and ``(0, 1)`` will be the primitive vectors and ``(0, 0)`` and ``(0.5, 0.5)``
the origins of the two lattices:
.. literalinclude:: faq.py
:start-after: #HIDDEN_BEGIN_lattice
:end-before: #HIDDEN_END_lattice
:start-after: #HIDDEN_BEGIN_lattice_monatomic
:end-before: #HIDDEN_END_lattice_monatomic
.. image:: ../images/faq_lattice.*
Above, we created 2 ``Monatomic`` lattices (``lat1`` and ``lat2``). ``(1, 0)``
and ``(0, 1)`` are the primitive vectors and ``(0, 0)`` and ``(0.5, 0.5)`` are
the origins of the two lattices. Next we create a ``Polyatomic`` lattice with the
same primitive vectors and 2 sites in the basis.
We can also create a ``Polyatomic`` lattice with the same primitive vectors and
two sites in the basis:
.. literalinclude:: faq.py
:start-after: #HIDDEN_BEGIN_lattice_polyatomic
:end-before: #HIDDEN_END_lattice_polyatomic
The two sublattices are equivalent to the two monatomic lattices that we
created previously. Because a ``Polyatomic`` lattice knows about its
sublattices, we can do things like calculate neighboring sites, even between
sublattices, which would not be possible with the two separate ``Monatomic``
lattices.
The two sublattices ``sub_a`` and ``sub_b`` are nothing else than ``Monatomic``
instances, and are equivalent to ``lat_a`` and ``lat_b`` that we created
previously. The advantage of the second approach is that there is now a
``Polyatomic`` object that is aware of both of its sublattices, and we can do
things like calculate neighboring sites, even between sublattices, which would
not be possible with the two separate ``Monatomic`` lattices.
the `kwant.lattice` module also defines several functions, such as
`~kwant.lattice.square` and `~kwant.lattice.honeycomb`, which serve as a
convenience for creating lattices of common types, without having to
explicitly specify all of the lattice vectors and basis vectors.
The `kwant.lattice` module also defines several convenience functions, such as
`~kwant.lattice.square` and `~kwant.lattice.honeycomb`, for creating lattices
of common types, without having to explicitly specify all of the lattice
vectors and basis vectors.
How do I plot a polyatomic lattice with different colors?
