eja: update the DESIGN and TODO documents.

diff --git a/mjo/eja/DESIGN b/mjo/eja/DESIGN
index 248af84883c27d9e9fa9a4f6e9502b535126d313..467e2ae027d2a20af5576b292576edf21a71b10b 100644 (file)
--- a/mjo/eja/DESIGN
+++ b/mjo/eja/DESIGN
@@ -6,28 +6,64 @@ the documentation. I'm just not sure where they go yet.
 Matrix representations
 ----------------------
 
-Why allow matrix representations for all algebras?
+All algebras have a "matrix representation" of their elements. This is
+the original, ambient representation of the elements as either column
+(n-by-1) or square (n-by-n) matrices. For example, the elements of the
+Jordan spin algebra are column vectors, and the elements of real
+symmetric matrix algebra are... real symmetric matrices.
+
+The CombinatorialFreeModule class actually supports such an
+alternative representation of its generators since it subclasses
+IndexedGenerators. However, using matrices as the index set turns out
+to be ugly: printing the generators, and especially printing an
+algebra element as a sum of said generators comes out wonky, since
+the matrices require more than one line. For example,
+
+    sage: A = matrix(QQ,[[1,2],[3,4]])
+    sage: B = matrix(QQ,[[5,6],[7,8]])
+    sage: A.set_immutable()
+    sage: B.set_immutable()
+    sage: M = CombinatorialFreeModule(QQ,[A,B],bracket=False,prefix="")
+    sage: 2*M(A) + 3*M(B)
+    2*[1 2]
+    [3 4] + 3*[5 6]
+    [7 8]
+
+And things only get worse if you leave the prefix in there to
+distinguish between e.g. the super- and sub-algebra elements
+corresponding to the same matrix. Thus, we store out own copy
+of the matrix generators, and have our own set of methods for
+accessing them.
+
+Why allow matrix representations for all algebras, rather than just
+the matrix algebras?
 
 1. We already have a to_vector() operation that turns an algebra
-element into a vector whose coordinates live in the algebra's
-base_ring(). Adding a to_matrix() operation is a natural
-generalization of that.
+   element into a vector whose coordinates live in the algebra's
+   base_ring(). Adding a to_matrix() operation is a natural
+   generalization of that.
+
+2. Having access to the ambient coordinates in a general way is useful
+   when converting between other coordinate systems. If we have two
+   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.
 
-2. 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...
+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...
 
 
 Basis normalization
 -------------------
-For performance reasons, we need a class (RationalBasis...) that
-orthonormalizes its own basis. We *could* insist that the user do
-this, of course, but the reason we don't want him to is because we
-need to know how to undo the process. If we run Gram-Schmidt on the
-basis matrix ourselves, then we can save the matrix that undoes the
-process. And by undoing the process, we can get to a basis where
-computations are fast again.
+For performance reasons, we prefer the algebra constructors to
+orthonormalize their own bases. 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
+computations in the original basis (like the "characteristic
+polynomial of"), which can be much faster when the original basis
+contains only rational entries.

diff --git a/mjo/eja/TODO b/mjo/eja/TODO
index 08b8e81b22e8b5fde0a368e11840267edab4d250..b298e6914da8a7ec8d21483b73606b12c8511576 100644 (file)
--- a/mjo/eja/TODO
+++ b/mjo/eja/TODO
@@ -21,8 +21,5 @@ sage: a0 = (1/4)*X[4]**2*X[6]**2 - (1/2)*X[2]*X[5]*X[6]**2 - (1/2)*X[3]*X[4]*X[6
 6. The main EJA element constructor is happy to convert between
    e.g. HadamardEJA(3) and JordanSpinEJA(3).
 
-7. Figure out if CombinatorialFreeModule's use of IndexedGenerators
-   can be used to replace the matrix_basis().
-
-9. Add back the check_field=False and check_axioms=False parameters
+8. Add back the check_field=False and check_axioms=False parameters
    for the EJAs we've constructed ourselves.