class galois.FieldArray(galois.Array)

An abstract ndarray subclass over \(\mathrm{GF}(p^m)\).

Abstract

FieldArray is an abstract base class and cannot be instantiated directly. Instead, FieldArray subclasses are created using the class factory GF().

Examples

Create a FieldArray subclass over \(\mathrm{GF}(3^5)\) using the class factory GF().

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

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

In [3]: 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 [4]: GF = galois.GF(3**5, repr="poly")

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

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

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

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

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

Create a FieldArray instance using GF’s constructor.

In [10]: x = GF([44, 236, 206, 138]); x
Out[10]: GF([ 44, 236, 206, 138], order=3^5)

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

In [12]: x = GF([44, 236, 206, 138]); x
Out[12]: 
GF([       α^3 + α^2 + 2α + 2,    2α^4 + 2α^3 + 2α^2 + 2,
    2α^4 + α^3 + α^2 + 2α + 2,            α^4 + 2α^3 + α], order=3^5)

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

In [14]: x = GF([44, 236, 206, 138]); x
Out[14]: GF([α^143, α^204,  α^55, α^113], order=3^5)

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

Constructors

FieldArray(x: ElementLike | ArrayLike, ...)

Creates an array over \(\mathrm{GF}(p^m)\).

classmethod Identity(size: int, ...) → Self

Creates an \(n \times n\) identity matrix.

classmethod Ones(shape: ShapeLike, ...) → Self

Creates an array of all ones.

classmethod Random(shape: ShapeLike = (), ...) → Self

Creates an array with random elements.

classmethod Range(start: ElementLike, stop, ...) → Self

Creates a 1-D array with a range of elements.

classmethod Vandermonde(element: ElementLike, rows, ...) → Self

Creates an \(m \times n\) Vandermonde matrix of \(a \in \mathrm{GF}(q)\).

classmethod Vector(array: ArrayLike, ...) → FieldArray

Creates an array over \(\mathrm{GF}(p^m)\) from length-\(m\) vectors over the prime subfield \(\mathrm{GF}(p)\).

classmethod Zeros(shape: ShapeLike, ...) → Self

Creates an array of all zeros.

String representation

__repr__() → str

Displays the array specifying the class and finite field order.

__str__() → str

Displays the array without specifying the class or finite field order.

class property properties : str

A formatted string of relevant properties of the Galois field.

Methods

additive_order() → int | ndarray

Computes the additive order of each element in \(x\).

classmethod arithmetic_table(operation, ...) → str

Generates the specified arithmetic table for the finite field.

characteristic_poly() → Poly

Computes the characteristic polynomial of a finite field element \(a\) or a square matrix \(\mathbf{A}\).

column_space() → Self

Computes the column space of the matrix \(\mathbf{A}\).

classmethod compile(mode)

Recompile the just-in-time compiled ufuncs for a new calculation mode.

field_norm() → FieldArray

Computes the field norm \(\mathrm{N}_{L / K}(x)\) of the elements of \(x\).

field_trace() → FieldArray

Computes the field trace \(\mathrm{Tr}_{L / K}(x)\) of the elements of \(x\).

is_square() → bool | ndarray

Determines if the elements of \(x\) are squares in the finite field.

left_null_space() → Self

Computes the left null space of the matrix \(\mathbf{A}\).

log(base: ElementLike | ArrayLike | None = None) → int | ndarray

Computes the logarithm of the array \(x\) base \(\beta\).

lu_decompose() → tuple[Self, Self]

Decomposes the input array into the product of lower and upper triangular matrices.

minimal_poly() → Poly

Computes the minimal polynomial of a finite field element \(a\).

multiplicative_order() → int | ndarray

Computes the multiplicative order \(\textrm{ord}(x)\) of each element in \(x\).

null_space() → Self

Computes the null space of the matrix \(\mathbf{A}\).

plu_decompose() → tuple[Self, Self, Self]

Decomposes the input array into the product of lower and upper triangular matrices using partial pivoting.

