galois.FieldClass

class galois.FieldClass(name, bases, namespace, **kwargs)

Defines a metaclass for all galois.FieldArray classes.

This metaclass gives galois.FieldArray subclasses returned from the class factory galois.GF() methods and attributes related to its Galois field.

Methods

arithmetic_table(operation[, x, y])

Generates the specified arithmetic table for the Galois field.

compile(mode)

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

display([mode])

Sets the display mode for all Galois field arrays of this type.

repr_table([primitive_element, sort])

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

Attributes

characteristic

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

default_ufunc_mode

The default ufunc arithmetic mode for this Galois field.

degree

The prime characteristic’s degree \(m\) of the Galois field \(\mathrm{GF}(p^m)\).

display_mode

The representation of Galois field elements, either "int", "poly", or "power".

dtypes

List of valid integer numpy.dtype values that are compatible with this Galois field.

irreducible_poly

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

is_extension_field

Indicates if the field’s order is a prime power.

is_prime_field

Indicates if the field’s order is prime.

is_primitive_poly

Indicates whether the irreducible_poly is a primitive polynomial.

name

The Galois field name.

order

The order \(p^m\) of the Galois field \(\mathrm{GF}(p^m)\).

prime_subfield

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

primitive_element

A primitive element \(\alpha\) of the Galois field \(\mathrm{GF}(p^m)\).

primitive_elements

All primitive elements \(\alpha\) of the Galois field \(\mathrm{GF}(p^m)\).

properties

A formatted string displaying relevant properties of the Galois field.

ufunc_mode

The mode for ufunc compilation, either "jit-lookup", "jit-calculate", or "python-calculate".

ufunc_modes

All supported ufunc modes for this Galois field array class.

arithmetic_table(operation, x=None, y=None)

Generates the specified arithmetic table for the Galois field.

Parameters
  • operation (str) – The arithmetic operation, either "+", "-", "*", or "/".

  • x (galois.FieldArray, optional) – Optionally specify the \(x\) values for the arithmetic table. The default is None which represents \(\{0, \dots, p^m - 1\}\).

  • y (galois.FieldArray, optional) – Optionally specify the \(y\) values for the arithmetic table. The default is None which represents \(\{0, \dots, p^m - 1\}\) for addition, subtraction, and multiplication and \(\{1, \dots, p^m - 1\}\) for division.

Returns

A UTF-8 formatted arithmetic table.

Return type

str

Examples

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

In [2]: print(GF.arithmetic_table("+"))
╔═══════╦═══╤═══╤═══╤═══╤═══╤═══╤═══╤═══╤═══╗
║ x + y ║ 0 │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 │ 7 │ 8 ║
╠═══════╬═══╪═══╪═══╪═══╪═══╪═══╪═══╪═══╪═══╣
║     0 ║ 0 │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 │ 7 │ 8 ║
╟───────╫───┼───┼───┼───┼───┼───┼───┼───┼───╢
║     1 ║ 1 │ 2 │ 0 │ 4 │ 5 │ 3 │ 7 │ 8 │ 6 ║
╟───────╫───┼───┼───┼───┼───┼───┼───┼───┼───╢
║     2 ║ 2 │ 0 │ 1 │ 5 │ 3 │ 4 │ 8 │ 6 │ 7 ║
╟───────╫───┼───┼───┼───┼───┼───┼───┼───┼───╢
║     3 ║ 3 │ 4 │ 5 │ 6 │ 7 │ 8 │ 0 │ 1 │ 2 ║
╟───────╫───┼───┼───┼───┼───┼───┼───┼───┼───╢
║     4 ║ 4 │ 5 │ 3 │ 7 │ 8 │ 6 │ 1 │ 2 │ 0 ║
╟───────╫───┼───┼───┼───┼───┼───┼───┼───┼───╢
║     5 ║ 5 │ 3 │ 4 │ 8 │ 6 │ 7 │ 2 │ 0 │ 1 ║
╟───────╫───┼───┼───┼───┼───┼───┼───┼───┼───╢
║     6 ║ 6 │ 7 │ 8 │ 0 │ 1 │ 2 │ 3 │ 4 │ 5 ║
╟───────╫───┼───┼───┼───┼───┼───┼───┼───┼───╢
║     7 ║ 7 │ 8 │ 6 │ 1 │ 2 │ 0 │ 4 │ 5 │ 3 ║
╟───────╫───┼───┼───┼───┼───┼───┼───┼───┼───╢
║     8 ║ 8 │ 6 │ 7 │ 2 │ 0 │ 1 │ 5 │ 3 │ 4 ║
╚═══════╩═══╧═══╧═══╧═══╧═══╧═══╧═══╧═══╧═══╝
In [3]: GF.display("poly");

