X-Git-Url: http://gitweb.michael.orlitzky.com/?p=sage.d.git;a=blobdiff_plain;f=mjo%2Feja%2FDESIGN;h=3a0b37ad382bf25ae70e0a94b81dcfebba426ca5;hp=35f3858fa8f863f06aa7580edb453b97d56df624;hb=HEAD;hpb=1a24108744e7861090d91d766b75f0f5cdeb868b

diff --git a/mjo/eja/DESIGN b/mjo/eja/DESIGN
index 35f3858..3a0b37a 100644
--- a/mjo/eja/DESIGN
+++ b/mjo/eja/DESIGN
@@ -48,19 +48,53 @@ the matrix algebras?
    subalgebras B and C of A, we can use to_matrix() to go from, say,
    C -> A -> B rather than having to convert from C to B directly.
 
-3. When constructing a Cartesian product algebra, we don't know a
-   priori whether or not the result will have matrix-algebra
-   factors. We can figure it out at runtime, but it would be nice if
-   DirectSumEJA always returned the same class. Maybe more
-   importantly, if a Cartesian product has one matrix and one
-   non-matrix factor, then what would its own matrix representation
-   look like? We want to delegate to the factors...
 
+Fielding questions
+------------------
+
+All Euclidean Jordan algebras are over the real scalar field. This
+presents a problem: in SageMath, the matrix and vector classes don't
+support scalar fields that are different than their entries. And three
+of the simple families of Euclidean Jordan algebras are matrices with
+non-real entries: the Hermitian comples, quaternion, and octonion
+algebras.
+
+At least in the complex and quaternion case, we can "embed" the
+complex numbers and quaternions into the space of 2-by-2 or 4-by-4
+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.
+
+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)
+
+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
 -------------------
-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
@@ -75,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.