Documentation Update

- Named examples included with some short comments
- References included from the paper
- Examples renamed to fit latest numbering scheme

Author: DMRobertson

docs/examples_table.txt

@@ -0,0 +1,86 @@
+alphabet_size_two
+	A toy example to test that the program works in :math:`V_{3,2}`.
+arity_four
+	Another example for sanity checking. This is an automorphism of :math:`V_{4,1}`.
+arity_three_order_inf
+	A purely :mod:`~thompson.infinite` automorphism of :math:`V_{3,1}`
+cyclic_order_six
+	An introductory example drawn on the board by NB. It is purely periodic of order six.
+example_4_1
+	This example is used in the paper to illustrate the meaning of a semi-normal form (Example :paperref:`ex:snf1`) and of a tree pair diagram (Example :paperref:`snf0`).
+example_4_11
+	This example is used in the paper to illustrate the meaning of a semi-normal form (Example :paperref:`ex:snf1`) and of a tree pair diagram (Example :paperref:`snf0`).
+example_4_12
+	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 to find a semi-normal (in fact quasi-normal) form.
+example_4_17
+	Nathan's example of an automorphism containing a pond. This was simpler than the first example found.
+example_4_33
+	Nathan's example of an automorphism containing a pond. This was simpler than the first example found.
+example_4_35
+	Nathan's example of an automorphism containing a pond. This was simpler than the first example found.
+example_4_5
+	This example is used to illustrate the different types of :mod:`components/orbits <thompson.orbits>` in the paper.
+example_4_7
+	This example is used to illustrate the different types of :mod:`components/orbits <thompson.orbits>` in the paper.
+example_5_12_phi
+	The example used in the paper to demonstrate the :meth:`periodic conjugacy test <thompson.periodic.PeriodicAut.test_conjugate_to>`.
+example_5_12_psi
+	The example used in the paper to demonstrate the :meth:`periodic conjugacy test <thompson.periodic.PeriodicAut.test_conjugate_to>`.
+example_5_15
+	This example is used in the paper to illustrate the process of finding the :meth:`quasi-normal basis <thompson.automorphism.Automorphism.compute_quasinormal_basis>`.
+example_5_18
+	This example is used in the paper to illustrate the process of finding the :meth:`quasi-normal basis <thompson.automorphism.Automorphism.compute_quasinormal_basis>`.
+example_5_2
+	This example is used to illustrate the different types of :mod:`components/orbits <thompson.orbits>` in the paper.
+example_5_26_phi
+	This example is used in the paper to illustrate the process of finding the :meth:`quasi-normal basis <thompson.automorphism.Automorphism.compute_quasinormal_basis>`.
+example_5_26_psi
+	The example used in the paper to demonstrate the :meth:`infinite conjugacy test <thompson.infinite.InfiniteAut.test_conjugate_to>`.
+example_5_3
+	This example is used to demonstrate how we can break down an automorphism into its :meth:`~thompson.mixed.MixedAut.free_factors`.
+example_5_3_i
+	A purely infinite free factor, extracted from example_5_3.
+example_5_3_p
+	A purely periodic free factor, extracted from example_5_3.
+example_5_9
+	This example is used in the paper to illustrate the definition of :class:`cycle types <thompson.periodic.PeriodicAut>`.
+example_6_2
+	Example :paperref:`pcExample1` of the paper, used to illustrate lemma :paperref:`AJDLEMMACMa`.
+example_6_8_phi
+	A purely infinite automorphism which illustrates the bounds :math:`\hat a, \hat b` for power conjugacy.
+example_6_8_psi
+	This example is used in the paper to illustrate the meaning of a semi-normal form (Example :paperref:`ex:snf1`) and of a tree pair diagram (Example :paperref:`snf0`).
+example_6_9_phi
+	Example :paperref:`pcExample1` of the paper, used to illustrate lemma :paperref:`AJDLEMMACMa`.
+example_6_9_psi
+	This example is used in the paper to illustrate the meaning of a semi-normal form (Example :paperref:`ex:snf1`) and of a tree pair diagram (Example :paperref:`snf0`).
+first_pond_example_phi
+	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`.
+first_pond_example_psi
+	The element which was conjugate to the first example of a pond orbit, found by a random search.
+inf_conj_phi
+	An example used to debug the :meth:`infinite conjugacy test <thompson.infinite.InfiniteAut.test_conjugate_to>`.
+inf_conj_psi
+	An example used to debug the :meth:`infinite conjugacy test <thompson.infinite.InfiniteAut.test_conjugate_to>`.
+mixed_pconj_phi
+	An example of mixed power conjugacy found by random search. Should have :math:`\psi^{-4} \sim \phi^2`.
+mixed_pconj_psi
+	An example of mixed power conjugacy found by random search. Should have :math:`\psi^{-4} \sim \phi^2`.
+nathan1_example
+	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."*
+nathan2_example
+	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.*"
+nathan3_example
+	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.*"
+nathan4_example
+	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.*"
+nathan_pond_example
+	Nathan's example of an automorphism containing a pond. This was simpler than the first example found.
+periodic_QNB_206
+	This purely periodic automorphism (again found by random search) has a quasinormal basis of size 206.
+periodic_QNB_344
+	This purely periodic automorphism (again found by random search) has a quasinormal basis of size 344.
+pond_width_4
+	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. 
+power_smaller_QNB
+	The square of this automorphism appears to have a QNB above the QNB of the original automorphism.

docs/generate_examples_table.py

@@ -0,0 +1,27 @@
+import os, sys
+os.chdir('..')
+sys.path.append(os.getcwd())
+
+from thompson import Automorphism
+import thompson.examples
+
+automorphisms = []
+
+for name, attr in thompson.examples.__dict__.items():
+	if not isinstance(attr, Automorphism):
+		continue
+	doc = attr.__doc__.split('\n', maxsplit=1)[0]
+	automorphisms.append((name, doc))
+
+automorphisms.sort()
+
+widths = [max(len(item[i]) for item in automorphisms) for i in range(2)]
+print(widths)
+format_string = "{}\n\t{}"
+
+
+os.chdir('docs')
+
+with open('examples_table.txt', 'wt') as f:
+	for name, docstring in automorphisms:
+		print(format_string.format(name, docstring), file=f)

docs/generate_references.py

@@ -28,6 +28,7 @@ def bibliography_entries(tex_source):
 	("~"     , ' '),
 	(r"\'{e}", "é"),
 	(r"\'{o}", "ó"),
+	(r"\"{o}", "ö"),
 	("---"   , "—"), #em dash
 	("--"    , "–"), #en dash
 	(r"\\"    , "")
@@ -44,7 +45,9 @@ def bibliography_entries(tex_source):
 	re.compile(tex_group.format('bf')),
 	re.compile(tex_macro.format('textbf'))
 ]
+code = re.compile(tex_group.format('tt'))
 maths = re.compile(r'\$(.+?)\$')
+url = re.compile(tex_macro.format('url'))
 
 def tidy_up(text):
 	text = text.strip()
@@ -55,7 +58,9 @@ def tidy_up(text):
 		text = italic.sub(r' *\1* ', text)
 	for bold in bolds:
 		text = bold.sub(r' **\1** ', text)
-	text = maths.sub(r' :math:`\1` ', text)
+	text = code.sub(r'``\1``', text)
+	text = url.sub(r'\1', text)
+	text = maths.sub(r' :math:`\1`', text)
 	return text
 
 if __name__ == '__main__':

docs/paper_bibliography.txt

@@ -1,21 +1,22 @@
 .. [AS74] \M. Anshel and P. Stebe, "The solvability of the conjugacy problem for certain HNN groups",  *Bull. Amer. Math. Soc.* ,  **80**  (2) (1974) 266–270.
 .. [B] \K. Brown, "Finiteness properties of groups".  *J. Pure Appl. Algebra*   **44**  (1987), no. 1-3, 45–75.
-.. [BGG11] \C. Bleak, , H. Bowman, A. Gordon, G. Graham, J.Hughes, F. Matucci , J.Sapir, F. Matucci, "Centralizers in R.Thompson's group  :math:`V_{n}` ",  *Groups, Geometry and Dynamics*   **7** , No. 4 (2013), 821-865.
+.. [BCR] \J. Burillo, S. Cleary and C. E. R\"over, "Obstructions for subgroups of Thompson's group  :math:`V`", arxiv.org/abs/1402.3860
+.. [BGG11] \C. Bleak, , H. Bowman, A. Gordon, G. Graham, J. Hughes, F. Matucci and J. Sapir, "Centralizers in R.Thompson's group  :math:`V_{n}`",  *Groups, Geometry and Dynamics*   **7** , No. 4 (2013), 821-865.
 .. [BM07] \J. M. Belk and F. Matucci, "Conjugacy and dynamics in Thompson's groups",  *Geom. Dedicata*   **169**  (1) (2014) 239-261.
 .. [BO93] \R. V. Book and F. Otto, "String-rewriting Systems", Springer, (1993).
-.. [Brin04] \M.G. Brin, "Higher dimensional Thompson groups",  *Geom. Dedicata* ,  **108**  (2004) 163-192.
-.. [CFP96] \J.W. Cannon, W.J. Floyd and W.R. Parry, "Introductory notes on Richard Thompson's groups",  *Enseign. Math.* , (2)  **42** (3-4) (1996) 215-256.
+.. [Brin04] \M. G. Brin, "Higher dimensional Thompson groups",  *Geom. Dedicata* ,  **108**  (2004) 163-192.
+.. [CFP96] \J. W. Cannon, W.J. Floyd and W. R. Parry, "Introductory notes on Richard Thompson's groups",  *Enseign. Math.* , (2)  **42** (3-4) (1996) 215-256.
 .. [Cohn81] \P. M. Cohn, "Universal Algebra". Mathematics and its Applications, 6, D. Reidel Pub. Company, (1981).
 .. [Cohn91] \P. M. Cohn, "Algebra, Volume 3". J. Wiley, (1991).
-.. [Com77] \L. P. J. Comerford, "A note on power-conjugacy",  *Houston J. Math.*  3 (1977), no. 3, 337—341.
 .. [DMP] \W. Dicks, C. Martinez-Pérez, "Isomorphisms of Brin-Higman-Thompson groups",  *Israel Journal of Mathematics* ,  **199**  (2014), 189–218.
+.. [DMR] \D. M. Robertson, "``thompson``: a package for Python 3.3+ to work with elements of the Higman-Thompson groups  :math:`G_{n,r}`". Source code available from https://github.com/DMRobertson/thompsons\_v and documentation available from http://thompsons-v.readthedocs.org/.
 .. [Hig74] \G. Higman, "Finitely presented infinite simple groups",   *Notes on Pure Mathematics* , Vol. 8 (1974).
 .. [JT61] \B. Jónsson and A. Tarski, "On two properties of free algebras",  *Math. Scand.* ,  **9**  (1961) 95-101.
 .. [Lip66] \S. Lipschutz, "Generalisation of Dehn's result on the conjugacy problem",  *Proc. Amer. Math. Soc.* ,  **17**  (1966) 759–762.
 .. [Lot83] \M. Lothaire, "Combinatorics on Words", Addison-Wesley, Advanced Book Program, World Science Division, (1983).
 .. [MPN] \C. Martinez-Perez, B. Nukinkis, "Bredon cohomological finiteness conditions for generalisations of Thompson's groups",  *Groups Geom. Dyn.*   **7**  (4) (2013) 931–959.
-.. [MT] \McKenzie, Ralph; Thompson, Richard J."An elementary construction of unsolvable word problems in group theory", Word problems: decision problems and the Burnside problem in group theory, Studies in Logic and the Foundations of Math., 71, pp. 457–478. North-Holland, Amsterdam, (1973).
+.. [MT] \R. McKenzie and R. J. Thompson, "An elementary construction of unsolvable word problems in group theory", Word problems: decision problems and the Burnside problem in group theory, Studies in Logic and the Foundations of Math., 71, pp. 457–478. North-Holland, Amsterdam, (1973).
 .. [Pardo] \E. Pardo, "The isomorphism problem for Higman-Thompson groups",  *Journal of Algebra* ,  **344**  (2011), 172-–183.
 .. [Pride08] \S. J. Pride, "On the residual finiteness and other properties of (relative) one-relator groups",  *Proc. Amer. Math. Soc.*   **136**  (2) (2008) 377–386.
-.. [SD10] \O.P. Salazar-Diaz, "Thompson's group V from a dynamical viewpoint",  *Internat. J. Algebra Comput.* , 1, 39-70, 20, (2010).
-.. [Tho] \R.J. Thompson, unpublished notes. http://www.math.binghamton.edu/matt/thompson/index.html
+.. [SD10] \O. P. Salazar-Diaz, "Thompson's group V from a dynamical viewpoint",  *Internat. J. Algebra Comput.* , 1, 39-70, 20, (2010).
+.. [Tho] \R. J. Thompson, unpublished notes. http://www.math.binghamton.edu/matt/thompson/index.html

docs/references.rst

@@ -14,7 +14,7 @@ Other references
 ----------------
 
 .. [Kogan] \R. Kogan, "`nVTrees Applet <http://www.math.tamu.edu/~romwell/nvTrees/>`_" (2008). Accessed 17th September, 2014. 
