GAP (linboxing) - Chapter 2: Installation and Use

Goto Chapter: Top 1 2 3 4 Ind
Top of Book Previous Chapter Next Chapter

2 Installation and Use
2.1 Installing the LinBox library
2.1-1 Setting up base system
2.1-2 Building and installing Givaro
2.1-3 Building and installing LinBox
2.1-4 Testing LinBox
2.2 Building the linboxing kernel module
2.3 Starting GAP with LinBox-friendly memory management
2.4 Loading and testing the linboxing package
2.5 Recompiling this documentation

### 2 Installation and Use

Before you can use the linboxing package in GAP, there are several things that you must do. You must install a compatible version of the LinBox library (Section 2.1), and you must build the linboxing package's kernel module (Section 2.2). Finally, you will most likely want to run GAP with special command-line parameters (Section 2.3). This chapter covers all of these technical details.

#### 2.1 Installing the LinBox library

Before you can install the linboxing package, you need to have built and installed the LinBox library on your machine. Versions 1.1.6 or 1.1.7 of LinBox are required to use the linboxing package. LinBox has its own prerequisites before it can be built. This section walks you through getting a working installation of LinBox. Full instructions for building each of these libraries are available on their own websites and should be referred to if you have any problems or (for example) wish to install the libraries in a non-standard location.

##### 2.1-1 Setting up base system

Before you can build LinBox library you will need the standard tools for building a package from source code, including a C++ compiler such as `g++`. Also needed are three standard mathematical libraries:

- the GNU Multiprecision Arithmetic (GMP) Library (see http://gmplib.org/)

- a library which provides the BLAS linear algebra routines (see http://www.netlib.org/blas/)

- a library which provides the LAPACK linear algebra routines (see http://www.netlib.org/lapack/)

Linux users should find all of these in their standard package repositories. On Ubuntu, for example type the following to install all of these:

            sudo apt-get install libgmp3c2 libgmp3-dev libblas3gf \
              libblas-dev liblapack3gf liblapack-dev

Equivalent packages should be available on other Linux distributions and OSX. If you are unsure whether or not you have either the GMP or BLAS libraries installed, the `configure` scripts for both LinBox and linboxing check for them in the standard locations and will tell you if they can't find them.

##### 2.1-2 Building and installing Givaro

LinBox uses the Givaro C++ library (http://ljk.imag.fr/CASYS/LOGICIELS/givaro/) for its field representations, so this needs to be built next. Be aware that particular versions of LinBox will only compile with particular versions of Givaro. For LinBox version 1.1.7, we recommend Givaro version 3.3.3 of Givaro (an alternative pairing would be LinBox 1.1.6, and Givaro 3.2.16). Download Givaro version 3.3.3 from http://ljk.imag.fr/CASYS/LOGICIELS/givaro/Downloads/givaro-3.3.3.tar.gz then unpack and build it using

            tar -xzf givaro-3.3.3.tar.gz
            cd givaro-3.3.3/
            ./configure --with-pic
            make
            sudo make install

The `--with-pic` configure option is necessary to build a shared library that the linboxing kernel module can use.

##### 2.1-3 Building and installing LinBox

We recommend using LinBox version 1.1.7 (released 10 November 2010), but this package has also been tested on version 1.1.6. It is not yet compatible with newer versions of LinBox. Full installation instructions come with the downloaded LinBox source archive, or are available from http://www.linalg.org/linbox-html/install-dist.html. Download the LinBox archive from http://www.linalg.org/linbox-1.1.7.tar.gz and use the following commands to extract and build it:

            tar -xzf linbox-1.1.7.tar.gz
            cd linbox-1.1.7/
            ./configure
            make
            sudo make install

##### 2.1-4 Testing LinBox

Before building the linboxing kernel module, we recommend testing your LinBox installation. To do this type

            make check

from within the `linbox-1.1.7` directory.

#### 2.2 Building the linboxing kernel module

To install the linboxing package, you should first unpack the linboxing archive file in a directory in the `pkg` hierarchy of your version of GAP. For example, for a package with the extension `.tar.gz`, type

          tar -xzf linboxing-0.5.2.tar.gz

This will extract all of the files into a directory called `linboxing`.

All of the useful functionality of the linboxing package is provided through a compiled GAP kernel module that uses the LinBox library directly. Change to the `linboxing` directory and build the kernel module using the commands

          cd linboxing
          ./configure
          make

The `configure` script runs lots of checks and will search for the locations of all of the required other packages, such as GMP, BLAS, Givaro, LinBox and GAP itself. If there are any problems, it should report them, and if not then `make` should proceed with no errors. Note that `make install` is not required for linboxing: `make` does all that is needed.

If the required packages are not in the standard locations, you can tell `configure` where they are using the following command-line switches:

`--with-blas=<lib>`

  specify the name of the BLAS library, or the linker flags needed to use it

`--with-gmpprefix=<prefix>`

  specify the prefix to which GMP library is installed

`--with-givaro=<lib>`

  specify the prefix to which Givaro was installed

`--with-linboxprefix=<prefix>`

  specify the prefix to which the LinBox library is installed

`--with-gaproot=<path>`

  specify the path to GAP's root directory

For example, you may need to use these switches in the following common case. If you do not have root access, you may have installed the LinBox library in your home directory at `/home/pas/software/`. To do this, you will have configured the LinBox build process using `--prefix=/home/pas/software` and when you did `make install`, it would have copied the LinBox library and header files into `/home/pas/software/include` and `/home/pas/software/lib` respectively. You now wish to build this linboxing package. To tell it where to find the LinBox library, you run `configure` with the same prefix that you gave to LinBox, i.e. `--with-linboxprefix=/home/pas/software`.

#### 2.3 Starting GAP with LinBox-friendly memory management

GAP and the LinBox library use different methods for allocating memory, and these do not work well together. GAP needs all of its memory to be contiguous, and so needs to have free space at the end of its current allocation if it ever wants to expand its workspace. The LinBox library allocates its memory using `malloc`, and allocates memory wherever it feels like it. Because of this, if you run GAP and use the linboxing package, then there is a good chance that when GAP needs more memory it will find that some LinBox-allocated memory gets in the way of it expanding the workspace. In this case, GAP will simply exit (without warning!) with the error `cannot extend the workspace any more`.

There are two current solutions to this problem, both of which require GAP to be run with a command-line switch:

Pre-allocate some `malloc` memory for LinBox to use

  The `-a` command-line option Reference: Command Line Options tells GAP to pre-allocate some memory that LinBox should, on most systems, use in preference to getting in the way of the GAP workspace. If you set this sufficiently large (i.e. larger than the largest amount of LinBox memory than you are likely to need at one time), then GAP should be able to expand its workspace as much as it likes. For example, to allocate 50Mb of memory to LinBox (enough for 100,000 small integer matrix elements), use

                gap -a 50M

Allocate GAP a big enough workspace that it will not need extending

  The `-m` command-line option Reference: Command Line Options tells GAP to allocate a set number of bytes for the GAP workspace when it starts up. If you set this sufficiently large then GAP will never need to expand its workspace and LinBox can allocate its matrices wherever it likes in the remaining memory. For example, to allocate 256Mb of memory to GAP, use

              gap -m 256M

  If you are unsure as to how much memory you might need, refer to Reference: Global Memory Information for various GAP commands to let you see how much memory your GAP workspace is using. Running GAP with the `-g` (or `-g -g`) command-line switch Reference: Command Line Options can also help you keep track of memory usage.

You can use both of these solutions at the same time, which may be a safe `belt and braces' approach. If you intend to regularly use the linboxing package, you can add these options to the `gap.sh` shell script, if you are using it. Future versions of GAP may modify GASMAN storage manager to allow the happy co-existance of GAP memory with `malloc`, which would mean that these switches may eventually not be needed.

#### 2.4 Loading and testing the linboxing package

The linboxing package is not loaded by default when GAP is started. To load the package, type the following at the GAP prompt:

          gap> LoadPackage( "linboxing");

If linboxing isn't already in memory then it is loaded and the author information is displayed. If you are a frequent user of the linboxing package, you might consider putting this line in your `.gaprc` file, or using the `PackagesToLoad` option in your `gap.ini` file.

You should test the installation of the linboxing package by running the GAP command `TestLinboxing` (3.2-3):

          gap> TestLinboxing();

A faster and less comprehensive test is provided in a standard GAP test file `tst/linboxing.tst` which can be accessed using:

          gap> d := DirectoriesPackageLibrary("linboxing", "tst");
          gap> ReadTest(Filename(d, "linboxing.tst"));

#### 2.5 Recompiling this documentation

This documentation is written using the GAPDoc package, and should be available in PDF, HTML and text formats. It should not normally be necessary to rebuild the documentation (if you are reading this!). However, rebuilding the documentation can be done from within GAP when running on a standard UNIX installation by using the GAP command `MakeLinboxingDoc` (3.2-2).

Top of Book Previous Chapter Next Chapter
Goto Chapter: Top 1 2 3 4 Ind

generated by GAPDoc2HTML