GAP (Alnuth) - Chapter 4: Installation

Goto Chapter: Top 1 2 3 4 Bib Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax off]

4 Installation
4.1 Installing Alnuth
4.2 Getting PARI/GP
4.3 Adjust the path of the executable for GP
4.3-1 PariVersion
4.3-2 SetAlnuthExternalExecutable
4.3-3 SetAlnuthExternalExecutablePermanently
4.3-4 RestoreAlnuthExternalExecutablePermanently
4.4 Loading and testing the package

### 4 Installation

This package provides an interface between GAP and either PARI/GP or OSCAR. When Alnuth is loaded in GAP running inside OSCAR, it automatically uses OSCAR. Otherwise, Alnuth uses PARI/GP, which has to be obtained and installed independently of this package. Alnuth works with PARI/GP Version 2.5 or higher.

#### 4.1 Installing Alnuth

The package Alnuth is part of the standard distribution of GAP so that in most cases there is no need to install it separately. If you are using GAP inside OSCAR, then Alnuth is already bundled and automatically uses OSCAR, so no further installation is required. Otherwise, to use Alnuth you need to have PARI/GP installed. See the following section for information on PARI/GP.

In case you want to update Alnuth independently of your main GAP installation or if you are interested in an old version of Alnuth interfacing to KANT/KASH you can find all released versions of Alnuth in the form of gzipped tar-archives at https://github.com/gap-packages/alnuth/releases

There are two ways of installing a GAP package. If you have permission to add files to the installation of GAP on your system you may install Alnuth into the `pkg` subdirectory of the GAP installation tree. Otherwise you may install Alnuth in a private `pkg` directory (for details see Subsections Reference: Installing a GAP Package and Reference: GAP Root Directories in the GAP reference manual).

To install the latest version of Alnuth download one of the archives `alnuth.tar.gz`, move it to the directory `pkg` in which you want to install, and unpack the archive. If you are using the command line you can unpack with the command `tar xzf alnuth.tar.gz`.

#### 4.2 Getting PARI/GP

Using Alnuth outside OSCAR requires an installation of PARI/GP in Version 2.5 or higher. The software PARI/GP is freely available at https://pari.math.u-bordeaux.fr/

Note that the place where PARI/GP is located in your system is independent of the place where Alnuth is installed.

1. Installing under Linux

   In many Linux distributions PARI/GP can be installed via the software package manager, but this might sometimes be an older version which cannot be used together with Alnuth. (Starting GP from the command line with the option `--version-short` will show you the version number.)

   If you install PARI/GP from source make sure you install with GMP support for better performance and complete the installation with `make install` so that you can start GP by just calling `gp` from the command line.

2. Installing under Windows

   For Windows it is sufficient to get the basic GP binary which can be found at https://pari.math.u-bordeaux.fr/download.html

#### 4.3 Adjust the path of the executable for GP

When Alnuth is used outside OSCAR, it needs to know where the executable for GP is. In the default setting Alnuth looks for an executable program named `gp` in the search paths of the system. More precisely, for a file `gp` inside one of the directories in the list returned by `DirectoriesSystemPrograms()` (called in a GAP session).

Under Linux the default setting should work with a standard installation of PARI/GP.

For the default setting to work under Windows the downloaded executable file, for example `gp-2-5-0.exe` has to be renamed to `gp.exe` and moved to one of the directories listed by `DirectoriesSystemPrograms()` (Ignore the leading `cygdrive` in each path name and note that the single letter specifies the drive, for example `/cygdrive/c/Windows/` denotes the folder `Windows` on drive `C:`).

To check whether an executable of GP in Version 2.5 or higher is available with the default setting, you can use the function

##### 4.3-1 PariVersion

`‣ PariVersion`( ) | ( function )

which prints the version number, if the user preference `PariGpPath` refers to a usable GP executable.

If you cannot use the default setting for you purpose, you have several ways to configure Alnuth.

The recommended approach is to use the GAP user preference system:

    gap> SetUserPreference("alnuth", "PariGpPath", "/home/my/pari-2.5.0/gp");
    gap> SetUserPreference("alnuth", "PariStackSize", 256);
    gap> WriteGapIniFile();

This changes the current session immediately. `WriteGapIniFile()` writes the current non-default settings to your personal `gap.ini`, so they are used again in future GAP sessions. See Reference: Configuring User preferences for background on the user preference system.

The user preferences relevant for Alnuth are shown by `ShowUserPreferences("alnuth");`. The most important ones are `PariGpPath`, `PariGpOptions`, `PariStackSize`, and `PrimitiveElementTrials`.

