Preliminaries

What is coercion all about?

The primary goal of the coercion is to be able to transparently do arithmetic, comparisons, etc. between elements of distinct sets.

As a concrete example, when one writes 1 + 1/2 one wants to perform arithmetic on the operands as rational numbers, despite the left being an integer. This makes sense given the obvious and natural inclusion of the integers into the rational numbers. The goal of the coercion system is to facilitate this (and more complicated arithmetic) without having to explicitly map everything over into the same domain, and at the same time being strict enough to not resolve ambiguity or accept nonsense. Here are some examples

sage: 1 + 1/2
3/2
sage: R.<x,y> = ZZ[]
sage: R
Multivariate Polynomial Ring in x, y over Integer Ring
sage: parent(x)
Multivariate Polynomial Ring in x, y over Integer Ring
sage: parent(1/3)
Rational Field
sage: x+1/3
x + 1/3
sage: parent(x+1/3)
Multivariate Polynomial Ring in x, y over Rational Field
Assume we want to do $a + b$ with $a \in R$ and $b \in S$

sage: GF(5)(1) + CC(I)
Traceback (most recent call last):
...
TypeError: unsupported operand parent(s) for '+': 'Finite Field of size 5' and 'Complex Field with 53 bits of precision'

Parents and Elements

Parents objects in concrete categories, and Elements are their members. Parents are first-class objects. Most things Sage either are parents or have a parent. Whenever one sees the word Parent one can think Set. Here are some examples:

sage: parent(1)
Integer Ring
sage: parent(1) is ZZ
True
sage: ZZ
Integer Ring
sage: parent(1.50000000000000000000000000000000000)
Real Field with 123 bits of precision
sage: parent(x)
Symbolic Ring
sage: x^sin(x)
x^sin(x)
sage: R.<t> = Qp(5)[]
sage: f = t^3-5; f
(1 + O(5^20))*t^3 + (4*5 + 4*5^2 + 4*5^3 + 4*5^4 + 4*5^5 + 4*5^6 + 4*5^7 + 4*5^8 + 4*5^9 + 4*5^10 + 4*5^11 + 4*5^12 + 4*5^13 + 4*5^14 + 4*5^15 + 4*5^16 + 4*5^17 + 4*5^18 + 4*5^19 + 4*5^20 + O(5^21))
sage: parent(f)
Univariate Polynomial Ring in t over 5-adic Field with capped relative precision 20
sage: f = EllipticCurve('37a').lseries().taylor_series(10); f
0.997997869801216 + 0.00140712894524925*z - 0.000498127610960097*z^2 + 0.000118835596665956*z^3 - 0.0000215906522442707*z^4 + (3.20363155418419e-6)*z^5 + O(z^6)
sage: parent(f)
Power Series Ring in z over Complex Field with 53 bits of precision

There is an important distinction between Parents and types

sage: a = GF(5).random_element()
sage: b = GF(7).random_element()
sage: type(a)
<type 'sage.rings.integer_mod.IntegerMod_int'>
sage: type(b)
<type 'sage.rings.integer_mod.IntegerMod_int'>
sage: type(a) == type(b)
True
sage: parent(a)
Finite Field of size 5
sage: parent(a) == parent(b)
False

However, non-sage objects don't really have parents, but we still want to be able to reason with them, so their type is used instead.

sage: a = int(10)
sage: parent(a)
<type 'int'>

In fact, under the hood, a special parent "The set of all Python objects of type T" is used in these cases.

Note that parents are not always as tight as possible.

sage: parent(1/2)
Rational Field
sage: parent(2/1)
Rational Field

Maps between Parents

Many parents come with maps to and from other parents.

Sage makes a distinction between being able to convert between various parents, and coerce between them. Conversion is explicit and tries to make sense of an object in the target domain if at all possible. It is invoked by calling

sage: ZZ(5)
5
sage: ZZ(10/5)
2
sage: QQ(10)
10
sage: parent(QQ(10))
Rational Field
sage: a = GF(5)(2); a
2
sage: parent(a)
Finite Field of size 5
sage: parent(ZZ(a))
Integer Ring

Conversions need not be canonical (they may for example involve a choice of lift) or even make sense mathematically (e.g. constructions of some kind).

sage: ZZ("123")
123
sage: ZZ['x']([4,3,2,1])
x^3 + 2*x^2 + 3*x + 4
sage: a = Qp(5, 10)(1/3); a
2 + 3*5 + 5^2 + 3*5^3 + 5^4 + 3*5^5 + 5^6 + 3*5^7 + 5^8 + 3*5^9 + O(5^10)
sage: ZZ(a)
6510417

On the other hand, Sage has the notion of a coercion which is a canonical morphism (occasionally up to a conventional choice made by developers) between parents. A coercion from one parent to another must be defined on the whole domain, and always succeeds. As it may be invoked implicitly, is should be obvious and natural (in both the mathematically rigorous and colloquial sense of the word). Up to inescapable rounding issues that arise with inexact representations, these coercion morphisms should all commute.