In [4]: print(GF.arithmetic_table("+"))
╔════════╦════════╤════════╤════════╤════════╤════════╤════════╤════════╤════════╤════════╗
║  x + y ║   0    │   1    │   2    │   α    │ α + 1  │ α + 2  │   2α   │ 2α + 1 │ 2α + 2 ║
╠════════╬════════╪════════╪════════╪════════╪════════╪════════╪════════╪════════╪════════╣
║      0 ║   0    │   1    │   2    │   α    │ α + 1  │ α + 2  │   2α   │ 2α + 1 │ 2α + 2 ║
╟────────╫────────┼────────┼────────┼────────┼────────┼────────┼────────┼────────┼────────╢
║      1 ║   1    │   2    │   0    │ α + 1  │ α + 2  │   α    │ 2α + 1 │ 2α + 2 │   2α   ║
╟────────╫────────┼────────┼────────┼────────┼────────┼────────┼────────┼────────┼────────╢
║      2 ║   2    │   0    │   1    │ α + 2  │   α    │ α + 1  │ 2α + 2 │   2α   │ 2α + 1 ║
╟────────╫────────┼────────┼────────┼────────┼────────┼────────┼────────┼────────┼────────╢
║      α ║   α    │ α + 1  │ α + 2  │   2α   │ 2α + 1 │ 2α + 2 │   0    │   1    │   2    ║
╟────────╫────────┼────────┼────────┼────────┼────────┼────────┼────────┼────────┼────────╢
║  α + 1 ║ α + 1  │ α + 2  │   α    │ 2α + 1 │ 2α + 2 │   2α   │   1    │   2    │   0    ║
╟────────╫────────┼────────┼────────┼────────┼────────┼────────┼────────┼────────┼────────╢
║  α + 2 ║ α + 2  │   α    │ α + 1  │ 2α + 2 │   2α   │ 2α + 1 │   2    │   0    │   1    ║
╟────────╫────────┼────────┼────────┼────────┼────────┼────────┼────────┼────────┼────────╢
║     2α ║   2α   │ 2α + 1 │ 2α + 2 │   0    │   1    │   2    │   α    │ α + 1  │ α + 2  ║
╟────────╫────────┼────────┼────────┼────────┼────────┼────────┼────────┼────────┼────────╢
║ 2α + 1 ║ 2α + 1 │ 2α + 2 │   2α   │   1    │   2    │   0    │ α + 1  │ α + 2  │   α    ║
╟────────╫────────┼────────┼────────┼────────┼────────┼────────┼────────┼────────┼────────╢
║ 2α + 2 ║ 2α + 2 │   2α   │ 2α + 1 │   2    │   0    │   1    │ α + 2  │   α    │ α + 1  ║
╚════════╩════════╧════════╧════════╧════════╧════════╧════════╧════════╧════════╧════════╝
In [5]: GF.display("power");

In [6]: print(GF.arithmetic_table("+"))
╔═══════╦═════╤═════╤═════╤═════╤═════╤═════╤═════╤═════╤═════╗
║ x + y ║  0  │  1  │  α  │ α^2 │ α^3 │ α^4 │ α^5 │ α^6 │ α^7 ║
╠═══════╬═════╪═════╪═════╪═════╪═════╪═════╪═════╪═════╪═════╣
║     0 ║  0  │  1  │  α  │ α^2 │ α^3 │ α^4 │ α^5 │ α^6 │ α^7 ║
╟───────╫─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────╢
║     1 ║  1  │ α^4 │ α^2 │ α^7 │ α^6 │  0  │ α^3 │ α^5 │  α  ║
╟───────╫─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────╢
║     α ║  α  │ α^2 │ α^5 │ α^3 │  1  │ α^7 │  0  │ α^4 │ α^6 ║
╟───────╫─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────╢
║   α^2 ║ α^2 │ α^7 │ α^3 │ α^6 │ α^4 │  α  │  1  │  0  │ α^5 ║
╟───────╫─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────╢
║   α^3 ║ α^3 │ α^6 │  1  │ α^4 │ α^7 │ α^5 │ α^2 │  α  │  0  ║
╟───────╫─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────╢
║   α^4 ║ α^4 │  0  │ α^7 │  α  │ α^5 │  1  │ α^6 │ α^3 │ α^2 ║
╟───────╫─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────╢
║   α^5 ║ α^5 │ α^3 │  0  │  1  │ α^2 │ α^6 │  α  │ α^7 │ α^4 ║
╟───────╫─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────╢
║   α^6 ║ α^6 │ α^5 │ α^4 │  0  │  α  │ α^3 │ α^7 │ α^2 │  1  ║
╟───────╫─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────╢
║   α^7 ║ α^7 │  α  │ α^6 │ α^5 │  0  │ α^2 │ α^4 │  1  │ α^3 ║
╚═══════╩═════╧═════╧═════╧═════╧═════╧═════╧═════╧═════╧═════╝
In [7]: GF.display("poly");

