### Navigation

- index
- modules |
- next |
- previous |
- Interpreter Interfaces »

# Interface to GAP3

This module implements an interface to GAP3.

AUTHORS:

- Franco Saliola (February 2010)

Warning

GAP3 is not distrubuted with Sage. You need to install it separately; see the section Obtaining GAP3.

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

  > http://trac.sagemath.org/sage_trac/ticket/8906

- 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

- Jean Michel maintains a version of GAP3 pre-packaged with CHEVIE and VKCURVE. It can be obtained here:

  > http://people.math.jussieu.fr/~jmichel/chevie/chevie.html

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

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

## Changing which GAP3 is used

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

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

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 - gap3chevie
       W...  to  the  CHEVIE  package, ...

## Examples

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

  - `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: 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
      Traceback (most recent call last):
      ...
      ValueError: you are attempting to redefine X; but you should never redefine E, X or Z in gap3 (because things will break!)

  AUTHORS:

  - Franco Saliola (Feb 2010)

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

  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:

  - 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

  `trait_names`()

    Defines the list of methods and attributes that will appear for tab completion.

    OUTPUT:

    - list of strings – the available fields and operations of the record

    EXAMPLES:

        sage: S5 = gap3.SymmetricGroup(5)              #optional - gap3
        sage: S5.trait_names()                         #optional - gap3
        [..., 'ConjugacyClassesTry', 'ConjugateSubgroup', 'ConjugateSubgroups',
        'Core', 'DegreeOperation', 'DerivedSeries', 'DerivedSubgroup',
        'Difference', 'DimensionsLoewyFactors', 'DirectProduct', ...]

class `sage.interfaces.gap3.``Gap3`(command='gap3')

  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 KeyboardInterrupt:
      ...     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
      Traceback (most recent call last):
      ...
      RuntimeError: Gap3 produced error output
      Error, List Element: <position> must be a positive integer at
      return L[0] ...

  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)

    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

  `help`(topic, pager=True)

    Print help on the given topic.

    INPUT:

    - `topic` – string

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

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

### Navigation

- index
- modules |
- next |
- previous |
- Interpreter Interfaces »