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:

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'>

Previous topic

libGAP shared library Interface to GAP

Next topic

FLINT fmpz_poly class wrapper

This Page