diff --git a/doc/source/images/plot_graphene.py.diff b/doc/source/images/plot_graphene.py.diff
new file mode 100644
index 0000000000000000000000000000000000000000..15cd417cde2b3c15cdf0d51a50b95ced753f7729
--- /dev/null
+++ b/doc/source/images/plot_graphene.py.diff
@@ -0,0 +1,78 @@
+--- original
++++ modified
+@@ -6,6 +6,7 @@
+ # --------------------------
+ # - demonstrate different ways of plotting
+
++import _defs
+ import kwant
+ from matplotlib import pyplot
+
+@@ -29,9 +30,11 @@
+
+
+ def plot_system(sys):
+- kwant.plot(sys)
+- # the standard plot is ok, but not very intelligible. One can do
+- # better by playing wioth colors and linewidths
++ # standard plot - not very intelligible for this particular situation
++ size = (_defs.figwidth_in, _defs.figwidth_in)
++ for extension in ('pdf', 'png'):
++ kwant.plot(sys, file="plot_graphene_sys1." + extension,
++ fig_size=size, dpi=_defs.dpi)
+
+ # use color and linewidths to get a better plot
+ def family_color(site):
+@@ -40,7 +43,11 @@
+ def hopping_lw(site1, site2):
+ return 0.04 if site1.family == site2.family else 0.1
+
+- kwant.plot(sys, site_lw=0.1, site_color=family_color, hop_lw=hopping_lw)
++ size = (_defs.figwidth_in, _defs.figwidth_in)
++ for extension in ('pdf', 'png'):
++ kwant.plot(sys, site_lw=0.1, site_color=family_color,
++ hop_lw=hopping_lw, file="plot_graphene_sys2." + extension,
++ fig_size=size, dpi=_defs.dpi)
+
+
+ def plot_data(sys, n):
+@@ -55,7 +62,11 @@
+ # the usual - works great in general, looks just a bit crufty for
+ # small systems
+
+- kwant.plotter.map(sys, wf, oversampling=10)
++ size = (_defs.figwidth_in, _defs.figwidth_in)
++ for extension in ('pdf', 'png'):
++ kwant.plotter.map(sys, wf, oversampling=10,
++ file="plot_graphene_data1." + extension,
++ fig_size=size, dpi=_defs.dpi)
+
+ # use two different sort of triangles to cleanly fill the space
+ def family_shape(i):
+@@ -65,15 +76,22 @@
+ def family_color(i):
+ return 'black' if sys.site(i).family == a else 'white'
+
+- kwant.plot(sys, site_color=wf, site_symbol=family_shape,
+- site_size=0.5, hop_lw=0, cmap='jet')
++ size = (_defs.figwidth_in, _defs.figwidth_in)
++ for extension in ('pdf', 'png'):
++ kwant.plot(sys, site_color=wf, site_symbol=family_shape,
++ site_size=0.5, hop_lw=0, cmap='jet',
++ file="plot_graphene_data2." + extension,
++ fig_size=size, dpi=_defs.dpi)
+
+ # plot by changing the symbols itself
+ def site_size(i):
+ return 3 * wf[i] / wf.max()
+
+- kwant.plot(sys, site_size=site_size, site_color=(0,0,1,0.3),
+- hop_lw=0.1)
++ size = (_defs.figwidth_in, _defs.figwidth_in)
++ for extension in ('pdf', 'png'):
++ kwant.plot(sys, site_size=site_size, site_color=(0,0,1,0.3),
++ hop_lw=0.1, file="plot_graphene_data3." + extension,
++ fig_size=size, dpi=_defs.dpi)
+
+
+ def main():
diff --git a/doc/source/tutorial/index.rst b/doc/source/tutorial/index.rst
index fab8d31b9bc16e0e99c507ab380d703bdcc58258..47a47bb88da70a9c133f61fc2b1b4c0c8e772f26 100644
--- a/doc/source/tutorial/index.rst
+++ b/doc/source/tutorial/index.rst
@@ -14,3 +14,4 @@ these notes may be safely skipped.
tutorial3
tutorial4
tutorial5
+ tutorial6
diff --git a/doc/source/tutorial/plot_graphene.py b/doc/source/tutorial/plot_graphene.py
new file mode 100644
index 0000000000000000000000000000000000000000..0f36ec797c7ea6f8f98fda909c9232c254f6c4ad
--- /dev/null
+++ b/doc/source/tutorial/plot_graphene.py
@@ -0,0 +1,109 @@
+# Physics background
+# ------------------
+# - graphene edge states
+#
+# Kwant features highlighted
+# --------------------------
+# - demonstrate different ways of plotting
+
+import kwant
+from matplotlib import pyplot
+
+#HIDDEN_BEGIN_makesys
+lat = kwant.lattice.honeycomb()
+a, b = lat.sublattices
+
+def make_system(r=8, t=-1, tp=-0.1):
+
+ def circle(pos):
+ x, y = pos
+ return x**2 + y**2 < r**2
+
+ sys = kwant.Builder()
+ sys[lat.shape(circle, (0,0))] = 0
+ sys[lat.neighbors()] = t
+ sys.eradicate_dangling()
+ if tp:
+ sys[lat.neighbors(2)] = tp
+
+ return sys
+#HIDDEN_END_makesys
+
+
+#HIDDEN_BEGIN_plotsys1
+def plot_system(sys):
+ kwant.plot(sys)
+#HIDDEN_END_plotsys1
+ # the standard plot is ok, but not very intelligible. One can do
+ # better by playing wioth colors and linewidths
+
+ # use color and linewidths to get a better plot
+#HIDDEN_BEGIN_plotsys2
+ def family_color(site):
+ return 'black' if site.family == a else 'white'
+
+ def hopping_lw(site1, site2):
+ return 0.04 if site1.family == site2.family else 0.1
+
+ kwant.plot(sys, site_lw=0.1, site_color=family_color, hop_lw=hopping_lw)
+#HIDDEN_END_plotsys2
+
+
+#HIDDEN_BEGIN_plotdata1
+def plot_data(sys, n):
+ import scipy.linalg as la
+
+ sys = sys.finalized()
+ ham = sys.hamiltonian_submatrix()
+ evecs = la.eigh(ham)[1]
+
+ wf = abs(evecs[:, n])**2
+#HIDDEN_END_plotdata1
+
+ # the usual - works great in general, looks just a bit crufty for
+ # small systems
+
+#HIDDEN_BEGIN_plotdata2
+ kwant.plotter.map(sys, wf, oversampling=10)
+#HIDDEN_END_plotdata2
+
+ # use two different sort of triangles to cleanly fill the space
+#HIDDEN_BEGIN_plotdata3
+ def family_shape(i):
+ site = sys.site(i)
+ return ('p', 3, 180) if site.family == a else ('p', 3, 0)
+
+ def family_color(i):
+ return 'black' if sys.site(i).family == a else 'white'
+
+ kwant.plot(sys, site_color=wf, site_symbol=family_shape,
+ site_size=0.5, hop_lw=0, cmap='jet')
+#HIDDEN_END_plotdata3
+
+ # plot by changing the symbols itself
+#HIDDEN_BEGIN_plotdata4
+ def site_size(i):
+ return 3 * wf[i] / wf.max()
+
+ kwant.plot(sys, site_size=site_size, site_color=(0,0,1,0.3),
+ hop_lw=0.1)
+#HIDDEN_END_plotdata4
+
+
+def main():
+ # plot the graphene system in different styles
+ sys = make_system()
+
+ plot_system(sys)
+
+ # compute a wavefunction (number 225) and plot it in different
+ # styles
+ sys = make_system(tp=0)
+
+ plot_data(sys, 225)
+
+
+# Call the main function if the script gets executed (as opposed to imported).
+# See <http://docs.python.org/library/__main__.html>.
+if __name__ == '__main__':
+ main()
diff --git a/doc/source/tutorial/tutorial6.rst b/doc/source/tutorial/tutorial6.rst
new file mode 100644
index 0000000000000000000000000000000000000000..5d350d41d6f3ef7c314ae84ed9c79259d920d092
--- /dev/null
+++ b/doc/source/tutorial/tutorial6.rst
@@ -0,0 +1,146 @@
+Plotting Kwant systems and data in various styles
+-------------------------------------------------
+
+The plotting functionality of Kwant has been used extensively (through
+`~kwant.plotter.plot` and `~kwant.plotter.map`) in the previous tutorials. In
+addition to this basic use, `~kwant.plotter.plot` offers many options to change
+the plotting style extensively. It is the goal of this tutorial to show
+how these options can be used to achieve various very different objectives.
+
+2D example: graphene quantum dot
+................................
+
+We begin by first considering a circular graphene quantum dot (similar
+to what has been used in parts of the tutorial :ref:`tutorial-graphene`.)
+In contrast to previous examples, we will also use hoppings beyond
+next-nearest neighbors:
+
+.. literalinclude:: plot_graphene.py
+ :start-after: #HIDDEN_BEGIN_makesys
+ :end-before: #HIDDEN_END_makesys
+
+Note that adding hoppings hoppings to the `n`-th nearest neighbors can be
+simply done by passing `n` as an argument to
+`~kwant.lattice.Polyatomic.neighbors`. Also note that we use the method
+`~kwant.builder.Builder.eradicate_dangling` to get rid of single atoms sticking out of
+the shape. It is necessary to do so *before* adding the next-nearest-neighbor
+hopping [#]_.
+
+Of course, the system can be plotted simply with default settings:
+
+.. literalinclude:: plot_graphene.py
+ :start-after: #HIDDEN_BEGIN_plotsys1
+ :end-before: #HIDDEN_END_plotsys1
+
+However, due to the richer structure of the lattice, this results in a rather
+busy plot:
+
+.. image:: ../images/plot_graphene_sys1.*
+
+A much clearer plot can be obtained by using different colors for both
+sublattices, and by having different linewidths for different hoppings.
+This can be achieved by passing a function to the arguments of
+`~kwant.plotter.plot`, instead of a constant. For properties of sites, this
+must be a function taking one site as argument, for hoppings
+a function taking the start end end site of hopping as arguments:
+
+.. literalinclude:: plot_graphene.py
+ :start-after: #HIDDEN_BEGIN_plotsys2
+ :end-before: #HIDDEN_END_plotsys2
+
+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
+that is more intelligible, still carrying all information:
+
+.. image:: ../images/plot_graphene_sys2.*
+
+Aport from plotting the *system* itself, `~kwant.plotter.plot` can also be
+used to plot *data* living on the system.
+
+As an example, we now compute the eigenstates of the graphene quantum dot
+and intend to plot the wave function probability in the quantum dot. For
+aesthetic reasons (the wave functions look a bit nicer), we restrict ourselves
+to nearest-neighbor hopping.
+Computing the wave functions is done in the usual way (note that for
+a large-scale system, one would probably want to use sparse linear algebra):
+
+.. literalinclude:: plot_graphene.py
+ :start-after: #HIDDEN_BEGIN_plotdata1
+ :end-before: #HIDDEN_END_plotdata1
+
+In most cases, to plot the wave function probability, one wouldn't use
+`~kwant.plotter.plot`, but rather `~kwant.plotter.map`. Here, we plot
+the `n`-th wave function using it:
+
+.. literalinclude:: plot_graphene.py
+ :start-after: #HIDDEN_BEGIN_plotdata2
+ :end-before: #HIDDEN_END_plotdata2
+
+This results in a standard pseudocolor plot, showing in this case (``n=225``)
+a graphene edge state, i.e. a wave function mostly localized at the zigzag
+edges of the quantum dot.
+
+.. image:: ../images/plot_graphene_data1.*
+
+However although in general preferable, `~kwant.plotter.map`
+has a few deficiencies for this small system: For example, there are
+a few distortions at the edge of the dot. (This cannot be avoided in the type
+of interpolation used in `~kwant.plotter.map`). However, we can also use
+`~kwant.plotter.plot` to achieve a similar, but smoother result.
+
+For this note that `~kwant.plotter.plot` can also take an array of
+floats (or function returning floats) as value for the
+`site_color` argument (the same holds for the hoppings). Via the
+colormap specified in `cmap` these are mapped to color, just as
+`~kwant.plotter.map` does! In addition, we can also change the symbol shape
+depending on the sublattice. With a triangle pointing up and down on the
+respective sublattice, the symbols used by plot fill the space completely:
+
+.. literalinclude:: plot_graphene.py
+ :start-after: #HIDDEN_BEGIN_plotdata3
+ :end-before: #HIDDEN_END_plotdata3
+
+Note that with ``hop_lw=0`` we deactivate plotting the hoppings (that would not
+serve any purpose here). Moreover, ``site_size=0.5`` guarantees that the two
+different types of triangles touch precisely: By default, `~kwant.plotter.plot`
+takes all sizes in units of the nearest-neighbor spacing. ``site_size=0.5``
+thus means half the distance between neighboring sites (and for the triangles
+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`, ``sys.site(i)`` can be used.
+
+With this we arrive at
+
+.. image:: ../images/plot_graphene_data2.*
+
+with the same information as `~kwant.plotter.map`, but with a cleaner look.
+
+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
+beyond pseudocolor-like plots. For example, we can represent the wave function
+probability using the symbols itself:
+
+.. literalinclude:: plot_graphene.py
+ :start-after: #HIDDEN_BEGIN_plotdata4
+ :end-before: #HIDDEN_END_plotdata4
+
+Here, we choose the symbol size proportional to the wave function
+probability, while the site color is transparent to also allow
+for overlapping symbols to be visible. The hoppings are also plotted in order
+to show the underlying lattice.
+
+With this, we arrive at
+
+.. image:: ../images/plot_graphene_data3.*
+
+which shows the edge state nature of the wave function most clearly.
+
+.. rubric:: Footnotes
+
+.. [#] A dangling site is defined as having only one hopping connecting
+ it to the rest. With next-nearest-neigbor hopping also all sites
+ that are dangling with only nearest-neighbor hopping have more than
+ one hopping.
+