classmethod primitive_root_of_unity(n: int) → Self

Finds a primitive \(n\)-th root of unity in the finite field.

classmethod primitive_roots_of_unity(n: int) → Self

Finds all primitive \(n\)-th roots of unity in the finite field.

classmethod repr(...) → Generator[None, None, None]

Sets the element representation for all arrays from this FieldArray subclass.

classmethod repr_table(...) → str

Generates a finite field element representation table comparing the power, polynomial, vector, and integer representations.

row_reduce(ncols: int | None = None, ...) → Self

Performs Gaussian elimination on the matrix to achieve reduced row echelon form (RREF).

row_space() → Self

Computes the row space of the matrix \(\mathbf{A}\).

vector(dtype: DTypeLike | None = None) → FieldArray

Converts an array over \(\mathrm{GF}(p^m)\) to length-\(m\) vectors over the prime subfield \(\mathrm{GF}(p)\).

Properties

class property characteristic : int

The prime characteristic \(p\) of the Galois field \(\mathrm{GF}(p^m)\). Adding \(p\) copies of any element will always result in 0.

class property default_ufunc_mode : 'jit-lookup' | 'jit-calculate' | 'python-calculate'

The default ufunc compilation mode for this FieldArray subclass. The ufuncs may be recompiled with compile().

class property degree : int

The extension degree \(m\) of the Galois field \(\mathrm{GF}(p^m)\). The degree is a positive integer.

class property dtypes : list[np.dtype]

List of valid integer numpy.dtype values that are compatible with this finite field. Creating an array with an unsupported dtype will raise a TypeError exception.

class property element_repr : 'int' | 'poly' | 'power'

The current finite field element representation. This can be changed with repr().

class property elements : FieldArray

All of the finite field’s elements \(\{0, \dots, p^m-1\}\).

class property irreducible_poly : Poly

The irreducible polynomial \(f(x)\) of the Galois field \(\mathrm{GF}(p^m)\). The irreducible polynomial is of degree \(m\) over \(\mathrm{GF}(p)\).

class property is_extension_field : bool

Indicates if the finite field is an extension field. This is true when the field’s order is a prime power.

class property is_prime_field : bool

Indicates if the finite field is a prime field, not an extension field. This is true when the field’s order is prime.

class property is_primitive_poly : bool

Indicates whether the irreducible_poly is a primitive polynomial. If so, \(x\) is a primitive element of the finite field.

class property name : str

The finite field’s name as a string GF(p) or GF(p^m).

class property non_squares : FieldArray

All non-squares in the Galois field.

class property order : int

The order \(p^m\) of the Galois field \(\mathrm{GF}(p^m)\). The order of the field is equal to the field’s size.

class property prime_subfield : type[FieldArray]

The prime subfield \(\mathrm{GF}(p)\) of the extension field \(\mathrm{GF}(p^m)\).

class property primitive_element : FieldArray

A primitive element \(\alpha\) of the Galois field \(\mathrm{GF}(p^m)\). A primitive element is a multiplicative generator of the field, such that \(\mathrm{GF}(p^m) = \{0, 1, \alpha, \alpha^2, \dots, \alpha^{p^m - 2}\}\).

class property primitive_elements : FieldArray

All primitive elements \(\alpha\) of the Galois field \(\mathrm{GF}(p^m)\). A primitive element is a multiplicative generator of the field, such that \(\mathrm{GF}(p^m) = \{0, 1, \alpha, \alpha^2, \dots, \alpha^{p^m - 2}\}\).

class property squares : FieldArray

All squares in the finite field.

class property ufunc_mode : 'jit-lookup' | 'jit-calculate' | 'python-calculate'

The current ufunc compilation mode for this FieldArray subclass. The ufuncs may be recompiled with compile().

class property ufunc_modes : list[str]

All supported ufunc compilation modes for this FieldArray subclass.

class property units : FieldArray

All of the finite field’s units \(\{1, \dots, p^m-1\}\). A unit is an element with a multiplicative inverse.