-.. [Mill] \B. Mill, "`Drawing Presentable Trees <http://billmill.org/pymag-trees/>_" (2010). Accessed 3rd September, 2014. 
+.. [Mill] \B. Mill, "`Drawing Presentable Trees <http://billmill.org/pymag-trees/>`_" (2010). Accessed 3rd September, 2014. 
 .. [RT] \E. M. Reingold and J. S. Tilford. "`Tidier Drawings of Trees <http://emr.cs.iit.edu/~reingold/tidier-drawings.pdf>`_", *IEEE Transactions on Software Engineering* 7, no. 2, pp. 223--228 (1981). See also sec. "`Trees as Blocks <http://billmill.org/pymag-trees/#heading6>`_" of [Mill].
 
-.. comment [Zaks] Zaks, S. (1980). `Lexicographic generation of ordered trees <http://ac.els-cdn.com/0304397580900730/1-s2.0-0304397580900730-main.pdf?_tid=a998eb50-4d3a-11e4-88d6-00000aacb35d&acdnat=1412587687_576aee4e88c728ef1ad84538f82f736d>`_. *Theoretical Computer Science* 10 (1980): 63-82.
+.. [Zaks] \S. Zaks, "`Lexicographic generation of ordered trees <http://ac.els-cdn.com/0304397580900730/1-s2.0-0304397580900730-main.pdf?_tid=a998eb50-4d3a-11e4-88d6-00000aacb35d&acdnat=1412587687_576aee4e88c728ef1ad84538f82f736d>`_", *Theoretical Computer Science* 10: 63-82 (1980).