In [8]: x = GF.Random(5); x
Out[8]: GF([2, α + 1, α + 2, 2α, 2α + 2], order=3^2)

In [9]: y = GF.Random(3); y
Out[9]: GF([α + 2, 1, α], order=3^2)

In [10]: print(GF.arithmetic_table("+", x=x, y=y))
╔════════╦════════╤════════╤════════╗
║  x + y ║ α + 2  │   1    │   α    ║
╠════════╬════════╪════════╪════════╣
║      2 ║ α + 1  │   0    │ α + 2  ║
╟────────╫────────┼────────┼────────╢
║  α + 1 ║   2α   │ α + 2  │ 2α + 1 ║
╟────────╫────────┼────────┼────────╢
║  α + 2 ║ 2α + 1 │   α    │ 2α + 2 ║
╟────────╫────────┼────────┼────────╢
║     2α ║   2    │ 2α + 1 │   0    ║
╟────────╫────────┼────────┼────────╢
║ 2α + 2 ║   1    │   2α   │   2    ║
╚════════╩════════╧════════╧════════╝

In [11]: GF.display();
compile(mode)

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

This function updates ufunc_mode.

Parameters

mode (str) –

The ufunc calculation mode.

  • "auto": Selects “jit-lookup” for fields with order less than \(2^{20}\), “jit-calculate” for larger fields, and “python-calculate” for fields whose elements cannot be represented with numpy.int64.

  • "jit-lookup": JIT compiles arithmetic ufuncs to use Zech log, log, and anti-log lookup tables for efficient computation. In the few cases where explicit calculation is faster than table lookup, explicit calculation is used.

  • "jit-calculate": JIT compiles arithmetic ufuncs to use explicit calculation. The “jit-calculate” mode is designed for large fields that cannot or should not store lookup tables in RAM. Generally, the “jit-calculate” mode is slower than “jit-lookup”.

  • "python-calculate": Uses pure-python ufuncs with explicit calculation. This is reserved for fields whose elements cannot be represented with numpy.int64 and instead use numpy.object_ with python int (which has arbitrary precision).

display(mode='int')

Sets the display mode for all Galois field arrays of this type.

The display mode can be set to either the integer representation, polynomial representation, or power representation. This function updates display_mode.

Warning

For the power representation, np.log() is computed on each element. So for large fields without lookup tables, displaying arrays in the power representation may take longer than expected.

Parameters

mode (str, optional) –

The field element representation.

  • "int" (default): The element displayed as the integer representation of the polynomial. For example, \(2x^2 + x + 2\) is an element of \(\mathrm{GF}(3^3)\) and is equivalent to the integer \(23 = 2 \cdot 3^2 + 3 + 2\).

  • "poly": The element as a polynomial over \(\mathrm{GF}(p)\) of degree less than \(m\). For example, \(2x^2 + x + 2\) is an element of \(\mathrm{GF}(3^3)\).

  • "power": The element as a power of the primitive element, see FieldClass.primitive_element. For example, \(2x^2 + x + 2 = \alpha^5\) in \(\mathrm{GF}(3^3)\) with irreducible polynomial \(x^3 + 2x + 1\) and primitive element \(\alpha = x\).

Examples

Change the display mode by calling the display() method.

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

In [2]: print(GF.properties)
GF(3^3):
  characteristic: 3
  degree: 3
  order: 27
  irreducible_poly: x^3 + 2x + 1
  is_primitive_poly: True
  primitive_element: x

In [3]: a = GF(23); a
Out[3]: GF(23, order=3^3)

# Permanently set the display mode to the polynomial representation
In [4]: GF.display("poly"); a
Out[4]: GF(2α^2 + α + 2, order=3^3)

# Permanently set the display mode to the power representation
In [5]: GF.display("power"); a
Out[5]: GF(α^5, order=3^3)

# Permanently reset the default display mode to the integer representation
In [6]: GF.display(); a
Out[6]: GF(23, order=3^3)

The display() method can also be used as a context manager, as shown below.

For the polynomial representation, when the primitive element is \(\alpha = x\) in \(\mathrm{GF}(p)[x]\) the polynomial indeterminate used is \(\alpha\).

In [7]: GF = galois.GF(2**8)

In [8]: print(GF.properties)
GF(2^8):
  characteristic: 2
  degree: 8
  order: 256
  irreducible_poly: x^8 + x^4 + x^3 + x^2 + 1
  is_primitive_poly: True
  primitive_element: x

