Coercion#

How to Implement#

Methods to implement#

Arithmetic on Elements: _add_, _sub_, _mul_, _div_

This is where the binary arithmetic operators should be implemented. Unlike Python’s __add__, both operands are guaranteed to have the same Parent at this point.
Coercion for Parents: _coerce_map_from_

Given two parents R and S, R._coerce_map_from_(S) is called to determine if there is a coercion \(\phi: S \rightarrow R\). Note that the function is called on the potential codomain. To indicate that there is no coercion from S to R (self), return False or None. This is the default behavior. If there is a coercion, return True (in which case a morphism using R._element_constructor_ will be created) or an actual Morphism object with S as the domain and R as the codomain.
Actions for Parents: _get_action_ or _rmul_, _lmul_, _act_on_, _acted_upon_

Suppose one wants R to act on S. Some examples of this could be \(R = \QQ\), \(S = \QQ[x]\) or \(R = {\rm Gal}(S/\QQ)\) where \(S\) is a number field. There are several ways to implement this:
- If \(R\) is the base of \(S\) (as in the first example), simply implement _rmul_ and/or _lmul_ on the Elements of \(S\). In this case r * s gets handled as s._rmul_(r) and s * r as s._lmul_(r). The argument to _rmul_ and _lmul_ are guaranteed to be Elements of the base of \(S\) (with coercion happening beforehand if necessary).
- If \(R\) acts on \(S\), one can define the methods _act_on_ on Elements of \(R\) or _acted_upon_ on Elements of \(S\). In this case r * s gets handled as r._act_on_(s, True) or s._acted_upon_(r, False) and s * r as r._act_on_(s, False) or s._acted_upon_(r, True). There is no constraint on the type or parents of objects passed to these methods; raise a TypeError or ValueError if the wrong kind of object is passed in to indicate the action is not appropriate here.
- If either \(R\) acts on \(S\) or \(S\) acts on \(R\), one may implement R._get_action_ to return an actual Action object to be used. This is how non-multiplicative actions must be implemented, and is the most powerful and complete way to do things.
It should be noted that for the first way to work, elements of \(S\) are required to be ModuleElements. This requirement is likely to be lifted in the future.
Element conversion/construction for Parents: use _element_constructor_ not __call__

The Parent.__call__() method dispatches to _element_constructor_. When someone writes R(x, ...), this is the method that eventually gets called in most cases. See the documentation on the __call__ method below.

Parents may also call the 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. This also allows one to specify a single coercion embedding out of self (whereas the rest of the coercion functions all specify maps into self). There is extensive documentation in the docstring of the _populate_coercion_lists_ method.

Example#

Sometimes a simple example is worth a thousand words. Here is a minimal example of setting up a simple Ring that handles coercion. (It is easy to imagine much more sophisticated and powerful localizations, but that would obscure the main points being made here.)

Sage

sage: from sage.structure.richcmp import richcmp
sage: from sage.structure.element import Element

sage: class MyLocalization(Parent):
....:     def __init__(self, primes):
....:         r"""
....:         Localization of `\ZZ` away from primes.
....:         """
....:         Parent.__init__(self, base=ZZ, category=Rings().Commutative())
....:         self._primes = primes
....:         self._populate_coercion_lists_()
....:
....:     def _repr_(self) -> str:
....:         """
....:         How to print ``self``.
....:         """
....:         return "%s localized at %s" % (self.base(), self._primes)
....:
....:     def _element_constructor_(self, x):
....:         """
....:         Make sure ``x`` is a valid member of ``self``, and return the constructed element.
....:         """
....:         if isinstance(x, MyLocalizationElement):
....:             x = x._value
....:         else:
....:             x = QQ(x)
....:         for p, e in x.denominator().factor():
....:             if p not in self._primes:
....:                 raise ValueError("not integral at %s" % p)
....:         return self.element_class(self, x)
....:
....:     def _an_element_(self):
....:         return self.element_class(self, 6)
....:
....:     def _coerce_map_from_(self, S):
....:         """
....:         The only things that coerce into this ring are:
....:
....:         - the integer ring
....:
....:         - other localizations away from fewer primes
....:         """
....:         if S is ZZ:
....:             return True
....:         if isinstance(S, MyLocalization):
....:             return all(p in self._primes for p in S._primes)