docs/thompson.examples.rst

@@ -3,18 +3,16 @@ Examples
 
 This module provides a number of explicit examples for use in doctests. Additionally, functions to generate random automorphisms are provided.
 
+.. automodule:: thompson.examples
+
 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.
+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 the paper.
 
-.. todo:: Make Sphinx show these examples here? A better system for importing/loading examples?
+.. todo:: The numbered examples need updating to a current version of the paper.
 
-.. automodule:: thompson.examples
-    :members:
-    :undoc-members:
-    :show-inheritance:
-    :exclude-members: random_signature, random_simple_word, random_basis, random_automorphism, random_periodic_automorphism, random_infinite_automorphism, random_conjugate_pair,  random_conjugate_periodic_pair, random_conjugate_infinite_pair, random_powers, random_power_conjugate_pair
+.. include:: examples_table.txt
 
 Randomly generated examples
 ---------------------------

thompson/automorphism.py

@@ -94,13 +94,13 @@ def image(self, key, inverse=False):
 		
 		Examples of finding inverse images:
 		
-			>>> print(example_4_25.image('x1 a2 a2', inverse=True))
+			>>> print(example_5_15.image('x1 a2 a2', inverse=True))
 			x1 a2 a2 a1 a1
-			>>> print(example_4_25.image('x1 a1 a1 a2 a2 a1', inverse=True))
+			>>> print(example_5_15.image('x1 a1 a1 a2 a2 a1', inverse=True))
 			x1 a2 a1 a2 a1