In [9]: a = GF.Random()

In [10]: print(GF.display_mode, a)
int GF(135, order=2^8)

In [11]: with GF.display("poly"):
   ....:     print(GF.display_mode, a)
   ....: 
poly GF(α^7 + α^2 + α + 1, order=2^8)

In [12]: with GF.display("power"):
   ....:     print(GF.display_mode, a)
   ....: 
power GF(α^13, order=2^8)

# The display mode is reset after exiting the context manager
In [13]: print(GF.display_mode, a)
int GF(135, order=2^8)

But when the primitive element is \(\alpha \ne x\) in \(\mathrm{GF}(p)[x]\), the polynomial indeterminate used is \(x\).

In [14]: GF = galois.GF(2**8, irreducible_poly=galois.Poly.Degrees([8,4,3,1,0]))

In [15]: print(GF.properties)
GF(2^8):
  characteristic: 2
  degree: 8
  order: 256
  irreducible_poly: x^8 + x^4 + x^3 + x + 1
  is_primitive_poly: False
  primitive_element: x + 1

In [16]: a = GF.Random()

In [17]: print(GF.display_mode, a)
int GF(123, order=2^8)

In [18]: with GF.display("poly"):
   ....:     print(GF.display_mode, a)
   ....: 
poly GF(x^6 + x^5 + x^4 + x^3 + x + 1, order=2^8)

In [19]: with GF.display("power"):
   ....:     print(GF.display_mode, a)
   ....: 
power GF(α^229, order=2^8)

# The display mode is reset after exiting the context manager
In [20]: print(GF.display_mode, a)
int GF(123, order=2^8)
repr_table(primitive_element=None, sort='power')

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

Parameters
  • primitive_element (galois.FieldArray, optional) – The primitive element to use for the power representation. The default is None which uses the field’s default primitive element, primitive_element.

  • sort (str, optional) – The sorting method for the table, either "power" (default), "poly", "vector", or "int". Sorting by “power” will order the rows of the table by ascending powers of the primitive element. Sorting by any of the others will order the rows in lexicographically-increasing polynomial/vector order, which is equivalent to ascending order of the integer representation.

Returns

A UTF-8 formatted table comparing the power, polynomial, vector, and integer representations of each field element.

Return type

str

Examples

In [1]: GF = galois.GF(2**4)

In [2]: print(GF.properties)
GF(2^4):
  characteristic: 2
  degree: 4
  order: 16
  irreducible_poly: x^4 + x + 1
  is_primitive_poly: True
  primitive_element: x

Generate a representation table for \(\mathrm{GF}(2^4)\). Since \(x^4 + x + 1\) is a primitive polynomial, \(x\) is a primitive element of the field. Notice, \(\textrm{ord}(x) = 15\).

In [3]: print(GF.repr_table())
╔═══════╤═══════════════════╤══════════════╤═════════╗
║ Power │     Polynomial    │    Vector    │ Integer ║
║═══════╪═══════════════════╪══════════════╪═════════║
║   0   │         0         │ [0, 0, 0, 0] │    0    ║
╟───────┼───────────────────┼──────────────┼─────────╢
║  x^0  │         1         │ [0, 0, 0, 1] │    1    ║
╟───────┼───────────────────┼──────────────┼─────────╢
║  x^1  │         x         │ [0, 0, 1, 0] │    2    ║
╟───────┼───────────────────┼──────────────┼─────────╢
║  x^2  │        x^2        │ [0, 1, 0, 0] │    4    ║
╟───────┼───────────────────┼──────────────┼─────────╢
║  x^3  │        x^3        │ [1, 0, 0, 0] │    8    ║
╟───────┼───────────────────┼──────────────┼─────────╢
║  x^4  │       x + 1       │ [0, 0, 1, 1] │    3    ║
╟───────┼───────────────────┼──────────────┼─────────╢
║  x^5  │      x^2 + x      │ [0, 1, 1, 0] │    6    ║
╟───────┼───────────────────┼──────────────┼─────────╢
║  x^6  │     x^3 + x^2     │ [1, 1, 0, 0] │    12   ║
╟───────┼───────────────────┼──────────────┼─────────╢
║  x^7  │    x^3 + x + 1    │ [1, 0, 1, 1] │    11   ║
╟───────┼───────────────────┼──────────────┼─────────╢
║  x^8  │      x^2 + 1      │ [0, 1, 0, 1] │    5    ║
╟───────┼───────────────────┼──────────────┼─────────╢
║  x^9  │      x^3 + x      │ [1, 0, 1, 0] │    10   ║
╟───────┼───────────────────┼──────────────┼─────────╢
║  x^10 │    x^2 + x + 1    │ [0, 1, 1, 1] │    7    ║
╟───────┼───────────────────┼──────────────┼─────────╢
║  x^11 │   x^3 + x^2 + x   │ [1, 1, 1, 0] │    14   ║
╟───────┼───────────────────┼──────────────┼─────────╢
║  x^12 │ x^3 + x^2 + x + 1 │ [1, 1, 1, 1] │    15   ║
╟───────┼───────────────────┼──────────────┼─────────╢
║  x^13 │   x^3 + x^2 + 1   │ [1, 1, 0, 1] │    13   ║
╟───────┼───────────────────┼──────────────┼─────────╢
║  x^14 │      x^3 + 1      │ [1, 0, 0, 1] │    9    ║
╚═══════╧═══════════════════╧══════════════╧═════════╝

