GAP element wrapper - C/C++ Library Interfaces

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

# GAP element wrapper

This document describes the individual wrappers for various GAP elements. For general information about GAP, you should read the `libgap` module documentation.

class sage.libs.gap.element.GapElement

  Bases: `RingElement`

  Wrapper for all Gap objects.

  Note

  In order to create `GapElements` you should use the `libgap` instance (the parent of all Gap elements) to convert things into `GapElement`. You must not create `GapElement` instances manually.

  EXAMPLES:

  Sage

      sage: libgap(0)
      0

  Python

      >>> from sage.all import *
      >>> libgap(Integer(0))
      0

  If Gap finds an error while evaluating, a `GAPError` exception is raised:

  Sage

      sage: libgap.eval('1/0')
      Traceback (most recent call last):
      ...
      GAPError: Error, Rational operations: <divisor> must not be zero

  [Python]

      >>> from sage.all import *
      >>> libgap.eval('1/0')
      Traceback (most recent call last):
      ...
      GAPError: Error, Rational operations: <divisor> must not be zero

  Also, a `GAPError` is raised if the input is not a simple expression:

  Sage

      sage: libgap.eval('1; 2; 3')
      Traceback (most recent call last):
      ...
      GAPError: can only evaluate a single statement

  Python

      >>> from sage.all import *
      >>> libgap.eval('1; 2; 3')
      Traceback (most recent call last):
      ...
      GAPError: can only evaluate a single statement

  deepcopy(mut)

    Return a deepcopy of this Gap object.

    Note that this is the same thing as calling `StructuralCopy` but much faster.

    INPUT:

    - `mut` – boolean; whether to return a mutable copy

    EXAMPLES:

    Sage

        sage: a = libgap([[0,1],[2,3]])
        sage: b = a.deepcopy(1)
        sage: b[0,0] = 5
        sage: a
        [ [ 0, 1 ], [ 2, 3 ] ]
        sage: b
        [ [ 5, 1 ], [ 2, 3 ] ]

        sage: l = libgap([0,1])
        sage: l.deepcopy(0).IsMutable()
        false
        sage: l.deepcopy(1).IsMutable()
        true

    Python

        >>> from sage.all import *
        >>> a = libgap([[Integer(0),Integer(1)],[Integer(2),Integer(3)]])
        >>> b = a.deepcopy(Integer(1))
        >>> b[Integer(0),Integer(0)] = Integer(5)
        >>> a
        [ [ 0, 1 ], [ 2, 3 ] ]
        >>> b
        [ [ 5, 1 ], [ 2, 3 ] ]

        >>> l = libgap([Integer(0),Integer(1)])
        >>> l.deepcopy(Integer(0)).IsMutable()
        false
        >>> l.deepcopy(Integer(1)).IsMutable()
        true

  is_bool()

    Return whether the wrapped GAP object is a GAP boolean.

    OUTPUT: boolean

    EXAMPLES:

    Sage

        sage: libgap(True).is_bool()
        True

    Python

        >>> from sage.all import *
        >>> libgap(True).is_bool()
        True

  is_function()

    Return whether the wrapped GAP object is a function.

    OUTPUT: boolean

    EXAMPLES:

    Sage

        sage: a = libgap.eval("NormalSubgroups")
        sage: a.is_function()
        True
        sage: a = libgap(2/3)
        sage: a.is_function()
        False

    Python

        >>> from sage.all import *
        >>> a = libgap.eval("NormalSubgroups")
        >>> a.is_function()
        True
        >>> a = libgap(Integer(2)/Integer(3))
        >>> a.is_function()
        False

  is_list()

    Return whether the wrapped GAP object is a GAP List.

    OUTPUT: boolean

    EXAMPLES:

    Sage

        sage: libgap.eval('[1, 2,,,, 5]').is_list()
        True
        sage: libgap.eval('3/2').is_list()
        False

    Python

        >>> from sage.all import *
        >>> libgap.eval('[1, 2,,,, 5]').is_list()
        True
        >>> libgap.eval('3/2').is_list()
        False

  is_permutation()

    Return whether the wrapped GAP object is a GAP permutation.

    OUTPUT: boolean

    EXAMPLES:

    Sage

        sage: perm = libgap.PermList( libgap([1,5,2,3,4]) );  perm
        (2,5,4,3)
        sage: perm.is_permutation()
        True
        sage: libgap('this is a string').is_permutation()
        False

    Python

        >>> from sage.all import *
        >>> perm = libgap.PermList( libgap([Integer(1),Integer(5),Integer(2),Integer(3),Integer(4)]) );  perm
        (2,5,4,3)
        >>> perm.is_permutation()
        True
        >>> libgap('this is a string').is_permutation()
        False

  is_record()

    Return whether the wrapped GAP object is a GAP record.

    OUTPUT: boolean

    EXAMPLES:

    Sage

        sage: libgap.eval('[1, 2,,,, 5]').is_record()
        False
        sage: libgap.eval('rec(a:=1, b:=3)').is_record()
        True

    Python

        >>> from sage.all import *
        >>> libgap.eval('[1, 2,,,, 5]').is_record()
        False
        >>> libgap.eval('rec(a:=1, b:=3)').is_record()
        True

  is_string()

    Return whether the wrapped GAP object is a GAP string.

    OUTPUT: boolean

    EXAMPLES:

    Sage

        sage: libgap('this is a string').is_string()
        True

    Python

        >>> from sage.all import *
        >>> libgap('this is a string').is_string()
        True

  sage()

    Return the Sage equivalent of the `GapElement`.

    EXAMPLES:

    Sage

        sage: libgap(1).sage()
        1
        sage: type(_)
        <class 'sage.rings.integer.Integer'>

        sage: libgap(3/7).sage()
        3/7
        sage: type(_)
        <class 'sage.rings.rational.Rational'>

        sage: libgap.eval('5 + 7*E(3)').sage()
        7*zeta3 + 5

        sage: libgap(Infinity).sage()
        +Infinity
        sage: libgap(-Infinity).sage()
        -Infinity

        sage: libgap(True).sage()
        True
        sage: libgap(False).sage()
        False
        sage: type(_)
        <... 'bool'>

        sage: libgap('this is a string').sage()
        'this is a string'
        sage: type(_)
        <... 'str'>

        sage: x = libgap.Integers.Indeterminate("x")

        sage: p = x^2 - 2*x + 3
        sage: p.sage()
        x^2 - 2*x + 3
        sage: p.sage().parent()
        Univariate Polynomial Ring in x over Integer Ring

        sage: p = x^-2 + 3*x
        sage: p.sage()
        x^-2 + 3*x
        sage: p.sage().parent()
        Univariate Laurent Polynomial Ring in x over Integer Ring

        sage: p = (3 * x^2 + x) / (x^2 - 2)
        sage: p.sage()
        (3*x^2 + x)/(x^2 - 2)
        sage: p.sage().parent()
        Fraction Field of Univariate Polynomial Ring in x over Integer Ring

        sage: G0 = libgap.SymplecticGroup(4,2)
        sage: P = G0.IsomorphismFpGroup().Range()
        sage: G = P.sage()
        sage: G.gap() == P
        True

        sage: F0 = libgap.FreeGroup(2)
        sage: F = F0.sage()
        sage: F.gap() is F0
        True

    Python

        >>> from sage.all import *
        >>> libgap(Integer(1)).sage()
        1
        >>> type(_)
        <class 'sage.rings.integer.Integer'>

        >>> libgap(Integer(3)/Integer(7)).sage()
        3/7
        >>> type(_)
        <class 'sage.rings.rational.Rational'>

        >>> libgap.eval('5 + 7*E(3)').sage()
        7*zeta3 + 5

        >>> libgap(Infinity).sage()
        +Infinity
        >>> libgap(-Infinity).sage()
        -Infinity

        >>> libgap(True).sage()
        True
        >>> libgap(False).sage()
        False
        >>> type(_)
        <... 'bool'>

        >>> libgap('this is a string').sage()
        'this is a string'
        >>> type(_)
        <... 'str'>

        >>> x = libgap.Integers.Indeterminate("x")

        >>> p = x**Integer(2) - Integer(2)*x + Integer(3)
        >>> p.sage()
        x^2 - 2*x + 3
        >>> p.sage().parent()
        Univariate Polynomial Ring in x over Integer Ring

        >>> p = x**-Integer(2) + Integer(3)*x
        >>> p.sage()
        x^-2 + 3*x
        >>> p.sage().parent()
        Univariate Laurent Polynomial Ring in x over Integer Ring

        >>> p = (Integer(3) * x**Integer(2) + x) / (x**Integer(2) - Integer(2))
        >>> p.sage()
        (3*x^2 + x)/(x^2 - 2)
        >>> p.sage().parent()
        Fraction Field of Univariate Polynomial Ring in x over Integer Ring

        >>> G0 = libgap.SymplecticGroup(Integer(4),Integer(2))
        >>> P = G0.IsomorphismFpGroup().Range()
        >>> G = P.sage()
        >>> G.gap() == P
        True

        >>> F0 = libgap.FreeGroup(Integer(2))
        >>> F = F0.sage()
        >>> F.gap() is F0
        True

