# 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([[195, 122,  80],
[233,  37,  62]], 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])


Last update: May 18, 2022