Array Classes¶

The galois library subclasses ndarray to provide arithmetic over Galois fields and rings (future).

Array subclasses¶

The main abstract base class is Array. It has two abstract subclasses: FieldArray and RingArray (future). None of these abstract classes may be instantiated directly. Instead, specific subclasses for \(\mathrm{GF}(p^m)\) and \(\mathrm{GR}(p^e, m)\) are created at runtime with GF() and GR() (future).

FieldArray subclasses¶

A FieldArray subclass is created using the class factory function GF().

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

In [2]: print(GF.properties)
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 GF class is a subclass of FieldArray and a subclasses of ndarray.

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

In [4]: issubclass(GF, galois.Array)
Out[4]: True

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

Class singletons¶

FieldArray subclasses of the same type (order, irreducible polynomial, and primitive element) 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 [6]: galois.GF(3**5) is galois.GF(3**5)
Out[6]: 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, GF() returns a unique FieldArray subclass.

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

Methods and properties¶

All of the methods and properties related to \(\mathrm{GF}(p^m)\), not one of its arrays, are documented as class methods and class properties in FieldArray. For example, the irreducible polynomial of the finite field is accessed with irreducible_poly.

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

FieldArray instances¶

A FieldArray instance is created using GF’s constructor.

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

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

The array x is an instance of FieldArray and also an instance of ndarray.

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

In [12]: isinstance(x, galois.FieldArray)
Out[12]: True

In [13]: isinstance(x, galois.Array)
Out[13]: True

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

The FieldArray subclass is easily recovered from a FieldArray instance using type().

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

Constructors¶

Several classmethods are defined in FieldArray that function as alternate constructors. By convention, alternate constructors use PascalCase while other classmethods use snake_case.

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

In [16]: GF.Random((2, 3))
Out[16]: 
GF([[ 93, 114, 156],
    [187,  26,  64]], order=3^5)

Or, create an identity matrix using Identity().

In [17]: GF.Identity(4)
Out[17]: 
GF([[1, 0, 0, 0],
    [0, 1, 0, 0],
    [0, 0, 1, 0],
    [0, 0, 0, 1]], order=3^5)

Methods¶

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

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