Generate a representation table for \(\mathrm{GF}(2^4)\) using a different primitive element \(x^3 + x^2 + x\). Notice, \(\textrm{ord}(x^3 + x^2 + x) = 15\).

In [4]: alpha = GF.primitive_elements[-1]

In [5]: print(GF.repr_table(alpha))
╔════════════════════╤═══════════════════╤══════════════╤═════════╗
║       Power        │     Polynomial    │    Vector    │ Integer ║
║════════════════════╪═══════════════════╪══════════════╪═════════║
║         0          │         0         │ [0, 0, 0, 0] │    0    ║
╟────────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2 + x)^0  │         1         │ [0, 0, 0, 1] │    1    ║
╟────────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2 + x)^1  │   x^3 + x^2 + x   │ [1, 1, 1, 0] │    14   ║
╟────────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2 + x)^2  │    x^3 + x + 1    │ [1, 0, 1, 1] │    11   ║
╟────────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2 + x)^3  │        x^3        │ [1, 0, 0, 0] │    8    ║
╟────────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2 + x)^4  │      x^3 + 1      │ [1, 0, 0, 1] │    9    ║
╟────────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2 + x)^5  │    x^2 + x + 1    │ [0, 1, 1, 1] │    7    ║
╟────────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2 + x)^6  │     x^3 + x^2     │ [1, 1, 0, 0] │    12   ║
╟────────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2 + x)^7  │        x^2        │ [0, 1, 0, 0] │    4    ║
╟────────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2 + x)^8  │   x^3 + x^2 + 1   │ [1, 1, 0, 1] │    13   ║
╟────────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2 + x)^9  │      x^3 + x      │ [1, 0, 1, 0] │    10   ║
╟────────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2 + x)^10 │      x^2 + x      │ [0, 1, 1, 0] │    6    ║
╟────────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2 + x)^11 │         x         │ [0, 0, 1, 0] │    2    ║
╟────────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2 + x)^12 │ x^3 + x^2 + x + 1 │ [1, 1, 1, 1] │    15   ║
╟────────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2 + x)^13 │      x^2 + 1      │ [0, 1, 0, 1] │    5    ║
╟────────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2 + x)^14 │       x + 1       │ [0, 0, 1, 1] │    3    ║
╚════════════════════╧═══════════════════╧══════════════╧═════════╝

Generate a representation table for \(\mathrm{GF}(2^4)\) using a non-primitive element \(x^3 + x^2\). Notice, \(\textrm{ord}(x^3 + x^2) = 5 \ne 15\).

In [6]: beta = GF("x^3 + x^2")

In [7]: print(GF.repr_table(beta))
╔════════════════╤═══════════════════╤══════════════╤═════════╗
║     Power      │     Polynomial    │    Vector    │ Integer ║
║════════════════╪═══════════════════╪══════════════╪═════════║
║       0        │         0         │ [0, 0, 0, 0] │    0    ║
╟────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2)^0  │         1         │ [0, 0, 0, 1] │    1    ║
╟────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2)^1  │     x^3 + x^2     │ [1, 1, 0, 0] │    12   ║
╟────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2)^2  │ x^3 + x^2 + x + 1 │ [1, 1, 1, 1] │    15   ║
╟────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2)^3  │        x^3        │ [1, 0, 0, 0] │    8    ║
╟────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2)^4  │      x^3 + x      │ [1, 0, 1, 0] │    10   ║
╟────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2)^5  │         1         │ [0, 0, 0, 1] │    1    ║
╟────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2)^6  │     x^3 + x^2     │ [1, 1, 0, 0] │    12   ║
╟────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2)^7  │ x^3 + x^2 + x + 1 │ [1, 1, 1, 1] │    15   ║
╟────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2)^8  │        x^3        │ [1, 0, 0, 0] │    8    ║
╟────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2)^9  │      x^3 + x      │ [1, 0, 1, 0] │    10   ║
╟────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2)^10 │         1         │ [0, 0, 0, 1] │    1    ║
╟────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2)^11 │     x^3 + x^2     │ [1, 1, 0, 0] │    12   ║
╟────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2)^12 │ x^3 + x^2 + x + 1 │ [1, 1, 1, 1] │    15   ║
╟────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2)^13 │        x^3        │ [1, 0, 0, 0] │    8    ║
╟────────────────┼───────────────────┼──────────────┼─────────╢
║ (x^3 + x^2)^14 │      x^3 + x      │ [1, 0, 1, 0] │    10   ║
╚════════════════╧═══════════════════╧══════════════╧═════════╝
property characteristic

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