class sage.libs.gap.element.GapElement_Boolean

  Bases: `GapElement`

  Derived class of GapElement for GAP boolean values.

  EXAMPLES:

  Sage

      sage: b = libgap(True)
      sage: type(b)
      <class 'sage.libs.gap.element.GapElement_Boolean'>

  Python

      >>> from sage.all import *
      >>> b = libgap(True)
      >>> type(b)
      <class 'sage.libs.gap.element.GapElement_Boolean'>

  sage()

    Return the Sage equivalent of the `GapElement`.

    OUTPUT:

    A Python boolean if the values is either true or false. GAP booleans can have the third value `Fail`, in which case a `ValueError` is raised.

    EXAMPLES:

    Sage

        sage: b = libgap.eval('true');  b
        true
        sage: type(_)
        <class 'sage.libs.gap.element.GapElement_Boolean'>
        sage: b.sage()
        True
        sage: type(_)
        <... 'bool'>

        sage: libgap.eval('fail')
        fail
        sage: _.sage()
        Traceback (most recent call last):
        ...
        ValueError: the GAP boolean value "fail" cannot be represented in Sage

    Python

        >>> from sage.all import *
        >>> b = libgap.eval('true');  b
        true
        >>> type(_)
        <class 'sage.libs.gap.element.GapElement_Boolean'>
        >>> b.sage()
        True
        >>> type(_)
        <... 'bool'>

        >>> libgap.eval('fail')
        fail
        >>> _.sage()
        Traceback (most recent call last):
        ...
        ValueError: the GAP boolean value "fail" cannot be represented in Sage

