mjo/clan/vinberg_clan.py: cite references

diff --git a/mjo/clan/vinberg_clan.py b/mjo/clan/vinberg_clan.py
index 86ab8a83d5dee5415498f205f514f23692405e91..9770dc320b5e67ea16d5cb7b5daf9f3bf62ecf9a 100644 (file)
--- a/mjo/clan/vinberg_clan.py
+++ b/mjo/clan/vinberg_clan.py
@@ -1,3 +1,26 @@
+"""
+The (up to isomorphism) clan associated with the Vinberg cone.
+
+REFERENCES:
+
+  .. [Herrington2021] Elliot Michael Herrington.
+     Highly symmetric homogeneous Kobayashi-hyperbolic manifolds.
+     Ph.D. Thesis, University of Adelaide, School of Mathematical
+     Sciences, 2021. https://hdl.handle.net/2440/133439
+
+  .. [Ishi2013] Hideyuki Ishi.
+     On a class of homogeneous cones consisting of real
+     symmetric matrices.
+     Josai Mathematical Monographs, 6(1)71-80, 2013.
+     :doi:`10.20566/13447777_6_71`.
+
+  .. [IshiKoufany2021] Hideyuki Ishi and Khalid Koufany.
+     The Compression Semigroup of the Dual Vinberg Cone.
+     Springer Proceedings in Mathematics & Statistics, vol 366.
+     Springer, Cham. :doi:`10.1007/978-3-030-78346-4_8`.
+
+"""
+
 from mjo.clan.normal_decomposition import NormalDecomposition
 
 class VinbergClan(NormalDecomposition):
@@ -241,11 +264,14 @@ class VinbergClan(NormalDecomposition):
         r"""
         Generate a random triangular automorphism of the Vinberg cone.
 
-        Elliot Herrington in his thesis "Highly symmetric homogeneous
-        Kobayashi-hyperbolic manifolds" gives a formula for the
-        connected component of the identity in the group of triangular
-        automorphisms. This won't generate the whole group, but it's
-        a good start.
+        We use the formula in [Herrington2021]_ for the connected
+        component of the identity in the group of triangular
+        automorphisms. This triangular group is simply connected, so
+        we obtain the whole thing.
+
+        Another option would be to use Lemma 4 in [Ishi2013]_ which
+        applies more generally to homogeneous cones arising from
+        chordal graphs.
         """
         from sage.matrix.matrix_space import MatrixSpace
         R = self.base_ring()
@@ -273,8 +299,8 @@ class VinbergClan(NormalDecomposition):
         Generate a random automorphism of the Vinberg cone that
         fixes the unit element.
 
-        This is effectively a guess, based on the work done by Ishi
-        and Koufany for the **dual** Vinberg cone.
+        This is ultimately a guess based on the results in
+        [IshiKoufany2021]_ for the dual Vinberg cone.
 
         SETUP::
 
@@ -333,6 +359,18 @@ class VinbergClan(NormalDecomposition):
     def random_cone_automorphism(self):
         r"""
         Generate a random automorphism of the Vinberg cone.
+
+        We have two options here. The current implementation combines
+        a random triangular automorphism from [Herrington2021]_ with a
+        random isotropy.
+
+        The introduction to [Ishi2013]_ claims that the full
+        automorphism group is generated by "two" transformations. His
+        clan differs from ours, but only in that the first two
+        idempotents are swapped, so we could easily translate between
+        the two. Option (b) would be to generate a random product of
+        these transformations, and then pre- and post-compose the
+        result with the e11 <-> e22 swap.
         """
         T = self.random_triangular_cone_automorphism()
         K = self.random_isotropy_cone_automorphism()