Interface to GAP3 - Interpreter Interfaces

Skip to content
Back to top
View this page
Edit this page

# 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

> https://webusers.imj-prg.fr/~jean.michel/gap3/

## Obtaining GAP3

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

- Frank Luebeck maintains a GAP3 Linux executable, optimized for i686 and statically linked for jobs of 2 GByte or more:

  > http://www.math.rwth-aachen.de/~Frank.Luebeck/gap/GAP3

- or you can download GAP3 from the GAP website below. Since GAP3 is no longer supported, it may not be easy to install this version.

  > https://www.gap-system.org/Gap3/Download3/download.html

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

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

Python

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

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

   Python

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

   Sage

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

   [Python]

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

       sage: # optional - gap3
       sage: S5.Size()
       120
       sage: S5.CharTable()
       CharTable( Group( (1,5), (2,5), (3,5), (4,5) ) )

   Python

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

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

   [Python]

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

       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)

   Python

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

       sage: gap3.interact()                            # not tested

         --> Switching to Gap3 <--

       gap3:

   Python

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

         --> Switching to Gap3 <--

       gap3:

3. You can start a new GAP3 session as follows:

   Sage

       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>

   Python

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

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

   Python

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

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

   Python

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

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

   [Python]

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

## Examples

Load a GAP3 package:

Sage

    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'

Python

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

    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

[Python]

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

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

Python

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

  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

      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

  Python

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

  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

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

    Python

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

    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

        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

    Python

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

  Bases: `Gap_generic`

  A simple Expect interface to GAP3.

  EXAMPLES:

  Sage

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

  Python

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

  AUTHORS:

  - Franco Saliola (Feb 2010)

  console()

    Spawn a new GAP3 command-line session.

    EXAMPLES:

    Sage

        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>

    Python

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

    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

        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

    Python

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

    Print help on the given topic.

    INPUT:

    - `topic` – string

    EXAMPLES:

    Sage

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

    Python

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

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

    [Python]

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

      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>

  Python

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

  Return the version of GAP3 that you have in your PATH on your computer.

  EXAMPLES:

  Sage

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

  Python

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