Galois Field Classes¶

There are two key classes in the galois library. Understanding them and their relationship will make using the library and accessing the appropriate documentation easier. These two classes are the galois.FieldClass metaclass and galois.FieldArray.

The documentation also regularly refers to a Galois field array class and a Galois field array. Both terms are defined on this page.

Galois field array class¶

A Galois field array class is created using the class factory function galois.GF().

In [1]: GF = galois.GF(3**5)

In [2]: GF
Out[2]: <class 'numpy.ndarray over GF(3^5)'>

In [3]: print(GF)
Galois Field:
  name: GF(3^5)
  characteristic: 3
  degree: 5
  order: 243
  irreducible_poly: x^5 + 2x + 1
  is_primitive_poly: True
  primitive_element: x

The Galois field array class GF is a subclass of galois.FieldArray (which itself subclasses numpy.ndarray) and has galois.FieldClass as its metaclass.

In [4]: issubclass(GF, np.ndarray)
Out[4]: True

In [5]: issubclass(GF, galois.FieldArray)
Out[5]: True

In [6]: isinstance(GF, galois.FieldClass)
Out[6]: True

Methods and properties¶

All of the methods and properties related to the Galois field itself, not one of its arrays, are documented in galois.FieldClass. For example, the irreducible polynomial of the finite field is accessed with galois.FieldClass.irreducible_poly.

In [7]: GF.irreducible_poly
Out[7]: Poly(x^5 + 2x + 1, GF(3))

Class singletons¶

Galois field array classes of the same order with the same irreducible polynomial are singletons.

Here is the creation (twice) of the field \(\mathrm{GF}(3^5)\) defined with the default irreducible polynomial \(x^5 + 2x + 1\). They are the same class (a singleton), not just equivalent classes.

In [8]: galois.GF(3**5) is galois.GF(3**5)
Out[8]: True

The expense of class creation is incurred only once. So, subsequent calls of galois.GF(3**5) are extremely inexpensive.

However, the field \(\mathrm{GF}(3^5)\) defined with irreducible polynomial \(x^5 + x^2 + x + 2\), while isomorphic to the first field, has different arithmetic. As such, galois.GF() returns a unique Galois field array class.

In [9]: galois.GF(3**5) is galois.GF(3**5, irreducible_poly="x^5 + x^2 + x + 2")
Out[9]: False

Galois field array¶

A Galois field array is created using the constructor of the Galois field array class GF.

In [10]: x = GF([23, 78, 163, 124])

In [11]: x
Out[11]: GF([ 23,  78, 163, 124], order=3^5)

The Galois field array x is an instance of the Galois field array class GF. Since GF subclasses numpy.ndarray, x is also an instance of numpy.ndarray.

In [12]: isinstance(x, np.ndarray)
Out[12]: True

In [13]: isinstance(x, GF)
Out[13]: True

A Galois field array class is easily recovered from a Galois field array using type().

In [14]: type(x) is GF
Out[14]: True

Methods¶

All of the methods that act on Galois field arrays are documented in galois.FieldArray. For example, the multiplicative order of each finite field element is calculated using galois.FieldArray.multiplicative_order().

In [15]: x.multiplicative_order()
Out[15]: array([242,  11, 242, 242])

Or, convert an N-D array over \(\mathrm{GF}(3^5)\) to an (N + 1)-D array of its polynomial coefficients over \(\mathrm{GF}(3)\) using galois.FieldArray.vector().

In [16]: x.vector()
Out[16]: 
GF([[0, 0, 2, 1, 2],
    [0, 2, 2, 2, 0],
    [2, 0, 0, 0, 1],
    [1, 1, 1, 2, 1]], order=3)

Classmethods¶

Several classmethods are defined in galois.FieldArray. These methods produce Galois field arrays. By convention, classmethods use PascalCase, while methods use snake_case.

For example, to generate a random array of given shape call galois.FieldArray.Random().

In [17]: GF.Random((2, 3))
Out[17]: 
GF([[168,  65, 219],
    [119,  56,  69]], order=3^5)