3.4 The Sage Rules and Conventions for Coercion and Arithmetic

Note: August 2008: Much of this material is out of date. We are working on a revised version.

Let and be Sage parent structures, e.g., groups, rings, point sets, etc.

OBJECT COERCION _coerce_: Suppose a _coerce_ map $R \to S$ is defined. This is a method of , so it is called using the notation S._coerce_(x), where is a parent of . It's signature is
```
    def _coerce_(self, x):
       ....
```
Then:
1. Either R.category() must be a subcategory of S.category() or conversely.
2. The set-theoretic map $R \to S$ defined by _coerce_ must define a morphism in the bigger category; in particular, the map must be defined on all of . It does not have to be injective. For example, $\mathbf{Z}$ is in the category of rings and $\mathbf{F}_7$ is in the category of fields, and the reduction $\mathbf{Z}\to\mathbf{F}_7$ is a morphism in the category of rings (not fields).
3. If _coerce_ is defined in both direction, i.e., $R \to S$ and $S \to R$ , then the composition in both directions must be the identity maps. (In particular, this allows for arithmetic when coercion in both ways is defined, in which case the parent is the left-hand operand.) Moreover, if the categories of and are different, the coerce morphism is only defined from the object of the bigger category to the object of the smaller category (this is a fairly arbitrary choice, but we have to make it for clarity and consistency-we go to the object that has more structure). E.g., there is a canonical coercion $\mathbf{Z}/7\mathbf{Z}\to \mathbf{F}_7$ , but not conversely.
4. (Reflexitivity) If R is S is True, then _coerce_ must be the identity map. Here, by R is S being True, we meant that and are identical Python objects.
5. (Transitivity) If coercion from to is defined and coercion from to is defined, then coercion from to must also be defined, and must agree with the composition of the coercion from to with the one from to , i.e., T._coerce_(S._coerce_(x)) == T._coerce_() must be True. (When you implement a new ring, this means you should look at what rings coerce to the rings that coerce to your ring, and make sure they also coerce to your ring.)
6. If R._coerce_(x) is defined, then R(x) (i.e., R.__call__(x)) must return the same thing, i.e., R.__call__(x) == R._coerce_(x) must be True. (We do not require that the same Python object is returned, just an equal object.)
7. Convention: _coerce_ should send generators to generators when this makes sense. This is only a convention, and can be violated when it isn't sensible, e.g., the map $\mathbf{Q}\hookrightarrow \mathbf{C}$ should be defined, but should not send to !.
In implementing _coerce_, we are making a fixed choice of identifications and inclusions throughout Sage that follow the above rules. E.g., embeddings of finite fields via Conway polynomials, or inclusions of extensions of number fields, fit into this structure, as does the inclusion $\mathbf{Q}\hookrightarrow \mathbf{C}$ and the surjection $\mathbf{Z} \to \mathbf{Z}/n\mathbf{Z}$ . The function _coerce_ does not have to be ``canonical'' in a precisely defined mathematical sense.
OBJECT CREATION __call__: If you write , then the __call__ method of is called. It should make an object of from , if at all possible. __call__ is never called implicitly by binary operators. If already has as its parent, then __call__ must return a new copy of , unless is immutable (this is to agree with standard Python conventions). For example, if $x \in \mathbf{Z}/n\mathbf{Z}$ , then ZZ.__call__(x) is defined but ZZ.__coerce__(x) is not.
ARITHMETIC __add__, __mul__, ...:: When doing a binary operation, if the parents are not identical (in the sense of is ), determine if precisely one _coerce_ map is defined; if so, apply it and do the arithmetic operation. If both are defined, the parents are canonically isomorphic, so use the left one. If neither are defined, raise a TypeError. (Whether or not there is a coerce map between objects should be cached for efficiency.)
PARENT OBJECT __cmp__: R == S by definition means that _coerce_ is defined in both directions. Roughly speaking this means that and are identical or canonically isomorphic, though there could be some exceptions to this. Note that both and must be in the same category in order to be considered equal, since there are never canonical coercion maps in both directions when the categories are different.
ELEMENT __cmp__: If the parents aren't identical, test if precisely one _coerce_ map is defined -- if so, return __cmp__ after applying the coerce. If both coercions are defined, compute both __cmp__'s (in both and ). Return the value if they give the same results. Otherwise return (the convention in Python is that __cmp__ never raises an exception). If no _coerce_ is defined return (i.e., not equal).
IN __contains__: x in R should be true if and only if R._coerce_(x) would not raise a TypeError.

See About this document... for information on suggesting changes.