sage: class MyLocalizationElement(Element):
....:
....:     def __init__(self, parent, x):
....:         Element.__init__(self, parent)
....:         self._value = x
....:
....:     # We are just printing out this way to make it easy to see what's going on in the examples.
....:
....:     def _repr_(self) -> str:
....:         return f"LocalElt({self._value})"
....:
....:     # Now define addition, subtraction and multiplication of elements.
....:     # Note that self and right always have the same parent.
....:
....:     def _add_(self, right):
....:         return self.parent()(self._value + right._value)
....:
....:     def _sub_(self, right):
....:         return self.parent()(self._value - right._value)
....:
....:     def _mul_(self, right):
....:         return self.parent()(self._value * right._value)
....:
....:     # The basering was set to ZZ, so c is guaranteed to be in ZZ
....:
....:     def _rmul_(self, c):
....:         return self.parent()(c * self._value)
....:
....:     def _lmul_(self, c):
....:         return self.parent()(self._value * c)
....:
....:     def _richcmp_(self, other, op):
....:         return richcmp(self._value, other._value, op)

sage: MyLocalization.element_class = MyLocalizationElement

Python

>>> from sage.all import *
>>> from sage.structure.richcmp import richcmp
>>> from sage.structure.element import Element

>>> class MyLocalization(Parent):
...     def __init__(self, primes):
...         r"""
...         Localization of `\ZZ` away from primes.
...         """
...         Parent.__init__(self, base=ZZ, category=Rings().Commutative())
...         self._primes = primes
...         self._populate_coercion_lists_()
....:
>>>     def _repr_(self) -> str:
...         """
...         How to print ``self``.
...         """
...         return "%s localized at %s" % (self.base(), self._primes)
....:
>>>     def _element_constructor_(self, x):
...         """
...         Make sure ``x`` is a valid member of ``self``, and return the constructed element.
...         """
...         if isinstance(x, MyLocalizationElement):
...             x = x._value
...         else:
...             x = QQ(x)
...         for p, e in x.denominator().factor():
...             if p not in self._primes:
...                 raise ValueError("not integral at %s" % p)
...         return self.element_class(self, x)
....:
>>>     def _an_element_(self):
...         return self.element_class(self, Integer(6))
....:
>>>     def _coerce_map_from_(self, S):
...         """
...         The only things that coerce into this ring are:
....:
>>>         - the integer ring
....:
>>>         - other localizations away from fewer primes
...         """
...         if S is ZZ:
...             return True
...         if isinstance(S, MyLocalization):
...             return all(p in self._primes for p in S._primes)

>>> class MyLocalizationElement(Element):
....:
>>>     def __init__(self, parent, x):
...         Element.__init__(self, parent)
...         self._value = x
....:
>>>     # We are just printing out this way to make it easy to see what's going on in the examples.
....:
>>>     def _repr_(self) -> str:
...         return f"LocalElt({self._value})"
....:
>>>     # Now define addition, subtraction and multiplication of elements.
...     # Note that self and right always have the same parent.
....:
>>>     def _add_(self, right):
...         return self.parent()(self._value + right._value)
....:
>>>     def _sub_(self, right):
...         return self.parent()(self._value - right._value)
....:
>>>     def _mul_(self, right):
...         return self.parent()(self._value * right._value)
....:
>>>     # The basering was set to ZZ, so c is guaranteed to be in ZZ
....:
>>>     def _rmul_(self, c):
...         return self.parent()(c * self._value)
....:
>>>     def _lmul_(self, c):
...         return self.parent()(self._value * c)
....:
>>>     def _richcmp_(self, other, op):
...         return richcmp(self._value, other._value, op)

>>> MyLocalization.element_class = MyLocalizationElement

That’s all there is to it. Now we can test it out:

Sage

sage: TestSuite(R).run(skip="_test_pickling")
sage: R = MyLocalization([2]); R
Integer Ring localized at [2]
sage: R(1)
LocalElt(1)
sage: R(1/2)
LocalElt(1/2)
sage: R(1/3)
Traceback (most recent call last):
...
ValueError: not integral at 3

sage: R.coerce(1)
LocalElt(1)
sage: R.coerce(1/4)
Traceback (most recent call last):
...
TypeError: no canonical coercion from Rational Field to Integer Ring localized at [2]

sage: R(1/2) + R(3/4)
LocalElt(5/4)
sage: R(1/2) + 5
LocalElt(11/2)
sage: 5 + R(1/2)
LocalElt(11/2)
sage: R(1/2) + 1/7
Traceback (most recent call last):
...
TypeError: unsupported operand parent(s) for +: 'Integer Ring localized at [2]' and 'Rational Field'
sage: R(3/4) * 7
LocalElt(21/4)

sage: cm = sage.structure.element.get_coercion_model()
sage: cm.explain(R, ZZ, operator.add)
Coercion on right operand via
   Coercion map:
     From: Integer Ring
     To:   Integer Ring localized at [2]
Arithmetic performed after coercions.
Result lives in Integer Ring localized at [2]
Integer Ring localized at [2]

sage: cm.explain(R, ZZ, operator.mul)
Coercion on right operand via
    Coercion map:
      From: Integer Ring
      To:   Integer Ring localized at [2]
Arithmetic performed after coercions.
Result lives in Integer Ring localized at [2]
Integer Ring localized at [2]

sage: R6 = MyLocalization([2,3]); R6
Integer Ring localized at [2, 3]
sage: R6(1/3) - R(1/2)
LocalElt(-1/6)
sage: parent(R6(1/3) - R(1/2))
Integer Ring localized at [2, 3]

sage: R.has_coerce_map_from(ZZ)
True
sage: R.coerce_map_from(ZZ)
Coercion map:
 From: Integer Ring
 To:   Integer Ring localized at [2]

sage: R6.coerce_map_from(R)
Coercion map:
 From: Integer Ring localized at [2]
 To:   Integer Ring localized at [2, 3]

sage: R6.coerce(R(1/2))
LocalElt(1/2)

sage: cm.explain(R, R6, operator.mul)
Coercion on left operand via
   Coercion map:
     From: Integer Ring localized at [2]
     To:   Integer Ring localized at [2, 3]
Arithmetic performed after coercions.
Result lives in Integer Ring localized at [2, 3]
Integer Ring localized at [2, 3]

Python

>>> from sage.all import *
>>> TestSuite(R).run(skip="_test_pickling")
>>> R = MyLocalization([Integer(2)]); R
Integer Ring localized at [2]
>>> R(Integer(1))
LocalElt(1)
>>> R(Integer(1)/Integer(2))
LocalElt(1/2)
>>> R(Integer(1)/Integer(3))
Traceback (most recent call last):
...
ValueError: not integral at 3

>>> R.coerce(Integer(1))
LocalElt(1)
>>> R.coerce(Integer(1)/Integer(4))
Traceback (most recent call last):
...
TypeError: no canonical coercion from Rational Field to Integer Ring localized at [2]

>>> R(Integer(1)/Integer(2)) + R(Integer(3)/Integer(4))
LocalElt(5/4)
>>> R(Integer(1)/Integer(2)) + Integer(5)
LocalElt(11/2)
>>> Integer(5) + R(Integer(1)/Integer(2))
LocalElt(11/2)
>>> R(Integer(1)/Integer(2)) + Integer(1)/Integer(7)
Traceback (most recent call last):
...
TypeError: unsupported operand parent(s) for +: 'Integer Ring localized at [2]' and 'Rational Field'
>>> R(Integer(3)/Integer(4)) * Integer(7)
LocalElt(21/4)

