README: rewrite it, it was rather out-of-date

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

diff --git a/mjo/eja/DESIGN b/mjo/eja/DESIGN
index 7607b1ceffeddabb19687a9da54e362b07c9d5f3..3a0b37ad382bf25ae70e0a94b81dcfebba426ca5 100644 (file)
--- a/mjo/eja/DESIGN
+++ b/mjo/eja/DESIGN
@@ -65,26 +65,36 @@ 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
+the correct structure). We generally cannot mess witht the entries of
+his basis, or use them to figure out what (for example) the ambient
+scalar ring is. None of these are insurmountable obstacles; we just
+have to be a little careful distinguishing between what's inside the
+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


@@ -99,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.