### Navigation

- index
- modules |
- next |
- previous |
- Basic Structures »

# Elements

Elements

AUTHORS:

- David Harvey (2006-10-16): changed CommutativeAlgebraElement to derive from CommutativeRingElement instead of AlgebraElement
- David Harvey (2006-10-29): implementation and documentation of new arithmetic architecture
- William Stein (2006-11): arithmetic architecture – pushing it through to completion.
- Gonzalo Tornaria (2007-06): recursive base extend for coercion – lots of tests
- Robert Bradshaw (2007-2010): arithmetic operators and coercion
- Maarten Derickx (2010-07): added architecture for is_square and sqrt

## The Abstract Element Class Hierarchy

This is the abstract class hierarchy, i.e., these are all abstract base classes.

    SageObject
        Element
            ModuleElement
                RingElement
                    CommutativeRingElement
                        IntegralDomainElement
                            DedekindDomainElement
                                PrincipalIdealDomainElement
                                    EuclideanDomainElement
                        FieldElement
                            FiniteFieldElement
                        CommutativeAlgebraElement
                    AlgebraElement   (note -- can't derive from module, since no multiple inheritance)
                        CommutativeAlgebra ??? (should be removed from element.pxd)
                        Matrix
                    InfinityElement
                        PlusInfinityElement
                        MinusInfinityElement
                AdditiveGroupElement
                Vector

            MonoidElement
                MultiplicativeGroupElement
        ElementWithCachedMethod

## How to Define a New Element Class

Elements typically define a method `_new_c`, e.g.,

    cdef _new_c(self, defining data):
        cdef FreeModuleElement_generic_dense x
        x = PY_NEW(FreeModuleElement_generic_dense)
        x._parent = self._parent
        x._entries = v

that creates a new sibling very quickly from defining data with assumed properties.

Sage has a special system in place for handling arithmetic operations for all Element subclasses. There are various rules that must be followed by both arithmetic implementers and callers.

A quick summary for the impatient:

- To implement addition for any Element class, override def _add_().
- If you want to add x and y, whose parents you know are IDENTICAL, you may call _add_(x, y). This will be the fastest way to guarantee that the correct implementation gets called. Of course you can still always use “x + y”.

Now in more detail. The aims of this system are to provide (1) an efficient calling protocol from both Python and Cython, (2) uniform coercion semantics across Sage, (3) ease of use, (4) readability of code.

We will take addition of RingElements as an example; all other operators and classes are similar. There are four relevant functions.

- def RingElement.__add__

  > This function is called by Python or Pyrex when the binary “+” operator is encountered. It ASSUMES that at least one of its arguments is a RingElement; only a really twisted programmer would violate this condition. It has a fast pathway to deal with the most common case where the arguments have the same parent. Otherwise, it uses the coercion module to work out how to make them have the same parent. After any necessary coercions have been performed, it calls _add_ to dispatch to the correct underlying addition implementation.

  > Note that although this function is declared as def, it doesn’t have the usual overheads associated with python functions (either for the caller or for __add__ itself). This is because python has optimised calling protocols for such special functions.

- def RingElement._add_

  This is the function you should override to implement addition in a python subclass of RingElement.

  Warning

  if you override this in a Cython class, it won’t get called. You should override _add_ instead. It is especially important to keep this in mind whenever you move a class down from Python to Cython.

  The two arguments to this function are guaranteed to have the SAME PARENT. Its return value MUST have the SAME PARENT as its arguments.

  If you want to add two objects from python, and you know that their parents are the same object, you are encouraged to call this function directly, instead of using “x + y”.

  The default implementation of this function is to call _add_, so if no-one has defined a python implementation, the correct Pyrex implementation will get called.

- cpdef RingElement._add_

  This is the function you should override to implement addition in a Pyrex subclass of RingElement.

  The two arguments to this function are guaranteed to have the SAME PARENT. Its return value MUST have the SAME PARENT as its arguments.

  The default implementation of this function is to raise a NotImplementedError, which will happen if no-one has supplied implementations of either _add_.

For speed, there are also inplace version of the arithmetic commands. DD NOT call them directly, they may mutate the object and will be called when and only when it has been determined that the old object will no longer be accessible from the calling function after this operation.

- def RingElement._iadd_

  This is the function you should override to inplace implement addition in a Python subclass of RingElement.

  The two arguments to this function are guaranteed to have the SAME PARENT. Its return value MUST have the SAME PARENT as its arguments.

  The default implementation of this function is to call _add_, so if no-one has defined a Python implementation, the correct Cython implementation will get called.

class `sage.structure.element.``AdditiveGroupElement`

  Bases: `sage.structure.element.ModuleElement`

  Generic element of an additive group.

  `order`()

    Return additive order of element

class `sage.structure.element.``AlgebraElement`

  Bases: `sage.structure.element.RingElement`

  INPUT:

  - `parent` - a SageObject

class `sage.structure.element.``CoercionModel`

  Bases: `object`

  Most basic coercion scheme. If it doesn’t already match, throw an error.

  `bin_op`(x, y, op)
  `canonical_coercion`(x, y)

class `sage.structure.element.``CommutativeAlgebra`

  Bases: `sage.structure.element.AlgebraElement`

  INPUT:

  - `parent` - a SageObject

class `sage.structure.element.``CommutativeAlgebraElement`

  Bases: `sage.structure.element.CommutativeRingElement`

  INPUT:

  - `parent` - a SageObject

class `sage.structure.element.``CommutativeRingElement`

  Bases: `sage.structure.element.RingElement`

  Base class for elements of commutative rings.

  `divides`(x)

    Return True if self divides x.

    EXAMPLES:

        sage: P.<x> = PolynomialRing(QQ)
        sage: x.divides(x^2)
        True
        sage: x.divides(x^2+2)
        False
        sage: (x^2+2).divides(x)
        False
        sage: P.<x> = PolynomialRing(ZZ)
        sage: x.divides(x^2)
        True
        sage: x.divides(x^2+2)
        False
        sage: (x^2+2).divides(x)
        False

    Ticket #5347 has been fixed:

        sage: K = GF(7)
        sage: K(3).divides(1)
        True
        sage: K(3).divides(K(1))
        True

        sage: R = Integers(128)
        sage: R(0).divides(1)
        False
        sage: R(0).divides(0)
        True
        sage: R(0).divides(R(0))
        True
        sage: R(1).divides(0)
        True
        sage: R(121).divides(R(120))
        True
        sage: R(120).divides(R(121))
        Traceback (most recent call last):
        ...
        ZeroDivisionError: reduction modulo right not defined.

    If x has different parent than \(self\), they are first coerced to a common parent if possible. If this coercion fails, it returns a TypeError. This fixes #5759

    ::
      sage: Zmod(2)(0).divides(Zmod(2)(0)) True sage: Zmod(2)(0).divides(Zmod(2)(1)) False sage: Zmod(5)(1).divides(Zmod(2)(1)) Traceback (most recent call last): ... TypeError: no common canonical parent for objects with parents: ‘Ring of integers modulo 5’ and ‘Ring of integers modulo 2’ sage: Zmod(35)(4).divides(Zmod(7)(1)) True sage: Zmod(35)(7).divides(Zmod(7)(1)) False
  `inverse_mod`(I)

    Return an inverse of self modulo the ideal \(I\), if defined, i.e., if \(I\) and self together generate the unit ideal.

  `is_square`(root=False)

    Returns whether or not ring element is a square. If the optional argument root is True, then also returns the square root (or None, if the it is not a square).

    INPUT:

    - `root` - whether or not to also return a square root (default: False)

    OUTPUT:

    - `bool` - whether or not a square
    - `object` - (optional) an actual square root if found, and None otherwise.

    EXAMPLES:

        sage: R.<x> = PolynomialRing(QQ)
        sage: f = 12*(x+1)^2 * (x+3)^2
        sage: f.is_square()
        False
        sage: f.is_square(root=True)
        (False, None)
        sage: h = f/3
        sage: h.is_square()
        True
        sage: h.is_square(root=True)
        (True, 2*x^2 + 8*x + 6)

    This is the is_square implementation for general commutative ring elements. It’s implementation is to raise a NotImplementedError. The function definition is here to show what functionality is expected and provide a general framework.

  `mod`(I)

    Return a representative for self modulo the ideal I (or the ideal generated by the elements of I if I is not an ideal.)

    EXAMPLE: Integers Reduction of 5 modulo an ideal:

        sage: n = 5
        sage: n.mod(3*ZZ)
        2

    Reduction of 5 modulo the ideal generated by 3:

        sage: n.mod(3)
        2

    Reduction of 5 modulo the ideal generated by 15 and 6, which is \((3)\).

        sage: n.mod([15,6])
        2

    EXAMPLE: Univariate polynomials

        sage: R.<x> = PolynomialRing(QQ)
        sage: f = x^3 + x + 1
        sage: f.mod(x + 1)
        -1

    When little is implemented about a given ring, then mod may return simply return \(f\). For example, reduction is not implemented for \(\ZZ[x]\) yet. (TODO!)

    > sage: R.<x> = PolynomialRing(ZZ) sage: f = x^3 + x + 1 sage: f.mod(x + 1) -1

    EXAMPLE: Multivariate polynomials We reduce a polynomial in two variables modulo a polynomial and an ideal:

        sage: R.<x,y,z> = PolynomialRing(QQ, 3)
        sage: (x^2 + y^2 + z^2).mod(x+y+z)
        2*y^2 + 2*y*z + 2*z^2

    Notice above that \(x\) is eliminated. In the next example, both \(y\) and \(z\) are eliminated:

        sage: (x^2 + y^2 + z^2).mod( (x - y, y - z) )
        3*z^2
        sage: f = (x^2 + y^2 + z^2)^2; f
        x^4 + 2*x^2*y^2 + y^4 + 2*x^2*z^2 + 2*y^2*z^2 + z^4
        sage: f.mod( (x - y, y - z) )
        9*z^4

    In this example \(y\) is eliminated:

        sage: (x^2 + y^2 + z^2).mod( (x^3, y - z) )
        x^2 + 2*z^2

  `sqrt`(extend=True, all=False, name=None)

    It computes the square root.

    INPUT:

    - `extend` - Whether to make a ring extension containing a square root if self is not a square (default: True)
    - `all` - Whether to return a list of all square roots or just a square root (default: False)
    - `name` - Required when extend=True and self is not a square. This will be the name of the generator extension.

    OUTPUT:

    - if all=False it returns a square root. (throws an error if extend=False and self is not a square)
    - if all=True it returns a list of all the square roots (could be empty if extend=False and self is not a square)

    ALGORITHM:

    It uses is_square(root=true) for the hard part of the work, the rest is just wrapper code.

    EXAMPLES:

        sage: R.<x> = ZZ[]
        sage: (x^2).sqrt()
        x
        sage: f=x^2-4*x+4; f.sqrt(all=True)
        [x - 2, -x + 2]
        sage: sqrtx=x.sqrt(name="y"); sqrtx
        y
        sage: sqrtx^2
        x
        sage: x.sqrt(all=true,name="y")
        [y, -y]
        sage: x.sqrt(extend=False,all=True)
        []
        sage: x.sqrt()
        Traceback (most recent call last):
        ...
        TypeError: Polynomial is not a square. You must specify the name of the square root when using the default extend = True
        sage: x.sqrt(extend=False)
        Traceback (most recent call last):
        ...
        ValueError: trying to take square root of non-square x with extend = False

    TESTS:

        sage: f = (x+3)^2; f.sqrt()
        x + 3
        sage: f = (x+3)^2; f.sqrt(all=True)
        [x + 3, -x - 3]
        sage: f = (x^2 - x + 3)^2; f.sqrt()
        x^2 - x + 3
        sage: f = (x^2 - x + 3)^6; f.sqrt()
        x^6 - 3*x^5 + 12*x^4 - 19*x^3 + 36*x^2 - 27*x + 27
        sage: g = (R.random_element(15))^2
        sage: g.sqrt()^2 == g
        True

        sage: R.<x> = GF(250037)[]
        sage: f = x^2/(x+1)^2; f.sqrt()
        x/(x + 1)
        sage: f = 9 * x^4 / (x+1)^2; f.sqrt()
        3*x^2/(x + 1)
        sage: f = 9 * x^4 / (x+1)^2; f.sqrt(all=True)
        [3*x^2/(x + 1), 250034*x^2/(x + 1)]

        sage: R.<x> = QQ[]
        sage: a = 2*(x+1)^2 / (2*(x-1)^2); a.sqrt()
        (2*x + 2)/(2*x - 2)
        sage: sqrtx=(1/x).sqrt(name="y"); sqrtx
        y
        sage: sqrtx^2
        1/x
        sage: (1/x).sqrt(all=true,name="y")
        [y, -y]
        sage: (1/x).sqrt(extend=False,all=True)
        []
        sage: (1/(x^2-1)).sqrt()
        Traceback (most recent call last):
        ...
        TypeError: Polynomial is not a square. You must specify the name of the square root when using the default extend = True
        sage: (1/(x^2-3)).sqrt(extend=False)
        Traceback (most recent call last):
        ...
        ValueError: trying to take square root of non-square 1/(x^2 - 3) with extend = False

class `sage.structure.element.``DedekindDomainElement`

  Bases: `sage.structure.element.IntegralDomainElement`

  INPUT:

  - `parent` - a SageObject

class `sage.structure.element.``Element`

  Bases: `sage.structure.sage_object.SageObject`

  Generic element of a structure. All other types of elements (RingElement, ModuleElement, etc) derive from this type.

  Subtypes must either call __init__() to set _parent, or may set _parent themselves if that would be more efficient.

  `N`(prec=None, digits=None, algorithm=None)

    Return a numerical approximation of x with at least prec bits of precision.

    EXAMPLES:

        sage: (2/3).n()
        0.666666666666667
        sage: pi.n(digits=10)
        3.141592654
        sage: pi.n(prec=20)   # 20 bits
        3.1416

    TESTS:

    Check that trac ticket #14778 is fixed:

        sage: (0).n(algorithm='foo')
        0.000000000000000

  `base_extend`(R)
  `base_ring`()

    Returns the base ring of this element’s parent (if that makes sense).

  `category`()
  `is_zero`()

    Return True if self equals self.parent()(0). The default implementation is to fall back to ‘not self.__nonzero__’.

    Warning

    Do not re-implement this method in your subclass but implement __nonzero__ instead.

  `n`(prec=None, digits=None, algorithm=None)

    Return a numerical approximation of x with at least prec bits of precision.

    EXAMPLES:

        sage: (2/3).n()
        0.666666666666667
        sage: pi.n(digits=10)
        3.141592654
        sage: pi.n(prec=20)   # 20 bits
        3.1416

    TESTS:

    Check that trac ticket #14778 is fixed:

        sage: (0).n(algorithm='foo')
        0.000000000000000

  `numerical_approx`(prec=None, digits=None, algorithm=None)

    Return a numerical approximation of x with at least prec bits of precision.

    EXAMPLES:

        sage: (2/3).n()
        0.666666666666667
        sage: pi.n(digits=10)
        3.141592654
        sage: pi.n(prec=20)   # 20 bits
        3.1416

    TESTS:

    Check that trac ticket #14778 is fixed:

        sage: (0).n(algorithm='foo')
        0.000000000000000

  `parent`(x=None)

    Returns parent of this element; or, if the optional argument x is supplied, the result of coercing x into the parent of this element.

  `subs`(in_dict=None, **kwds)

    Substitutes given generators with given values while not touching other generators. This is a generic wrapper around __call__. The syntax is meant to be compatible with the corresponding method for symbolic expressions.

    INPUT:

    - `in_dict` - (optional) dictionary of inputs
    - `**kwds` - named parameters

    OUTPUT:

    - new object if substitution is possible, otherwise self.

    EXAMPLES:

        sage: x, y = PolynomialRing(ZZ,2,'xy').gens()
        sage: f = x^2 + y + x^2*y^2 + 5
        sage: f((5,y))
        25*y^2 + y + 30
        sage: f.subs({x:5})
        25*y^2 + y + 30
        sage: f.subs(x=5)
        25*y^2 + y + 30
        sage: (1/f).subs(x=5)
        1/(25*y^2 + y + 30)
        sage: Integer(5).subs(x=4)
        5

  `substitute`(in_dict=None, **kwds)

    This is an alias for self.subs().

    INPUT:

    - `in_dict` - (optional) dictionary of inputs
    - `**kwds` - named parameters

    OUTPUT:

    - new object if substitution is possible, otherwise self.

    EXAMPLES:

        sage: x, y = PolynomialRing(ZZ,2,'xy').gens()
        sage: f = x^2 + y + x^2*y^2 + 5
        sage: f((5,y))
        25*y^2 + y + 30
        sage: f.substitute({x:5})
        25*y^2 + y + 30
        sage: f.substitute(x=5)
        25*y^2 + y + 30
        sage: (1/f).substitute(x=5)
        1/(25*y^2 + y + 30)
        sage: Integer(5).substitute(x=4)
        5

class `sage.structure.element.``ElementWithCachedMethod`

  Bases: `sage.structure.element.Element`

  An element class that fully supports cached methods.

  NOTE:

  The `cached_method` decorator provides a convenient way to automatically cache the result of a computation. Since trac ticket #11115, the cached method decorator applied to a method without optional arguments is faster than a hand-written cache in Python, and a cached method without any arguments (except `self`) is actually faster than a Python method that does nothing more but to return `1`. A cached method can also be inherited from the parent or element class of a category.

  However, this holds true only if attribute assignment is supported. If you write an extension class in Cython that does not accept attribute assignment then a cached method inherited from the category will be slower (for `Parent`) or the cache would even break (for `Element`).

  This class should be used if you write an element class, can not provide it with attribute assignment, but want that it inherits a cached method from the category. Under these conditions, your class should inherit from this class rather than `Element`. Then, the cache will work, but certainly slower than with attribute assignment. Lazy attributes work as well.

  EXAMPLE:

  We define three element extension classes. The first inherits from `Element`, the second from this class, and the third simply is a Python class. We also define a parent class and, in Python, a category whose element and parent classes define cached methods.

      sage: cython_code = ["from sage.structure.element cimport Element, ElementWithCachedMethod",
      ... "cdef class MyBrokenElement(Element):",
      ... "    cdef public object x",
      ... "    def __init__(self,P,x):",
      ... "        self.x=x",
      ... "        Element.__init__(self,P)",
      ... "    def __neg__(self):",
      ... "        return MyBrokenElement(self.parent(),-self.x)",
      ... "    def _repr_(self):",
      ... "        return '<%s>'%self.x",
      ... "    def __hash__(self):",
      ... "        return hash(self.x)",
      ... "    def __cmp__(left, right):",
      ... "        return (<Element>left)._cmp(right)",
      ... "    def __richcmp__(left, right, op):",
      ... "        return (<Element>left)._richcmp(right,op)",
      ... "    cdef int _cmp_c_impl(left, Element right) except -2:",
      ... "        return cmp(left.x,right.x)",
      ... "    def raw_test(self):",
      ... "        return -self",
      ... "cdef class MyElement(ElementWithCachedMethod):",
      ... "    cdef public object x",
      ... "    def __init__(self,P,x):",
      ... "        self.x=x",
      ... "        Element.__init__(self,P)",
      ... "    def __neg__(self):",
      ... "        return MyElement(self.parent(),-self.x)",
      ... "    def _repr_(self):",
      ... "        return '<%s>'%self.x",
      ... "    def __hash__(self):",
      ... "        return hash(self.x)",
      ... "    def __cmp__(left, right):",
      ... "        return (<Element>left)._cmp(right)",
      ... "    def __richcmp__(left, right, op):",
      ... "        return (<Element>left)._richcmp(right,op)",
      ... "    cdef int _cmp_c_impl(left, Element right) except -2:",
      ... "        return cmp(left.x,right.x)",
      ... "    def raw_test(self):",
      ... "        return -self",
      ... "class MyPythonElement(MyBrokenElement): pass",
      ... "from sage.structure.parent cimport Parent",
      ... "cdef class MyParent(Parent):",
      ... "    Element = MyElement"]
      sage: cython('\n'.join(cython_code))
      sage: cython_code = ["from sage.all import cached_method, cached_in_parent_method, Category, Objects",
      ... "class MyCategory(Category):",
      ... "    @cached_method",
      ... "    def super_categories(self):",
      ... "        return [Objects()]",
      ... "    class ElementMethods:",
      ... "        @cached_method",
      ... "        def element_cache_test(self):",
      ... "            return -self",
      ... "        @cached_in_parent_method",
      ... "        def element_via_parent_test(self):",
      ... "            return -self",
      ... "    class ParentMethods:",
      ... "        @cached_method",
      ... "        def one(self):",
      ... "            return self.element_class(self,1)",
      ... "        @cached_method",
      ... "        def invert(self, x):",
      ... "            return -x"]
      sage: cython('\n'.join(cython_code))
      sage: C = MyCategory()
      sage: P = MyParent(category=C)
      sage: ebroken = MyBrokenElement(P,5)
      sage: e = MyElement(P,5)

  The cached methods inherited by `MyElement` works:

      sage: e.element_cache_test()
      <-5>
      sage: e.element_cache_test() is e.element_cache_test()
      True
      sage: e.element_via_parent_test()
      <-5>
      sage: e.element_via_parent_test() is e.element_via_parent_test()
      True

  The other element class can only inherit a `cached_in_parent_method`, since the cache is stored in the parent. In fact, equal elements share the cache, even if they are of different types:

      sage: e == ebroken
      True
      sage: type(e) == type(ebroken)
      False
      sage: ebroken.element_via_parent_test() is e.element_via_parent_test()
      True

  However, the cache of the other inherited method breaks, although the method as such works:

      sage: ebroken.element_cache_test()
      <-5>
      sage: ebroken.element_cache_test() is ebroken.element_cache_test()
      False

  Since `e` and `ebroken` share the cache, when we empty it for one element it is empty for the other as well:

      sage: b = ebroken.element_via_parent_test()
      sage: e.element_via_parent_test.clear_cache()
      sage: b is ebroken.element_via_parent_test()
      False

  Note that the cache only breaks for elements that do no allow attribute assignment. A Python version of `MyBrokenElement` therefore allows for cached methods:

      sage: epython = MyPythonElement(P,5)
      sage: epython.element_cache_test()
      <-5>
      sage: epython.element_cache_test() is epython.element_cache_test()
      True

class `sage.structure.element.``EuclideanDomainElement`

  Bases: `sage.structure.element.PrincipalIdealDomainElement`

  INPUT:

  - `parent` - a SageObject
  `degree`()
  `leading_coefficient`()
  `quo_rem`(other)

class `sage.structure.element.``FieldElement`

  Bases: `sage.structure.element.CommutativeRingElement`

  INPUT:

  - `parent` - a SageObject
  `divides`(other)

    Check whether self divides other, for field elements.

    Since this is a field, all values divide all other values, except that zero does not divide any non-zero values.

    EXAMPLES:

        sage: K.<rt3> = QQ[sqrt(3)]
        sage: K(0).divides(rt3)
        False
        sage: rt3.divides(K(17))
        True
        sage: K(0).divides(K(0))
        True
        sage: rt3.divides(K(0))
        True

  `is_unit`()

    Return True if self is a unit in its parent ring.

    EXAMPLES:

        sage: a = 2/3; a.is_unit()
        True

    On the other hand, 2 is not a unit, since its parent is ZZ.

        sage: a = 2; a.is_unit()
        False
        sage: parent(a)
        Integer Ring

    However, a is a unit when viewed as an element of QQ:

        sage: a = QQ(2); a.is_unit()
        True

  `quo_rem`(right)

    Return the quotient and remainder obtained by dividing \(self\) by \(other\). Since this element lives in a field, the remainder is always zero and the quotient is \(self/right\).

    TESTS:

    Test if #8671 is fixed:

        sage: R.<x,y> = QQ[]
        sage: S.<a,b> = R.quo(y^2 + 1)
        sage: S.is_field = lambda : False
        sage: F = Frac(S); u = F.one_element()
        sage: u.quo_rem(u)
        (1, 0)

class `sage.structure.element.``InfinityElement`

  Bases: `sage.structure.element.RingElement`

  INPUT:

  - `parent` - a SageObject

class `sage.structure.element.``IntegralDomainElement`

  Bases: `sage.structure.element.CommutativeRingElement`

  INPUT:

  - `parent` - a SageObject
  `is_nilpotent`()

class `sage.structure.element.``Matrix`

  Bases: `sage.structure.element.ModuleElement`

  INPUT:

  - `parent` - a SageObject

class `sage.structure.element.``MinusInfinityElement`

  Bases: `sage.structure.element.InfinityElement`

  INPUT:

  - `parent` - a SageObject

class `sage.structure.element.``ModuleElement`

  Bases: `sage.structure.element.Element`

  Generic element of a module.

  `additive_order`()

    Return the additive order of self.

  `order`()

    Return the additive order of self.

class `sage.structure.element.``MonoidElement`

  Bases: `sage.structure.element.Element`

  Generic element of a monoid.

  `multiplicative_order`()

    Return the multiplicative order of self.

  `order`()

    Return the multiplicative order of self.

class `sage.structure.element.``MultiplicativeGroupElement`

  Bases: `sage.structure.element.MonoidElement`

  Generic element of a multiplicative group.

  `order`()

    Return the multiplicative order of self.

class `sage.structure.element.``NamedBinopMethod`

  Bases: `object`

  A decorator to be used on binary operation methods that should operate on elements of the same parent. If the parents of the arguments differ, coercion is performed, then the method is re-looked up by name on the first argument.

  In short, using the `NamedBinopMethod` (alias `coerce_binop`) decorator on a method gives it the exact same semantics of the basic arithmetic operations like `_add_`, `_sub_`, etc. in that both operands are guaranteed to have exactly the same parent.

class `sage.structure.element.``PlusInfinityElement`

  Bases: `sage.structure.element.InfinityElement`

  INPUT:

  - `parent` - a SageObject

class `sage.structure.element.``PrincipalIdealDomainElement`

  Bases: `sage.structure.element.DedekindDomainElement`

  INPUT:

  - `parent` - a SageObject
  `lcm`(right)

    Returns the least common multiple of self and right.

class `sage.structure.element.``RingElement`

  Bases: `sage.structure.element.ModuleElement`

  INPUT:

  - `parent` - a SageObject
  `abs`()

    Return the absolute value of self. (This just calls the __abs__ method, so it is equivalent to the abs() built-in function.)

    EXAMPLES:

        sage: RR(-1).abs()
        1.00000000000000
        sage: ZZ(-1).abs()
        1
        sage: CC(I).abs()
        1.00000000000000
        sage: Mod(-15, 37).abs()
        Traceback (most recent call last):
        ...
        ArithmeticError: absolute valued not defined on integers modulo n.

  `additive_order`()

    Return the additive order of self.

  `is_nilpotent`()

    Return True if self is nilpotent, i.e., some power of self is 0.

  `is_one`()
  `multiplicative_order`()

    Return the multiplicative order of self, if self is a unit, or raise `ArithmeticError` otherwise.

class `sage.structure.element.``Vector`

  Bases: `sage.structure.element.ModuleElement`

  INPUT:

  - `parent` - a SageObject

`sage.structure.element.``bin_op`(x, y, op)

`sage.structure.element.``canonical_coercion`(x, y)

  canonical_coercion(x,y) is what is called before doing an arithmetic operation between x and y. It returns a pair (z,w) such that z is got from x and w from y via canonical coercion and the parents of z and w are identical.

  EXAMPLES:

      sage: A = Matrix([[0,1],[1,0]])
      sage: canonical_coercion(A,1)
      (
      [0 1]  [1 0]
      [1 0], [0 1]
      )

`sage.structure.element.``coerce_binop`

  alias of `NamedBinopMethod`

`sage.structure.element.``coerce_cmp`(x, y)

`sage.structure.element.``coercion_traceback`(dump=True)

  This function is very helpful in debugging coercion errors. It prints the tracebacks of all the errors caught in the coercion detection. Note that failure is cached, so some errors may be omitted the second time around (as it remembers not to retry failed paths for speed reasons.

  For performance and caching reasons, exception recording must be explicitly enabled before using this function.

  EXAMPLES:

      sage: cm = sage.structure.element.get_coercion_model()
      sage: cm.record_exceptions()
      sage: 1 + 1/5
      6/5
      sage: coercion_traceback()  # Should be empty, as all went well.
      sage: 1/5 + GF(5).gen()
      Traceback (most recent call last):
      ...
      TypeError: unsupported operand parent(s) for '+': 'Rational Field' and 'Finite Field of size 5'
      sage: coercion_traceback()
      Traceback (most recent call last):
      ...
      TypeError: no common canonical parent for objects with parents: 'Rational Field' and 'Finite Field of size 5'

`sage.structure.element.``gcd`(x, y)

`sage.structure.element.``generic_power`(a, n, one=None)

  Computes \(a^n\), where \(n\) is an integer, and \(a\) is an object which supports multiplication. Optionally an additional argument, which is used in the case that n == 0:

  - `one` - the “unit” element, returned directly (can be anything)

  If this is not supplied, int(1) is returned.

  EXAMPLES:

      sage: from sage.structure.element import generic_power
      sage: generic_power(int(12),int(0))
      1
      sage: generic_power(int(0),int(100))
      0
      sage: generic_power(Integer(10),Integer(0))
      1
      sage: generic_power(Integer(0),Integer(23))
      0
      sage: sum([generic_power(2,i) for i in range(17)]) #test all 4-bit combinations
      131071
      sage: F = Zmod(5)
      sage: a = generic_power(F(2), 5); a
      2
      sage: a.parent() is F
      True
      sage: a = generic_power(F(1), 2)
      sage: a.parent() is F
      True

      sage: generic_power(int(5), 0)
      1

`sage.structure.element.``get_coercion_model`()

  Return the global coercion model.

  EXAMPLES:

      sage: import sage.structure.element as e
      sage: cm = e.get_coercion_model()
      sage: cm
      <sage.structure.coerce.CoercionModel_cache_maps object at ...>

`sage.structure.element.``is_AdditiveGroupElement`(x)

  Return True if x is of type AdditiveGroupElement.

`sage.structure.element.``is_AlgebraElement`(x)

  Return True if x is of type AlgebraElement.

`sage.structure.element.``is_CommutativeAlgebraElement`(x)

  Return True if x is of type CommutativeAlgebraElement.

`sage.structure.element.``is_CommutativeRingElement`(x)

  Return True if x is of type CommutativeRingElement.

`sage.structure.element.``is_DedekindDomainElement`(x)

  Return True if x is of type DedekindDomainElement.

`sage.structure.element.``is_Element`(x)

  Return True if x is of type Element.

  EXAMPLES:

      sage: from sage.structure.element import is_Element
      sage: is_Element(2/3)
      True
      sage: is_Element(QQ^3)
      False

`sage.structure.element.``is_EuclideanDomainElement`(x)

  Return True if x is of type EuclideanDomainElement.

`sage.structure.element.``is_FieldElement`(x)

  Return True if x is of type FieldElement.

`sage.structure.element.``is_InfinityElement`(x)

  Return True if x is of type InfinityElement.

`sage.structure.element.``is_IntegralDomainElement`(x)

  Return True if x is of type IntegralDomainElement.

`sage.structure.element.``is_Matrix`(x)

`sage.structure.element.``is_ModuleElement`(x)

  Return True if x is of type ModuleElement.

  This is even faster than using isinstance inline.

  EXAMPLES:

      sage: from sage.structure.element import is_ModuleElement
      sage: is_ModuleElement(2/3)
      True
      sage: is_ModuleElement((QQ^3).0)
      True
      sage: is_ModuleElement('a')
      False

`sage.structure.element.``is_MonoidElement`(x)

  Return True if x is of type MonoidElement.

`sage.structure.element.``is_MultiplicativeGroupElement`(x)

  Return True if x is of type MultiplicativeGroupElement.

`sage.structure.element.``is_PrincipalIdealDomainElement`(x)

  Return True if x is of type PrincipalIdealDomainElement.

`sage.structure.element.``is_RingElement`(x)

  Return True if x is of type RingElement.

`sage.structure.element.``is_Vector`(x)

`sage.structure.element.``lcm`(x, y)

`sage.structure.element.``make_element`(_class, _dict, parent)

  This function is only here to support old pickles.

  Pickling functionality is moved to Element.{__getstate__,__setstate__} functions.

`sage.structure.element.``parent`(x)

`sage.structure.element.``py_scalar_to_element`(py)

`sage.structure.element.``set_coercion_model`(cm)

`sage.structure.element.``xgcd`(x, y)

### Navigation

- index
- modules |
- next |
- previous |
- Basic Structures »