# 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 : GF = galois.GF(3**5)

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

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

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


## FieldArray instances¶

A FieldArray instance is created using GF’s constructor.

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

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


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

In : isinstance(x, GF)
Out: True

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

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

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


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

In : type(x) is GF
Out: 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 : GF.Random((2, 3))
Out:
GF([[195, 122,  80],
[233,  37,  62]], order=3^5)


Or, create an identity matrix using Identity().

In : GF.Identity(4)
Out:
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 : x.multiplicative_order()
Out: array([242,  11, 242, 242])


Last update: May 18, 2022