>>> cm = sage.structure.element.get_coercion_model()
>>> cm.explain(R, ZZ, operator.add)
Coercion on right operand via
   Coercion map:
     From: Integer Ring
     To:   Integer Ring localized at [2]
Arithmetic performed after coercions.
Result lives in Integer Ring localized at [2]
Integer Ring localized at [2]

>>> cm.explain(R, ZZ, operator.mul)
Coercion on right operand via
    Coercion map:
      From: Integer Ring
      To:   Integer Ring localized at [2]
Arithmetic performed after coercions.
Result lives in Integer Ring localized at [2]
Integer Ring localized at [2]

>>> R6 = MyLocalization([Integer(2),Integer(3)]); R6
Integer Ring localized at [2, 3]
>>> R6(Integer(1)/Integer(3)) - R(Integer(1)/Integer(2))
LocalElt(-1/6)
>>> parent(R6(Integer(1)/Integer(3)) - R(Integer(1)/Integer(2)))
Integer Ring localized at [2, 3]

>>> R.has_coerce_map_from(ZZ)
True
>>> R.coerce_map_from(ZZ)
Coercion map:
 From: Integer Ring
 To:   Integer Ring localized at [2]

>>> R6.coerce_map_from(R)
Coercion map:
 From: Integer Ring localized at [2]
 To:   Integer Ring localized at [2, 3]

>>> R6.coerce(R(Integer(1)/Integer(2)))
LocalElt(1/2)

>>> cm.explain(R, R6, operator.mul)
Coercion on left operand via
   Coercion map:
     From: Integer Ring localized at [2]
     To:   Integer Ring localized at [2, 3]
Arithmetic performed after coercions.
Result lives in Integer Ring localized at [2, 3]
Integer Ring localized at [2, 3]

Provided Methods#

__call__

This provides a consistent interface for element construction. In particular, it makes sure that conversion always gives the same result as coercion, if a coercion exists. (This used to be violated for some Rings in Sage as the code for conversion and coercion got edited separately.) Let R be a Parent and assume the user types R(x), where x has parent X. Roughly speaking, the following occurs:
1. If X is R, return x (*)
2. If there is a coercion \(f: X \rightarrow R\), return \(f(x)\)
3. If there is a coercion \(f: R \rightarrow X\), try to return \({f^{-1}}(x)\)
4. Return R._element_constructor_(x) (**)
Keywords and extra arguments are passed on. The result of all this logic is cached.

(*) Unless there is a “copy” keyword like R(x, copy=False)

(**) Technically, a generic morphism is created from X to R, which may use magic methods like _integer_ or other data provided by _populate_coercion_lists_.
coerce

Coerces elements into self, raising a type error if there is no coercion map.
coerce_map_from, convert_map_from

Returns an actual Morphism object to coerce/convert from another Parent to self. Barring direct construction of elements of R, R.convert_map_from(S) will provide a callable Python object which is the fastest way to convert elements of S to elements of R. From Cython, it can be invoked via the cdef _call_ method.
has_coerce_map_from

Returns True or False depending on whether or not there is a coercion. R.has_coerce_map_from(S) is shorthand for R.coerce_map_from(S) is not None
get_action

This will unwind all the _get_action_, _rmul_, _lmul_, _act_on_, _acted_upon_, ... methods to provide an actual Action object, if one exists.

Discovering new parents#

New parents are discovered using an algorithm in sage/category/pushout.py. The fundamental idea is that most Parents in Sage are constructed from simpler objects via various functors. These are accessed via the construction() method, which returns a (simpler) Parent along with a functor with which one can create self.

Sage

sage: CC.construction()
(AlgebraicClosureFunctor, Real Field with 53 bits of precision)
sage: RR.construction()
(Completion[+Infinity, prec=53], Rational Field)
sage: QQ.construction()
(FractionField, Integer Ring)
sage: ZZ.construction()  # None

sage: Zp(5).construction()
(Completion[5, prec=20], Integer Ring)
sage: QQ.completion(5, 100, {})
5-adic Field with capped relative precision 100
sage: c, R = RR.construction()
sage: a = CC.construction()[0]
sage: a.commutes(c)
False
sage: RR == c(QQ)
True

