Implementing arithmetic operations in Sage

Why would this addition be "mathematically reasonable"? This is related with the notion of a coercion.

Def:

Let $P_1, P_2, P_3$ be parents.

1. A coercion $\phi$ from $P_1$ to $P_2$ is a morphism in the meet $\mathcal C$ of the categories of $P_1$ and $P_2$:

      $\phi\in \mathrm{Hom}_{\mathcal C}(P_1,P_2)$

2. There is at most one coercion from one parent to another, and if it exists, then it coincides with conversion.

3. The identity morphism is a coercion.

4. If $\phi$ is a coercion from $P_1$ to $P_2$ and $\psi$ is a coercion from $P_2$ to $P_3$, then $\psi\circ\phi$ is a (the!) coercion from $P_1$ to $P_3$

Coercions will implicitly be used in arithmetic operations!

Warning/Example:

If $P_1$ is an additive group and $P_2$ is a ring, and $P_1$ coerces into $P_2$ by a morphism in the category of additive groups, then this coercion will also be used to multiply elements of $P_1$ with elements of $P_2$ (the result lives in $P_2$)!

By now, Sage knows that there is a conversion from Sage matrices into our matrix space, but it doesn't know that it is a coercion:

In contrast, Sage knows that the base ring of MS coerces into MS. This is automatically  done for any parent that is initialised in the category of algebras over a base ring: We see the category framework at work.

Hence, we can already add an integer to a square matrix: The integer is implicitly converted into a diagonal matrix.

In order to make Sage aware of a coercion, one can implement a _coerce_map_from_() method. If it returns True, then an existing conversion is used as coercion. If it returns a map, then this map is used for coercion.

Now, Sage detects coercions from "usual" matrix spaces into "our" matrix space.

3. Pushout construction: Automatic creation of new parents (a teaser)

The material of this section is treated in more detail in the thematic tutorial on "coercions and categories".

Many parents in Sage can tell how they are constructed:

Here, we see a so-called construction functor. This is a covariant functor $\mathcal F:\mathcal C_1\to \mathcal C_2$, so that applying $\mathcal F$ to any coercion map $\phi\in\mathrm{Hom}_{\mathcal C_1}(P,Q)$ yields a coercion map from $\mathcal F(P)$ to $\mathcal F(Q)$. Examples include:

• the construction of a matrix space
• the construction of a polynomial ring
• the construction of a fraction field
• the construction of the algebraic closure.

Often, there is a coercion from $R$ to $\mathcal F(R)$, for any object $R$ of $\mathcal C_1$. Here is an exception of this rule:

Every construction functor has a  "rank":

If two parents $P_1$, $P_2$ are obtained from a common "ancestor" by two sequences of construction functors, then Sage will try to "shuffle" the two construction sequences, applying first a functor with lower rank. The result is called the pushout of $P_1$ and $P_2$, and is a reasonable candidate for performing arithmetic operations involving elements from both $P_1$  and $P_2$:

When two different functors of the same rank clash when shuffling, Sage will raise an error, unless it is asserted that one can apply the functors in any order, or Sage is told how to merge the two functors into one.

Here, we create a new matrix construction functor, imposing the rule that Sage's matrix functors will henceforth merge into our matrix functors:

Now, if Sage can not find a coercion from one parent into another, then it constructs a pushout and coerces into it:

4. Actions

"Act-on" and "acted-upon" actions

One way of implementing an action of anything on an element is: Implement a method _acted_upon_ of the element.

cpdef _acted_upon_(self, x, bint self_on_left):
    """
    Use this method to implement self acted on by x.

    Return None or raise a CoercionException if no
    such action is defined here.
    """
    return None

Similarly, an action of the element on anything can be defined by a method _act_on_ of the element.

We implement a left action of a permutation group on our matrices, by permuting rows.

Refresh our matrix space definition, and let permutations act:

*@#/}!!!

Someone has killed Sage's category framework for permutations, by overloading __mul__! You should not do that!

def __mul__(self, rp):
    """
    TESTS::

        sage: p213 = Permutation([2,1,3])
        sage: p312 = Permutation([3,1,2])
        sage: PermutationOptions(mult='l2r')
        sage: p213*p312
        [1, 3, 2]
        sage: PermutationOptions(mult='r2l')
        sage: p213*p312
        [3, 2, 1]
        sage: PermutationOptions(mult='l2r')
    """
    if self.parent().global_options['mult'] == 'l2r':
        return self._left_to_right_multiply_on_right(rp)
    else:
        return self._left_to_right_multiply_on_left(rp)