They is can be discovered via the has_coerce_map_from method, and if needed explicitly invoked with the coerce method.

sage: QQ.has_coerce_map_from(ZZ)
True
sage: QQ.has_coerce_map_from(RR)
False
sage: ZZ['x'].has_coerce_map_from(QQ)
False
sage: ZZ['x'].has_coerce_map_from(ZZ)
True
sage: ZZ['x'].coerce(5)
5
sage: ZZ['x'].coerce(5).parent()
Univariate Polynomial Ring in x over Integer Ring
sage: ZZ['x'].coerce(5/1)
Traceback (most recent call last):
...
TypeError: no cannonical coercion from Rational Field to Univariate Polynomial Ring in x over Integer Ring

Basic Rules

Suppose we want to add two element, a and b, whose parents are R and S respectively. When we type a+b then

  1. If R is S, call a._add_(b)

  2. If there is a coercion \phi: S \rightarrow R, call a._add_(\phi(b))

  3. If there is a coercion \phi: R \rightarrow S, call \phi(a)._add_(b)

  4. Look for T such that there is a coercion \phi_S: S \rightarrow Z and \phi_R: R \rightarrow Z, call \phi(a)._add_(\phi(b))

sage: parent(1 + 1/2)
Rational Field
sage: cm = sage.structure.element.get_coercion_model()
sage: cm.bin_op(77, 9, gcd)
1
sage: cm.explain(ZZ, QQ)
Coercion on left operand via
    Natural morphism:
      From: Integer Ring
      To:   Rational Field
Arithmetic performed after coercions.
Result lives in Rational Field
Rational Field
sage: cm.explain(ZZ['x','y'], QQ['x'])
Coercion on left operand via
    Call morphism:
      From: Multivariate Polynomial Ring in x, y over Integer Ring
      To:   Multivariate Polynomial Ring in x, y over Rational Field
Coercion on right operand via
    Call morphism:
      From: Univariate Polynomial Ring in x over Rational Field
      To:   Multivariate Polynomial Ring in x, y over Rational Field
Arithmetic performed after coercions.
Result lives in Multivariate Polynomial Ring in x, y over Rational Field
Multivariate Polynomial Ring in x, y over Rational Field

There are also actions.

sage: cm.explain(ZZ['x'], ZZ, operator.mul)
Action discovered.
    Right scalar multiplication by Integer Ring on Univariate Polynomial Ring in x over Integer Ring
Result lives in Univariate Polynomial Ring in x over Integer Ring
Univariate Polynomial Ring in x over Integer Ring

sage: cm.explain(ZZ['x'], ZZ, operator.div)
Action discovered.
    Right inverse action by Rational Field on Univariate Polynomial Ring in x over Integer Ring
    with precomposition on right by Natural morphism:
      From: Integer Ring
      To:   Rational Field
Result lives in Univariate Polynomial Ring in x over Rational Field
Univariate Polynomial Ring in x over Rational Field

sage: f = QQ.coerce_map_from(ZZ)
sage: f(3).parent()
Rational Field
sage: QQ.coerce_map_from(int)
Native morphism:
  From: Set of Python objects of type 'int'
  To:   Rational Field
sage: QQ.has_coerce_map_from(RR)
False
sage: QQ['x'].get_action(QQ)
Right scalar multiplication by Rational Field on Univariate Polynomial Ring in x over Rational Field
sage: (QQ^2).get_action(QQ)
Right scalar multiplication by Rational Field on Vector space of dimension 2 over Rational Field
sage: QQ['x'].get_action(RR)
Right scalar multiplication by Real Field with 53 bits of precision on Univariate Polynomial Ring in x over Rational Field

How to Implement

Special methods to implement:

Parents may also call self._populate_coercion_lists_ method in their __init__ functions to pass any callable for use instead of _element_constructor_, provide a list of Parents with coercions to self (as an alternative to implementing _coerce_map_from_), provide special construction methods (like _integer_ for ZZ), etc. There is extensive documentation in the docstring of that method.

What is provided

Discovering new parents

New parents are discovered using a heuristic algorithm in sage/category/pushout.py.

TODO

sage: CC.construction()
(AlgebraicClosureFunctor, Real Field with 53 bits of precision)
sage: RR.construction()
(CompletionFunctor, Rational Field)
sage: Qp(5).construction()
(CompletionFunctor, Rational Field)
sage: c, R = RR.construction()
sage: QQ.completion(5, 100)
5-adic Field with capped relative precision 100
sage: a = CC.construction()[0]
sage: a.commutes(c)
False
sage: RR == c(QQ)
True
sage: QQ.construction()
(FractionField, Integer Ring)
sage: ZZ.construction()