eja: update some docstrings.

diff --git a/mjo/eja/eja_algebra.py b/mjo/eja/eja_algebra.py
index ed8c85c9f60dc30c0b1f959533208b81e542b734..ec58b57e8d78b004bcdc0ffaa83fc773c3cfffa8 100644 (file)
--- a/mjo/eja/eja_algebra.py
+++ b/mjo/eja/eja_algebra.py
@@ -101,6 +101,20 @@ class FiniteDimensionalEuclideanJordanAlgebra(FiniteDimensionalAlgebra):
     def _repr_(self):
         """
         Return a string representation of ``self``.
+
+        SETUP::
+
+            sage: from mjo.eja.eja_algebra import JordanSpinEJA
+
+        TESTS:
+
+        Ensure that it says what we think it says::
+
+            sage: JordanSpinEJA(2, field=QQ)
+            Euclidean Jordan algebra of degree 2 over Rational Field
+            sage: JordanSpinEJA(3, field=RDF)
+            Euclidean Jordan algebra of degree 3 over Real Double Field
+
         """
         fmt = "Euclidean Jordan algebra of degree {} over {}"
         return fmt.format(self.degree(), self.base_ring())
@@ -110,6 +124,21 @@ class FiniteDimensionalEuclideanJordanAlgebra(FiniteDimensionalAlgebra):
         """
         Guess a regular element. Needed to compute the basis for our
         characteristic polynomial coefficients.
+
+        SETUP::
+
+            sage: from mjo.eja.eja_algebra import random_eja
+
+        TESTS:
+
+        Ensure that this hacky method succeeds for every algebra that we
+        know how to construct::
+
+            sage: set_random_seed()
+            sage: J = random_eja()
+            sage: J._a_regular_element().is_regular()
+            True
+
         """
         gs = self.gens()
         z = self.sum( (i+1)*gs[i] for i in range(len(gs)) )
@@ -218,19 +247,16 @@ class FiniteDimensionalEuclideanJordanAlgebra(FiniteDimensionalAlgebra):
     @cached_method
     def characteristic_polynomial(self):
         """
-
-        .. WARNING::
-
-            This implementation doesn't guarantee that the polynomial
-            denominator in the coefficients is not identically zero, so
-            theoretically it could crash. The way that this is handled
-            in e.g. Faraut and Koranyi is to use a basis that guarantees
-            the denominator is non-zero. But, doing so requires knowledge
-            of at least one regular element, and we don't even know how
-            to do that. The trade-off is that, if we use the standard basis,
-            the resulting polynomial will accept the "usual" coordinates. In
-            other words, we don't have to do a change of basis before e.g.
-            computing the trace or determinant.
+        Return a characteristic polynomial that works for all elements
+        of this algebra.
+
+        The resulting polynomial has `n+1` variables, where `n` is the
+        dimension of this algebra. The first `n` variables correspond to
+        the coordinates of an algebra element: when evaluated at the
+        coordinates of an algebra element with respect to a certain
+        basis, the result is a univariate polynomial (in the one
+        remaining variable ``t``), namely the characteristic polynomial
+        of that element.
 
         SETUP::