class sage.libs.gap.element.GapElement_Cyclotomic

  Bases: `GapElement`

  Derived class of GapElement for GAP universal cyclotomics.

  EXAMPLES:

  Sage

      sage: libgap.eval('E(3)')
      E(3)
      sage: type(_)
      <class 'sage.libs.gap.element.GapElement_Cyclotomic'>

  Python

      >>> from sage.all import *
      >>> libgap.eval('E(3)')
      E(3)
      >>> type(_)
      <class 'sage.libs.gap.element.GapElement_Cyclotomic'>

  sage(ring=None)

    Return the Sage equivalent of the `GapElement_Cyclotomic`.

    INPUT:

    - `ring` – a Sage cyclotomic field or `None` (default); if not specified, a suitable minimal cyclotomic field will be constructed

    OUTPUT: a Sage cyclotomic field element

    EXAMPLES:

    Sage

        sage: n = libgap.eval('E(3)')
        sage: n.sage()
        zeta3
        sage: parent(_)
        Cyclotomic Field of order 3 and degree 2

        sage: n.sage(ring=CyclotomicField(6))
        zeta6 - 1

        sage: libgap.E(3).sage(ring=CyclotomicField(3))
        zeta3
        sage: libgap.E(3).sage(ring=CyclotomicField(6))
        zeta6 - 1

    Python

        >>> from sage.all import *
        >>> n = libgap.eval('E(3)')
        >>> n.sage()
        zeta3
        >>> parent(_)
        Cyclotomic Field of order 3 and degree 2

        >>> n.sage(ring=CyclotomicField(Integer(6)))
        zeta6 - 1

        >>> libgap.E(Integer(3)).sage(ring=CyclotomicField(Integer(3)))
        zeta3
        >>> libgap.E(Integer(3)).sage(ring=CyclotomicField(Integer(6)))
        zeta6 - 1

class sage.libs.gap.element.GapElement_FiniteField

  Bases: `GapElement`

  Derived class of GapElement for GAP finite field elements.

  EXAMPLES:

  Sage

      sage: libgap.eval('Z(5)^2')
      Z(5)^2
      sage: type(_)
      <class 'sage.libs.gap.element.GapElement_FiniteField'>

  Python

      >>> from sage.all import *
      >>> libgap.eval('Z(5)^2')
      Z(5)^2
      >>> type(_)
      <class 'sage.libs.gap.element.GapElement_FiniteField'>

  lift()

    Return an integer lift.

    OUTPUT:

    The smallest positive `GapElement_Integer` that equals `self` in the prime finite field.

    EXAMPLES:

    Sage

        sage: n = libgap.eval('Z(5)^2')
        sage: n.lift()
        4
        sage: type(_)
        <class 'sage.libs.gap.element.GapElement_Integer'>

        sage: n = libgap.eval('Z(25)')
        sage: n.lift()
        Traceback (most recent call last):
        TypeError: not in prime subfield

    Python

        >>> from sage.all import *
        >>> n = libgap.eval('Z(5)^2')
        >>> n.lift()
        4
        >>> type(_)
        <class 'sage.libs.gap.element.GapElement_Integer'>

        >>> n = libgap.eval('Z(25)')
        >>> n.lift()
        Traceback (most recent call last):
        TypeError: not in prime subfield

  sage(ring=None, var='a')

    Return the Sage equivalent of the `GapElement_FiniteField`.

    INPUT:

    - `ring` – a Sage finite field or `None` (default). The field to return `self` in. If not specified, a suitable finite field will be constructed.

    OUTPUT:

    A Sage finite field element. The isomorphism is chosen such that the Gap `PrimitiveRoot()` maps to the Sage `multiplicative_generator()`.

    EXAMPLES:

    Sage

        sage: n = libgap.eval('Z(25)^2')
        sage: n.sage()
        a + 3
        sage: parent(_)
        Finite Field in a of size 5^2

        sage: n.sage(ring=GF(5))
        Traceback (most recent call last):
        ...
        ValueError: the given ring is incompatible ...

    Python

        >>> from sage.all import *
        >>> n = libgap.eval('Z(25)^2')
        >>> n.sage()
        a + 3
        >>> parent(_)
        Finite Field in a of size 5^2

        >>> n.sage(ring=GF(Integer(5)))
        Traceback (most recent call last):
        ...
        ValueError: the given ring is incompatible ...

