This module implements an interface to GAP3.
AUTHORS:
Warning
GAP3 is not distrubuted with Sage. You need to install it separately; see the section Obtaining GAP3.
The GAP3 interface will only work if GAP3 is installed on your computer. Here are some ways to obtain GAP3:
There is an optional Sage package providing GAP3 pre-packaged with several GAP3 packages:
Frank Luebeck maintains a GAP3 Linux executable, optimized for i686 and statically linked for jobs of 2 GByte or more:
Jean Michel maintains a version of GAP3 pre-packaged with CHEVIE and VKCURVE. It can be obtained here:
Finally, you can download GAP3 from the GAP website below. Since GAP3 is no longer supported, it may not be easy to install this version.
Warning
There is a bug in the pexpect module (see trac ticket #8471) that prevents the following from working correctly. For now, just make sure that gap3 is in your PATH.
Sage assumes that GAP3 can be launched with the command gap3; that is, Sage assumes that the command gap3 is in your PATH. If this is not the case, then you can start GAP3 using the following command:
sage: gap3 = Gap3(command='/usr/local/bin/gap3') #not tested
The interface to GAP3 offers the following functionality.
gap3(expr) - Evaluation of arbitrary GAP3 expressions, with the result returned as a Sage object wrapping the corresponding GAP3 element:
sage: a = gap3('3+2') #optional - gap3
sage: a #optional - gap3
5
sage: type(a) #optional - gap3
<class 'sage.interfaces.gap3.GAP3Element'>
sage: S5 = gap3('SymmetricGroup(5)') #optional - gap3
sage: S5 #optional - gap3
Group( (1,5), (2,5), (3,5), (4,5) )
sage: type(S5) #optional - gap3
<class 'sage.interfaces.gap3.GAP3Record'>
This provides a Pythonic interface to GAP3. If gap_function is the name of a GAP3 function, then the syntax gap_element.gap_function() returns the gap_element obtained by evaluating the command gap_function(gap_element) in GAP3:
sage: S5.Size() #optional - gap3
120
sage: S5.CharTable() #optional - gap3
CharTable( Group( (1,5), (2,5), (3,5), (4,5) ) )
Alternatively, you can instead use the syntax gap3.gap_function(gap_element):
sage: gap3.DerivedSeries(S5) #optional - gap3
[ Group( (1,5), (2,5), (3,5), (4,5) ),
Subgroup( Group( (1,5), (2,5), (3,5), (4,5) ),
[ (1,2,5), (1,3,5), (1,4,5) ] ) ]
If gap_element corresponds to a GAP3 record, then gap_element.recfield provides a means to access the record element corresponding to the field recfield:
sage: S5.IsRec() #optional - gap3
true
sage: S5.recfields() #optional - gap3
['isDomain', 'isGroup', 'identity', 'generators', 'operations',
'isPermGroup', 'isFinite', '1', '2', '3', '4', 'degree']
sage: S5.identity #optional - gap3
()
sage: S5.degree #optional - gap3
5
sage: S5.1 #optional - gap3
(1,5)
sage: S5.2 #optional - gap3
(2,5)
By typing %gap3 or gap3.interact() at the command-line, you can interact directly with the underlying GAP3 session.
sage: gap3.interact() #not tested
--> Switching to Gap3 <--
gap3:
You can start a new GAP3 session as follows:
sage: gap3.console() #not tested
######## Lehrstuhl D fuer Mathematik
### #### RWTH Aachen
## ##
## # ####### #########
## # ## ## # ##
## # # ## # ##
#### ## ## # # ##
##### ### ## ## ## ##
######### # ######### #######
# #
## Version 3 #
### Release 4.4 #
## # 18 Apr 97 #
## #
## # Alice Niemeyer, Werner Nickel, Martin Schoenert
## # Johannes Meier, Alex Wegner, Thomas Bischops
## # Frank Celler, Juergen Mnich, Udo Polis
### ## Thomas Breuer, Goetz Pfeiffer, Hans U. Besche
###### Volkmar Felsch, Heiko Theissen, Alexander Hulpke
Ansgar Kaup, Akos Seress, Erzsebet Horvath
Bettina Eick
For help enter: ?<return>
gap>
The interface also has access to the GAP3 help system:
sage: gap3.help('help', pager=False) #not tested
Help _______________________________________________________...
This section describes together with the following sections the GAP
help system. The help system lets you read the manual interactively...
If you want to pass a string to GAP3, then you need to wrap it in single quotes as follows:
sage: gap3('"This is a GAP3 string"') #optional - gap3
"This is a GAP3 string"
This is particularly important when a GAP3 package is loaded via the RequirePackage method (note that one can instead use the load_package method):
sage: gap3.RequirePackage('"chevie"') #optional - gap3chevie
W... to the CHEVIE package, ...
Load a GAP3 package:
sage: gap3.load_package("chevie") #optional - gap3chevie
sage: gap3.version() # random #optional - gap3
'lib: v3r4p4 1997/04/18, src: v3r4p0 1994/07/10, sys: usg gcc ansi'
Working with GAP3 lists. Note that GAP3 lists are 1-indexed:
sage: L = gap3([1,2,3]) #optional - gap3
sage: L[1] #optional - gap3
1
sage: L[2] #optional - gap3
2
sage: 3 in L #optional - gap3
True
sage: 4 in L #optional - gap3
False
sage: m = gap3([[1,2],[3,4]]) #optional - gap3
sage: m[2,1] #optional - gap3
3
sage: [1,2] in m #optional - gap3
True
sage: [3,2] in m #optional - gap3
False
sage: gap3([1,2]) in m #optional - gap3
True
Controlling variable names used by GAP3:
sage: gap3('2', name='x') #optional - gap3
2
sage: gap3('x') #optional - gap3
2
sage: gap3.unbind('x') #optional - gap3
sage: gap3('x') #optional - gap3
...
TypeError: Gap3 produced error output
Error, Variable: 'x' must have a value
...
Bases: sage.interfaces.gap.GapElement_generic
A GAP3 element
Note
If the corresponding GAP3 element is a GAP3 record, then the class is changed to a GAP3Record.
INPUT:
Note
If you pass E, X or Z for name, then an error is raised because these are sacred variable names in GAP3 that should never be redefined. Sage raises an error because GAP3 does not!
EXAMPLES:
sage: from sage.interfaces.gap3 import GAP3Element #optional - gap3
sage: gap3 = Gap3() #optional - gap3
sage: GAP3Element(gap3, value='3+2') #optional - gap3
5
sage: GAP3Element(gap3, value='sage0', is_name=True) #optional - gap3
5
TESTS:
sage: GAP3Element(gap3, value='3+2', is_name=False, name='X') #optional - gap3
...
ValueError: you are attempting to redefine X; but you should never redefine E, X or Z in gap3 (because things will break!)
AUTHORS:
Bases: sage.interfaces.gap3.GAP3Element
A GAP3 record
Note
This class should not be called directly, use GAP3Element instead. If the corresponding GAP3 element is a GAP3 record, then the class is changed to a GAP3Record.
AUTHORS:
Return a list of the GAP3 operations for the record.
OUTPUT:
EXAMPLES:
sage: S5 = gap3.SymmetricGroup(5) #optional - gap3
sage: S5.operations() #optional - gap3
[..., 'NormalClosure', 'NormalIntersection', 'Normalizer',
'NumberConjugacyClasses', 'PCore', 'Radical', 'SylowSubgroup',
'TrivialSubgroup', 'FusionConjugacyClasses', 'DerivedSeries', ...]
sage: S5.DerivedSeries() #optional - gap3
[ Group( (1,5), (2,5), (3,5), (4,5) ),
Subgroup( Group( (1,5), (2,5), (3,5), (4,5) ),
[ (1,2,5), (1,3,5), (1,4,5) ] ) ]
Return a list of the fields for the record. (Record fields are akin to object attributes in Sage.)
OUTPUT:
EXAMPLES:
sage: S5 = gap3.SymmetricGroup(5) #optional - gap3
sage: S5.recfields() #optional - gap3
['isDomain', 'isGroup', 'identity', 'generators',
'operations', 'isPermGroup', 'isFinite', '1', '2',
'3', '4', 'degree']
sage: S5.degree #optional - gap3
5
Defines the list of methods and attributes that will appear for tab completion.
OUTPUT:
EXAMPLES:
sage: S5 = gap3.SymmetricGroup(5) #optional - gap3
sage: S5.trait_names() #optional - gap3
[..., 'ConjugacyClassesTry', 'ConjugateSubgroup', 'ConjugateSubgroups',
'Core', 'DegreeOperation', 'DerivedSeries', 'DerivedSubgroup',
'Difference', 'DimensionsLoewyFactors', 'DirectProduct', ...]
Bases: sage.interfaces.gap.Gap_generic
A simple Expect interface to GAP3.
EXAMPLES:
sage: from sage.interfaces.gap3 import Gap3
sage: gap3 = Gap3(command='gap3')
TESTS:
sage: gap3(2) == gap3(3) #optional - gap3
False
sage: gap3(2) == gap3(2) #optional - gap3
True
sage: gap3.trait_names() #optional - gap3
[]
We test the interface behaves correctly after a keyboard interrupt:
sage: gap3(2) #optional - gap3
2
sage: try:
... gap3._keyboard_interrupt()
... except:
... pass #optional - gap3
Interrupting Gap3...
sage: gap3(2) #optional - gap3
2
We test that the interface busts out of GAP3’s break loop correctly:
sage: f = gap3('function(L) return L[0]; end;;') #optional - gap3
sage: f([1,2,3]) #optional - gap3
...
RuntimeError: Gap3 produced error output
Error, List Element: <position> must be a positive integer at
return L[0] ...
AUTHORS:
Spawn a new GAP3 command-line session.
EXAMPLES:
sage: gap3.console() #not tested
######## Lehrstuhl D fuer Mathematik
### #### RWTH Aachen
## ##
## # ####### #########
## # ## ## # ##
## # # ## # ##
#### ## ## # # ##
##### ### ## ## ## ##
######### # ######### #######
# #
## Version 3 #
### Release 4.4 #
## # 18 Apr 97 #
## #
## # Alice Niemeyer, Werner Nickel, Martin Schoenert
## # Johannes Meier, Alex Wegner, Thomas Bischops
## # Frank Celler, Juergen Mnich, Udo Polis
### ## Thomas Breuer, Goetz Pfeiffer, Hans U. Besche
###### Volkmar Felsch, Heiko Theissen, Alexander Hulpke
Ansgar Kaup, Akos Seress, Erzsebet Horvath
Bettina Eick
For help enter: ?<return>
gap>
Returns the amount of CPU time that the GAP session has used in seconds. If t is not None, then it returns the difference between the current CPU time and t.
EXAMPLES:
sage: t = gap3.cputime() #optional - gap3
sage: t #random #optional - gap3
0.02
sage: gap3.SymmetricGroup(5).Size() #optional - gap3
120
sage: gap3.cputime() #random #optional - gap3
0.14999999999999999
sage: gap3.cputime(t) #random #optional - gap3
0.13
Print help on the given topic.
INPUT:
EXAMPLES:
sage: gap3.help('help', pager=False) #optional - gap3
Help _______________________________________________________...
<BLANKLINE>
This section describes together with the following sectio...
help system. The help system lets you read the manual inter...
sage: gap3.help('SymmetricGroup', pager=False) #optional - gap3
no section with this name was found
TESTS:
sage: m = gap3([[1,2,3],[4,5,6]]); m #optional - gap3
[ [ 1, 2, 3 ], [ 4, 5, 6 ] ]
sage: gap3.help('help', pager=False) #optional - gap3
Help _______________________________________________________...
sage: m #optional - gap3
[ [ 1, 2, 3 ], [ 4, 5, 6 ] ]
sage: m.Print() #optional - gap3
[ [ 1, 2, 3 ], [ 4, 5, 6 ] ]
sage: gap3.help('Group', pager=False) #optional - gap3
Group ______________________________________________________...
sage: m #optional - gap3
[ [ 1, 2, 3 ], [ 4, 5, 6 ] ]
sage: m.Print() #optional - gap3
[ [ 1, 2, 3 ], [ 4, 5, 6 ] ]
Spawn a new GAP3 command-line session.
EXAMPLES:
sage: gap3.console() #not tested
######## Lehrstuhl D fuer Mathematik
### #### RWTH Aachen
## ##
## # ####### #########
## # ## ## # ##
## # # ## # ##
#### ## ## # # ##
##### ### ## ## ## ##
######### # ######### #######
# #
## Version 3 #
### Release 4.4 #
## # 18 Apr 97 #
## #
## # Alice Niemeyer, Werner Nickel, Martin Schoenert
## # Johannes Meier, Alex Wegner, Thomas Bischops
## # Frank Celler, Juergen Mnich, Udo Polis
### ## Thomas Breuer, Goetz Pfeiffer, Hans U. Besche
###### Volkmar Felsch, Heiko Theissen, Alexander Hulpke
Ansgar Kaup, Akos Seress, Erzsebet Horvath
Bettina Eick
For help enter: ?<return>
gap>
Return the version of GAP3 that you have in your PATH on your computer.
EXAMPLES:
sage: gap3_version() # random, optional - gap3
'lib: v3r4p4 1997/04/18, src: v3r4p0 1994/07/10, sys: usg gcc ansi'