### Navigation

- index
- modules |
- next |
- previous |
- C/C++ Library Interfaces »

# libGAP element wrapper

libGAP element wrapper

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

class `sage.libs.gap.element.``GapElement`

  Bases: `sage.structure.element.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: libgap(0)
      0

  If Gap finds an error while evaluating, a corresponding assertion is raised:

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

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

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

  `is_bool`()

    Return whether the wrapped GAP object is a GAP boolean.

    OUTPUT:

    Boolean.

    EXAMPLES:

        sage: libgap(True).is_bool()
        True

  `is_function`()

    Return whether the wrapped GAP object is a function.

    OUTPUT:

    Boolean.

    EXAMPLES:

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

  `is_list`()

    Return whether the wrapped GAP object is a GAP List.

    OUTPUT:

    Boolean.

    EXAMPLES:

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

  `is_permutation`()

    Return whether the wrapped GAP object is a GAP permutation.

    OUTPUT:

    Boolean.

    EXAMPLES:

        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

  `is_record`()

    Return whether the wrapped GAP object is a GAP record.

    OUTPUT:

    Boolean.

    EXAMPLES:

        sage: libgap.eval('[1, 2,,,, 5]').is_record()
        False
        sage: 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: libgap('this is a string').is_string()
        True

  `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: m = libgap.eval('[[Z(2^2), Z(2)^0],[0*Z(2), Z(2^2)^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]

    GAP is also starting to introduce a specialized matrix type. Currently, you need to use `Unpack` to convert it back to a list-of-lists:

        sage: M = libgap.eval('SL(2,GF(5))').GeneratorsOfGroup()[1]
        sage: type(M)       # not a GAP list
        <type 'sage.libs.gap.element.GapElement'>
        sage: M.IsMatrix()
        true
        sage: M.matrix()
        [4 1]
        [4 0]

  `sage`()

    Return the Sage equivalent of the `GapElement`

    EXAMPLES:

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

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

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

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

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

  `trait_names`()

    Return all Gap function names.

    OUTPUT:

    A list of strings.

    EXAMPLES:

        sage: x = libgap(1)
        sage: len(x.trait_names()) > 1000
        True

  `vector`(ring=None)

    Return the list as a vector.

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

    OUTPUT:

    A Sage vector.

    EXAMPLES:

        sage: m = libgap.eval('[0*Z(2), Z(2^2), Z(2)^0, Z(2^2)^2]');  m
        [ 0*Z(2), Z(2^2), Z(2)^0, Z(2^2)^2 ]
        sage: vector(m)
        (0, a, 1, a + 1)
        sage: vector(GF(4,'B'), m)
        (0, B, 1, B + 1)

class `sage.libs.gap.element.``GapElement_Boolean`

  Bases: `sage.libs.gap.element.GapElement`

  Derived class of GapElement for GAP boolean values.

  EXAMPLES:

      sage: b = libgap(True)
      sage: type(b)
      <type '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: b = libgap.eval('true');  b
        true
        sage: type(_)
        <type 'sage.libs.gap.element.GapElement_Boolean'>
        sage: b.sage()
        True
        sage: type(_)
        <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

class `sage.libs.gap.element.``GapElement_Cyclotomic`

  Bases: `sage.libs.gap.element.GapElement`

  Derived class of GapElement for GAP universal cyclotomics.

  EXAMPLES:

      sage: libgap.eval('E(3)')
      E(3)
      sage: type(_)
      <type '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: 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

    TESTS:

    Check that trac ticket #15204 is fixed:

        sage: libgap.E(3).sage(ring=UniversalCyclotomicField())
        E(3)
        sage: libgap.E(3).sage(ring=CC)
        -0.500000000000000 + 0.866025403784439*I

class `sage.libs.gap.element.``GapElement_FiniteField`

  Bases: `sage.libs.gap.element.GapElement`

  Derived class of GapElement for GAP finite field elements.

  EXAMPLES:

      sage: libgap.eval('Z(5)^2')
      Z(5)^2
      sage: type(_)
      <type '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: n = libgap.eval('Z(5)^2')
        sage: n.lift()
        4
        sage: type(_)
        <type '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

  `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:

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

    EXAMPLES:

        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 finite field has incompatible size

class `sage.libs.gap.element.``GapElement_Function`

  Bases: `sage.libs.gap.element.GapElement`

  Derived class of GapElement for GAP functions.

  EXAMPLES:

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

class `sage.libs.gap.element.``GapElement_Integer`

  Bases: `sage.libs.gap.element.GapElement`

  Derived class of GapElement for GAP rational numbers.

  EXAMPLES:

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

  `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: n = libgap(1)
        sage: type(n)
        <type 'sage.libs.gap.element.GapElement_Integer'>
        sage: n.is_C_int()
        True
        sage: n.IsInt()
        true

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

  `sage`(ring=None)

    Return the Sage equivalent of the `GapElement_Integer`

    - `ring` – Integer ring or `None` (default). If not specified, a the default Sage integer ring is used.

    OUTPUT:

    A Sage integer

    EXAMPLES:

        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

    TESTS:

        sage: large = libgap.eval('2^130');  large
        1361129467683753853853498429727072845824
        sage: large.sage()
        1361129467683753853853498429727072845824

        sage: huge = libgap.eval('10^9999');  huge     # gap abbreviates very long ints
        <integer 100...000 (10000 digits)>
        sage: huge.sage().ndigits()
        10000

class `sage.libs.gap.element.``GapElement_IntegerMod`

  Bases: `sage.libs.gap.element.GapElement`

  Derived class of GapElement for GAP integers modulo an integer.

  EXAMPLES:

      sage: n = IntegerModRing(123)(13)
      sage: i = libgap(n)
      sage: type(i)
      <type '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: n = libgap.eval('One(ZmodnZ(123)) * 13')
        sage: n.lift()
        13
        sage: type(_)
        <type '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 ringa is used automatically.

    OUTPUT:

    A Sage integer modulo another integer.

    EXAMPLES:

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

class `sage.libs.gap.element.``GapElement_List`

  Bases: `sage.libs.gap.element.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: lst = libgap.SymmetricGroup(3).List(); lst
      [ (), (1,3), (1,2,3), (2,3), (1,3,2), (1,2) ]
      sage: type(lst)
      <type 'sage.libs.gap.element.GapElement_List'>
      sage: len(lst)
      6
      sage: lst[3]
      (2,3)

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

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

  Range checking is performed:

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

  `sage`(**kwds)

    Return the Sage equivalent of the `GapElement`

    OUTPUT:

    A Python list.

    EXAMPLES:

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

class `sage.libs.gap.element.``GapElement_MethodProxy`

  Bases: `sage.libs.gap.element.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: lst = libgap([])
      sage: lst.Add
      <Gap function "Add">
      sage: type(_)
      <type 'sage.libs.gap.element.GapElement_MethodProxy'>
      sage: lst.Add(1)
      sage: lst
      [ 1 ]

class `sage.libs.gap.element.``GapElement_Permutation`

  Bases: `sage.libs.gap.element.GapElement`

  Derived class of GapElement for GAP permutations.

  Note

  Permutations in GAP act on the numbers starting with 1.

  EXAMPLES:

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

  `sage`()

    Return the Sage equivalent of the `GapElement`

    EXAMPLES:

        sage: perm_gap = libgap.eval('(1,5,2)(4,3,8)');  perm_gap
        (1,5,2)(3,8,4)
        sage: perm_gap.sage()
        (1,5,2)(3,8,4)
        sage: type(_)
        <type 'sage.groups.perm_gps.permgroup_element.PermutationGroupElement'>

class `sage.libs.gap.element.``GapElement_Rational`

  Bases: `sage.libs.gap.element.GapElement`

  Derived class of GapElement for GAP rational numbers.

  EXAMPLES:

      sage: r = libgap(123/456)
      sage: type(r)
      <type '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: r = libgap(123/456);  r
        41/152
        sage: type(_)
        <type 'sage.libs.gap.element.GapElement_Rational'>
        sage: r.sage()
        41/152
        sage: type(_)
        <type 'sage.rings.rational.Rational'>

class `sage.libs.gap.element.``GapElement_Record`

  Bases: `sage.libs.gap.element.GapElement`

  Derived class of GapElement for GAP records.

  EXAMPLES:

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

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

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

  Range checking is performed:

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

  `record_name_to_index`(py_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(!)

    EXAMPLE:

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

  `sage`()

    Return the Sage equivalent of the `GapElement`

    EXAMPLES:

        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}

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: rec = libgap.eval('rec(a:=123, b:=456)')
      sage: list(rec)
      [('a', 123), ('b', 456)]
      sage: dict(rec)
      {'a': 123, 'b': 456}

  `next`()

    x.next() -> the next value, or raise StopIteration

class `sage.libs.gap.element.``GapElement_Ring`

  Bases: `sage.libs.gap.element.GapElement`

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

  EXAMPLES:

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

  `ring_cyclotomic`()

    Construct an integer ring.

    EXAMPLES:

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

  `ring_finite_field`(var='a')

    Construct an integer ring.

    EXAMPLES:

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

  `ring_integer`()

    Construct the Sage integers.

    EXAMPLES:

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

  `ring_integer_mod`()

    Construct a Sage integer mod ring.

    EXAMPLES:

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

  `ring_rational`()

    Construct the Sage rationals.

    EXAMPLES:

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

  `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: 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

class `sage.libs.gap.element.``GapElement_String`

  Bases: `sage.libs.gap.element.GapElement`

  Derived class of GapElement for GAP strings.

  EXAMPLES:

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

  `sage`()

    Return the Sage equivalent of the `GapElement`

    OUTPUT:

    A Python list.

    EXAMPLES:

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

### Navigation

- index
- modules |
- next |
- previous |
- C/C++ Library Interfaces »