class sage.libs.gap.element.GapElement_Float

  Bases: `GapElement`

  Derived class of GapElement for GAP floating point numbers.

  EXAMPLES:

  Sage

      sage: i = libgap(123.5)
      sage: type(i)
      <class 'sage.libs.gap.element.GapElement_Float'>
      sage: RDF(i)
      123.5
      sage: float(i)
      123.5

  Python

      >>> from sage.all import *
      >>> i = libgap(RealNumber('123.5'))
      >>> type(i)
      <class 'sage.libs.gap.element.GapElement_Float'>
      >>> RDF(i)
      123.5
      >>> float(i)
      123.5

  sage(ring=None)

    Return the Sage equivalent of the `GapElement_Float`.

    - `ring` – a floating point field or `None` (default); if not specified, the default Sage `RDF` is used

    OUTPUT: a Sage double precision floating point number

    EXAMPLES:

    Sage

        sage: a = libgap.eval("Float(3.25)").sage()
        sage: a
        3.25
        sage: parent(a)
        Real Double Field

    Python

        >>> from sage.all import *
        >>> a = libgap.eval("Float(3.25)").sage()
        >>> a
        3.25
        >>> parent(a)
        Real Double Field

class sage.libs.gap.element.GapElement_Function

  Bases: `GapElement`

  Derived class of GapElement for GAP functions.

  EXAMPLES:

  Sage

      sage: f = libgap.Cycles
      sage: type(f)
      <class 'sage.libs.gap.element.GapElement_Function'>

  Python

      >>> from sage.all import *
      >>> f = libgap.Cycles
      >>> type(f)
      <class 'sage.libs.gap.element.GapElement_Function'>

class sage.libs.gap.element.GapElement_Integer

  Bases: `GapElement`

  Derived class of GapElement for GAP integers.

  EXAMPLES:

  Sage

      sage: i = libgap(123)
      sage: type(i)
      <class 'sage.libs.gap.element.GapElement_Integer'>
      sage: ZZ(i)
      123

  Python

      >>> from sage.all import *
      >>> i = libgap(Integer(123))
      >>> type(i)
      <class 'sage.libs.gap.element.GapElement_Integer'>
      >>> ZZ(i)
      123

  is_C_int()

    Return whether the wrapped GAP object is a immediate GAP integer.

    An immediate integer is one that is stored as a C integer, and is subject to the usual size limits. Larger integers are stored in GAP as GMP integers.

    OUTPUT: boolean

    EXAMPLES:

    Sage

        sage: n = libgap(1)
        sage: type(n)
        <class 'sage.libs.gap.element.GapElement_Integer'>
        sage: n.is_C_int()
        True
        sage: n.IsInt()
        true

        sage: N = libgap(2^130)
        sage: type(N)
        <class 'sage.libs.gap.element.GapElement_Integer'>
        sage: N.is_C_int()
        False
        sage: N.IsInt()
        true

    Python

        >>> from sage.all import *
        >>> n = libgap(Integer(1))
        >>> type(n)
        <class 'sage.libs.gap.element.GapElement_Integer'>
        >>> n.is_C_int()
        True
        >>> n.IsInt()
        true

        >>> N = libgap(Integer(2)**Integer(130))
        >>> type(N)
        <class 'sage.libs.gap.element.GapElement_Integer'>
        >>> N.is_C_int()
        False
        >>> N.IsInt()
        true

  sage(ring=None)

    Return the Sage equivalent of the `GapElement_Integer`.

    - `ring` – integer ring or `None` (default); if not specified, the default Sage integer ring is used

    OUTPUT: a Sage integer

    EXAMPLES:

    Sage

        sage: libgap([ 1, 3, 4 ]).sage()
        [1, 3, 4]
        sage: all( x in ZZ for x in _ )
        True

        sage: libgap(132).sage(ring=IntegerModRing(13))
        2
        sage: parent(_)
        Ring of integers modulo 13

    Python

        >>> from sage.all import *
        >>> libgap([ Integer(1), Integer(3), Integer(4) ]).sage()
        [1, 3, 4]
        >>> all( x in ZZ for x in _ )
        True

        >>> libgap(Integer(132)).sage(ring=IntegerModRing(Integer(13)))
        2
        >>> parent(_)
        Ring of integers modulo 13

