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.
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
Return whether the wrapped GAP object is a GAP boolean.
OUTPUT:
Boolean.
EXAMPLES:
sage: libgap(True).is_bool()
True
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
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
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
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
Return whether the wrapped GAP object is a GAP string.
OUTPUT:
Boolean.
EXAMPLES:
sage: libgap('this is a string').is_string()
True
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]
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'>
Return all Gap function names.
OUTPUT:
A list of strings.
EXAMPLES:
sage: x = libgap(1)
sage: len(x.trait_names()) > 1000
True
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)
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'>
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
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'>
Return the Sage equivalent of the GapElement_Cyclotomic.
INPUT:
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
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'>
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
Return the Sage equivalent of the GapElement_FiniteField.
INPUT:
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
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'>
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'>
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
Return the Sage equivalent of the GapElement_Integer
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
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'>
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'>
Return the Sage equivalent of the GapElement_IntegerMod
INPUT:
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
Bases: sage.libs.gap.element.GapElement
Derived class of GapElement for GAP Lists.
Note
Lists are indexed by , as expected from
Python. This differs from the GAP convention where lists start
at
.
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.
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
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 ]
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'>
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'>
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'>
Return the Sage equivalent of the GapElement.
INPUT:
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'>
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
Convert string to GAP record index.
INPUT:
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
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()
{'a': 123,
'Sym3': NotImplementedError('cannot construct equivalent Sage object',),
'b': 456}
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}
x.next() -> the next value, or raise StopIteration
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'>
Construct an integer ring.
EXAMPLES:
sage: libgap.CyclotomicField(6).ring_cyclotomic()
Cyclotomic Field of order 3 and degree 2
Construct an integer ring.
EXAMPLES:
sage: libgap.GF(3,2).ring_finite_field(var='A')
Finite Field in A of size 3^2
Construct the Sage integers.
EXAMPLES:
sage: libgap.eval('Integers').ring_integer()
Integer Ring
Construct a Sage integer mod ring.
EXAMPLES:
sage: libgap.eval('ZmodnZ(15)').ring_integer_mod()
Ring of integers modulo 15
Construct the Sage rationals.
EXAMPLES:
sage: libgap.eval('Rationals').ring_rational()
Rational Field
Return the Sage equivalent of the GapElement_Ring.
INPUT:
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
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'>
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'>