@@ -42,7 +42,7 @@ description check `~kwant.plotter.plot` documentation.

 The behavior of `~kwant.plotter.plot` with low level systems has changed.

 Arguments of plot which are functions are given site numbers in place of

-`~kwant.builder.Site` objects when plotting a low level system.  This

+`~kwant.system.Site` objects when plotting a low level system.  This

 provides an easy way to make the appearance of lines and symbols depend on

 computation results.

@@ -39,7 +39,7 @@ now it suffices to write ::

     syst[lat.neighbors()] = t

 This is possible because `~kwant.builder.Builder` now accepts *functions* as

-keys in addition to `~kwant.builder.Site` objects and tuples of them

+keys in addition to `~kwant.system.Site` objects and tuples of them

 (hoppings).  These functions are expected to yield either sites or hoppings,

 when given a builder instance as the sole argument. The use of such keys is to

 implement sets of sites or hoppings that depend on what is already present in

@@ -3,6 +3,40 @@ What's new in Kwant 1.5

 This article explains the user-visible changes in Kwant 1.5.0.

+

+Value functions may now be vectorized

+-------------------------------------

+It is now possible to define value functions that act on whole

+arrays of sites at a time.

+::

+

+    def onsite(sites):

+        r = sites.positions()

+        return np.exp(-np.linalg.norm(r, axis=1)**2)

+

+    def hopping(to_sites, from_sites):

+        dr = to_sites.positions() - from_sites.positions()

+        return 1 / np.linalg.norm(dr, axis=1)**2

+

+

+    lat = kwant.lattice.square(norbs=1)

+    syst = kwant.Builder(vectorize=True)

+    syst[(lat(i, j) for i in range(4) for j in range(10)] = onsite

+    syst[lat.neighbors()] = hopping

+    syst = syst.finalized()

+

+    syst.hamiltonian_submatrix()

+

+Notice that when creating the Builder we provide the ``vectorize=True`` flag,

+and that the value functions now take `~kwant.system.SiteArray` objects

+(which have a ``positions`` method, rather than a ``pos`` property as for

+`~kwant.system.Site`). We can now operate on the array of site positions

+using ``numpy``. Using vectorized value functions in this way can produce an

+order of magnitude speedup when evaluating system Hamiltonians (though this

+speedup may be masked by other parts of your computation e.g. calculating

+the scattering matrix).

+

+

 Deprecation of leaving 'norbs' unset for site families

 ------------------------------------------------------

 When constructing site families (e.g. lattices) it is now deprecated to

@@ -9,7 +9,6 @@ Types

    :toctree: generated/

    Builder

-   Site

    HoppingKind

    SimpleSiteFamily

    BuilderLead

@@ -17,13 +16,14 @@ Types

    ModesLead

    FiniteSystem

    InfiniteSystem

+   FiniteVectorizedSystem

+   InfiniteVectorizedSystem

 Abstract base classes

 ---------------------

 .. autosummary::

    :toctree: generated/

-   SiteFamily

    Symmetry

    Lead

@@ -33,3 +33,11 @@ Functions

    :toctree: generated/

    add_peierls_phase

+

+Mixin Classes

+-------------

+.. autosummary::

+   :toctree: generated/

+

+   _FinalizedBuilderMixin

+   _VectorizedFinalizedBuilderMixin

@@ -19,10 +19,32 @@ In practice, very often Kwant systems are finalized

 `kwant.builder.FiniteSystem` or `kwant.builder.InfiniteSystem`) and offer some

 additional attributes.

+Sites

+-----

+.. autosummary::

+   :toctree: generated/

+

+   Site

+   SiteArray

+   SiteFamily

+

+Systems

+-------

 .. autosummary::

    :toctree: generated/

    System

+   VectorizedSystem

    InfiniteSystem

+   InfiniteVectorizedSystem

    FiniteSystem

+   FiniteVectorizedSystem

    PrecalculatedLead

+

+Mixin Classes

+-------------

+.. autosummary::

+   :toctree: generated/

+

+   FiniteSystemMixin

+   InfiniteSystemMixin

@@ -358,13 +358,13 @@ subbands that increases with energy.

      **sites** as indices. Sites themselves have a certain type, and

      belong to a **site family**. A site family is also used to convert

      something that represents a site (like a tuple) into a

