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

In [3]: GF = galois.GF(3**5, display="poly")

In [4]: 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

In [5]: GF = galois.GF(3**5, display="power")

In [6]: 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 [7]: issubclass(GF, galois.FieldArray)
Out[7]: True

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

In [9]: issubclass(GF, np.ndarray)
Out[9]: 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 [10]: galois.GF(3**5) is galois.GF(3**5)
Out[10]: 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 [11]: galois.GF(3**5) is galois.GF(3**5, irreducible_poly="x^5 + x^2 + x + 2")
Out[11]: 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 [12]: GF.irreducible_poly
Out[12]: Poly(x^5 + 2x + 1, GF(3))

FieldArray instances

A FieldArray instance is created using GF’s constructor.

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

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

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

In [16]: x
Out[16]: 
GF([            2α^2 + α + 2,         2α^3 + 2α^2 + 2α,
                    2α^4 + 1, α^4 + α^3 + α^2 + 2α + 1], order=3^5)

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

In [18]: x
Out[18]: GF([ α^17, α^132, α^241,  α^41], order=3^5)

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

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

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

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

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

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

In [23]: type(x) is GF
Out[23]: 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 [24]: GF.Random((3, 2), seed=1)
Out[24]: 
GF([[242, 216],
    [ 32, 114],
    [230, 179]], order=3^5)

In [25]: GF.Random((3, 2), seed=1)
Out[25]: 
GF([[2α^4 + 2α^3 + 2α^2 + 2α + 2,                 2α^4 + 2α^3],
    [                α^3 + α + 2,              α^4 + α^3 + 2α],
    [  2α^4 + 2α^3 + α^2 + α + 2,         2α^4 + α^2 + 2α + 2]], order=3^5)

In [26]: GF.Random((3, 2), seed=1)
Out[26]: 
GF([[α^185, α^193],
    [ α^49, α^231],
    [ α^81,  α^60]], order=3^5)

Or, create an identity matrix using Identity().

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

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

In [29]: GF.Identity(4)
Out[29]: 
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 [30]: x.multiplicative_order()
Out[30]: array([242,  11, 242, 242])
Last update: Nov 04, 2022