Examples

In [1]: GF = galois.GF(2**8, display="poly")

In [2]: GF.characteristic
Out[2]: 2

In [3]: a = GF.Random(low=1); a
Out[3]: GF(α^5 + α^4 + α^2 + α, order=2^8)

In [4]: a * GF.characteristic
Out[4]: GF(0, order=2^8)
In [5]: GF = galois.GF(31)

In [6]: GF.characteristic
Out[6]: 31

In [7]: a = GF.Random(low=1); a
Out[7]: GF(12, order=31)

In [8]: a * GF.characteristic
Out[8]: GF(0, order=31)
Type

int

property default_ufunc_mode

The default ufunc arithmetic mode for this Galois field.

Examples

In [1]: galois.GF(2).default_ufunc_mode
Out[1]: 'jit-calculate'

In [2]: galois.GF(2**8).default_ufunc_mode
Out[2]: 'jit-lookup'

In [3]: galois.GF(31).default_ufunc_mode
Out[3]: 'jit-lookup'

In [4]: galois.GF(2**100).default_ufunc_mode
Out[4]: 'python-calculate'
Type

str

property degree

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

Examples

In [1]: galois.GF(2).degree
Out[1]: 1

In [2]: galois.GF(2**8).degree
Out[2]: 8

In [3]: galois.GF(31).degree
Out[3]: 1

In [4]: galois.GF(7**5).degree
Out[4]: 5
Type

int

property display_mode

The representation of Galois field elements, either "int", "poly", or "power". This can be changed with display().

Examples

For the polynomial representation, when the primitive element is \(\alpha = x\) in \(\mathrm{GF}(p)[x]\) the polynomial indeterminate used is \(\alpha\).

In [1]: GF = galois.GF(2**8)

In [2]: print(GF.properties)
GF(2^8):
  characteristic: 2
  degree: 8
  order: 256
  irreducible_poly: x^8 + x^4 + x^3 + x^2 + 1
  is_primitive_poly: True
  primitive_element: x

In [3]: a = GF.Random()

In [4]: print(GF.display_mode, a)
int GF(63, order=2^8)

In [5]: with GF.display("poly"):
   ...:     print(GF.display_mode, a)
   ...: 
poly GF(α^5 + α^4 + α^3 + α^2 + α + 1, order=2^8)

In [6]: with GF.display("power"):
   ...:     print(GF.display_mode, a)
   ...: 
power GF(α^166, order=2^8)

# The display mode is reset after exiting the context manager
In [7]: print(GF.display_mode, a)
int GF(63, order=2^8)

But when the primitive element is \(\alpha \ne x\) in \(\mathrm{GF}(p)[x]\), the polynomial indeterminate used is \(x\).

In [8]: GF = galois.GF(2**8, irreducible_poly=galois.Poly.Degrees([8,4,3,1,0]))

In [9]: print(GF.properties)
GF(2^8):
  characteristic: 2
  degree: 8
  order: 256
  irreducible_poly: x^8 + x^4 + x^3 + x + 1
  is_primitive_poly: False
  primitive_element: x + 1

In [10]: a = GF.Random()

In [11]: print(GF.display_mode, a)
int GF(118, order=2^8)

In [12]: with GF.display("poly"):
   ....:     print(GF.display_mode, a)
   ....: 
poly GF(x^6 + x^5 + x^4 + x^2 + x, order=2^8)

In [13]: with GF.display("power"):
   ....:     print(GF.display_mode, a)
   ....: 
power GF(α^94, order=2^8)

# The display mode is reset after exiting the context manager
In [14]: print(GF.display_mode, a)
int GF(118, order=2^8)

The power representation displays elements as powers of \(\alpha\) the primitive element, see FieldClass.primitive_element.

In [15]: with GF.display("power"):
   ....:     print(GF.display_mode, a)
   ....: 
power GF(α^94, order=2^8)

# The display mode is reset after exiting the context manager
In [16]: print(GF.display_mode, a)
int GF(118, order=2^8)
Type

str

