eja: update the DESIGN doc.

[sage.d.git] / mjo / eja / DESIGN

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.
 
-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)
 
-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
@@ -91,8 +93,8 @@ algebra elements and what's outside them.
 
 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
@@ -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
-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.