-     proper `~kwant.builder.Site` object that can be used with

+     proper `~kwant.system.Site` object that can be used with

      `~kwant.builder.Builder`.

      In the above example, `lat` is the site family. ``lat(i, j)``

      then translates the description of a lattice site in terms of two

      integer indices (which is the natural way to do here) into

-     a proper `~kwant.builder.Site` object.

+     a proper `~kwant.system.Site` object.

      The concept of site families and sites allows `~kwant.builder.Builder`

      to mix arbitrary lattices and site families

@@ -438,7 +438,7 @@ the `~kwant.operator.Current`, instead of a constant matrix:

     # evaluate the operator

     m_current = J_m(psi, params=dict(r0=25, delta=10))

-The function must take a `~kwant.builder.Site` as its first parameter,

+The function must take a `~kwant.system.Site` as its first parameter,

 and may optionally take other parameters (i.e. it must have the same

 signature as a Hamiltonian onsite function), and must return the square

 matrix that defines the operator we wish to calculate.

@@ -529,8 +529,8 @@ We see that the probability current is conserved across the scattering region,

 but the z-projected spin current is not due to the fact that the Hamiltonian

 does not commute with :math:`σ_z` everywhere in the scattering region.

-.. note:: ``where`` can also be provided as a sequence of `~kwant.builder.Site`

-          or a sequence of hoppings (i.e. pairs of `~kwant.builder.Site`),

+.. note:: ``where`` can also be provided as a sequence of `~kwant.system.Site`

+          or a sequence of hoppings (i.e. pairs of `~kwant.system.Site`),

           rather than a function.

@@ -105,7 +105,7 @@ the start end end site of hopping as arguments:

     kwant.plot(syst, site_lw=0.1, site_color=family_color, hop_lw=hopping_lw);

 Note that since we are using an unfinalized Builder, a ``site`` is really an

-instance of `~kwant.builder.Site`. With these adjustments we arrive at a plot

+instance of `~kwant.system.Site`. With these adjustments we arrive at a plot

 that carries the same information, but is much easier to interpret.

 Apart from plotting the *system* itself, `~kwant.plotter.plot` can also be used

@@ -175,7 +175,7 @@ this is interpreted as the radius of the inner circle).

 Finally, note that since we are dealing with a finalized system now, a site `i`

 is represented by an integer. In order to obtain the original

-`~kwant.builder.Site`, ``syst.sites[i]`` can be used.

+`~kwant.system.Site`, ``syst.sites[i]`` can be used.

 The way how data is presented of course influences what features of the data

 are best visible in a given plot. With `~kwant.plotter.plot` one can easily go

@@ -285,7 +285,7 @@ define the potential profile of a quantum well as:

         else:

             return 0

-This function takes two arguments: the first of type `~kwant.builder.Site`,

+This function takes two arguments: the first of type `~kwant.system.Site`,

 from which you can get the real-space coordinates using ``site.pos``, and the

 value of the potential as the second.  Note that in `potential` we can access

 variables `L` and `L_well` that are defined globally.

@@ -375,10 +375,10 @@ oscillatory transmission behavior through resonances in the quantum well.

 .. specialnote:: Technical details

   - Functions can also be used for hoppings. In this case, they take

-    two `~kwant.builder.Site`'s as arguments and then an arbitrary number

+    two `~kwant.system.Site`'s as arguments and then an arbitrary number

     of additional arguments.

-  - Apart from the real-space position `pos`, `~kwant.builder.Site` has also an

+  - Apart from the real-space position `pos`, `~kwant.system.Site` has also an

     attribute `tag` containing the lattice indices of the site.

 .. _tutorial-abring:

@@ -449,7 +449,7 @@ that returns ``True`` whenever a point is inside the shape, and

         return (r1 ** 2 < rsq < r2 ** 2)

 Note that this function takes a real-space position as argument (not a

-`~kwant.builder.Site`).

+`~kwant.system.Site`).

 We can now simply add all of the lattice points inside this shape at

 once, using the function `~kwant.lattice.Square.shape`

@@ -1,4 +1,4 @@

