Interface to GAP3

This module implements an interface to GAP3.

AUTHORS:

  • Franco Saliola (February 2010)

  • Christian Stump (March 2016)

Warning

The experimental 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 Issue #20107 and also

Obtaining GAP3

Instead of installing the experimental GAP3 package, one can as well install by hand either of the following two versions of GAP3:

Changing which GAP3 is used

Warning

There is a bug in the pexpect module (see Issue #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

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


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

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

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

    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)

  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:

  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>

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

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"

    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

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'

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

Controlling variable names used by GAP3:

sage: # optional - gap3
sage: gap3('2', name='x')
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
>>> gap3('2', name='x')
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
...
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

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) ] ) ]
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
class sage.interfaces.gap3.Gap3(command='gap3')[source]

Bases: Gap_generic

A simple Expect interface to GAP3.

EXAMPLES:

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

>>> from sage.all import *
>>> from sage.interfaces.gap3 import Gap3
>>> gap3 = Gap3(command='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>
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
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...


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