eja: update the DESIGN doc.

diff --git a/mjo/eja/DESIGN b/mjo/eja/DESIGN
index 75302ca0f9ba4323ac634834f4be816aa8866010..3a0b37ad382bf25ae70e0a94b81dcfebba426ca5 100644 (file)
--- a/mjo/eja/DESIGN
+++ b/mjo/eja/DESIGN
@@ -65,21 +65,23 @@ matrices. But the octonions are not associative, so they can't be
 embedded (via a homomorphism) into any real matrix space. So what
 do we do? Write it ourselves, obviously.
 
 embedded (via a homomorphism) into any real matrix space. So what
 do we do? Write it ourselves, obviously.
 

-The octonion matrix algebra is implemented separately, as a subclass
-of CombinatorialFreeModule, to work around that issue. The custom
-class supports a scalar field that is different than the entries of
-the matrices. However, this means that we actually have FOUR
-different types of "matrices" to support:
+In contrast to the algebra of real symmetric matrices, the complex,
+quaternion, and octonion matrix algebras are implemented separately,
+as a subclasses of CombinatorialFreeModule, to work around that
+issue. The custom class supports a scalar field that is different than
+the entries of the matrices. However, this means that we actually have
+FOUR different types of "matrices" to support:

 
   (1) Sage vectors
   (2) Sage matrices
   (3) Our custom matrices
   (4) Cartesian products of the (1) through (3)
 
 
   (1) Sage vectors
   (2) Sage matrices
   (3) Our custom matrices
   (4) Cartesian products of the (1) through (3)
 

-All other Euclidean Jordan algebras could of course be implemented in
-the same way as the octonion algebra, but for the sake of the user
-interface, we must also support at least the usual SageMath vectors
-and matrices.
+The real symmetric matrices could of course be implemented in the same
+manner as the others; but for the sake of the user interface, we must
+also support at least the usual SageMath vectors and matrices. Having
+the real symmetric matrices actually be (SageMath) matrices ensures
+that we don't accidentally break support for such things.

 
 Note: this has one less-than-obvious consequence: we have to assume
 that the user has supplied an entirely-correct basis (with entries in
 
 Note: this has one less-than-obvious consequence: we have to assume
 that the user has supplied an entirely-correct basis (with entries in


@@ -91,8 +93,8 @@ algebra elements and what's outside them.
 
 Basis normalization
 -------------------
 
 Basis normalization
 -------------------

-For performance reasons, we prefer the algebra constructors to
-orthonormalize their own bases. We _could_ ask the user to do that,
+For performance reasons, we prefer the algebra constructor to
+orthonormalize its own basis. We _could_ ask the user to do that,

 but there's a good reason to do it ourselves: if _we_ run
 Gram-Schmidt, then we can compute/store the matrix that undoes the
 process. Undoing the change-of-coordinates allows us to perform some
 but there's a good reason to do it ourselves: if _we_ run
 Gram-Schmidt, then we can compute/store the matrix that undoes the
 process. Undoing the change-of-coordinates allows us to perform some


@@ -107,4 +109,6 @@ and check_axioms=False because the theory guarantees that they will be
 satisfied. Well, you know what they say about theory and practice. The
 first thing you should do when a problem is discovered it replace all
 of those with check_field=True and check_axioms=True, and then re-run
 satisfied. Well, you know what they say about theory and practice. The
 first thing you should do when a problem is discovered it replace all
 of those with check_field=True and check_axioms=True, and then re-run

-the test suite.
+the test suite. The Cartesian product class bypasses its superclass
+constructor, so any extra axiom/field checks on product algebras must
+be inserted at debug-time.