property dtypes

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

Examples

In [1]: GF = galois.GF(2); GF.dtypes
Out[1]: 
[numpy.uint8,
 numpy.uint16,
 numpy.uint32,
 numpy.int8,
 numpy.int16,
 numpy.int32,
 numpy.int64]

In [2]: GF = galois.GF(2**8); GF.dtypes
Out[2]: 
[numpy.uint8,
 numpy.uint16,
 numpy.uint32,
 numpy.int16,
 numpy.int32,
 numpy.int64]

In [3]: GF = galois.GF(31); GF.dtypes
Out[3]: 
[numpy.uint8,
 numpy.uint16,
 numpy.uint32,
 numpy.int8,
 numpy.int16,
 numpy.int32,
 numpy.int64]

In [4]: GF = galois.GF(7**5); GF.dtypes
Out[4]: [numpy.uint16, numpy.uint32, numpy.int16, numpy.int32, numpy.int64]

For Galois fields that cannot be represented by numpy.int64, the only valid dtype is numpy.object_.

In [5]: GF = galois.GF(2**100); GF.dtypes
Out[5]: [numpy.object_]

In [6]: GF = galois.GF(36893488147419103183); GF.dtypes
Out[6]: [numpy.object_]
Type

list

property irreducible_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)\).

Examples

In [1]: galois.GF(2).irreducible_poly
Out[1]: Poly(x + 1, GF(2))

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

In [3]: galois.GF(31).irreducible_poly
Out[3]: Poly(x + 28, GF(31))

In [4]: galois.GF(7**5).irreducible_poly
Out[4]: Poly(x^5 + x + 4, GF(7))
Type

galois.Poly

property is_extension_field

Indicates if the field’s order is a prime power.

Examples

In [1]: galois.GF(2).is_extension_field
Out[1]: False

In [2]: galois.GF(2**8).is_extension_field
Out[2]: True

In [3]: galois.GF(31).is_extension_field
Out[3]: False

In [4]: galois.GF(7**5).is_extension_field
Out[4]: True
Type

bool

property is_prime_field

Indicates if the field’s order is prime.

Examples

In [1]: galois.GF(2).is_prime_field
Out[1]: True

In [2]: galois.GF(2**8).is_prime_field
Out[2]: False

In [3]: galois.GF(31).is_prime_field
Out[3]: True

In [4]: galois.GF(7**5).is_prime_field
Out[4]: False
Type

bool

property is_primitive_poly

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

Examples

In [1]: GF = galois.GF(2**8, display="poly")

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

In [3]: GF.primitive_element
Out[3]: GF(α, order=2^8)

# The irreducible polynomial is a primitive polynomial if the primitive element is a root
In [4]: GF.irreducible_poly(GF.primitive_element, field=GF)
Out[4]: GF(0, order=2^8)

In [5]: GF.is_primitive_poly
Out[5]: True

Here is an example using the \(\mathrm{GF}(2^8)\) field from AES, which does not use a primitive polynomial.

In [6]: GF = galois.GF(2**8, irreducible_poly=galois.Poly.Degrees([8,4,3,1,0]), display="poly")

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

In [8]: GF.primitive_element
Out[8]: GF(x + 1, order=2^8)

# The irreducible polynomial is a primitive polynomial if the primitive element is a root
In [9]: GF.irreducible_poly(GF.primitive_element, field=GF)
Out[9]: GF(x^2 + x, order=2^8)

In [10]: GF.is_primitive_poly
Out[10]: False
Type

bool

property name

The Galois field name.

Examples

In [1]: galois.GF(2).name
Out[1]: 'GF(2)'

In [2]: galois.GF(2**8).name
Out[2]: 'GF(2^8)'

In [3]: galois.GF(31).name
Out[3]: 'GF(31)'

In [4]: galois.GF(7**5).name
Out[4]: 'GF(7^5)'
Type

str

property order

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

Examples

In [1]: galois.GF(2).order
Out[1]: 2

In [2]: galois.GF(2**8).order
Out[2]: 256

In [3]: galois.GF(31).order
Out[3]: 31

In [4]: galois.GF(7**5).order
Out[4]: 16807
Type

int

property prime_subfield

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

Examples

In [1]: print(galois.GF(2).prime_subfield.properties)
GF(2):
  characteristic: 2
  degree: 1
  order: 2
  irreducible_poly: x + 1
  is_primitive_poly: True
  primitive_element: 1

In [2]: print(galois.GF(2**8).prime_subfield.properties)
GF(2):
  characteristic: 2
  degree: 1
  order: 2
  irreducible_poly: x + 1
  is_primitive_poly: True
  primitive_element: 1