In older versions of Alnuth configuration was done via the global variables `AL_EXECUTABLE`, `AL_PATH`, `AL_OPTIONS`, `AL_STACKSIZE`, and `PRIM_TEST`. These globals are deprecated, and they trigger a warning when used. The globals except for `AL_PATH` still serve as a fallback if the corresponding user preference is unusable. Their replacements are as follows:

`AL_EXECUTABLE`

  use the user preference `PariGpPath`

`AL_OPTIONS`

  use the user preference `PariGpOptions`

`AL_STACKSIZE`

  use the user preference `PariStackSize`

`PRIM_TEST`

  use the user preference `PrimitiveElementTrials`

`AL_PATH`

  has been removed; Alnuth now always uses the bundled GP helper files.

For backwards compatibility, the following functions still exist after loading the package (see Section 4.4), but they are deprecated wrappers around the user preference system.

##### 4.3-2 SetAlnuthExternalExecutable

`‣ SetAlnuthExternalExecutable`( path ) | ( function )

sets the user preference `PariGpPath` for the current GAP session. Depending on your installation of PARI/GP and your operating system the string path can be either the command to start GP in a terminal (for example `gp`) or the complete path to the executable of GP. The function is deprecated; new code should call `SetUserPreference("alnuth", "PariGpPath", path);` directly.

The function returns the stored preference value.

##### 4.3-3 SetAlnuthExternalExecutablePermanently

`‣ SetAlnuthExternalExecutablePermanently`( path ) | ( function )

does the same as `SetAlnuthExternalExecutable` and then calls `WriteGapIniFile()` to persist the current user preference settings in your personal `gap.ini`. The function is deprecated; new code should call `SetUserPreference("alnuth", "PariGpPath", path); WriteGapIniFile();` instead.

##### 4.3-4 RestoreAlnuthExternalExecutablePermanently

`‣ RestoreAlnuthExternalExecutablePermanently`( ) | ( function )

restores the default value of `PariGpPath` and then calls `WriteGapIniFile()`. The function is deprecated; new code should set `PariGpPath` to the desired default command or path and then call `WriteGapIniFile()` directly.

#### 4.4 Loading and testing the package

If Alnuth is not loaded when GAP is started you have to request it explicitly to use it. This is done by calling `LoadPackage("alnuth");` in a GAP session. If Alnuth had not been loaded already a short banner will be displayed.

    gap> LoadPackage("alnuth");
    Loading Alnuth 4.0.0 (ALgebraic NUmber THeory and an interface to PARI/GP and OSCAR)
    by Björn Assmann,
       Andreas Distler (a.distler@tu-bs.de), and
       Bettina Eick (http://www.iaa.tu-bs.de/beick).
    maintained by:
       Max Horn (https://www.quendi.de/math) and
       The GAP Team (support@gap-system.org).
    Homepage: https://gap-packages.github.io/alnuth
    Report issues at https://github.com/gap-packages/alnuth/issues
    true
    gap>

To load a certain version of Alnuth you can specify the version number as second argument in the call to `LoadPackage`. (See `LoadPackage` (Reference: LoadPackage) in the GAP reference manual or type `?LoadPackage` within a GAP session).

Once the package is loaded, it is possible to check the correct installation running a short test by calling `ReadPackage("Alnuth", "tst/testinstall.tst");`.

    gap> ReadPackage("Alnuth", "tst/testinstall.g");
    Architecture: aarch64-apple-darwin21.4.0-default64-kv8

    testing: GAPROOT/pkg/alnuth/tst/ALNUTH.tst
          66 ms (33 ms GC) and 11.0MB allocated for GAPROOT/pkg/alnuth/tst/ALNUTH.tst
    testing: GAPROOT/pkg/alnuth/tst/version.tst
          21 ms (21 ms GC) and 29.6KB allocated for GAPROOT/pkg/alnuth/tst/version.tst
    -----------------------------------
    total        87 ms (54 ms GC) and 11.0MB allocated
                  0 failures in 2 files

    #I  No errors detected while testing
    gap>

The architecture, timings and memory usage will usually differ; other discrepancies in the output indicate some problem.

If the test suite runs into an error in the first part, which when running outside OSCAR verifies the availability of PARI/GP, check your installation of PARI/GP and consult the last chapter of the documentation of Alnuth for more information.

If you find any bugs or have any suggestions or comments, we would very much appreciate it if you would let us know by submitting an issue at the Alnuth issue tracker on GitHub https://github.com/gap-packages/alnuth/issues or by writing an mail to support@gap-system.org.

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 Bib Ind

generated by GAPDoc2HTML