mjo/eja/DESIGN

   1 Overview
   2 --------
   3 This is a collection of design notes that should eventually wind up in
   4 the documentation. I'm just not sure where they go yet.
   5
   6 Matrix representations
   7 ----------------------
   8
   9 All algebras have a "matrix representation" of their elements. This is
  10 the original, ambient representation of the elements as either column
  11 (n-by-1) or square (n-by-n) matrices. For example, the elements of the
  12 Jordan spin algebra are column vectors, and the elements of real
  13 symmetric matrix algebra are... real symmetric matrices.
  14
  15 The CombinatorialFreeModule class actually supports such an
  16 alternative representation of its generators since it subclasses
  17 IndexedGenerators. However, using matrices as the index set turns out
  18 to be ugly: printing the generators, and especially printing an
  19 algebra element as a sum of said generators comes out wonky, since
  20 the matrices require more than one line. For example,
  21
  22     sage: A = matrix(QQ,[[1,2],[3,4]])
  23     sage: B = matrix(QQ,[[5,6],[7,8]])
  24     sage: A.set_immutable()
  25     sage: B.set_immutable()
  26     sage: M = CombinatorialFreeModule(QQ,[A,B],bracket=False,prefix="")
  27     sage: 2*M(A) + 3*M(B)
  28     2*[1 2]
  29     [3 4] + 3*[5 6]
  30     [7 8]
  31
  32 And things only get worse if you leave the prefix in there to
  33 distinguish between e.g. the super- and sub-algebra elements
  34 corresponding to the same matrix. Thus, we store out own copy
  35 of the matrix generators, and have our own set of methods for
  36 accessing them.
  37
  38 Why allow matrix representations for all algebras, rather than just
  39 the matrix algebras?
  40
  41 1. We already have a to_vector() operation that turns an algebra
  42    element into a vector whose coordinates live in the algebra's
  43    base_ring(). Adding a to_matrix() operation is a natural
  44    generalization of that.
  45
  46 2. Having access to the ambient coordinates in a general way is useful
  47    when converting between other coordinate systems. If we have two
  48    subalgebras B and C of A, we can use to_matrix() to go from, say,
  49    C -> A -> B rather than having to convert from C to B directly.
  50
  51
  52 Fielding questions
  53 ------------------
  54
  55 All Euclidean Jordan algebras are over the real scalar field. This
  56 presents a problem: in SageMath, the matrix and vector classes don't
  57 support scalar fields that are different than their entries. And three
  58 of the simple families of Euclidean Jordan algebras are matrices with
  59 non-real entries: the Hermitian comples, quaternion, and octonion
  60 algebras.
  61
  62 At least in the complex and quaternion case, we can "embed" the
  63 complex numbers and quaternions into the space of 2-by-2 or 4-by-4
  64 matrices. But the octonions are not associative, so they can't be
  65 embedded (via a homomorphism) into any real matrix space. So what
  66 do we do? Write it ourselves, obviously.
  67
  68 The octonion matrix algebra is implemented separately, as a subclass
  69 of CombinatorialFreeModule, to work around that issue. The custom
  70 class supports a scalar field that is different than the entries of
  71 the matrices. However, this means that we actually have FOUR
  72 different types of "matrices" to support:
  73
  74   (1) Sage vectors
  75   (2) Sage matrices
  76   (3) Our custom matrices
  77   (4) Cartesian products of the (1) through (3)
  78
  79 All other Euclidean Jordan algebras could of course be implemented in
  80 the same way as the octonion algebra, but for the sake of the user
  81 interface, we must also support at least the usual SageMath vectors
  82 and matrices.
  83
  84 Note: this has one less-than-obvious consequence: we have to assume
  85 that the user has supplied an entirely-correct basis (with entries in
  86 the correct structure). We generally cannot mess witht the entries of
  87 his basis, or use them to figure out what (for example) the ambient
  88 scalar ring is. None of these are insurmountable obstacles; we just
  89 have to be a little careful distinguishing between what's inside the
  90 algebra elements and what's outside them.
  91
  92 Basis normalization
  93 -------------------
  94 For performance reasons, we prefer the algebra constructors to
  95 orthonormalize their own bases. We _could_ ask the user to do that,
  96 but there's a good reason to do it ourselves: if _we_ run
  97 Gram-Schmidt, then we can compute/store the matrix that undoes the
  98 process. Undoing the change-of-coordinates allows us to perform some
  99 computations in the original basis (like the "characteristic
 100 polynomial of"), which can be much faster when the original basis
 101 contains only rational entries.
 102
 103 Debugging
 104 ---------
 105 There are several places in the code where we set check_field=False
 106 and check_axioms=False because the theory guarantees that they will be
 107 satisfied. Well, you know what they say about theory and practice. The
 108 first thing you should do when a problem is discovered it replace all
 109 of those with check_field=True and check_axioms=True, and then re-run
 110 the test suite.