In [3]: print(galois.GF(31).prime_subfield.properties)
GF(31):
  characteristic: 31
  degree: 1
  order: 31
  irreducible_poly: x + 28
  is_primitive_poly: True
  primitive_element: 3

In [4]: print(galois.GF(7**5).prime_subfield.properties)
GF(7):
  characteristic: 7
  degree: 1
  order: 7
  irreducible_poly: x + 4
  is_primitive_poly: True
  primitive_element: 3
Type

galois.FieldClass

property primitive_element

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}\}\).

A primitive element is a root of the primitive polynomial \(f(x)\), such that \(f(\alpha) = 0\) over \(\mathrm{GF}(p^m)\).

Examples

In [1]: galois.GF(2).primitive_element
Out[1]: GF(1, order=2)

In [2]: galois.GF(2**8).primitive_element
Out[2]: GF(2, order=2^8)

In [3]: galois.GF(31).primitive_element
Out[3]: GF(3, order=31)

In [4]: galois.GF(7**5).primitive_element
Out[4]: GF(7, order=7^5)
Type

galois.FieldArray

property primitive_elements

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}\}\).

Examples

In [1]: galois.GF(2).primitive_elements
Out[1]: GF([1], order=2)

In [2]: galois.GF(2**8).primitive_elements
Out[2]: 
GF([  2,   4,   6,   9,  13,  14,  16,  18,  19,  20,  22,  24,  25,  27,
     29,  30,  31,  34,  35,  40,  42,  43,  48,  49,  50,  52,  57,  60,
     63,  65,  66,  67,  71,  72,  73,  74,  75,  76,  81,  82,  83,  84,
     88,  90,  91,  92,  93,  95,  98,  99, 104, 105, 109, 111, 112, 113,
    118, 119, 121, 122, 123, 126, 128, 129, 131, 133, 135, 136, 137, 140,
    141, 142, 144, 148, 149, 151, 154, 155, 157, 158, 159, 162, 163, 164,
    165, 170, 171, 175, 176, 177, 178, 183, 187, 188, 189, 192, 194, 198,
    199, 200, 201, 202, 203, 204, 209, 210, 211, 212, 213, 216, 218, 222,
    224, 225, 227, 229, 232, 234, 236, 238, 240, 243, 246, 247, 248, 249,
    250, 254], order=2^8)

In [3]: galois.GF(31).primitive_elements
Out[3]: GF([ 3, 11, 12, 13, 17, 21, 22, 24], order=31)

In [4]: galois.GF(7**5).primitive_elements
Out[4]: GF([    7,     8,    14, ..., 16797, 16798, 16803], order=7^5)
Type

galois.FieldArray

property properties

A formatted string displaying relevant properties of the Galois field.

Examples

In [1]: GF = galois.GF(2); print(GF.properties)
GF(2):
  characteristic: 2
  degree: 1
  order: 2
  irreducible_poly: x + 1
  is_primitive_poly: True
  primitive_element: 1

In [2]: GF = galois.GF(2**8); print(GF.properties)
GF(2^8):
  characteristic: 2
  degree: 8
  order: 256
  irreducible_poly: x^8 + x^4 + x^3 + x^2 + 1
  is_primitive_poly: True
  primitive_element: x

In [3]: GF = galois.GF(31); print(GF.properties)
GF(31):
  characteristic: 31
  degree: 1
  order: 31
  irreducible_poly: x + 28
  is_primitive_poly: True
  primitive_element: 3

In [4]: GF = galois.GF(7**5); print(GF.properties)
GF(7^5):
  characteristic: 7
  degree: 5
  order: 16807
  irreducible_poly: x^5 + x + 4
  is_primitive_poly: True
  primitive_element: x
Type

str

property ufunc_mode

The mode for ufunc compilation, either "jit-lookup", "jit-calculate", or "python-calculate".

Examples

In [1]: galois.GF(2).ufunc_mode
Out[1]: 'jit-calculate'

In [2]: galois.GF(2**8).ufunc_mode
Out[2]: 'jit-lookup'

In [3]: galois.GF(31).ufunc_mode
Out[3]: 'jit-lookup'

In [4]: galois.GF(7**5).ufunc_mode
Out[4]: 'jit-lookup'
Type

str

property ufunc_modes

All supported ufunc modes for this Galois field array class.

Examples

In [1]: galois.GF(2).ufunc_modes
Out[1]: ['jit-calculate']

In [2]: galois.GF(2**8).ufunc_modes
Out[2]: ['jit-lookup', 'jit-calculate']

In [3]: galois.GF(31).ufunc_modes
Out[3]: ['jit-lookup', 'jit-calculate']

In [4]: galois.GF(2**100).ufunc_modes
Out[4]: ['python-calculate']
Type

list