Documentation update: drawing functions

docs/index.rst

@@ -55,6 +55,7 @@ Contents
    MixedAuts <thompson.mixed>
    Free factors <thompson.factors>
    Examples <thompson.examples>
+   Drawing automorphisms <thompson.drawing>
    References <references>
    Todo list <todo>
 

docs/thompson.drawing.rst

@@ -0,0 +1,69 @@
+Drawing automorphisms
+=====================
+
+It can be helpful to see automorphisms rather than just read a description of them.
+To that end we introduce functions for rendering automorphisms as tree pair diagrams.
+The output looks best for automorphisms with a small arity (2--5) and a reasonable number of leaves.
+
+Examples
+--------
+
+First we take a well-behaved automorphism. 
+The solid carets are those belonging to both the domain and range trees.
+All other carets are dotted.
+Some edges are highlighted in red---these correspond to the repellers and attractors discussed by [SD10]_.
+
+.. sourcecode:: python
+
+	>>> from thompson import *
+	>>> x0 = standard_generator(0)
+	>>> plot(x0)
+	>>> forest(x0)
+
+.. image:: _static/images/x0_plot.svg
+	:alt: A plot of the standard generator x_0 of Thompson's group F.
+	:target: `thompson.drawing.plot`_
+
+.. image:: _static/images/x0_forest.png
+	:alt: The tree pair diagram for the standard generator x_0 of Thompson's group F.
+	:target: `thompson.drawing.forest`_
+
+Discontinuities are fine too. Here's ``example_4_17`` for instance.
+
+.. sourcecode:: python
+
+	>>> pond = load_example('example_4_17')
+	>>> plot(pond, discontinuities=True)
+	>>> forest(pond)
+
+.. image:: _static/images/pond_plot.svg
+	:alt: A plot of a specific element of G_{2,1}.
+	:target: `thompson.drawing.plot`_
+
+.. image:: _static/images/pond_forest.png
+	:alt: The tree pair diagram for a specific element of G_{2,1}..
+	:target: `thompson.drawing.forest`_
+
+Let's aim for something more chaotic.
+This example is complicated enough that the drawings don't really give us much insight into the automorphism.
+
+.. sourcecode:: python
+
+	>>> random = random_automorphism() #different every time!
+	>>> plot(random)
+	>>> forest(random, horiz=False)
+
+.. image:: _static/images/random_plot.svg
+	:alt: A plot of a randomly generated element of G_{3,4}.
+	:target: `thompson.drawing.plot`_
+
+.. image:: _static/images/random_forest.png
+	:alt: The tree pair diagram for a randomly generated element of G_{3,4}.
+	:target: `thompson.drawing.forest`_
+
+Drawing functions
+-----------------
+
+.. automodule:: thompson.drawing
+	:members:
+	:undoc-members:

docs/thompson.examples.rst

@@ -23,6 +23,8 @@ Use the following functions to load one of these examples.
 List of named examples
 ^^^^^^^^^^^^^^^^^^^^^^
 
+Note that some automorphisms have more than one name---they will appear once in this list for every alias.
+
 .. include:: examples_table.txt
 
 Randomly generated examples

thompson/automorphism.py

@@ -53,7 +53,8 @@ class Automorphism(Homomorphism):
 	:ivar cycle_type: the set :math:`\{d \in \mathbb{N} : \text{$\exists$ an orbit of length $d$.}\}`
 	:ivar order: The :func:`~thompson.number_theory.lcm` of the automorphism's cycle type. This is the group-theoretic order of the :mod:`periodic factor <thompson.periodic>` of :math:`\phi`. If the cycle type is empty, the order is :math:`\infty`.
 	
-	..doctest::
+	.. doctest::
+	
 		>>> def display_orbits(orbits_by_size):
 		... 	for key in sorted(orbits_by_size):
 		... 		print('Orbits of length', key)
@@ -67,7 +68,7 @@ class Automorphism(Homomorphism):
 		... -> x1 a1 a1 a1 -> x1 a1 a1 a2 -> x1 a1 a2 -> ...
 	
 	.. note::
-		:mod:`mixed automorhpisms <thompson.mixed>` will have a **finite** order, despite being infinite-order group elements.
+		:mod:`mixed automorphisms <thompson.mixed>` will have a **finite** order, despite being infinite-order group elements.
 	
 	Infinite attributes:
 	
@@ -267,7 +268,9 @@ def compute_quasinormal_basis(self):
 		r"""We say that :math:`\phi` is *in semi-normal form* with respect to the basis :math:`X` if no element of :math:`X` lies in an incomplete :math:`X`-component of a :math:`\phi` orbit. See the :mod:`~thompson.orbits` module for more details.
 		
 		There is a minimal such basis, :math:`X_\phi` say, and we say that :math:`\phi` is *in quasi-normal form* with respect to :math:`X_\phi`. This method determines and returns the basis :math:`X_\phi` where :math:`\phi` denotes the current automorphism. The result is cached so that further calls to this method perform no additional computation. 
-			
+		
+		.. note:: This method is called automatically at creation time and does **not** need to be called by the user.
+					
 			>>> for name in ['example_4_5', 'alphabet_size_two', 'example_5_12_phi', 'example_6_2', 'example_6_8_phi']:
 			... 	print(load_example(name).quasinormal_basis)
 			[x1 a1 a1, x1 a1 a2, x1 a2 a1, x1 a2 a2]
@@ -277,8 +280,7 @@ def compute_quasinormal_basis(self):
 			[x1 a1, x1 a2]
 		
 		:rtype: a :class:`~thompson.generators.Generators` instance.
-		
-		.. note:: This method is called automatically at creation time and is **not** needed to be called by the user.
+
 		
 		.. seealso:: Quasi-normal forms are introduced in Section :paperref:`sec:qnf` of the paper. In particular, this method implements Lemma :paperref:`lem:qnf`. Higman first described the idea of quasi-normal forms in Section 9 of [Hig74]_.
 		"""