class sage.libs.gap.element.GapElement_IntegerMod

  Bases: `GapElement`

  Derived class of GapElement for GAP integers modulo an integer.

  EXAMPLES:

  Sage

      sage: n = IntegerModRing(123)(13)
      sage: i = libgap(n)
      sage: type(i)
      <class 'sage.libs.gap.element.GapElement_IntegerMod'>

  Python

      >>> from sage.all import *
      >>> n = IntegerModRing(Integer(123))(Integer(13))
      >>> i = libgap(n)
      >>> type(i)
      <class 'sage.libs.gap.element.GapElement_IntegerMod'>

  lift()

    Return an integer lift.

    OUTPUT:

    A `GapElement_Integer` that equals `self` in the integer mod ring.

    EXAMPLES:

    Sage

        sage: n = libgap.eval('One(ZmodnZ(123)) * 13')
        sage: n.lift()
        13
        sage: type(_)
        <class 'sage.libs.gap.element.GapElement_Integer'>

    Python

        >>> from sage.all import *
        >>> n = libgap.eval('One(ZmodnZ(123)) * 13')
        >>> n.lift()
        13
        >>> type(_)
        <class 'sage.libs.gap.element.GapElement_Integer'>

  sage(ring=None)

    Return the Sage equivalent of the `GapElement_IntegerMod`.

    INPUT:

    - `ring` – Sage integer mod ring or `None` (default); if not specified, a suitable integer mod ring is used automatically

    OUTPUT: a Sage integer modulo another integer

    EXAMPLES:

    Sage

        sage: n = libgap.eval('One(ZmodnZ(123)) * 13')
        sage: n.sage()
        13
        sage: parent(_)
        Ring of integers modulo 123

    Python

        >>> from sage.all import *
        >>> n = libgap.eval('One(ZmodnZ(123)) * 13')
        >>> n.sage()
        13
        >>> parent(_)
        Ring of integers modulo 123

class sage.libs.gap.element.GapElement_List

  Bases: `GapElement`

  Derived class of GapElement for GAP Lists.

  Note

  Lists are indexed by \(0..len(l)-1\), as expected from Python. This differs from the GAP convention where lists start at \(1\).

  EXAMPLES:

  Sage

      sage: lst = libgap.SymmetricGroup(3).List(); lst
      [ (), (1,3), (1,2,3), (2,3), (1,3,2), (1,2) ]
      sage: type(lst)
      <class 'sage.libs.gap.element.GapElement_List'>
      sage: len(lst)
      6
      sage: lst[3]
      (2,3)

  Python

      >>> from sage.all import *
      >>> lst = libgap.SymmetricGroup(Integer(3)).List(); lst
      [ (), (1,3), (1,2,3), (2,3), (1,3,2), (1,2) ]
      >>> type(lst)
      <class 'sage.libs.gap.element.GapElement_List'>
      >>> len(lst)
      6
      >>> lst[Integer(3)]
      (2,3)

  We can easily convert a Gap `List` object into a Python `list`:

  Sage

      sage: list(lst)
      [(), (1,3), (1,2,3), (2,3), (1,3,2), (1,2)]
      sage: type(_)
      <... 'list'>

  [Python]

      >>> from sage.all import *
      >>> list(lst)
      [(), (1,3), (1,2,3), (2,3), (1,3,2), (1,2)]
      >>> type(_)
      <... 'list'>

  Range checking is performed:

  Sage

      sage: lst[10]
      Traceback (most recent call last):
      ...
      IndexError: index out of range.

  Python

      >>> from sage.all import *
      >>> lst[Integer(10)]
      Traceback (most recent call last):
      ...
      IndexError: index out of range.

  matrix(ring=None)

    Return the list as a matrix.

    GAP does not have a special matrix data type, they are just lists of lists. This function converts a GAP list of lists to a Sage matrix.

    OUTPUT: a Sage matrix

    EXAMPLES:

    Sage

        sage: F = libgap.GF(4)
        sage: a = F.PrimitiveElement()
        sage: m = libgap([[a,a^0],[0*a,a^2]]); m
        [ [ Z(2^2), Z(2)^0 ],
          [ 0*Z(2), Z(2^2)^2 ] ]
        sage: m.IsMatrix()
        true
        sage: matrix(m)
        [    a     1]
        [    0 a + 1]
        sage: matrix(GF(4,'B'), m)
        [    B     1]
        [    0 B + 1]

        sage: M = libgap.eval('SL(2,GF(5))').GeneratorsOfGroup()[1]
        sage: type(M)
        <class 'sage.libs.gap.element.GapElement_List'>
        sage: M[0][0]
        Z(5)^2
        sage: M.IsMatrix()
        true
        sage: M.matrix()
        [4 1]
        [4 0]

    Python

        >>> from sage.all import *
        >>> F = libgap.GF(Integer(4))
        >>> a = F.PrimitiveElement()
        >>> m = libgap([[a,a**Integer(0)],[Integer(0)*a,a**Integer(2)]]); m
        [ [ Z(2^2), Z(2)^0 ],
          [ 0*Z(2), Z(2^2)^2 ] ]
        >>> m.IsMatrix()
        true
        >>> matrix(m)
        [    a     1]
        [    0 a + 1]
        >>> matrix(GF(Integer(4),'B'), m)
        [    B     1]
        [    0 B + 1]

        >>> M = libgap.eval('SL(2,GF(5))').GeneratorsOfGroup()[Integer(1)]
        >>> type(M)
        <class 'sage.libs.gap.element.GapElement_List'>
        >>> M[Integer(0)][Integer(0)]
        Z(5)^2
        >>> M.IsMatrix()
        true
        >>> M.matrix()
        [4 1]
        [4 0]

  sage(**kwds)

    Return the Sage equivalent of the `GapElement`.

    OUTPUT: a Python list

    EXAMPLES:

    Sage

        sage: libgap([ 1, 3, 4 ]).sage()
        [1, 3, 4]
        sage: all( x in ZZ for x in _ )
        True

    Python

        >>> from sage.all import *
        >>> libgap([ Integer(1), Integer(3), Integer(4) ]).sage()
        [1, 3, 4]
        >>> all( x in ZZ for x in _ )
        True

  vector(ring=None)

    Return the list as a vector.

    GAP does not have a special vector data type, they are just lists. This function converts a GAP list to a Sage vector.

    OUTPUT: a Sage vector

    EXAMPLES:

    Sage

        sage: F = libgap.GF(4)
        sage: a = F.PrimitiveElement()
        sage: m = libgap([0*a, a, a^3, a^2]); m
        [ 0*Z(2), Z(2^2), Z(2)^0, Z(2^2)^2 ]
        sage: type(m)
        <class 'sage.libs.gap.element.GapElement_List'>
        sage: m[3]
        Z(2^2)^2
        sage: vector(m)
        (0, a, 1, a + 1)
        sage: vector(GF(4,'B'), m)
        (0, B, 1, B + 1)

    Python

        >>> from sage.all import *
        >>> F = libgap.GF(Integer(4))
        >>> a = F.PrimitiveElement()
        >>> m = libgap([Integer(0)*a, a, a**Integer(3), a**Integer(2)]); m
        [ 0*Z(2), Z(2^2), Z(2)^0, Z(2^2)^2 ]
        >>> type(m)
        <class 'sage.libs.gap.element.GapElement_List'>
        >>> m[Integer(3)]
        Z(2^2)^2
        >>> vector(m)
        (0, a, 1, a + 1)
        >>> vector(GF(Integer(4),'B'), m)
        (0, B, 1, B + 1)

