Interface to GAP3

This module implements an interface to GAP3.

AUTHORS:

  • Franco Saliola (February 2010)

  • Christian Stump (March 2016)

Note

The optional package for GAP3 is Jean Michel’s pre-packaged GAP3, which is a minimal GAP3 distribution containing packages that have no equivalent in GAP4, see package gap3.

Obtaining GAP3

Instead of installing the optional GAP3 package, one can as well install by hand the following version of GAP3:

Changing which GAP3 is used

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

>>> from sage.all import *
>>> gap3 = Gap3(command='/usr/local/bin/gap3')            # not tested

gap3 = Gap3(command='/usr/local/bin/gap3')            # not tested

Functionality and Examples

The interface to GAP3 offers the following functionality.

  1. gap3(expr) – evaluation of arbitrary GAP3 expressions, with the result returned as a Sage object wrapping the corresponding GAP3 element:

    sage: # optional - gap3
sage: a = gap3('3+2')
sage: a
5
sage: type(a)
<class 'sage.interfaces.gap3.GAP3Element'>

    >>> from sage.all import *
>>> # optional - gap3
>>> a = gap3('3+2')
>>> a
5
>>> type(a)
<class 'sage.interfaces.gap3.GAP3Element'>

    # optional - gap3
a = gap3('3+2')
a
type(a)

    sage: # optional - gap3
sage: S5 = gap3('SymmetricGroup(5)')
sage: S5
Group( (1,5), (2,5), (3,5), (4,5) )
sage: type(S5)
<class 'sage.interfaces.gap3.GAP3Record'>

    >>> from sage.all import *
>>> # optional - gap3
>>> S5 = gap3('SymmetricGroup(5)')
>>> S5
Group( (1,5), (2,5), (3,5), (4,5) )
>>> type(S5)
<class 'sage.interfaces.gap3.GAP3Record'>

    # optional - gap3
S5 = gap3('SymmetricGroup(5)')
S5
type(S5)

    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: # optional - gap3
sage: S5.Size()
120
sage: S5.CharTable()
CharTable( Group( (1,5), (2,5), (3,5), (4,5) ) )

    >>> from sage.all import *
>>> # optional - gap3
>>> S5.Size()
120
>>> S5.CharTable()
CharTable( Group( (1,5), (2,5), (3,5), (4,5) ) )

    # optional - gap3
S5.Size()
S5.CharTable()

    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) ] ) ]

    >>> from sage.all import *
>>> 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) ] ) ]

    gap3.DerivedSeries(S5)                       #optional - gap3

    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: # optional - gap3
sage: S5.IsRec()
true
sage: S5.recfields()
['isDomain', 'isGroup', 'identity', 'generators', 'operations',
'isPermGroup', 'isFinite', '1', '2', '3', '4', 'degree']
sage: S5.identity
()
sage: S5.degree
5
sage: S5.1
(1,5)
sage: S5.2
(2,5)

    >>> from sage.all import *
>>> # optional - gap3
>>> S5.IsRec()
true
>>> S5.recfields()
['isDomain', 'isGroup', 'identity', 'generators', 'operations',
'isPermGroup', 'isFinite', '1', '2', '3', '4', 'degree']
>>> S5.identity
()
>>> S5.degree
5
>>> S5.gen(1)
(1,5)
>>> S5.gen(2)
(2,5)

    # optional - gap3
S5.IsRec()
S5.recfields()
S5.identity
S5.degree
S5.1
S5.2

  2. 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:

    >>> from sage.all import *
>>> gap3.interact()                            # not tested

  --> Switching to Gap3 <--

gap3:

    gap3.interact()                            # not tested

  3. 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>

    >>> from sage.all import *
>>> 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>

    gap3.console()                             # not tested

  4. 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...

    >>> from sage.all import *
>>> 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...

    gap3.help('help', pager=False)             # not tested

Common Pitfalls

  1. 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"

    >>> from sage.all import *
>>> gap3('"This is a GAP3 string"')              #optional - gap3
"This is a GAP3 string"

    gap3('"This is a GAP3 string"')              #optional - gap3

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

    >>> from sage.all import *
>>> gap3.RequirePackage('"chevie"')             #optional - gap3

    gap3.RequirePackage('"chevie"')             #optional - gap3

Examples

