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

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

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

    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: # 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)
    
  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:
    
  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>
    
  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...
    

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"
    

    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
    

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'

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

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
...
class sage.interfaces.gap3.GAP3Element(parent, value, is_name=False, name=None)#

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 – bool (default: False); if True, then value is the variable name for the object

  • name – str (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

AUTHORS:

  • Franco Saliola (Feb 2010)

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

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

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) ] ) ]
recfields()#

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

Bases: Gap_generic

A simple Expect interface to GAP3.

EXAMPLES:

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

AUTHORS:

  • Franco Saliola (Feb 2010)

console()#

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>
cputime(t=None)#

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
help(topic, pager=True)#

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...
sage: gap3.help('SymmetricGroup', pager=False) #optional - gap3
no section with this name was found
sage.interfaces.gap3.gap3_console()#

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>
sage.interfaces.gap3.gap3_version()#

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'