Coerce actions - Coercion

Skip to content
Back to top
View this page
Edit this page

# Coerce actions

class sage.structure.coerce_actions.ActOnAction

  Bases: `GenericAction`

  Class for actions defined via the _act_on_ method.

class sage.structure.coerce_actions.ActedUponAction

  Bases: `GenericAction`

  Class for actions defined via the _acted_upon_ method.

class sage.structure.coerce_actions.GenericAction

  Bases: `Action`

  codomain()

    Return the “codomain” of this action, i.e. the Parent in which the result elements live. Typically, this should be the same as the acted upon set.

    EXAMPLES:

    Note that coerce actions should only be used inside of the coercion model. For this test, we need to strongly reference the domains, for otherwise they could be garbage collected, giving rise to random errors (see Issue #18157).

    Sage

        sage: M = MatrixSpace(ZZ, 2)                                                # needs sage.modules
        sage: A = sage.structure.coerce_actions.ActedUponAction(M, Cusps, True)     # needs sage.modular sage.modules
        sage: A.codomain()                                                          # needs sage.modular sage.modules
        Set P^1(QQ) of all cusps

        sage: # needs sage.groups
        sage: S3 = SymmetricGroup(3)
        sage: QQxyz = QQ['x,y,z']
        sage: A = sage.structure.coerce_actions.ActOnAction(S3, QQxyz, False)
        sage: A.codomain()
        Multivariate Polynomial Ring in x, y, z over Rational Field

    Python

        >>> from sage.all import *
        >>> M = MatrixSpace(ZZ, Integer(2))                                                # needs sage.modules
        >>> A = sage.structure.coerce_actions.ActedUponAction(M, Cusps, True)     # needs sage.modular sage.modules
        >>> A.codomain()                                                          # needs sage.modular sage.modules
        Set P^1(QQ) of all cusps

        >>> # needs sage.groups
        >>> S3 = SymmetricGroup(Integer(3))
        >>> QQxyz = QQ['x,y,z']
        >>> A = sage.structure.coerce_actions.ActOnAction(S3, QQxyz, False)
        >>> A.codomain()
        Multivariate Polynomial Ring in x, y, z over Rational Field

class sage.structure.coerce_actions.IntegerAction

  Bases: `Action`

  Abstract base class representing some action by integers on something. Here, “integer” is defined loosely in the “duck typing” sense.

  INPUT:

  - `Z` – a type or parent representing integers

  For the other arguments, see `Action`.

  Note

  This class is used internally in Sage’s coercion model. Outside of the coercion model, special precautions are needed to prevent domains of the action from being garbage collected.

class sage.structure.coerce_actions.IntegerMulAction

  Bases: `IntegerAction`

  Implement the action \(n \cdot a = a + a + ... + a\) via repeated doubling.

  Both addition and negation must be defined on the set \(M\).

  INPUT:

  - `Z` – a type or parent representing integers

  - `M` – a `ZZ`-module

  - `m` – (optional) an element of `M`

  EXAMPLES:

  Sage

      sage: from sage.structure.coerce_actions import IntegerMulAction
      sage: R.<x> = QQ['x']
      sage: act = IntegerMulAction(ZZ, R)
      sage: act(5, x)
      5*x
      sage: act(0, x)
      0
      sage: act(-3, x-1)
      -3*x + 3

  Python

      >>> from sage.all import *
      >>> from sage.structure.coerce_actions import IntegerMulAction
      >>> R = QQ['x']; (x,) = R._first_ngens(1)
      >>> act = IntegerMulAction(ZZ, R)
      >>> act(Integer(5), x)
      5*x
      >>> act(Integer(0), x)
      0
      >>> act(-Integer(3), x-Integer(1))
      -3*x + 3

class sage.structure.coerce_actions.IntegerPowAction

  Bases: `IntegerAction`

  The right action `a ^ n = a * a * ... * a` where \(n\) is an integer.

  The action is implemented using the `_pow_int` method on elements.

  INPUT:

  - `Z` – a type or parent representing integers

  - `M` – a parent whose elements implement `_pow_int`

  - `m` – (optional) an element of `M`

  EXAMPLES:

  Sage

      sage: from sage.structure.coerce_actions import IntegerPowAction
      sage: R.<x> = LaurentSeriesRing(QQ)
      sage: act = IntegerPowAction(ZZ, R)
      sage: act(x, 5)
      x^5
      sage: act(x, -2)
      x^-2
      sage: act(x, int(5))
      x^5

  Python

      >>> from sage.all import *
      >>> from sage.structure.coerce_actions import IntegerPowAction
      >>> R = LaurentSeriesRing(QQ, names=('x',)); (x,) = R._first_ngens(1)
      >>> act = IntegerPowAction(ZZ, R)
      >>> act(x, Integer(5))
      x^5
      >>> act(x, -Integer(2))
      x^-2
      >>> act(x, int(Integer(5)))
      x^5

class sage.structure.coerce_actions.LeftModuleAction

  Bases: `ModuleAction`

class sage.structure.coerce_actions.ModuleAction

  Bases: `Action`

  Module action.

  See also

  This is an abstract class, one must actually instantiate a `LeftModuleAction` or a `RightModuleAction`.

  INPUT:

  - `G` – the actor, an instance of `Parent`

  - `S` – the object that is acted upon

  - `g` – (optional) an element of `G`

  - `a` – (optional) an element of `S`

  - `check` – if `True` (default), then there will be no consistency tests performed on sample elements

  NOTE:

  By default, the sample elements of `S` and `G` are obtained from `an_element()`, which relies on the implementation of an `_an_element_()` method. This is not always available. But usually, the action is only needed when one already has two elements. Hence, by Issue #14249, the coercion model will pass these two elements to the `ModuleAction` constructor.

  The actual action is implemented by the `_rmul_` or `_lmul_` function on its elements. We must, however, be very particular about what we feed into these functions, because they operate under the assumption that the inputs lie exactly in the base ring and may segfault otherwise. Thus we handle all possible base extensions manually here.

  codomain()

    The codomain of self, which may or may not be equal to the domain.

    EXAMPLES:

    Note that coerce actions should only be used inside of the coercion model. For this test, we need to strongly reference the domains, for otherwise they could be garbage collected, giving rise to random errors (see Issue #18157).

    Sage

        sage: from sage.structure.coerce_actions import LeftModuleAction
        sage: ZZxyz = ZZ['x,y,z']
        sage: A = LeftModuleAction(QQ, ZZxyz)
        sage: A.codomain()
        Multivariate Polynomial Ring in x, y, z over Rational Field

    Python

        >>> from sage.all import *
        >>> from sage.structure.coerce_actions import LeftModuleAction
        >>> ZZxyz = ZZ['x,y,z']
        >>> A = LeftModuleAction(QQ, ZZxyz)
        >>> A.codomain()
        Multivariate Polynomial Ring in x, y, z over Rational Field

  domain()

    The domain of self, which is the module that is being acted on.

    EXAMPLES:

    Note that coerce actions should only be used inside of the coercion model. For this test, we need to strongly reference the domains, for otherwise they could be garbage collected, giving rise to random errors (see Issue #18157).

    Sage

        sage: from sage.structure.coerce_actions import LeftModuleAction
        sage: ZZxyz = ZZ['x,y,z']
        sage: A = LeftModuleAction(QQ, ZZxyz)
        sage: A.domain()
        Multivariate Polynomial Ring in x, y, z over Integer Ring

    Python

        >>> from sage.all import *
        >>> from sage.structure.coerce_actions import LeftModuleAction
        >>> ZZxyz = ZZ['x,y,z']
        >>> A = LeftModuleAction(QQ, ZZxyz)
        >>> A.domain()
        Multivariate Polynomial Ring in x, y, z over Integer Ring

class sage.structure.coerce_actions.PyScalarAction

  Bases: `Action`

class sage.structure.coerce_actions.RightModuleAction

  Bases: `ModuleAction`

sage.structure.coerce_actions.detect_element_action(X, Y, X_on_left, X_el=None, Y_el=None)

  Return an action of X on Y as defined by elements of X, if any.

  EXAMPLES:

  Note that coerce actions should only be used inside of the coercion model. For this test, we need to strongly reference the domains, for otherwise they could be garbage collected, giving rise to random errors (see Issue #18157).

  Sage

      sage: from sage.structure.coerce_actions import detect_element_action
      sage: ZZx = ZZ['x']
      sage: M = MatrixSpace(ZZ, 2)                                                    # needs sage.modules
      sage: detect_element_action(ZZx, ZZ, False)
      Left scalar multiplication by Integer Ring
       on Univariate Polynomial Ring in x over Integer Ring
      sage: detect_element_action(ZZx, QQ, True)
      Right scalar multiplication by Rational Field
       on Univariate Polynomial Ring in x over Integer Ring
      sage: detect_element_action(Cusps, M, False)                                    # needs sage.modular sage.modules
      Left action by Full MatrixSpace of 2 by 2 dense matrices over Integer Ring
       on Set P^1(QQ) of all cusps
      sage: detect_element_action(Cusps, M, True),                                    # needs sage.modular sage.modules
      (None,)
      sage: detect_element_action(ZZ, QQ, True),
      (None,)

  Python

      >>> from sage.all import *
      >>> from sage.structure.coerce_actions import detect_element_action
      >>> ZZx = ZZ['x']
      >>> M = MatrixSpace(ZZ, Integer(2))                                                    # needs sage.modules
      >>> detect_element_action(ZZx, ZZ, False)
      Left scalar multiplication by Integer Ring
       on Univariate Polynomial Ring in x over Integer Ring
      >>> detect_element_action(ZZx, QQ, True)
      Right scalar multiplication by Rational Field
       on Univariate Polynomial Ring in x over Integer Ring
      >>> detect_element_action(Cusps, M, False)                                    # needs sage.modular sage.modules
      Left action by Full MatrixSpace of 2 by 2 dense matrices over Integer Ring
       on Set P^1(QQ) of all cusps
      >>> detect_element_action(Cusps, M, True),                                    # needs sage.modular sage.modules
      (None,)
      >>> detect_element_action(ZZ, QQ, True),
      (None,)