Load a GAP3 package:

sage: # optional - gap3
sage: gap3.load_package("chevie")
sage: gap3.version() # random  # not tested
'lib: v3r4p4 1997/04/18, src: v3r4p0 1994/07/10, sys: usg gcc ansi'

>>> from sage.all import *
>>> # optional - gap3
>>> gap3.load_package("chevie")
>>> gap3.version() # random  # not tested
'lib: v3r4p4 1997/04/18, src: v3r4p0 1994/07/10, sys: usg gcc ansi'

# optional - gap3
gap3.load_package("chevie")
gap3.version() # random  # not tested

Working with GAP3 lists. Note that GAP3 lists are 1-indexed:

sage: # optional - gap3
sage: L = gap3([1,2,3])
sage: L[1]
1
sage: L[2]
2
sage: 3 in L
True
sage: 4 in L
False
sage: m = gap3([[1,2],[3,4]])
sage: m[2,1]
3
sage: [1,2] in m
True
sage: [3,2] in m
False
sage: gap3([1,2]) in m
True

>>> from sage.all import *
>>> # optional - gap3
>>> L = gap3([Integer(1),Integer(2),Integer(3)])
>>> L[Integer(1)]
1
>>> L[Integer(2)]
2
>>> Integer(3) in L
True
>>> Integer(4) in L
False
>>> m = gap3([[Integer(1),Integer(2)],[Integer(3),Integer(4)]])
>>> m[Integer(2),Integer(1)]
3
>>> [Integer(1),Integer(2)] in m
True
>>> [Integer(3),Integer(2)] in m
False
>>> gap3([Integer(1),Integer(2)]) in m
True

# optional - gap3
L = gap3([1,2,3])
L[1]
L[2]
3 in L
4 in L
m = gap3([[1,2],[3,4]])
m[2,1]
[1,2] in m
[3,2] in m
gap3([1,2]) in m

Controlling variable names used by GAP3:

sage: # optional - gap3
sage: a = gap3('2', name='x'); a
2
sage: gap3('x')
2
sage: gap3.unbind('x')
sage: gap3('x')
Traceback (most recent call last):
...
TypeError: Gap3 produced error output
Error, Variable: 'x' must have a value
...

>>> from sage.all import *
>>> # optional - gap3
>>> a = gap3('2', name='x'); a
2
>>> gap3('x')
2
>>> gap3.unbind('x')
>>> gap3('x')
Traceback (most recent call last):
...
TypeError: Gap3 produced error output
Error, Variable: 'x' must have a value
...

# optional - gap3
a = gap3('2', name='x'); a
gap3('x')
gap3.unbind('x')
gap3('x')

The Python wrapper can outlive an explicit unbind without corrupting a later GAP value when it is collected:

sage: b = gap3(3)
sage: del a
sage: import gc; _ = gc.collect()
sage: c = gap3(4)
sage: b
3

>>> from sage.all import *
>>> b = gap3(Integer(3))
>>> del a
>>> import gc; _ = gc.collect()
>>> c = gap3(Integer(4))
>>> b
3

b = gap3(3)
del a
import gc; _ = gc.collect()
c = gap3(4)
b
class sage.interfaces.gap3.GAP3Element(parent, value, is_name=False, name=None)[source]

Bases: GapElement_generic

A GAP3 element.

Note

If the corresponding GAP3 element is a GAP3 record, then the class is changed to a GAP3Record.

INPUT:

  • parent – the GAP3 session

  • value – the GAP3 command as a string

  • is_name – boolean (default: False); if True, then value is the variable name for the object

  • name – string (default: None); the variable name to use for the object. If None, then a variable name is generated

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: # optional - gap3
sage: from sage.interfaces.gap3 import GAP3Element
sage: gap3 = Gap3()
sage: GAP3Element(gap3, value='3+2')
5
sage: GAP3Element(gap3, value='sage0', is_name=True)
5

>>> from sage.all import *
>>> # optional - gap3
>>> from sage.interfaces.gap3 import GAP3Element
>>> gap3 = Gap3()
>>> GAP3Element(gap3, value='3+2')
5
>>> GAP3Element(gap3, value='sage0', is_name=True)
5

# optional - gap3
from sage.interfaces.gap3 import GAP3Element
gap3 = Gap3()
GAP3Element(gap3, value='3+2')
GAP3Element(gap3, value='sage0', is_name=True)

