eja: update the design document.

diff --git a/mjo/eja/DESIGN b/mjo/eja/DESIGN
index 35f3858fa8f863f06aa7580edb453b97d56df624..7607b1ceffeddabb19687a9da54e362b07c9d5f3 100644 (file)
--- a/mjo/eja/DESIGN
+++ b/mjo/eja/DESIGN
@@ -48,14 +48,38 @@ 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.
+
+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:
+
+  (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.
 
 Basis normalization
 -------------------