---

Introduction to GaloisLib

0.1.1

Index

• What is GaloisLib?
• How do I use it?
• Where can I find it?
• How do install it?

What is GaloisLib?

GaloisLib is a C++ library for doing arithmetic with finite fields. It implements the Generic Ring Interface and it can be used within any algorithm exploiting such an interface. Do not be fooled by the buzzing name: this means, roughly, that the class defines

• the usual math operations +, -, *, / together with their "assignement" versions such as +=
• the usual comparison operators == and != together with specialized methods is_zero() and is_one() (Note that x.is_zero() gives the same result of x == 0, but the former is more efficient)
• A default constructor which initializes the constructed object to 0 and a constructor which expect an integer parameter
• Two specialized constructors zero() and one() which return, respectively, the "0" and the "1" of the finite field
• I/O operators >> and <<. See section External representations for more details about how an element of a Galois field is coded for I/O.
• When some exception occurs, library functions throw exceptions of class RingEx::RingException

Actually, you do not find one library, but three:

• GF2 (header file gf2.H) this gives a template class which implements only fields of characteristic 2, i.e., . The advantage of this library is its efficiency since every element is stored as an -bit integer. This makes sum and multiplication more efficient (for example, sum boils down to a bitwise xor).

• GF (header file gf.H) this gives a template class which implements generic finite fields . This is library is more general, but less efficient since field elements must be stored as vectors of integers between 0 and and this makes sum and product more expensive.

• GALOIS (header file galois.H) this is not a template library, but a "normal" class which implements generic finite fields . The advantage of this library is that allows for changing the field at runtime, while GF2 and GF fix the field size at compile time. Altough this is more flexible, we loose compile time type checking.

How do I use it?

Briefly, in order to use one of the offered libraries (GF2, GF or GALOIS) you need to

1. include the corresponding header file, as given in the following table

   Library	Header file
   GF2	gf2.H
   GF	gf.H
   GALOIS	galois.H

2. link your code with the library libgalois.a (usually this means to add -lgalois in the linking phase)

Of course, if you installed the headers/the library in a directory which is not a "standard" one, you will need to give to the compiler the corresponding -I and -L options.

You can find some examples of usage in the example directory.

Where can I find it?

You can download the tarball from http://www.diegm.uniud.it/bernardini/Software/Cplusplus

How do install it?

The tarball follows the GNU conventions and if you already installed GNU software from sources you should not have any problem: it is the usual "configure, make, make install" stuff.

Briefly,

1. Download the tarball galoislib-1.0.tar.gz from http://www.diegm.uniud.it/bernardini/Software/Cplusplus

2. Extract the archive with
   tar zxvf galoislib-1.0.tar.gz

   this should create a subdirectory galoislib-1.0

3. Enter the directory galoislib-1.0 with cd galoislib-1.0 and configure the package with
   ./configure

   If you want to install the file in a different tree from the default one (/usr/local/) you can use

   ./configure --prefix=/new/dir

   and the files will be installed in /new/dir/include and /new/dir/lib. In this case be sure to pass options -I and -L to your compiler when you compile/link.

4. Compile and install the package with
   make install

5. That's all!

More detailed instruction can be found in the INSTALL file.

---