AUTHORS:

  • Franco Saliola (Feb 2010)

class sage.interfaces.gap3.GAP3Record(parent, value, is_name=False, name=None)[source]

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

  • Franco Saliola (Feb 2010)

operations()[source]

Return a list of the GAP3 operations for the record.

OUTPUT: list of strings – operations of the record

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) ] ) ]

>>> from sage.all import *
>>> S5 = gap3.SymmetricGroup(Integer(5))              #optional - gap3
>>> S5.operations()                          #optional - gap3
[..., 'NormalClosure', 'NormalIntersection', 'Normalizer',
'NumberConjugacyClasses', 'PCore', 'Radical', 'SylowSubgroup',
'TrivialSubgroup', 'FusionConjugacyClasses', 'DerivedSeries', ...]
>>> 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) ] ) ]

S5 = gap3.SymmetricGroup(5)              #optional - gap3
S5.operations()                          #optional - gap3
S5.DerivedSeries()                       #optional - gap3
recfields()[source]

Return a list of the fields for the record. (Record fields are akin to object attributes in Sage.)

OUTPUT: list of strings – the field records

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

>>> from sage.all import *
>>> S5 = gap3.SymmetricGroup(Integer(5))              #optional - gap3
>>> S5.recfields()                           #optional - gap3
['isDomain', 'isGroup', 'identity', 'generators',
 'operations', 'isPermGroup', 'isFinite', '1', '2',
 '3', '4', 'degree']
>>> S5.degree                                      #optional - gap3
5

S5 = gap3.SymmetricGroup(5)              #optional - gap3
S5.recfields()                           #optional - gap3
S5.degree                                      #optional - gap3
class sage.interfaces.gap3.Gap3(command=None)[source]

Bases: Gap_generic

A simple Expect interface to GAP3.

EXAMPLES:

sage: from sage.interfaces.gap3 import Gap3
sage: gap3 = Gap3()

>>> from sage.all import *
>>> from sage.interfaces.gap3 import Gap3
>>> gap3 = Gap3()

from sage.interfaces.gap3 import Gap3
gap3 = Gap3()

AUTHORS:

  • Franco Saliola (Feb 2010)

console()[source]

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>

>>> from sage.all import *
>>> 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>

gap3.console()                             # not tested
cputime(t=None)[source]

Return 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: # optional - gap3
sage: t = gap3.cputime()
sage: t  # random
0.02
sage: gap3.SymmetricGroup(5).Size()
120
sage: gap3.cputime()  # random
0.14999999999999999
sage: gap3.cputime(t)  # random
0.13

>>> from sage.all import *
>>> # optional - gap3
>>> t = gap3.cputime()
>>> t  # random
0.02
>>> gap3.SymmetricGroup(Integer(5)).Size()
120
>>> gap3.cputime()  # random
0.14999999999999999
>>> gap3.cputime(t)  # random
0.13

# optional - gap3
t = gap3.cputime()
t  # random
gap3.SymmetricGroup(5).Size()
gap3.cputime()  # random
gap3.cputime(t)  # random
help(topic, pager=True)[source]

Print help on the given topic.

INPUT:

  • topic – string

EXAMPLES:

sage: gap3.help('help', pager=False)           #optional - gap3
Help _______________________________________________________...

This  section describes  together with  the following sectio...
help system.  The help system lets you read the manual inter...

>>> from sage.all import *
>>> 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...

gap3.help('help', pager=False)           #optional - gap3

sage: gap3.help('SymmetricGroup', pager=False) #optional - gap3
no section with this name was found

>>> from sage.all import *
>>> gap3.help('SymmetricGroup', pager=False) #optional - gap3
no section with this name was found

gap3.help('SymmetricGroup', pager=False) #optional - gap3
sage.interfaces.gap3.gap3_console()[source]

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>

>>> from sage.all import *
>>> 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>

gap3.console()                             # not tested
sage.interfaces.gap3.gap3_version()[source]

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'

>>> from sage.all import *
>>> gap3_version()                                           # random, optional - gap3
'lib: v3r4p4 1997/04/18, src: v3r4p0 1994/07/10, sys: usg gcc ansi'

gap3_version()                                           # random, optional - gap3