From 5b79bc7a2a7455195885dbeab162bf0e5c9c3a41 Mon Sep 17 00:00:00 2001
From: Michael Wimmer <wimmer@lorentz.leidenuniv.nl>
Date: Fri, 30 Aug 2013 16:24:36 +0200
Subject: [PATCH] add 3D example to plotting tutorial
---
doc/source/images/plot_zincblende.py.diff | 34 ++++++++++
doc/source/tutorial/plot_zincblende.py | 48 ++++++++++++++
doc/source/tutorial/tutorial6.rst | 78 +++++++++++++++++++++++
3 files changed, 160 insertions(+)
create mode 100644 doc/source/images/plot_zincblende.py.diff
create mode 100644 doc/source/tutorial/plot_zincblende.py
diff --git a/doc/source/images/plot_zincblende.py.diff b/doc/source/images/plot_zincblende.py.diff
new file mode 100644
index 0000000..2f5c24d
--- /dev/null
+++ b/doc/source/images/plot_zincblende.py.diff
@@ -0,0 +1,34 @@
+--- original
++++ modified
+@@ -1,3 +1,4 @@
++import _defs
+ import kwant
+ from matplotlib import pyplot
+
+@@ -22,7 +23,10 @@
+ # checking shapes:
+ sys = make_cuboid()
+
+- kwant.plot(sys)
++ size = (_defs.figwidth_in, _defs.figwidth_in)
++ for extension in ('pdf', 'png'):
++ kwant.plot(sys, file="plot_zincblende_sys1." + extension,
++ fig_size=size, dpi=_defs.dpi)
+
+ # visualize the crystal structure better for a very small system
+ sys = make_cuboid(a=1.5, b=1.5, c=1.5)
+@@ -30,8 +34,12 @@
+ def family_colors(site):
+ return 'r' if site.family == a else 'g'
+
+- kwant.plot(sys, site_size=0.18, site_lw=0.01, hop_lw=0.05,
+- site_color=family_colors)
++ size = (_defs.figwidth_in, _defs.figwidth_in)
++ for extension in ('pdf', 'png'):
++ kwant.plot(sys, site_size=0.18, site_lw=0.01, hop_lw=0.05,
++ site_color=family_colors,
++ file="plot_zincblende_sys2." + extension,
++ fig_size=size, dpi=_defs.dpi)
+
+
+ # Call the main function if the script gets executed (as opposed to imported).
diff --git a/doc/source/tutorial/plot_zincblende.py b/doc/source/tutorial/plot_zincblende.py
new file mode 100644
index 0000000..fc05e36
--- /dev/null
+++ b/doc/source/tutorial/plot_zincblende.py
@@ -0,0 +1,48 @@
+import kwant
+from matplotlib import pyplot
+
+#HIDDEN_BEGIN_zincblende1
+lat = kwant.lattice.general([(0,0.5,0.5), (0.5,0,0.5), (0.5,0.5,0)],
+ [(0,0,0), (0.25,0.25,0.25)])
+a, b = lat.sublattices
+#HIDDEN_END_zincblende1
+
+#HIDDEN_BEGIN_zincblende2
+def make_cuboid(a=15, b=10, c=5):
+ def cube(pos):
+ x, y, z = pos
+ return 0 <= x < a and 0 <= y < b and 0 <= z < c
+
+ sys = kwant.Builder()
+ sys[lat.shape(cube, (0,0,0))] = None
+ sys[lat.neighbors()] = None
+
+ return sys
+#HIDDEN_END_zincblende2
+
+
+def main():
+ # the standard plotting style for 3D is mainly useful for
+ # checking shapes:
+#HIDDEN_BEGIN_plot1
+ sys = make_cuboid()
+
+ kwant.plot(sys)
+#HIDDEN_END_plot1
+
+ # visualize the crystal structure better for a very small system
+#HIDDEN_BEGIN_plot2
+ sys = make_cuboid(a=1.5, b=1.5, c=1.5)
+
+ def family_colors(site):
+ return 'r' if site.family == a else 'g'
+
+ kwant.plot(sys, site_size=0.18, site_lw=0.01, hop_lw=0.05,
+ site_color=family_colors)
+#HIDDEN_END_plot2
+
+
+# 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
index 5d350d4..7fe9e2f 100644
--- a/doc/source/tutorial/tutorial6.rst
+++ b/doc/source/tutorial/tutorial6.rst
@@ -144,3 +144,81 @@ which shows the edge state nature of the wave function most clearly.
that are dangling with only nearest-neighbor hopping have more than
one hopping.
+3D example: zincblende structure
+................................
+
+Zincblende is a very common crystal structure of semiconductors. It is
+a face-centered cuubic crystal with two unequivalent atoms in the
+unit cell (i.e. two different types of atoms, unlike diamond which has
+the same crystal structure, but to equivalent atoms per unit cell).
+
+It is very easily generated in kwant with `kwant.lattice.general`:
+
+.. literalinclude:: plot_zincblende.py
+ :start-after: #HIDDEN_BEGIN_zincblende1
+ :end-before: #HIDDEN_END_zincblende1
+
+Note how we keep references to the two different sublattices for later use.
+
+A three-dimensional structure is created as easily as in two dimensions,
+by using the `~kwant.lattice.PolyatomicLattice.shape`-functionality:
+
+.. literalinclude:: plot_zincblende.py
+ :start-after: #HIDDEN_BEGIN_zincblende2
+ :end-before: #HIDDEN_END_zincblende2
+
+We restrict ourselves here to a simple cuboid, and do not bother to add
+real values for onsite and hopping energies, but only the placeholder
+``None`` (in a real calculation, several atomic orbitals would have to be
+considered).
+
+`~kwant.plotter.plot` can plot 3D systems just as easily as its two-dimensional
+counterparts:
+
+.. literalinclude:: plot_zincblende.py
+ :start-after: #HIDDEN_BEGIN_plot1
+ :end-before: #HIDDEN_END_plot1
+
+resulting in
+
+.. image:: ../images/plot_zincblende_sys1.*
+
+You might notice that the standard options for plotting are quite different in
+3D than in 2D. For example, by default hoppings are not printed, but sites
+are instead represented by little "balls" touching each other (which
+is achieved by a default ``site_size=0.5``). In fact, this style of
+plotting 3D shows quite decently the overall geometry of the system.
+
+When plotting into a window, the 3D plots can also be rotated and scaled
+arbitrarily, allowing for a good inspection of the geometry from all sides.
+
+.. note::
+
+ Interactive 3D plots usually have not the proper aspect ratio, but are
+ a bit squashed. This is due to bugs in matplotlib's 3D plotting
+ module that does not properly honor the corresponding arguments. By resizing
+ the plot window however one can manually adjust the aspect ratio.
+
+Also for 3D it is possible to customize the plot. For example, we
+can explicitely plot the hoppings as lines, and color sites differently
+depending on the sublattice:
+
+.. literalinclude:: plot_zincblende.py
+ :start-after: #HIDDEN_BEGIN_plot2
+ :end-before: #HIDDEN_END_plot2
+
+which results in a 3D plot that allows to interactively (when plotted
+in a window) explore the crystal structure:
+
+.. image:: ../images/plot_zincblende_sys2.*
+
+Hence, a few lines of code using kwant allows for exploring all the different
+crystal lattices out there!
+
+.. note::
+
+ - The 3D plots are in fact only *fake* 3D. For example, sites will always
+ be plotted above hoppings (this is due to the limitations of matplotlib's
+ 3d module)
+ - Plotting hoppings in 3D is inherently much slower than plotting sites.
+ Hence, this is not done by default.
--
GitLab