-# Copyright 2011-2013 Kwant authors.

+# Copyright 2011-2019 Kwant authors.

 #

 # This file is part of Kwant.  It is subject to the license terms in the file

 # LICENSE.rst found in the top-level directory of this distribution and at

@@ -12,12 +12,16 @@ import numpy as np

 from scipy import sparse as sp

 from itertools import chain

 import types

+import bisect

 from .graph.core cimport CGraph, gintArraySlice

 from .graph.defs cimport gint

 from .graph.defs import gint_dtype

 from ._common import deprecate_args

+

+### Non-vectorized methods

+

 msg = ('Hopping from site {0} to site {1} does not match the '

        'dimensions of onsite Hamiltonians of these sites.')

@@ -352,3 +356,383 @@ def hamiltonian_submatrix(self, args=(), to_sites=None, from_sites=None,

         mat = func(ham, args, params, self.graph, diag, from_sites,

                    n_by_to_site, to_norb, to_off, from_norb, from_off)

     return (mat, to_norb, from_norb) if return_norb else mat

+

+

+### Vectorized methods

+

+

+_shape_error_msg = (

+    "The following hoppings have matrix elements of incompatible shape "

+    "with other matrix elements: {}"

+)

+

+

+@cython.boundscheck(False)

+def _vectorized_make_sparse(subgraphs, hams, long [:] norbs, long [:] orb_offsets,

+                 long [:] site_offsets, shape=None):

+    ndata = sum(h.shape[0] * h.shape[1] * h.shape[2] for h in hams)

+

+    cdef long [:] rows_view, cols_view

+    cdef complex [:] data_view

+

+    rows = np.empty((ndata,), dtype=long)

+    cols = np.empty((ndata,), dtype=long)

+    data = np.empty((ndata,), dtype=complex)

+    rows_view = rows

+    cols_view = cols

+    data_view = data

+

+    cdef long i, j, k, m, N, M, P, to_off, from_off,\

+              ta, fa, to_norbs, from_norbs

+    cdef long [:] ts_offs, fs_offs

+    cdef complex [:, :, :] h

+

+    m = 0

+    # This outer loop zip() is pure Python, but that's ok, as it

+    # has very few entries and the inner loops are fully vectorized

+    for ((ta, fa), (ts_offs, fs_offs)), h in zip(subgraphs, hams):

+        N = h.shape[0]

+        M = h.shape[1]

+        P = h.shape[2]

+

+        if norbs[ta] != M or norbs[fa] != P:

+            to_sites = site_offsets[ta] + np.array(ts_offs)

+            from_sites = site_offsets[fa] + np.array(fs_offs)

+            hops = np.array([to_sites, from_sites]).transpose()

+            raise ValueError(_shape_error_msg.format(hops))

+

+        for i in range(N):

+            to_off = orb_offsets[ta] + norbs[ta] * ts_offs[i]

+            from_off = orb_offsets[fa] + norbs[fa] * fs_offs[i]

+            for j in range(M):

+                for k in range(P):

+                    rows_view[m] = to_off + j

+                    cols_view[m] = from_off + k

+                    data_view[m] = h[i, j, k]

+                    m += 1

+

+    if shape is None:

+        shape = (orb_offsets[-1], orb_offsets[-1])

+

+    return sp.coo_matrix((data, (rows, cols)), shape=shape)

+

+

+@cython.boundscheck(False)

+def _vectorized_make_dense(subgraphs, hams, long [:] norbs, long [:] orb_offsets,

+                long [:] site_offsets, shape=None):

+    if shape is None:

+        shape = (orb_offsets[-1], orb_offsets[-1])

+    mat = np.zeros(shape, dtype=complex)

+    cdef complex [:, :] mat_view

+    mat_view = mat

+

+    cdef long i, j, k, N, M, P, to_off, from_off,\

+              ta, fa, to_norbs, from_norbs

+    cdef long [:] ts_offs, fs_offs

+    cdef complex [:, :, :] h

+

+    # This outer loop zip() is pure Python, but that's ok, as it

+    # has very few entries and the inner loops are fully vectorized

+    for ((ta, fa), (ts_offs, fs_offs)), h in zip(subgraphs, hams):

+        N = h.shape[0]

+        M = h.shape[1]

+        P = h.shape[2]

+

+        if norbs[ta] != M or norbs[fa] != P:

+            to_sites = site_offsets[ta] + np.array(ts_offs)

+            from_sites = site_offsets[fa] + np.array(fs_offs)

+            hops = np.array([to_sites, from_sites]).transpose()

+            raise ValueError(_shape_error_msg.format(hops))

+

+        for i in range(N):

+            to_off = orb_offsets[ta] + norbs[ta] * ts_offs[i]

+            from_off = orb_offsets[fa] + norbs[fa] * fs_offs[i]

+            for j in range(M):

+                for k in range(P):

+                    mat_view[to_off + j, from_off + k] = h[i, j, k]

+    return mat

+

+

+def _count_norbs(syst, site_offsets, hams, args=(), params=None):

+    """Return the norbs and orbital offset of each site family in 'syst'

+

+    Parameters

+    ----------

+    syst : `kwant.system.System`

+    site_offsets : sequence of int

+        Contains the index of the first site for each site array

+        in 'syst.site_arrays'.

+    hams : sequence of arrays or 'None'

+        The Hamiltonian for each term in 'syst.terms'. 'None'

+        if the corresponding term has not been evaluated.

+    args, params : positional and keyword arguments to the system Hamiltonian

+    """

+    site_ranges = syst.site_ranges

+    if site_ranges is None:

+        # NOTE: Remove this branch once we can rely on

+        #       site families storing the norb information.

+

+        site_arrays = syst.site_arrays

+        family_norbs = {s.family: None for s in site_arrays}

+

+        # Compute the norbs per site family using already evaluated

+        # Hamiltonian terms where possible

+        for ham, t in zip(hams, syst.terms):

+            (to_w, from_w), _ = syst.subgraphs[t.subgraph]

+            if ham is not None:

+                family_norbs[site_arrays[to_w].family] = ham.shape[1]

+                family_norbs[site_arrays[from_w].family] = ham.shape[2]

+

+        # Evaluate Hamiltonian terms where we do not already have them

+        for n, t in enumerate(syst.terms):

+            (to_w, from_w), _ = syst.subgraphs[t.subgraph]

+            to_fam = site_arrays[to_w].family

+            from_fam = site_arrays[from_w].family

+            if family_norbs[to_fam] is None or family_norbs[from_fam] is None:

+                ham = syst.hamiltonian_term(n, args=args, params=params)

+                family_norbs[to_fam] = ham.shape[1]

+                family_norbs[from_fam] = ham.shape[2]

+

+        # This case is technically allowed by the format (some sites present

+        # but no hamiltonian terms that touch them) but is very unlikely.

+        if any(norbs is None for norbs in family_norbs.values()):

+            raise ValueError("Cannot determine the number of orbitals for "

+                             "some site families.")

+

+        orb_offset = 0

+        site_ranges = []

+        for start, site_array in zip(site_offsets, syst.site_arrays):

+            norbs = family_norbs[site_array.family]

+            site_ranges.append((start, norbs, orb_offset))

+            orb_offset += len(site_array) * norbs

+        site_ranges.append((site_offsets[-1], 0, orb_offset))

+        site_ranges = np.array(site_ranges)

+

+    _, norbs, orb_offsets = site_ranges.transpose()

+    # The final (extra) element in orb_offsets is the total number of orbitals

+    assert len(orb_offsets) == len(syst.site_arrays) + 1

+

+    return norbs, orb_offsets

+

+

+def _expand_norbs(compressed_norbs, site_offsets):

+    "Return norbs per site, given norbs per site array."

+    norbs = np.empty(site_offsets[-1], int)

+    for start, stop, norb in zip(site_offsets, site_offsets[1:],

+                                  compressed_norbs):

+        norbs[start:stop] = norb

+    return norbs

+

+

+def _reverse_subgraph(subgraph):

+    (to_sa, from_sa), (to_off, from_off) = subgraph

+    return ((from_sa, to_sa), (from_off, to_off))

+

+

+@deprecate_args

+@cython.binding(True)

+def vectorized_hamiltonian_submatrix(self, args=(), sparse=False,

+                                     return_norb=False, *, params=None):

+    """Return The system Hamiltonian.

+

+    Parameters

+    ----------

+    args : tuple, defaults to empty

+        Positional arguments to pass to ``hamiltonian_term``. Mutually

+        exclusive with 'params'.

+    sparse : bool

+        Whether to return a sparse or a dense matrix. Defaults to ``False``.

+    return_norb : bool

+        Whether to return arrays of numbers of orbitals.  Defaults to ``False``.

+    params : dict, optional

+        Dictionary of parameter names and their values. Mutually exclusive

+        with 'args'.

+

+    Returns

+    -------

+    hamiltonian_part : numpy.ndarray or scipy.sparse.coo_matrix

+       The Hamiltonian of the system.

+    norb : array of integers

+        Numbers of orbitals on each site. Only returned when ``return_norb``

+        is true.

+

+    Notes

+    -----

+    Providing positional arguments via 'args' is deprecated,

+    instead, provide named parameters as a dictionary via 'params'.

+    """

+

+    site_offsets = np.cumsum([0] + [len(arr) for arr in self.site_arrays])

+

+    subgraphs = [

+        self.subgraphs[t.subgraph]

+        for t in self.terms

+    ]

+    # Add Hermitian conjugates

+    subgraphs += [

+        _reverse_subgraph(self.subgraphs[t.subgraph])

+        for t in self.terms

+        if t.hermitian

+    ]

+

+    hams = [

+        self.hamiltonian_term(n, args=args, params=params)

+        for n, _ in enumerate(self.terms)

+    ]

+    # Add Hermitian conjugates

+    hams += [

+        ham.conjugate().transpose(0, 2, 1)

+        for ham, t in zip(hams, self.terms)

+        if t.hermitian

+    ]

+

+    norbs, orb_offsets = _count_norbs(self, site_offsets, hams,

+                                      args=args, params=params)

+

+    func = _vectorized_make_sparse if sparse else _vectorized_make_dense

+    mat = func(subgraphs, hams, norbs, orb_offsets, site_offsets)

+

+    if return_norb:

+        return (mat, _expand_norbs(norbs, site_offsets))

+    else:

+        return mat

+

+

+@deprecate_args

+@cython.binding(True)

+def vectorized_cell_hamiltonian(self, args=(), sparse=False, *, params=None):

+    """Hamiltonian of a single cell of the infinite system.

+

+    Providing positional arguments via 'args' is deprecated,

+    instead, provide named parameters as a dictionary via 'params'.

+    """

+

+    site_offsets = np.cumsum([0] + [len(arr) for arr in self.site_arrays])

+    # Site array where next cell starts

+    next_cell = bisect.bisect(site_offsets, self.cell_size) - 1

+

+    def inside_cell(term):

+        (to_which, from_which), _= self.subgraphs[term.subgraph]

+        return to_which < next_cell and from_which < next_cell

+

+    cell_terms = [

+        n for n, t in enumerate(self.terms)

+        if inside_cell(t)

+    ]

+

+    subgraphs = [

+        self.subgraphs[self.terms[n].subgraph]

+        for n in cell_terms

+    ]

+    # Add Hermitian conjugates

+    subgraphs += [

+        _reverse_subgraph(self.subgraphs[self.terms[n].subgraph])

+        for n in cell_terms

+        if self.terms[n].hermitian

+    ]

+

+    hams = [

+        self.hamiltonian_term(n, args=args, params=params)

+        for n in cell_terms

+    ]

+    # Add Hermitian conjugates

+    hams += [

+        ham.conjugate().transpose(0, 2, 1)

+        for ham, n in zip(hams, cell_terms)

+        if self.terms[n].hermitian

+    ]

+

+    # _count_norbs requires passing hamiltonians for all terms, or 'None'

+    # if it has not been evaluated

+    all_hams = [None] * len(self.terms)

+    for n, ham in zip(cell_terms, hams):

+        all_hams[n] = ham

+    norbs, orb_offsets = _count_norbs(self, site_offsets, all_hams,

+                                      args=args, params=params)

+

+    shape = (orb_offsets[next_cell], orb_offsets[next_cell])

+    func = _vectorized_make_sparse if sparse else _vectorized_make_dense

+    mat = func(subgraphs, hams, norbs, orb_offsets, site_offsets, shape=shape)

+

+    return mat

+

+

+@deprecate_args

+@cython.binding(True)

+def vectorized_inter_cell_hopping(self, args=(), sparse=False, *, params=None):

+    """Hopping Hamiltonian between two cells of the infinite system.

+

+    Providing positional arguments via 'args' is deprecated,

+    instead, provide named parameters as a dictionary via 'params'.

+    """

+

+    # Take advantage of the fact that there are distinct entries in

+    # onsite_terms for sites inside the unit cell, and distinct entries

+    # in onsite_terms for hoppings between the unit cell sites and

+    # interface sites. This way we only need to check the first entry

+    # in onsite/hopping_terms

+

+    site_offsets = np.cumsum([0] + [len(arr) for arr in self.site_arrays])

+    # Site array where next cell starts

+    next_cell = bisect.bisect(site_offsets, self.cell_size) - 1

+

+    inter_cell_hopping_terms = [

+        n for n, t in enumerate(self.terms)

+        # *from* site is in interface

+        if (self.subgraphs[t.subgraph][0][1] >= next_cell

+            and self.subgraphs[t.subgraph][0][0] < next_cell)

+    ]

+    reversed_inter_cell_hopping_terms = [

+        n for n, t in enumerate(self.terms)

+        # *to* site is in interface

+        if (self.subgraphs[t.subgraph][0][0] >= next_cell

+            and self.subgraphs[t.subgraph][0][1] < next_cell)

+    ]

+

+    # Evaluate inter-cell hoppings only

+    inter_cell_hams = [

+        self.hamiltonian_term(n, args=args, params=params)

+        for n in inter_cell_hopping_terms

+    ]

+    reversed_inter_cell_hams = [

+        self.hamiltonian_term(n, args=args, params=params)

+            .conjugate().transpose(0, 2, 1)

+        for n in reversed_inter_cell_hopping_terms

+    ]

+

+    hams = inter_cell_hams + reversed_inter_cell_hams

+

+    subgraphs = [

+        self.subgraphs[self.terms[n].subgraph]

+        for n in inter_cell_hopping_terms

+    ]

+    subgraphs += [

+        _reverse_subgraph(self.subgraphs[self.terms[n].subgraph])

+        for n in reversed_inter_cell_hopping_terms

+    ]

+

+    # All the 'from' sites are in the previous domain, but to build a

+    # matrix we need to get the equivalent sites in the fundamental domain.

+    # We set the 'from' site array to the one from the fundamental domain.

+    subgraphs = [

+        ((to_sa, from_sa - next_cell), (to_off, from_off))

+        for (to_sa, from_sa), (to_off, from_off) in subgraphs

+    ]

+

+    # _count_norbs requires passing hamiltonians for all terms, or 'None'

+    # if it has not been evaluated

+    all_hams = [None] * len(self.terms)

+    for n, ham in zip(inter_cell_hopping_terms, inter_cell_hams):

+        all_hams[n] = ham

+    for n, ham in zip(reversed_inter_cell_hopping_terms,

+                      reversed_inter_cell_hams):

+        # Transpose to get back correct shape wrt. original term

+        all_hams[n] = ham.transpose(0, 2, 1)

+    norbs, orb_offsets = _count_norbs(self, site_offsets, all_hams,

+                                      args=args, params=params)

+

+    shape = (orb_offsets[next_cell],

+             orb_offsets[len(self.site_arrays) - next_cell])

+    func = _vectorized_make_sparse if sparse else _vectorized_make_dense

+    mat = func(subgraphs, hams, norbs, orb_offsets, site_offsets, shape=shape)

+    return mat

@@ -1,4 +1,4 @@

-# Copyright 2011-2016 Kwant authors.

+# Copyright 2011-2019 Kwant authors.

 #

 # This file is part of Kwant.  It is subject to the license terms in the file

 # LICENSE.rst found in the top-level directory of this distribution and at

@@ -14,11 +14,14 @@ import copy

 from functools import total_ordering, wraps, update_wrapper

 from itertools import islice, chain

 import textwrap

+import bisect

+import numbers

 import inspect

 import tinyarray as ta

 import numpy as np

 from scipy import sparse

 from . import system, graph, KwantDeprecationWarning, UserCodeError

+from .system import Site, SiteArray, SiteFamily

 from .linalg import lll

 from .operator import Density

 from .physics import DiscreteSymmetry, magnetic_gauge

@@ -26,182 +29,13 @@ from ._common import (ensure_isinstance, get_parameters, reraise_warnings,

                       interleave, deprecate_args, memoize)

-__all__ = ['Builder', 'Site', 'SiteFamily', 'SimpleSiteFamily', 'Symmetry',

-           'HoppingKind', 'Lead', 'BuilderLead', 'SelfEnergyLead', 'ModesLead',

-           'add_peierls_phase']

+__all__ = ['Builder', 'SimpleSiteFamily', 'Symmetry', 'HoppingKind', 'Lead',

+           'BuilderLead', 'SelfEnergyLead', 'ModesLead', 'add_peierls_phase']

-################ Sites and site families

-

-class Site(tuple):

-    """A site, member of a `SiteFamily`.

-

-    Sites are the vertices of the graph which describes the tight binding

-    system in a `Builder`.

-

-    A site is uniquely identified by its family and its tag.

-

-    Parameters

-    ----------

-    family : an instance of `SiteFamily`

-        The 'type' of the site.

-    tag : a hashable python object

-        The unique identifier of the site within the site family, typically a

-        vector of integers.

-

-    Raises

-    ------

-    ValueError

-        If `tag` is not a proper tag for `family`.

-

-    Notes

-    -----

-    For convenience, ``family(*tag)`` can be used instead of ``Site(family,

-    tag)`` to create a site.

-

-    The parameters of the constructor (see above) are stored as instance

-    variables under the same names.  Given a site ``site``, common things to

-    query are thus ``site.family``, ``site.tag``, and ``site.pos``.

-    """

-    __slots__ = ()

-

-    family = property(operator.itemgetter(0),

-                      doc="The site family to which the site belongs.")

-    tag = property(operator.itemgetter(1), doc="The tag of the site.")

-

-

-    def __new__(cls, family, tag, _i_know_what_i_do=False):

-        if _i_know_what_i_do:

-            return tuple.__new__(cls, (family, tag))

-        try:

-            tag = family.normalize_tag(tag)

-        except (TypeError, ValueError) as e:

-            msg = 'Tag {0} is not allowed for site family {1}: {2}'

-            raise type(e)(msg.format(repr(tag), repr(family), e.args[0]))

-        return tuple.__new__(cls, (family, tag))

-

-    def __repr__(self):

-        return 'Site({0}, {1})'.format(repr(self.family), repr(self.tag))

-

-    def __str__(self):

-        sf = self.family

-        return '<Site {0} of {1}>'.format(self.tag, sf.name if sf.name else sf)

-

-    def __getnewargs__(self):

-        return (self.family, self.tag, True)

-

-    @property

-    def pos(self):

-        """Real space position of the site.

-

-        This relies on ``family`` having a ``pos`` method (see `SiteFamily`).

-        """

-        return self.family.pos(self.tag)

-

+################ Site families

 @total_ordering

-class SiteFamily(metaclass=abc.ABCMeta):

-    """Abstract base class for site families.

-

-    Site families are the 'type' of `Site` objects.  Within a family, individual

-    sites are uniquely identified by tags.  Valid tags must be hashable Python

-    objects, further details are up to the family.

-

-    Site families must be immutable and fully defined by their initial

-    arguments.  They must inherit from this abstract base class and call its

-    __init__ function providing it with two arguments: a canonical

-    representation and a name.  The canonical representation will be returned as

-    the objects representation and must uniquely identify the site family

-    instance.  The name is a string used to distinguish otherwise identical site

-    families.  It may be empty. ``norbs`` defines the number of orbitals

-    on sites associated with this site family; it may be `None`, in which case

-    the number of orbitals is not specified.

-

-

-    All site families must define the method `normalize_tag` which brings a tag

-    to the standard format for this site family.

-

-    Site families that are intended for use with plotting should also provide a

-    method `pos(tag)`, which returns a vector with real-space coordinates of the

-    site belonging to this family with a given tag.

-

-    If the ``norbs`` of a site family are provided, and sites of this family

-    are used to populate a `~kwant.builder.Builder`, then the associated

-    Hamiltonian values must have the correct shape. That is, if a site family

-    has ``norbs = 2``, then any on-site terms for sites belonging to this

-    family should be 2x2 matrices. Similarly, any hoppings to/from sites

-    belonging to this family must have a matrix structure where there are two

-    rows/columns. This condition applies equally to Hamiltonian values that

-    are given by functions. If this condition is not satisfied, an error will

-    be raised.

-    """

-

-    def __init__(self, canonical_repr, name, norbs):

-        self.canonical_repr = canonical_repr

-        self.hash = hash(canonical_repr)

-        self.name = name

-        if norbs is None:

-            warnings.warn("Not specfying norbs is deprecated. Always specify "

-                          "norbs when creating site families.",

-                          KwantDeprecationWarning, stacklevel=3)

-        if norbs is not None:

-            if int(norbs) != norbs or norbs <= 0:

-                raise ValueError('The norbs parameter must be an integer > 0.')

-            norbs = int(norbs)

-        self.norbs = norbs

-

-    def __repr__(self):

-        return self.canonical_repr

-

-    def __str__(self):

-        if self.name:

-            msg = '<{0} site family {1}{2}>'

-        else:

-            msg = '<unnamed {0} site family{2}>'

-        orbs = ' with {0} orbitals'.format(self.norbs) if self.norbs else ''

-        return msg.format(self.__class__.__name__, self.name, orbs)

-

-    def __hash__(self):

-        return self.hash

-

-    def __eq__(self, other):

-        try:

-            return self.canonical_repr == other.canonical_repr

-        except AttributeError:

-            return False

-

-    def __ne__(self, other):

-        try:

-            return self.canonical_repr != other.canonical_repr

-        except AttributeError:

-            return True

-

-    def __lt__(self, other):

-        # If this raises an AttributeError, we were trying

-        # to compare it to something non-comparable anyway.

-        return self.canonical_repr < other.canonical_repr

-

-    @abc.abstractmethod

-    def normalize_tag(self, tag):

-        """Return a normalized version of the tag.

-

-        Raises TypeError or ValueError if the tag is not acceptable.

-        """

-        pass

-

-    def __call__(self, *tag):

-        """

-        A convenience function.

-

-        This function allows to write fam(1, 2) instead of Site(fam, (1, 2)).

-        """

-        # Catch a likely and difficult to find mistake.

-        if tag and isinstance(tag[0], tuple):

-            raise ValueError('Use site_family(1, 2) instead of '

-                             'site_family((1, 2))!')

-        return Site(self, tag)

-

-

 class SimpleSiteFamily(SiteFamily):

     """A site family used as an example and for testing.

@@ -307,19 +141,44 @@ class Symmetry(metaclass=abc.ABCMeta):

     def which(self, site):

         """Calculate the domain of the site.

-        Return the group element whose action on a certain site from the

-        fundamental domain will result in the given ``site``.

+        Parameters

+        ----------

+        site : `~kwant.system.Site` or `~kwant.system.SiteArray`

+

+        Returns

+        -------

+        group_element : tuple or sequence of tuples

+            A single tuple if ``site`` is a Site, or a sequence of tuples if

+            ``site`` is a SiteArray.  The group element(s) whose action

+            on a certain site(s) from the fundamental domain will result

+            in the given ``site``.

         """

         pass

     @abc.abstractmethod

     def act(self, element, a, b=None):

-        """Act with a symmetry group element on a site or hopping."""

+        """Act with symmetry group element(s) on site(s) or hopping(s).

+

+        Parameters

+        ----------

+        element : tuple or sequence of tuples

+            Group element(s) with which to act on the provided site(s)

+            or hopping(s)

+        a, b : `~kwant.system.Site` or `~kwant.system.SiteArray`

+            If Site then ``element`` is a single tuple, if SiteArray then

+            ``element`` is a sequence of tuples. If only ``a`` is provided then

+            ``element`` acts on the site(s) of ``a``. If ``b`` is also provided

+            then ``element`` acts on the hopping(s) ``(a, b)``.

+        """

         pass