class sage.libs.gap.element.GapElement_MethodProxy

  Bases: `GapElement_Function`

  Helper class returned by `GapElement.__getattr__`.

  Derived class of GapElement for GAP functions. Like its parent, you can call instances to implement function call syntax. The only difference is that a fixed first argument is prepended to the argument list.

  EXAMPLES:

  Sage

      sage: lst = libgap([])
      sage: lst.Add
      <Gap function "Add">
      sage: type(_)
      <class 'sage.libs.gap.element.GapElement_MethodProxy'>
      sage: lst.Add(1)
      sage: lst
      [ 1 ]

  Python

      >>> from sage.all import *
      >>> lst = libgap([])
      >>> lst.Add
      <Gap function "Add">
      >>> type(_)
      <class 'sage.libs.gap.element.GapElement_MethodProxy'>
      >>> lst.Add(Integer(1))
      >>> lst
      [ 1 ]

class sage.libs.gap.element.GapElement_Permutation

  Bases: `GapElement`

  Derived class of GapElement for GAP permutations.

  Note

  Permutations in GAP act on the numbers starting with 1.

  EXAMPLES:

  Sage

      sage: perm = libgap.eval('(1,5,2)(4,3,8)')
      sage: type(perm)
      <class 'sage.libs.gap.element.GapElement_Permutation'>

  Python

      >>> from sage.all import *
      >>> perm = libgap.eval('(1,5,2)(4,3,8)')
      >>> type(perm)
      <class 'sage.libs.gap.element.GapElement_Permutation'>

  sage(parent=None)

    Return the Sage equivalent of the `GapElement`.

    If the permutation group is given as parent, this method is much faster.

    EXAMPLES:

    Sage

        sage: perm_gap = libgap.eval('(1,5,2)(4,3,8)');  perm_gap
        (1,5,2)(3,8,4)
        sage: perm_gap.sage()
        [5, 1, 8, 3, 2, 6, 7, 4]
        sage: type(_)
        <class 'sage.combinat.permutation.StandardPermutations_all_with_category.element_class'>
        sage: perm_gap.sage(PermutationGroup([(1,2),(1,2,3,4,5,6,7,8)]))
        (1,5,2)(3,8,4)
        sage: type(_)
        <class 'sage.groups.perm_gps.permgroup_element.PermutationGroupElement'>

    Python

        >>> from sage.all import *
        >>> perm_gap = libgap.eval('(1,5,2)(4,3,8)');  perm_gap
        (1,5,2)(3,8,4)
        >>> perm_gap.sage()
        [5, 1, 8, 3, 2, 6, 7, 4]
        >>> type(_)
        <class 'sage.combinat.permutation.StandardPermutations_all_with_category.element_class'>
        >>> perm_gap.sage(PermutationGroup([(Integer(1),Integer(2)),(Integer(1),Integer(2),Integer(3),Integer(4),Integer(5),Integer(6),Integer(7),Integer(8))]))
        (1,5,2)(3,8,4)
        >>> type(_)
        <class 'sage.groups.perm_gps.permgroup_element.PermutationGroupElement'>

