Trac #8598: Add graphical output to operation tables

Operation tables can be output as grids with color or grayscale squares
representing the different elements of the algebraic structure.  Adding
these into {{{sage.matrix.operation_table.OperationTable}}} would be a
nice self-contained project for someone looking for a project involving
plotting and graphics.  Despite the localized nature of the project, it
would see wide applicability throughout Sage.  Look for stubs in the
source code,

I'm pretty sure Mathematica does this for groups (Cayley table), but I
can't get Wolfram Alpha or MathWorld to cough it up again for me now
that I want it.

URL: https://trac.sagemath.org/8598
Reported by: rbeezer
Ticket author(s): Bruno Edwards
Reviewer(s): Dima Pasechnik

Author: Release Manager

src/sage/matrix/operation_table.py

@@ -15,6 +15,11 @@
 # ****************************************************************************
 
 from sage.structure.sage_object import SageObject
+from matplotlib.cm import gist_rainbow, Greys
+from sage.plot.matrix_plot import matrix_plot
+from sage.matrix.constructor import Matrix
+from sage.plot.text import text
+from copy import copy
 
 
 class OperationTable(SageObject):
@@ -374,15 +379,12 @@ class OperationTable(SageObject):
         k| k i g f d e l b h a j c
         l| l c j i g a h e k b d f
 
-    .. TODO::
-
-        Provide color and grayscale graphical representations of tables.
-        See commented-out stubs in source code.
-
-    AUTHOR:
+    AUTHORS:
 
     - Rob Beezer (2010-03-15)
+    - Bruno Edwards (2022-10-31)
     """
+
     def __init__(self, S, operation, names='letters', elements=None):
         r"""
         TESTS::
@@ -432,7 +434,7 @@ def __init__(self, S, operation, names='letters', elements=None):
         supported = {
             add: (add, '+', '+'),
             mul: (mul, '*', '\\ast')
-            }
+        }
         # default symbols for upper-left-hand-corner of table
         self._ascii_symbol = '.'
         self._latex_symbol = '\\cdot'
@@ -451,7 +453,7 @@ def __init__(self, S, operation, names='letters', elements=None):
         # the elements might not be hashable. But if they are it is much
         # faster to lookup in a hash table rather than in a list!
         try:
-            get_row = {e: i for i,e in enumerate(self._elts)}.__getitem__
+            get_row = {e: i for i, e in enumerate(self._elts)}.__getitem__
         except TypeError:
             get_row = self._elts.index
 
@@ -461,7 +463,8 @@ def __init__(self, S, operation, names='letters', elements=None):
                 try:
                     result = self._operation(g, h)
                 except Exception:
-                    raise TypeError('elements %s and %s of %s are incompatible with operation: %s' % (g,h,S,self._operation))
+                    raise TypeError('elements %s and %s of %s are incompatible with operation: %s' % (
+                        g, h, S, self._operation))
 
                 try:
                     r = get_row(result)
@@ -477,7 +480,8 @@ def __init__(self, S, operation, names='letters', elements=None):
                         except (KeyError, ValueError):
                             failed = True
                     if failed:
-                        raise ValueError('%s%s%s=%s, and so the set is not closed' % (g, self._ascii_symbol, h, result))
+                        raise ValueError('%s%s%s=%s, and so the set is not closed' % (
+                            g, self._ascii_symbol, h, result))
 
                 row.append(r)
             self._table.append(row)
@@ -558,7 +562,8 @@ def _name_maker(self, names):
             else:
                 width = int(log(self._n - 1, base)) + 1
             for i in range(self._n):
-                places = Integer(i).digits(base=base, digits=letters, padto=width)
+                places = Integer(i).digits(
+                    base=base, digits=letters, padto=width)
                 places.reverse()
                 name_list.append(''.join(places))
         elif names == 'elements':
@@ -570,19 +575,22 @@ def _name_maker(self, names):
                 name_list.append(estr)
         elif isinstance(names, list):
             if len(names) != self._n:
-                raise ValueError('list of element names must be the same size as the set, %s != %s'%(len(names), self._n))
+                raise ValueError('list of element names must be the same size as the set, %s != %s' % (
+                    len(names), self._n))
             width = 0
             for name in names:
                 if not isinstance(name, str):
-                    raise ValueError('list of element names must only contain strings, not %s' % name)
+                    raise ValueError(
+                        'list of element names must only contain strings, not %s' % name)
                 if len(name) > width:
                     width = len(name)
                 name_list.append(name)
         else:
-            raise ValueError("element names must be a list, or one of the keywords: 'letters', 'digits', 'elements'")
+            raise ValueError(
+                "element names must be a list, or one of the keywords: 'letters', 'digits', 'elements'")
         name_dict = {}
         for i in range(self._n):
-            name_dict[name_list[i]]=self._elts[i]
+            name_dict[name_list[i]] = self._elts[i]
         return width, name_list, name_dict
 
     def __getitem__(self, pair):
