update docs, and use the new functionality in tutorial

doc/source/reference/kwant.lattice.rst

@@ -12,6 +12,7 @@ General
    general
    Monatomic
    Polyatomic
+   Shape
 
 Library of lattices
 -------------------

doc/source/reference/kwant.linalg.rst

@@ -4,8 +4,9 @@
 .. module:: kwant.linalg
 
 This package wraps some selected LAPACK functionality not available via NumPy
-and also contains a Python-wrapper for MUMPS.  It is meant for internal use by
-kwant itself, but of course nothing prevents you from using it directly.
+and also contains a Python-wrapper for MUMPS.  It also has several algorithms
+for finding approximately orthonormal lattice bases. It is meant for internal
+use by kwant itself, but of course nothing prevents you from using it directly.
 
 The documentation of this package is not included here on purpose in order not
 to add too many things to this reference.  Please consult the source code

doc/source/tutorial/ab_ring.py

@@ -73,7 +73,7 @@ def make_system(a=1, t=1.0, W=10, r1=10, r2=20):
 
     def lead_shape(pos):
         (x, y) = pos
-        return (-1 < x < 1) and (-W / 2 < y < W / 2)
+        return (-W / 2 < y < W / 2)
 
     lead[lat.shape(lead_shape, (0, 0))] = 4 * t
     lead[lat.nearest] = -t

doc/source/tutorial/graphene.py

@@ -70,7 +70,7 @@ def make_system(r=10, w=2.0, pot=0.1):
 
     def lead0_shape(pos):
         x, y = pos
-        return (-1 < x < 1) and (-0.4 * r < y < 0.4 * r)
+        return (-0.4 * r < y < 0.4 * r)
 
     lead0 = kwant.Builder(sym0)
     lead0[graphene.shape(lead0_shape, (0, 0))] = -pot
@@ -80,10 +80,8 @@ def make_system(r=10, w=2.0, pot=0.1):
     sym1 = kwant.TranslationalSymmetry(graphene.vec((0, 1)))
 
     def lead1_shape(pos):
-        x, y = pos
-        u = x * sin_30 + y * cos_30
-        v = y * sin_30 - x * cos_30
-        return (-1 < u < 1) and (-0.4 * r < v < 0.4 * r)
+        v = pos[1] * sin_30 - pos[0] * cos_30
+        return (-0.4 * r < v < 0.4 * r)
 
     lead1 = kwant.Builder(sym1)
     lead1[graphene.shape(lead1_shape, (0, 0))] = pot

doc/source/whatsnew/0.3.rst

@@ -120,3 +120,14 @@ containing all the parameters as attributes::
 
 Arguments can be passed in an equivalent way in calls to
 `~kwant.solvers.default.wave_function` and `~kwant.solvers.default.ldos`.
+
+Lattice and shape improvements
+------------------------------
+`~kwant.lattice.Monoatomic.closest` now returns an exact, and not approximately
+closest point. A new method `~kwant.lattice.Monoatomic.n_closest` was added,
+which returns n closest lattice points. Likewise
+`~kwant.lattice.Polyatomic.shape` has acquired an improved flood-fill
+algorithm, making it work better on narrow ribbon (which were sometimes buggy
+before with non-square lattices). Additionally, it was made symmetry-aware, so
+if a shape is used for a lead, no conditions with regard to coordnate parallel
+to the lead period are required.

kwant/lattice.py

@@ -74,10 +74,6 @@ class Polyatomic(object):
     ------
     ValueError
         If dimensionalities do not match.
-
-    Notes
-    -----
-
     """
     def __init__(self, prim_vecs, basis, name=''):
         prim_vecs = ta.array(prim_vecs, float)
@@ -408,6 +404,17 @@ class Shape(object):
             and False otherwise.
         start : float vector
             The origin for the flood-fill algorithm.
+
+        Notes
+        -----
+        A ``Shape`` is a callable object: When called with a
+        `~kwant.builder.Builder` as sole argument, an instance of this class will
+        return an iterator over all the sites from the shape that are in the fundamental domain of the builder's symmetry.
+
+        Because a `~kwant.builder.Builder` can be indexed with functions or
+        iterables of functions, ``Shape`` instances (or any non-tuple
+        iterables of them, e.g. a list) can be used directly as "wildcards" when
+        setting or deleting sites.
         """
         self.lat, self.func, self.start = lattice, function, start