class sage.libs.gap.element.GapElement_Rational

  Bases: `GapElement`

  Derived class of GapElement for GAP rational numbers.

  EXAMPLES:

  Sage

      sage: r = libgap(123/456)
      sage: type(r)
      <class 'sage.libs.gap.element.GapElement_Rational'>

  Python

      >>> from sage.all import *
      >>> r = libgap(Integer(123)/Integer(456))
      >>> type(r)
      <class 'sage.libs.gap.element.GapElement_Rational'>

  sage(ring=None)

    Return the Sage equivalent of the `GapElement`.

    INPUT:

    - `ring` – the Sage rational ring or `None` (default); if not specified, the rational ring is used automatically

    OUTPUT: a Sage rational number

    EXAMPLES:

    Sage

        sage: r = libgap(123/456);  r
        41/152
        sage: type(_)
        <class 'sage.libs.gap.element.GapElement_Rational'>
        sage: r.sage()
        41/152
        sage: type(_)
        <class 'sage.rings.rational.Rational'>

    Python

        >>> from sage.all import *
        >>> r = libgap(Integer(123)/Integer(456));  r
        41/152
        >>> type(_)
        <class 'sage.libs.gap.element.GapElement_Rational'>
        >>> r.sage()
        41/152
        >>> type(_)
        <class 'sage.rings.rational.Rational'>

class sage.libs.gap.element.GapElement_Record

  Bases: `GapElement`

  Derived class of GapElement for GAP records.

  EXAMPLES:

  Sage

      sage: rec = libgap.eval('rec(a:=123, b:=456)')
      sage: type(rec)
      <class 'sage.libs.gap.element.GapElement_Record'>
      sage: len(rec)
      2
      sage: rec['a']
      123

  Python

      >>> from sage.all import *
      >>> rec = libgap.eval('rec(a:=123, b:=456)')
      >>> type(rec)
      <class 'sage.libs.gap.element.GapElement_Record'>
      >>> len(rec)
      2
      >>> rec['a']
      123

  We can easily convert a Gap `rec` object into a Python `dict`:

  Sage

      sage: dict(rec)
      {'a': 123, 'b': 456}
      sage: type(_)
      <... 'dict'>

  [Python]

      >>> from sage.all import *
      >>> dict(rec)
      {'a': 123, 'b': 456}
      >>> type(_)
      <... 'dict'>

  Range checking is performed:

  Sage

      sage: rec['no_such_element']
      Traceback (most recent call last):
      ...
      GAPError: Error, Record Element: '<rec>.no_such_element' must have an assigned value

  Python

      >>> from sage.all import *
      >>> rec['no_such_element']
      Traceback (most recent call last):
      ...
      GAPError: Error, Record Element: '<rec>.no_such_element' must have an assigned value

  record_name_to_index(name)

    Convert string to GAP record index.

    INPUT:

    - `py_name` – a python string

    OUTPUT:

    A `UInt`, which is a GAP hash of the string. If this is the first time the string is encountered, a new integer is returned(!)

    EXAMPLES:

    Sage

        sage: rec = libgap.eval('rec(first:=123, second:=456)')
        sage: rec.record_name_to_index('first')   # random output
        1812
        sage: rec.record_name_to_index('no_such_name') # random output
        3776

    Python

        >>> from sage.all import *
        >>> rec = libgap.eval('rec(first:=123, second:=456)')
        >>> rec.record_name_to_index('first')   # random output
        1812
        >>> rec.record_name_to_index('no_such_name') # random output
        3776

  sage()

    Return the Sage equivalent of the `GapElement`.

    EXAMPLES:

    Sage

        sage: libgap.eval('rec(a:=1, b:=2)').sage()
        {'a': 1, 'b': 2}
        sage: all( isinstance(key,str) and val in ZZ for key,val in _.items() )
        True

        sage: rec = libgap.eval('rec(a:=123, b:=456, Sym3:=SymmetricGroup(3))')
        sage: rec.sage()
        {'Sym3': NotImplementedError('cannot construct equivalent Sage object'...),
         'a': 123,
         'b': 456}

    Python

        >>> from sage.all import *
        >>> libgap.eval('rec(a:=1, b:=2)').sage()
        {'a': 1, 'b': 2}
        >>> all( isinstance(key,str) and val in ZZ for key,val in _.items() )
        True

        >>> rec = libgap.eval('rec(a:=123, b:=456, Sym3:=SymmetricGroup(3))')
        >>> rec.sage()
        {'Sym3': NotImplementedError('cannot construct equivalent Sage object'...),
         'a': 123,
         'b': 456}