@@ -632,13 +640,15 @@ def __getitem__(self, pair):
             IndexError: invalid indices of operation table: ((1,512), (1,3,2,4)(5,7))
         """
         if not (isinstance(pair, tuple) and len(pair) == 2):
-            raise TypeError('indexing into an operation table requires exactly two elements')
+            raise TypeError(
+                'indexing into an operation table requires exactly two elements')
         g, h = pair
         try:
             row = self._elts.index(g)
             col = self._elts.index(h)
         except ValueError:
-            raise IndexError('invalid indices of operation table: (%s, %s)' % (g, h))
+            raise IndexError(
+                'invalid indices of operation table: (%s, %s)' % (g, h))
         return self._elts[self._table[row][col]]
 
     def __eq__(self, other):
@@ -747,8 +757,9 @@ def set_print_symbols(self, ascii, latex):
             ...
             ValueError: ASCII symbol should be a single character, not 5
         """
-        if not isinstance(ascii, str) or not len(ascii)==1:
-            raise ValueError('ASCII symbol should be a single character, not %s' % ascii)
+        if not isinstance(ascii, str) or not len(ascii) == 1:
+            raise ValueError(
+                'ASCII symbol should be a single character, not %s' % ascii)
         if not isinstance(latex, str):
             raise ValueError('LaTeX symbol must be a string, not %s' % latex)
         self._ascii_symbol = ascii
@@ -935,22 +946,79 @@ def matrix_of_variables(self):
         from sage.rings.rational_field import QQ
         R = PolynomialRing(QQ, 'x', self._n)
         MS = MatrixSpace(R, self._n, self._n)
-        entries = [R('x'+str(self._table[i][j])) for i in range(self._n) for j in range(self._n)]
-        return MS( entries )
-
-    #def color_table():
-        #r"""
-        #Returns a graphic image as a square grid where entries are color coded.
-        #"""
-        #pass
-        #return None
-
-    #def gray_table():
-        #r"""
-        #Returns a graphic image as a square grid where entries are coded as grayscale values.
-        #"""
-        #pass
-        #return None
+        entries = [R('x'+str(self._table[i][j]))
+                   for i in range(self._n) for j in range(self._n)]
+        return MS(entries)
+
+    # documentation hack
+    # makes the cmap default argument look nice in the docs
+    # by copying the gist_rainbow object and overriding __repr__
+    gist_rainbow_copy=copy(gist_rainbow)
+    class ReprOverrideLinearSegmentedColormap(gist_rainbow_copy.__class__):
+        def __repr__(self):
+            return "gist_rainbow"
+    gist_rainbow_copy.__class__=ReprOverrideLinearSegmentedColormap
+    
+
+    def color_table(self, element_names=True, cmap=gist_rainbow_copy, **options):
+        r"""
+        Returns a graphic image as a square grid where entries are color coded.
+
+        INPUT:
+
+        - ``element_names`` - (default : ``True``) Whether to display text with element names on the image
+
+        - ``cmap`` - (default : ``gist_rainbow``) colour map for plot, see matplotlib.cm
+
+        - ``**options`` - passed on to matrix_plot call
+
+        EXAMPLES::
+
+            sage: from sage.matrix.operation_table import OperationTable
+            sage: OTa = OperationTable(SymmetricGroup(3), operation=operator.mul)
+            sage: OTa.color_table()
+            Graphics object consisting of 37 graphics primitives
+
+        .. PLOT::
+
+            from sage.matrix.operation_table import OperationTable
+            OTa = OperationTable(SymmetricGroup(3), operation=operator.mul)
+            sphinx_plot(OTa.color_table(), figsize=(3.0,3.0))
+        """
+
+        # Base matrix plot object, without text
+        plot = matrix_plot(Matrix(self._table), cmap=cmap,
+                           frame=False, **options)
+
+        if element_names:
+
+            # adapted from ._ascii_table()
+            # prepare widenames[] list for labelling on image
+            n = self._n
+            width = self._width
+
+            widenames = []
+            for name in self._names:
+                widenames.append("{0: >{1}s}".format(name, width))
+
+            # iterate through each element
+            for g in range(n):
+                for h in range(n):
+
+                    # add text to the plot
+                    tPos = (g, h)
+                    tText = widenames[self._table[g][h]]
+                    t = text(tText, tPos, rgbcolor=(0, 0, 0))
+                    plot = plot + t
+
+        # https://moyix.blogspot.com/2022/09/someones-been-messing-with-my-subnormals.html
+        import warnings
+        warnings.filterwarnings("ignore", message="The value of the smallest subnormal for")
+
+        return plot
+
+    def gray_table(self, **options):
+        return self.color_table(cmap=Greys, **options)
 
     def _ascii_table(self):
         r"""
@@ -1031,7 +1099,7 @@ def _ascii_table(self):
             widenames.append('{0: >{1}s}'.format(name, width))
 
         # Headers
-        table = ['{0: >{1}s} '.format(self._ascii_symbol,width)]
+        table = ['{0: >{1}s} '.format(self._ascii_symbol, width)]
         table += [' '+widenames[i] for i in range(n)]+['\n']
         table += [' ']*width + ['+'] + ['-']*(n*(width+1))+['\n']
 
@@ -1068,7 +1136,8 @@ def _latex_(self):
 
         # Row label and body of table
         for g in range(n):
-            table.append('{}')  # Interrupts newline and [], so not line spacing
+            # Interrupts newline and [], so not line spacing
+            table.append('{}')
             table.append(names[g])
             for h in range(n):
                 table.append('&'+names[self._table[g][h]])