Documentation update w/examples

DMRobertson · DMRobertson · commit 8584a5534192 · 2014-12-15T11:36:05.000Z
- Adding docstrings for the random generator functions - Adding comments to the example automorphisms - Including the examples created by @nbarkercmep
diff --git a/docs/thompson.examples.rst b/docs/thompson.examples.rst
@@ -1,7 +1,29 @@
-thompson.examples module
-========================
+Examples
+========
+
+This module provides a number of explicit examples for use in doctests. Additionally, functions to generate random automorphisms are provided.
+
+Explict named examples
+----------------------
+
+A list of named examples is loaded from the ``.aut`` files in `the examples folder <https://github.com/DMRobertson/thompsons_v/tree/master/thompson/examples>`_. This includes all the examples given in AJD and NB's paper.
+
+.. todo:: Make Sphinx show these examples here?
 
 .. automodule:: thompson.examples
     :members:
     :undoc-members:
     :show-inheritance:
+    :exclude-members: random_signature, random_simple_word, random_basis, random_automorphism, random_conjugate_pair, random_conjugate_factors, random_conjugate_periodic_factors, random_conjugate_infinite_factors
+
+Randomly generated examples
+---------------------------
+
+.. autofunction:: random_signature
+.. autofunction:: random_simple_word
+.. autofunction:: random_basis
+.. autofunction:: random_automorphism
+.. autofunction:: random_conjugate_pair
+.. autofunction:: random_conjugate_factors
+.. autofunction:: random_conjugate_periodic_factors
+.. autofunction:: random_conjugate_infinite_factors
diff --git a/thompson/automorphism.py b/thompson/automorphism.py
@@ -736,6 +736,22 @@ def test_conjugate_to(self, other):
 			>>> psi * rho == rho * phi
 			True
 		