class sage.libs.gap.element.GapElement_RecordIterator

  Bases: `object`

  Iterator for `GapElement_Record`.

  Since Cython does not support generators yet, we implement the older iterator specification with this auxiliary class.

  INPUT:

  - `rec` – the `GapElement_Record` to iterate over

  EXAMPLES:

  Sage

      sage: rec = libgap.eval('rec(a:=123, b:=456)')
      sage: sorted(rec)
      [('a', 123), ('b', 456)]
      sage: dict(rec)
      {'a': 123, 'b': 456}

  Python

      >>> from sage.all import *
      >>> rec = libgap.eval('rec(a:=123, b:=456)')
      >>> sorted(rec)
      [('a', 123), ('b', 456)]
      >>> dict(rec)
      {'a': 123, 'b': 456}

class sage.libs.gap.element.GapElement_Ring

  Bases: `GapElement`

  Derived class of GapElement for GAP rings (parents of ring elements).

  EXAMPLES:

  Sage

      sage: i = libgap(ZZ)
      sage: type(i)
      <class 'sage.libs.gap.element.GapElement_Ring'>

  Python

      >>> from sage.all import *
      >>> i = libgap(ZZ)
      >>> type(i)
      <class 'sage.libs.gap.element.GapElement_Ring'>

  ring_cyclotomic()

    Construct a cyclotomic field.

    This method is not meant to be called directly, use `sage()` instead.

  ring_finite_field(var='a')

    Construct a finite field.

    This method is not meant to be called directly, use `sage()` instead.

    Note that for non-prime finite fields, this method is likely unintended, it always use the default-constructed finite field with `var` provided, which means the `DefiningPolynomial` of the GAP field is often not the same as the `.modulus()` of the Sage field. They are isomorphic, but the isomorphism may be difficult to compute.

    INPUT:

    - `var` – string (default: ‘a’); name of the generator of the finite field

  ring_integer()

    Construct the Sage integers.

    This method is not meant to be called directly, use `sage()` instead.

  ring_integer_mod()

    Construct a Sage integer mod ring.

    This method is not meant to be called directly, use `sage()` instead.

  ring_polynomial()

    Construct a polynomial ring.

    This method is not meant to be called directly, use `sage()` instead.

  ring_rational()

    Construct the Sage rationals.

    This method is not meant to be called directly, use `sage()` instead.

  sage(**kwds)

    Return the Sage equivalent of the `GapElement_Ring`.

    INPUT:

    - `**kwds` – keywords that are passed on to the `ring_` method

    OUTPUT: a Sage ring

    EXAMPLES:

    Sage

        sage: libgap.eval('Integers').sage()
        Integer Ring

        sage: libgap.eval('Rationals').sage()
        Rational Field

        sage: libgap.eval('ZmodnZ(15)').sage()
        Ring of integers modulo 15

        sage: libgap.GF(3,2).sage(var='A')
        Finite Field in A of size 3^2

        sage: libgap.CyclotomicField(6).sage()
        Cyclotomic Field of order 3 and degree 2

        sage: libgap(QQ['x','y']).sage()
        Multivariate Polynomial Ring in x, y over Rational Field

    Python

        >>> from sage.all import *
        >>> libgap.eval('Integers').sage()
        Integer Ring

        >>> libgap.eval('Rationals').sage()
        Rational Field

        >>> libgap.eval('ZmodnZ(15)').sage()
        Ring of integers modulo 15

        >>> libgap.GF(Integer(3),Integer(2)).sage(var='A')
        Finite Field in A of size 3^2

        >>> libgap.CyclotomicField(Integer(6)).sage()
        Cyclotomic Field of order 3 and degree 2

        >>> libgap(QQ['x','y']).sage()
        Multivariate Polynomial Ring in x, y over Rational Field

class sage.libs.gap.element.GapElement_String

  Bases: `GapElement`

  Derived class of GapElement for GAP strings.

  EXAMPLES:

  Sage

      sage: s = libgap('string')
      sage: type(s)
      <class 'sage.libs.gap.element.GapElement_String'>
      sage: s
      "string"
      sage: print(s)
      string

  Python

      >>> from sage.all import *
      >>> s = libgap('string')
      >>> type(s)
      <class 'sage.libs.gap.element.GapElement_String'>
      >>> s
      "string"
      >>> print(s)
      string

  sage()

    Convert this `GapElement_String` to a Python string.

    OUTPUT: a Python string

    EXAMPLES:

    Sage

        sage: s = libgap.eval(' "string" '); s
        "string"
        sage: type(_)
        <class 'sage.libs.gap.element.GapElement_String'>
        sage: str(s)
        'string'
        sage: s.sage()
        'string'
        sage: type(_)
        <class 'str'>

    Python

        >>> from sage.all import *
        >>> s = libgap.eval(' "string" '); s
        "string"
        >>> type(_)
        <class 'sage.libs.gap.element.GapElement_String'>
        >>> str(s)
        'string'
        >>> s.sage()
        'string'
        >>> type(_)
        <class 'str'>

sage.libs.gap.element.make_GapElement_Integer_from_sage_integer(parent, x)

  Internal helper to convert Sage `Integer` into GapElement objects. Not to be used directly, use `libgap(x)` instead.