sage: sage.categories.pushout.construction_tower(Frac(CDF['x']))
[(None,
  Fraction Field of Univariate Polynomial Ring in x over Complex Double Field),
 (FractionField, Univariate Polynomial Ring in x over Complex Double Field),
 (Poly[x], Complex Double Field),
 (AlgebraicClosureFunctor, Real Double Field),
 (Completion[+Infinity, prec=53], Rational Field),
 (FractionField, Integer Ring)]

Python

>>> from sage.all import *
>>> CC.construction()
(AlgebraicClosureFunctor, Real Field with 53 bits of precision)
>>> RR.construction()
(Completion[+Infinity, prec=53], Rational Field)
>>> QQ.construction()
(FractionField, Integer Ring)
>>> ZZ.construction()  # None

>>> Zp(Integer(5)).construction()
(Completion[5, prec=20], Integer Ring)
>>> QQ.completion(Integer(5), Integer(100), {})
5-adic Field with capped relative precision 100
>>> c, R = RR.construction()
>>> a = CC.construction()[Integer(0)]
>>> a.commutes(c)
False
>>> RR == c(QQ)
True

>>> sage.categories.pushout.construction_tower(Frac(CDF['x']))
[(None,
  Fraction Field of Univariate Polynomial Ring in x over Complex Double Field),
 (FractionField, Univariate Polynomial Ring in x over Complex Double Field),
 (Poly[x], Complex Double Field),
 (AlgebraicClosureFunctor, Real Double Field),
 (Completion[+Infinity, prec=53], Rational Field),
 (FractionField, Integer Ring)]

Given Parents R and S, such that there is no coercion either from R to S or from S to R, one can find a common Z with coercions \(R \rightarrow Z\) and \(S \rightarrow Z\) by considering the sequence of construction functors to get from a common ancestor to both R and S. We then use a heuristic algorithm to interleave these constructors in an attempt to arrive at a suitable Z (if one exists). For example:

Sage

sage: ZZ['x'].construction()
(Poly[x], Integer Ring)
sage: QQ.construction()
(FractionField, Integer Ring)
sage: sage.categories.pushout.pushout(ZZ['x'], QQ)
Univariate Polynomial Ring in x over Rational Field
sage: sage.categories.pushout.pushout(ZZ['x'], QQ).construction()
(Poly[x], Rational Field)

Python

>>> from sage.all import *
>>> ZZ['x'].construction()
(Poly[x], Integer Ring)
>>> QQ.construction()
(FractionField, Integer Ring)
>>> sage.categories.pushout.pushout(ZZ['x'], QQ)
Univariate Polynomial Ring in x over Rational Field
>>> sage.categories.pushout.pushout(ZZ['x'], QQ).construction()
(Poly[x], Rational Field)

The common ancestor is \(Z\) and our options for Z are \(\mathrm{Frac}(\ZZ[x])\) or \(\mathrm{Frac}(\ZZ)[x]\). In Sage we choose the later, treating the fraction field functor as binding “more tightly” than the polynomial functor, as most people agree that \(\QQ[x]\) is the more natural choice. The same procedure is applied to more complicated Parents, returning a new Parent if one can be unambiguously determined.

Sage

sage: sage.categories.pushout.pushout(Frac(ZZ['x,y,z']), QQ['z, t'])
Univariate Polynomial Ring in t over Fraction Field of Multivariate Polynomial Ring in x, y, z over Rational Field

Python

>>> from sage.all import *
>>> sage.categories.pushout.pushout(Frac(ZZ['x,y,z']), QQ['z, t'])
Univariate Polynomial Ring in t over Fraction Field of Multivariate Polynomial Ring in x, y, z over Rational Field

Coercion#

Preliminaries#

What is coercion all about?#

Parents and Elements#

Maps between Parents#

Basic Arithmetic Rules#

How to Implement#

Methods to implement#

Example#

Provided Methods#

Discovering new parents#

Modules#

Indices and Tables#