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: libgap(0)
0

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

sage: 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: 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: 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
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
sage()#

Return the Sage equivalent of the GapElement

EXAMPLES:

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
class sage.libs.gap.element.GapElement_Boolean#

Bases: GapElement

Derived class of GapElement for GAP boolean values.

EXAMPLES:

sage: b = libgap(True)
sage: 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: 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
class sage.libs.gap.element.GapElement_Cyclotomic#

Bases: GapElement

Derived class of GapElement for GAP universal cyclotomics.

EXAMPLES:

sage: libgap.eval('E(3)')
E(3)
sage: 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: 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
class sage.libs.gap.element.GapElement_FiniteField#

Bases: GapElement

Derived class of GapElement for GAP finite field elements.

EXAMPLES:

sage: libgap.eval('Z(5)^2')
Z(5)^2
sage: 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: 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
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: 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 ...
class sage.libs.gap.element.GapElement_Float#

Bases: GapElement

Derived class of GapElement for GAP floating point numbers.

EXAMPLES:

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
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: a = libgap.eval("Float(3.25)").sage()
sage: a
3.25
sage: parent(a)
Real Double Field
class sage.libs.gap.element.GapElement_Function#

Bases: GapElement

Derived class of GapElement for GAP functions.

EXAMPLES:

sage: f = libgap.Cycles
sage: 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: i = libgap(123)
sage: type(i)
<class 'sage.libs.gap.element.GapElement_Integer'>
sage: 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: 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
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
class sage.libs.gap.element.GapElement_IntegerMod#

Bases: GapElement

Derived class of GapElement for GAP integers modulo an integer.

EXAMPLES:

sage: n = IntegerModRing(123)(13)
sage: i = libgap(n)
sage: 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: n = libgap.eval('One(ZmodnZ(123)) * 13')
sage: n.lift()
13
sage: 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 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: 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)
<class '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(_)
<... 'list'>

Range checking is performed:

sage: lst[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: 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]
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
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: 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)
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: lst = libgap([])
sage: lst.Add
<Gap function "Add">
sage: type(_)
<class 'sage.libs.gap.element.GapElement_MethodProxy'>
sage: lst.Add(1)
sage: 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: perm = libgap.eval('(1,5,2)(4,3,8)')
sage: 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: 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'>
class sage.libs.gap.element.GapElement_Rational#

Bases: GapElement

Derived class of GapElement for GAP rational numbers.

EXAMPLES:

sage: r = libgap(123/456)
sage: 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: 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'>
class sage.libs.gap.element.GapElement_Record#

Bases: GapElement

Derived class of GapElement for GAP records.

EXAMPLES:

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

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

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

Range checking is performed:

sage: 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: 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
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: sorted(rec)
[('a', 123), ('b', 456)]
sage: 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: i = libgap(ZZ)
sage: type(i)
<class '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_polynomial()#

Construct a polynomial ring.

EXAMPLES:

sage: B = libgap(QQ['x'])
sage: B.ring_polynomial()
Univariate Polynomial Ring in x over Rational Field

sage: B = libgap(ZZ['x','y'])
sage: B.ring_polynomial()
Multivariate Polynomial Ring in x, y over Integer Ring
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

sage: 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: s = libgap('string')
sage: type(s)
<class 'sage.libs.gap.element.GapElement_String'>
sage: s
"string"
sage: print(s)
string
sage()#

Convert this GapElement_String to a Python string.

OUTPUT:

A Python string.

EXAMPLES:

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