+		..doctest::
+			:hide:
+			
+			>>> rho = nathan_pond_example.test_conjugate_to(nathan1_example)
+			>>> rho is None
+			True
+			>>> rho = nathan2_example.test_conjugate_to(nathan3_example)
+			>>> rho is not None
+			True
+			>>> nathan2_example * rho == rho * nathan3_example
+			True
+			>>> rho = nathan4_example
+			>>> nathan2_example * rho == rho * nathan3_example
+			True
+			
+		
 		.. seealso:: This is an implementation of Algorithm 5.6 in the paper. It depends on Algorithms 5.13 and 5.27; these are the :meth:`periodic <thompson.factors.PeriodicFactor.test_conjugate_to>` and :meth:`infinite <thompson.factors.InfiniteFactor.test_conjugate_to>` tests for conjugacy.
 		"""
 		#TODO Doctest: try assembling a conjugator from factors
diff --git a/thompson/examples/__init__.py b/thompson/examples/__init__.py
@@ -1,4 +1,8 @@
-"""A list of examples for use in doctests."""
+"""
+.. testsetup::
+	
+	from thompson.examples import *
+"""
 
 import pkg_resources
 import string
diff --git a/thompson/examples/alphabet_size_two.aut b/thompson/examples/alphabet_size_two.aut
@@ -5,4 +5,5 @@ x1 a2	->	x1 a2 a3
 x1 a3	->	x2
 x2 a1	->	x1 a3
 x2 a2	->	x1 a2 a2
-x2 a3	->	x1 a2 a1
+x2 a3	->	x1 a2 a1
+A toy example to test that the program works with :math:`n > 2` and :math:`r > 1`.
diff --git a/thompson/examples/arity_four.aut b/thompson/examples/arity_four.aut
@@ -9,4 +9,5 @@ x1 a3		->	x1 a3 a3
 x1 a4 a1	->	x1 a3 a4
 x1 a4 a2	->	x1 a2
 x1 a4 a3	->	x1 a3 a1
-x1 a4 a4	->	x1 a4
+x1 a4 a4	->	x1 a4
+An example created to test that the package works with examples of arity four.
diff --git a/thompson/examples/arity_three_order_inf.aut b/thompson/examples/arity_three_order_inf.aut
@@ -6,4 +6,5 @@ x1 a1 a3	->	x1 a3 a1
 x1 a2		->	x1 a3 a2
 x1 a3 a1	->	x1 a3 a3 a3
 x1 a3 a2	->	x1 a3 a3 a2
-x1 a3 a3	->	x1 a3 a3 a1
+x1 a3 a3	->	x1 a3 a3 a1
+A toy example created to test the beahviour of the program with automorphisms of arity 3. This automorphism is of infinite order and is (I think? TODO: check this) purely infinite.
diff --git a/thompson/examples/cyclic_order_six.aut b/thompson/examples/cyclic_order_six.aut
@@ -5,4 +5,5 @@ x a1 a2 a1		->	x a1 a2 a2 a2
 x a1 a2 a2 a1	->	x a2 a1
 x a1 a2 a2 a2	->	x a2 a2
 x a2 a1			->	x a1 a2 a2 a1
-x a2 a2			->	x a1 a2 a1
+x a2 a2			->	x a1 a2 a1
+An introductory example drawn on the board by NB. It is purely periodic, of order six.
diff --git a/thompson/examples/example_4_11.aut b/thompson/examples/example_4_11.aut
@@ -2,4 +2,5 @@
 (2,1)	->	(2,1)
 x a1 a1	->	x a1
 x a1 a2	->	x a2 a1
-x a2	->	x a2 a2
+x a2	->	x a2 a2
+This example is used in the paper to illustrate the meaning of a semi-normal form.
diff --git a/thompson/examples/example_4_12.aut b/thompson/examples/example_4_12.aut
@@ -2,4 +2,5 @@
 (2,1)	->	(2,1)
 x a1 a1	->	x a2 a2
 x a1 a2	->	x a2 a1
-x a2	->	x a1
+x a2	->	x a1
+This example is used in the paper to illustrate the meaning of a semi-normal form. This example needs to be expanded from its minimal representation (above) to find a semi-normal (in fact quasi-normal) form.
diff --git a/thompson/examples/example_4_25.aut b/thompson/examples/example_4_25.aut
@@ -4,4 +4,5 @@ x a1			->	x a1 a1 a1
 x a2 a1			->	x a1 a1 a2
 x a2 a2 a1 a1	->	x a2 a2
 x a2 a2 a1 a2	->	x a1 a2
-x a2 a2 a2		->	x a2 a1
+x a2 a2 a2		->	x a2 a1
+This example is used in the paper to illustrate the process of finding the :meth:`~thompson.automorphism.Automorphism.quasinormal_basis`.
diff --git a/thompson/examples/example_4_5.aut b/thompson/examples/example_4_5.aut
@@ -4,4 +4,5 @@ x1 a1 a1 a1	->	x1 a1 a1
 x1 a1 a1 a2	->	x1 a1 a2 a1
 x1 a1 a2	->	x1 a1 a2 a2
 x1 a2 a1	->	x1 a2 a2
-x1 a2 a2	->	x1 a2 a1
+x1 a2 a2	->	x1 a2 a1
+This example is used to illustrate the different types of components/orbits in the paper.
diff --git a/thompson/examples/example_5_12_phi.aut b/thompson/examples/example_5_12_phi.aut
@@ -1,4 +1,5 @@
 2
 (2,1)	->	(2,1)
 x a1	->	x a2
-x a2	->	x a1
+x a2	->	x a1
+The example used in the paper to demonstrate the :meth`periodic conjugacy test <thompson.factors.PeriodicFactor.test_conjugate_to>`.
diff --git a/thompson/examples/example_5_12_psi.aut b/thompson/examples/example_5_12_psi.aut
@@ -5,4 +5,5 @@ x a1 a1 a1 a2	->	x a1 a1 a1 a1
 x a1 a1 a2		->	x a1 a2
 x a1 a2			->	x a1 a1 a2
 x a2 a1			->	x a2 a2
-x a2 a2			->	x a2 a1
+x a2 a2			->	x a2 a1
+The example used in the paper to demonstrate the :meth`periodic conjugacy test <thompson.factors.PeriodicFactor.test_conjugate_to>`.
diff --git a/thompson/examples/example_5_26_psi.aut b/thompson/examples/example_5_26_psi.aut
@@ -3,4 +3,5 @@
 x a1		->	x a1 a1 a1
 x a2 a1 a1	->	x a2
 x a2 a1 a2	->	x a1 a1 a2
-x a2 a2		->	x a1 a2
+x a2 a2		->	x a1 a2
+The example used in the paper to demonstrate the :meth`infinite conjugacy test <thompson.factors.InfiniteFactor.test_conjugate_to>`.
diff --git a/thompson/examples/example_5_3.aut b/thompson/examples/example_5_3.aut
@@ -7,4 +7,5 @@ x a1 a2 a1		->	x a1 a2 a2
 x a1 a2 a2		->	x a1 a2 a1
 x a2 a1			->	x a2 a1 a1
 x a2 a2 a1		->	x a2 a1 a2
-x a2 a2 a2		->	x a2 a2
+x a2 a2 a2		->	x a2 a2
+This example is used to demonstrate how we can break down an automorphism into its :meth:`~thompson.automorphism.Automorphism.free_factors`.
diff --git a/thompson/examples/example_5_9.aut b/thompson/examples/example_5_9.aut
@@ -6,4 +6,5 @@ x a1 a2		->	x a1 a1 a1
 x a2 a1 a1	->	x a2 a1 a2
 x a2 a1 a2	->	x a2 a1 a1
 x a2 a2 a1	->	x a2 a2 a2
-x a2 a2 a2	->	x a2 a2 a1
+x a2 a2 a2	->	x a2 a2 a1
+This example is used in the paper to illustrate the definition of :class:`cycle types <thompson.factors.PeriodicFactor>`.
diff --git a/thompson/examples/first_pond_example_phi.aut b/thompson/examples/first_pond_example_phi.aut
@@ -10,4 +10,4 @@ x1 a2 a1 a1          -> x1 a2 a2 a1 a2 a2
 x1 a2 a1 a2          -> x1 a1 a2 a2 a2
 x1 a2 a2 a1          -> x1 a1 a2 a1
 x1 a2 a2 a2          -> x1 a1 a2 a2 a1
-
+The first example of a pond orbit, found by a random search. Its banks are :math:`x\alpha_1^4\alpha_2` and :math:`x\alpha_1\alpha_2^2`.
diff --git a/thompson/examples/first_pond_example_psi.aut b/thompson/examples/first_pond_example_psi.aut
@@ -6,3 +6,4 @@ x1 a2 a2 a1 a1 a1 -> x1 a2 a2
 x1 a2 a2 a1 a1 a2 -> x1 a2 a1 a2 a1
 x1 a2 a2 a1 a2 -> x1 a1 a2
 x1 a2 a2 a2 -> x1 a2 a1 a2 a2
+The element which was conjugate to the first example of a pond orbit, found by a random search.
diff --git a/thompson/examples/inf_conj_phi.aut b/thompson/examples/inf_conj_phi.aut
@@ -9,3 +9,4 @@ x1 a2 a2 a1 a1 a1 -> x1 a2 a1 a2 a1 a1
 x1 a2 a2 a1 a1 a2 -> x1 a1 a1 a1
 x1 a2 a2 a1 a2 -> x1 a1 a1 a2
 x1 a2 a2 a2 -> x1 a2 a2 a1
+An example used to debug the :meth:`infinite conjugacy test <thompson.factors.InfiniteFactor.test_conjugate_to>`.
diff --git a/thompson/examples/inf_conj_psi.aut b/thompson/examples/inf_conj_psi.aut
@@ -6,3 +6,4 @@ x1 a2 a2 a1 -> x1 a2 a2
 x1 a2 a2 a2 a1 a1 -> x1 a1 a1 a1
 x1 a2 a2 a2 a1 a2 -> x1 a2 a1 a1
 x1 a2 a2 a2 a2 -> x1 a2 a1 a2
+An example used to debug the :meth:`infinite conjugacy test <thompson.factors.InfiniteFactor.test_conjugate_to>`.
diff --git a/thompson/examples/nathan1_example.aut b/thompson/examples/nathan1_example.aut
@@ -0,0 +1,9 @@
+6
+(2,1)			->	(2,1)
+x a1 a1 		->	x a2 a2 a2 a2
+x a1 a2 		->	x a2 a2 a2 a1
+x a2 a1 a1 a1	->	x a2 a1
+x a2 a1 a1 a2	->	x a2 a2 a1 a1
+x a2 a1	a2		->	x a1
+x a2 a2			->	x a2 a2 a1 a2
+One of Nathan's examples. This is *almost*, but not quite conjugate to nathan_pond_example. Nathan had this to say: "*I untwisted one of the infinite orbits after a conjugation and so they definitely should not be conjugate.*"
diff --git a/thompson/examples/nathan2_example.aut b/thompson/examples/nathan2_example.aut
@@ -0,0 +1,10 @@
+7
+(2,1)			->	(2,1)
+x a1 a1 		->	x a2 a1
+x a1 a2 a1 		->	x a1 a2
+x a1 a2 a2 		->	x a2 a2 a2
+x a2 a1 		->	x a1 a1 a2 a1
+x a2 a2	a1 a1	->	x a1 a1 a2 a2
+x a2 a2 a1 a2	->	x a2 a2 a1
+x a2 a2	a2		->	x a1 a1 a1
+One of Nathan's examples. Nathan had this to say: "*nathan2_example is conjugate to nathan3_example, via a rho that can be found using your program or nathan4_example. Note that characteristics are not the same for two of the semi-infinite orbits.*"
diff --git a/thompson/examples/nathan3_example.aut b/thompson/examples/nathan3_example.aut
@@ -0,0 +1,16 @@
+13
+(2,1)			->	(2,1)
+x a1 a1 		->	x a2 a2 a2
+x a1 a2 		->	x a2 a1 a1 a1
+x a2 a1 a1 a1	->	x a1 a2 a1 a2
+x a2 a1 a1 a2 a1 a1	->	x a1 a2 a2 a1
+x a2 a1	a1 a2 a1 a2		->	x a1 a1
+x a2 a1	a1 a2 a2	->	x a1 a2 a2 a2
+x a2 a1 a2 a1 a1 a1 		->	x a2 a1 a1 a2 a1 a1
+x a2 a1 a2 a1 a1 a2 		->	x a2 a1 a1 a2 a2
+x a2 a1 a2 a1 a2	->	x a2 a1 a2 a1
+x a2 a1 a2 a2 a1	->	x a2 a1 a2 a2
+x a2 a1	a2 a2 a2		->	x a2 a2 a1
+x a2 a2	a1		->	x a2 a1 a1 a2 a1 a2
+x a2 a2	a2		->	x a1 a2 a1 a1
+One of Nathan's examples. Nathan had this to say: "*nathan2_example is conjugate to nathan3_example, via a rho that can be found using your program or nathan4_example. Note that characteristics are not the same for two of the semi-infinite orbits.*"
diff --git a/thompson/examples/nathan4_example.aut b/thompson/examples/nathan4_example.aut
@@ -0,0 +1,13 @@
+10
+(2,1)			->	(2,1)
+x a1 a1 a1		->	x a2 a1 a1 a2 a1 a2
+x a1 a1 a2 a1 a1 		->	x a2 a2 a2
+x a1 a1 a2 a1 a2	->	x a2 a1 a1 a1
+x a1 a1 a2 a2 a1	->	x a2 a1 a1 a2 a1 a1
+x a1 a1	a2 a2 a2		->	x a2 a1 a1 a2 a2
+x a1 a2	->	x a2 a1 a2 a2
+x a2 a1 a1 		->	x a1 a1
+x a2 a1 a2 		->	x a1 a2
+x a2 a2 a1	->	x a2 a1 a2 a1
+x a2 a2 a2	->	x a2 a2 a1
+One of Nathan's examples. Nathan had this to say: "*nathan2_example is conjugate to nathan3_example, via a rho that can be found using your program or nathan4_example. Note that characteristics are not the same for two of the semi-infinite orbits.*"
diff --git a/thompson/examples/nathan_pond_example.aut b/thompson/examples/nathan_pond_example.aut
@@ -6,4 +6,5 @@ x a1 a1 a2 a1	->	x a2 a2
 x a1 a1 a2 a2	->	x a2 a1
 x a1 a2			->	x a1 a2 a1 a2
 x a2 a1			->	x a1 a2 a2 a2
-x a2 a2			->	x a1 a2 a2 a1
+x a2 a2			->	x a1 a2 a2 a1
+Nathan's example of an automorphism containing a pond. This was simpler than the first example found.
diff --git a/thompson/examples/periodic_QNB_206.aut b/thompson/examples/periodic_QNB_206.aut
@@ -25,4 +25,5 @@ x4 a4 a1 -> x3 a3 a4
 x4 a4 a2 -> x3 a1
 x4 a4 a3 -> x3 a3 a2
 x4 a4 a4 -> x3 a2
-x5 -> x2 a3 a4
+x5 -> x2 a3 a4
+This purely periodic automorphism (again found by random search) has a quasinormal basis of size 206. TODO: verify this!
diff --git a/thompson/examples/periodic_QNB_344.aut b/thompson/examples/periodic_QNB_344.aut
@@ -20,3 +20,4 @@ x3 a3 a4 -> x5 a1 a4 a1 a1
 x3 a4 -> x5 a1 a4 a2
 x4 -> x5 a3 a4
 x5 -> x2
+This purely periodic automorphism (again found by random search) has a quasinormal basis of size 344. TODO: verify this!
diff --git a/thompson/examples/pond_width_4.aut b/thompson/examples/pond_width_4.aut
@@ -9,6 +9,7 @@ x3 a2    -> x1 a2 a2 a1
 x4 a1    -> x4 a2      
 x4 a2 a1 -> x3         
 x4 a2 a2 -> x1 a2 a1   
+An example found by random search of a pond orbit of width 4. Prior to this we had only seen ponds of width 1 or 2. 
 
 I haven't looked at this in detail; this is just what the script produced. Python believes that the QNB consists of the following:
 
diff --git a/thompson/examples/random.py b/thompson/examples/random.py
@@ -18,12 +18,22 @@ def decd(num_expansions=None, signature=None):
 		if signature is None:
 			signature = random_signature()
 		return undec(num_expansions, signature)
+	decd.__doc__ = undec.__doc__
 	return decd
 
 def random_signature():
+	r"""Randomly generates a :class:`~thompson.word.Signature` :math:`(n, r)` for use in the functions below. The values of :math:`n` and :math:`r` are chosen (uniformly) at random from :math:`n \in \{2, 3, 4\}` and :math:`r \in \{1, 2, 3, 4, 5\}`, respectively.
+	
+	.. note:: This function is used to select a random signature when no *signature* argument is provided to the following random functions.
+	"""
 	return Signature(randint(2, 4), randint(1, 5))
 
 def random_simple_word(signature=None):
+	r"""Randomly generates a :meth:`simple <thompson.word.Word.is_simple>` :class:`~thompson.word.Word` belonging to the algebra with the given *signature*. The word consists of an :math:`x_i` followed by 0--15 descendant operators :math:`\alpha_j`. The length and the index of each :math:`\alpha_j` is chosen (uniformly) at random.
+	
+		>>> random_simple_word().is_simple()
+		True
+	"""
 	signature = signature or random_signature()
 	letters = []
 	base = randint(1, signature.alphabet_size)
@@ -32,10 +42,17 @@ def random_simple_word(signature=None):
 	num_alphas = randint(0, 15)
 	for i in range(num_alphas):
 		letters.append(-randint(1, signature.arity))
-	return Word(letters, signature)
+	return Word(letters, signature, preprocess=False)
 
 @needs_defaults
 def random_basis(num_expansions, signature):
+	r"""Randomly generates a basis for the algebra with the given *signature* :math:`(n,r)`. The basis is generated by expanding the :meth:`~thompson.generators.Generators.standard_basis` *num_expansions* times. The expansion point is chosen (uniformly) at random each time. If *num_expansions* is not provided, a value from :math:`\{1, 2, 3, 4, 5\}` is chosen (uniformly) at random.
+	
+		>>> random_basis().is_basis()
+		True
+	
+	.. note:: This does not generate *bases* uniformly at random. For instance, take :math:`V_{n,r} = V_{2,1}` and let *num_expansions = 3*. The first expansion always gives the basis :math:`[x\alpha_1, x\alpha_2]`. Expanding this twice produces give six bases, one of which appears twice. (To see this, enumeate the rooted binary trees with four leaves.)
+	"""
 	basis = Generators.standard_basis(signature)
 	
 	for _ in range(num_expansions):
@@ -45,27 +62,37 @@ def random_basis(num_expansions, signature):
 
 @needs_defaults
 def random_automorphism(num_expansions, signature):
+	"""Randomly generates an automorphism for the algebra with the given signature. Two bases *domain* and *range* are generated by :func:`random_basis`; then *range* is :func:`randomly shuffled <py3:random.shuffle>`. An automorphism is returned which maps the elements of *domain* to those of *range* in order.
+	
+	..note :: The bases may be reduced when the automorphism is created (if they contain redundancy.
+	"""
 	domain = random_basis(num_expansions, signature)
 	range  = random_basis(num_expansions, signature)
 	shuffle(range)
 	return Automorphism(domain, range)
 
 @needs_defaults
 def random_conjugate_pair(num_expansions, signature):
+	r"""Calls :func:`random_automorphism` to create two automorphisms :math:`\psi` and :math:`\rho`. Returns the pair :math:`(\psi, \rho^{-1}\psi\rho)`, which are conjugate by definition."""
 	psi = random_automorphism(num_expansions, signature)
 	rho = random_automorphism(num_expansions, signature)
 	phi = ~rho * psi * rho
 	return psi, phi
 
 @needs_defaults
 def random_conjugate_factors(num_expansions, signature):
+	r"""Calls :func:`random_conjugate_pair` to create two automorphisms :math:`\psi` and :math:`\phi`. Returns the :meth:`~thompson.automorphism.Automorphism.free_factors` :math:`\psi_P, \psi_I, \phi_P, \phi_I.`
+	
+	.. note:: Some of the factors may be ``None`` if they are trivial.
+	"""
 	psi, phi = random_conjugate_pair(num_expansions, signature)
 	psi_p, psi_i = psi.free_factors()
 	phi_p, phi_i = phi.free_factors()
 	return psi_p, psi_i, phi_p, phi_i
 
 @needs_defaults
 def random_conjugate_periodic_factors(num_expansions, signature):
+	r"""Calls :func:`random_conjugate_factors` but returns only the peroidic factors. This method returns :math:`\psi_P, \phi_P` and ensures they are non-trivial.`"""
 	psi_p = phi_p = None
 	while psi_p is None or phi_p is None:
 		psi_p, _, phi_p, _ = random_conjugate_factors()
@@ -74,6 +101,7 @@ def random_conjugate_periodic_factors(num_expansions, signature):
 
 @needs_defaults
 def random_conjugate_infinite_factors(num_expansions, signature):
+	r"""Calls :func:`random_conjugate_factors` but returns only the infinite factors. This method returns :math:`\psi_I, \phi_I` and ensures they are non-trivial.`"""
 	psi_i = phi_i = None
 	while psi_i is None or phi_i is None:
 		_, psi_i, _, phi_i = random_conjugate_factors()
diff --git a/thompson/factors.py b/thompson/factors.py
@@ -60,6 +60,8 @@ def relabel(self):
 		
 		:raises AttributeError: if the factor has not been assigned any relabellers.
 		
+		.. doctest::
+			
 			>>> psi = example_5_12_psi; phi = example_5_12_phi
 			>>> rho = psi.test_conjugate_to(phi)
 			>>> print(rho)
diff --git a/thompson/homomorphism.py b/thompson/homomorphism.py