-			>>> print(example_4_25.image('x a2', inverse=True))
+			>>> print(example_5_15.image('x a2', inverse=True))
 			x1 a2 a2 a2 x1 a2 a2 a1 a1 L
-			>>> print(example_4_25.image('x a2 a2 x a1 a2 L', inverse=True))
+			>>> print(example_5_15.image('x a2 a2 x a1 a2 L', inverse=True))
 			x1 a2 a2 a1
 		"""
 		if inverse:
@@ -130,9 +130,9 @@ def repeated_image(self, key, power):
 		
 		.. doctest::
 			
-			>>> print(example_4_25.repeated_image('x1 a1', 10))
+			>>> print(example_5_15.repeated_image('x1 a1', 10))
 			x1 a1 a1 a1 a1 a1 a1 a1 a1 a1 a1 a1 a1 a1 a1 a1 a1 a1 a1 a1 a1 a1
-			>>> print(example_4_25.repeated_image('x1 a1 a1 a1 a1 a1 a1 a1', -3))
+			>>> print(example_5_15.repeated_image('x1 a1 a1 a1 a1 a1 a1 a1', -3))
 			x1 a1
 			>>> print(arity_four.repeated_image('x1 a4 a4 a2', 4))
 			x1 a3 a3 a2
@@ -335,7 +335,7 @@ def seminormal_form_start_point(self):
 			Generators((2, 1), ['x1 a1', 'x1 a2'])
 			>>> example_4_12.seminormal_form_start_point()
 			Generators((2, 1), ['x1 a1', 'x1 a2'])
-			>>> example_4_25.seminormal_form_start_point()
+			>>> example_5_15.seminormal_form_start_point()
 			Generators((2, 1), ['x1 a1', 'x1 a2 a1', 'x1 a2 a2'])
 			>>> cyclic_order_six.seminormal_form_start_point()
 			Generators((2, 1), ['x1 a1 a1', 'x1 a1 a2 a1', 'x1 a1 a2 a2', 'x1 a2'])
@@ -400,7 +400,7 @@ def orbit_type(self, y, basis):
 			x1 a2 a2: Periodic component of order 4
 			with respect to the basis [x1 a1 a1, x1 a1 a2, x1 a2 a1, x1 a2 a2]
 			>>> #Example 4.25
-			>>> print_component_types(example_4_25)
+			>>> print_component_types(example_5_15)
 			x1 a1: Right semi-infinite component with characteristic (1, a1 a1)
 			x1 a2 a1: Bi-infinite component
 			x1 a2 a2: Left semi-infinite component with characteristic (-1, a1 a1)
@@ -538,7 +538,7 @@ def semi_infinite_end_points(self, exclude_characteristics=False):
 			[x1 a1] [x1 a2]
 			>>> print(*example_4_12.semi_infinite_end_points())
 			[] []
-			>>> print(*example_4_25.semi_infinite_end_points())
+			>>> print(*example_5_15.semi_infinite_end_points())
 			[x1 a2 a2, x1 a2 a2 a1] [x1 a1, x1 a1 a1]
 			>>> print(*example_6_2.semi_infinite_end_points())
 			[x1 a1 a1] [x1 a2]
@@ -610,7 +610,7 @@ def print_characteristics(self):
 			>>> example_4_1.print_characteristics()
 			(-1, a1)
 			(1, a2)
-			>>> example_4_25.print_characteristics()
+			>>> example_5_15.print_characteristics()
 			(-1, a1 a1)
 			(1, a1 a1)
 			>>> example_6_2.print_characteristics()
@@ -675,9 +675,9 @@ def share_orbit(self, u, v):
 			>>> u  = Word('x a2 a2 a1 a1 a2', (2, 1))
 			>>> v1 = Word('x a1 a2', (2, 1))
 			>>> v2 = Word('x a1 a1 a2', (2, 1))
-			>>> print(example_4_25.share_orbit(u, v1))
+			>>> print(example_5_15.share_orbit(u, v1))
 			{}
-			>>> print(example_4_25.share_orbit(u, v2))
+			>>> print(example_5_15.share_orbit(u, v2))
 			{3}
 			>>> u  = Word('x a2 a2 x a1 a2 L x a2 a1 L x a1 a1 a1 a2 L', (2, 1))
 			>>> vs = [
@@ -686,7 +686,7 @@ def share_orbit(self, u, v):
 			... 	Word('x a2 a2 x a1 a2 L', (2, 1)),
 			... 	Word('x a1 a1 x a1 a2 x a2 a2 L L', (2, 1))]
 			... 
-			>>> for v in vs: print(example_4_25.share_orbit(u, v))
+			>>> for v in vs: print(example_5_15.share_orbit(u, v))
 			{-4}
 			{}
 			{-1}
@@ -788,12 +788,12 @@ def _type_b_descendant(self, head, tail, head_data):
 		* :math:`\widetilde{y}\widetilde{\Gamma}` is in the same orbit as :math:`y\Gamma`.
 		* :math:`\widetilde{\Gamma}` does not start with the characteristic multiplier of :math:`\widetilde{y}`.
 		
-			>>> basis = example_4_25.quasinormal_basis
+			>>> basis = example_5_15.quasinormal_basis
 			>>> basis
 			Generators((2, 1), ['x1 a1', 'x1 a2 a1', 'x1 a2 a2'])
 			>>> head = Word('x a2 a2', (2, 1))
-			>>> _, _, type_b_data = example_4_25.orbit_type(head, basis)
-			>>> example_4_25._type_b_descendant(head, from_string('a1 a1 a2'), type_b_data)
+			>>> _, _, type_b_data = example_5_15.orbit_type(head, basis)
+			>>> example_5_15._type_b_descendant(head, from_string('a1 a1 a2'), type_b_data)
 			(1, Word('x1 a2 a2', (2, 1)), (-2,))
 		"""
 		orig_head = head

thompson/examples/__init__.py

@@ -23,6 +23,7 @@
 
 def add_module_attribute(name, value):
 	globals()[name] = value
+	# print('loading', name)
 	__all__.append(name)
 
 remove_whitespace = str.maketrans('', '', string.whitespace)
@@ -47,6 +48,8 @@ def read_examples():
 			p, i = aut.free_factors()
 			add_module_attribute(name + '_p', p)
 			add_module_attribute(name + '_i', i)
+			p.__doc__ = "A purely periodic free factor, extracted from {}.".format(name)
+			i.__doc__ = "A purely infinite free factor, extracted from {}.".format(name)
 
 	#3. If any examples have more than one name, deal with that next.
 	aliases = pkg_resources.resource_filename("thompson.examples", "aliases.txt")