galois.FieldClass¶

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

Defines a metaclass for all galois.FieldArray classes.

Important

galois.FieldClass is a metaclass for galois.FieldArray subclasses created with the class factory galois.GF() and should not be instantiated directly. This metaclass gives galois.FieldArray subclasses methods and attributes related to their Galois fields.

This class is included in the API to allow the user to test if a class is a Galois field array class.

In [1]: GF = galois.GF(7)

In [2]: isinstance(GF, galois.FieldClass)
Out[2]: True

Constructors

__init__(name, bases, namespace, **kwargs)

Special Methods

__repr__()	Return repr(self).
__str__()	A formatted string displaying relevant properties of the finite field.

Methods

arithmetic_table(operation[, x, y])	Generates the specified arithmetic table for the finite field.
compile(mode)	Recompile the just-in-time compiled ufuncs for a new calculation mode.
display([mode])	Sets the display mode for all Galois field arrays from this field.
repr_table([primitive_element, sort])	Generates a finite 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 compilation mode for this Galois field array class.
degree	The extension degree \(m\) of the Galois field \(\mathrm{GF}(p^m)\).
display_mode	The current finite field element representation.
dtypes	List of valid integer numpy.dtype values that are compatible with this finite field.
irreducible_poly	The irreducible polynomial \(f(x)\) of the Galois field \(\mathrm{GF}(p^m)\).
is_extension_field	Indicates if the finite field is an extension field.
is_prime_field	Indicates if the finite field is a prime field, not an extension field.
is_primitive_poly	Indicates whether the FieldClass.irreducible_poly is a primitive polynomial.
name	The finite field's name as a string GF(p) or GF(p^m).
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)\).
quadratic_non_residues	All quadratic non-residues in the Galois field.
quadratic_residues	All quadratic residues in the finite field.
ufunc_mode	The current ufunc compilation mode.
ufunc_modes	All supported ufunc compilation modes for this Galois field array class.

__init__(name, bases, namespace, **kwargs)¶

__repr__()¶

Return repr(self).

__str__()¶

A formatted string displaying relevant properties of the finite field.

Examples

In [1]: GF = galois.GF(2); print(GF)
Galois Field:
  name: 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)
Galois Field:
  name: 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)
Galois Field:
  name: 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)
Galois Field:
  name: GF(7^5)
  characteristic: 7
  degree: 5
  order: 16807
  irreducible_poly: x^5 + x + 4
  is_primitive_poly: True
  primitive_element: x

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

Generates the specified arithmetic table for the finite field.

Parameters

operation : Literal['+', '-', '*', '/']

The arithmetic operation.

x : Optional[galois.FieldArray]

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

y : Optional[galois.FieldArray]

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

Arithmetic tables can be displayed using the integer representation.

Integer

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 |
+-------+---+---+---+---+---+---+---+---+---+

Polynomial

In [3]: GF = galois.GF(3**2, 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 |
+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+

Power

In [5]: GF = galois.GF(3**2, 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 |
+-------+-----+-----+-----+-----+-----+-----+-----+-----+-----+

An arithmetic table may also be constructed from arbitrary \(x\) and \(y\).

Integer

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

In [8]: x = GF([7, 2, 8]); x
Out[8]: GF([α^3, α^4, α^6], order=3^2)

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

In [10]: print(GF.arithmetic_table("+", x=x, y=y))
+-------+-----+-----+
| x + y |   1 | α^2 |
+-------+-----+-----+
|   α^3 | α^6 | α^4 |
+-------+-----+-----+
|   α^4 |   0 |   α |
+-------+-----+-----+
|   α^6 | α^5 |   0 |
+-------+-----+-----+

Polynomial

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

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

In [13]: y = GF([1, 4]); y
Out[13]: GF([    1, α + 1], order=3^2)

In [14]: print(GF.arithmetic_table("+", x=x, y=y))
+--------+--------+--------+
|  x + y |      1 |  α + 1 |
+--------+--------+--------+
| 2α + 1 | 2α + 2 |      2 |
+--------+--------+--------+
|      2 |      0 |      α |
+--------+--------+--------+
| 2α + 2 |     2α |      0 |
+--------+--------+--------+

Power

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

In [16]: x = GF([7, 2, 8]); x
Out[16]: GF([α^3, α^4, α^6], order=3^2)

In [17]: y = GF([1, 4]); y
Out[17]: GF([  1, α^2], order=3^2)

In [18]: print(GF.arithmetic_table("+", x=x, y=y))
+-------+-----+-----+
| x + y |   1 | α^2 |
+-------+-----+-----+
|   α^3 | α^6 | α^4 |
+-------+-----+-----+
|   α^4 |   0 |   α |
+-------+-----+-----+
|   α^6 | α^5 |   0 |
+-------+-----+-----+

compile(mode)¶

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

This function updates ufunc_mode.

Parameters

mode : Literal['auto', 'jit-lookup', 'jit-calculate', 'python-calculate']

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 from this field.

The display mode can be set to either the integer representation, polynomial representation, or power representation. See Field Element Representation for a further discussion.

This function updates display_mode.

Warning

For the power representation, numpy.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 : Literal['int', 'poly', 'power']

The field element representation.

• "int": Sets the display mode to the integer representation.

• "poly": Sets the display mode to the polynomial representation.

• "power": Sets the display mode to the power representation.

Returns

A context manager for use in a with statement. If permanently setting the display mode, disregard the return value.

Return type

contextlib.AbstractContextManager

Examples

The default display mode is the integer representation.

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

In [2]: x = GF.Elements(); x
Out[2]: GF([0, 1, 2, 3, 4, 5, 6, 7, 8], order=3^2)

Permanently set the display mode by calling display().

Polynomial

In [3]: GF.display("poly");

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

Power

In [5]: GF.display("power");

In [6]: x
Out[6]: GF([  0,   1, α^4,   α, α^2, α^7, α^5, α^3, α^6], order=3^2)

Temporarily modify the display mode by using display() as a context manager.

Polynomial

In [7]: print(x)
[0, 1, 2, 3, 4, 5, 6, 7, 8]

In [8]: with GF.display("poly"):
   ...:     print(x)
   ...: 
[     0,      1,      2,      α,  α + 1,  α + 2,     2α, 2α + 1, 2α + 2]

# Outside the context manager, the display mode reverts to its previous value
In [9]: print(x)
[0, 1, 2, 3, 4, 5, 6, 7, 8]

Power

In [10]: print(x)
[0, 1, 2, 3, 4, 5, 6, 7, 8]

In [11]: with GF.display("power"):
   ....:     print(x)
   ....: 
[  0,   1, α^4,   α, α^2, α^7, α^5, α^3, α^6]

# Outside the context manager, the display mode reverts to its previous value
In [12]: print(x)
[0, 1, 2, 3, 4, 5, 6, 7, 8]

repr_table(primitive_element=None, sort='power')¶

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

Parameters

primitive_element : Optional[Union[int, str, numpy.ndarray, galois.FieldArray]]

The primitive element to use for the power representation. The default is None which uses the field’s default primitive element, FieldClass.primitive_element. If an array, it must be a 0-D array.

sort : Literal['power', 'poly', 'vector', 'int']

The sorting method for the table. The default is "power". 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

Create a Galois field array class for \(\mathrm{GF}(2^4)\).

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

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

Default

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    |
+-------+-------------------+--------------+---------+

Primitive element

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]: print(GF.repr_table("x^3 + x^2 + x"))
+--------------------+-------------------+--------------+---------+
|       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    |
+--------------------+-------------------+--------------+---------+

Non-primitive element

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 [5]: print(GF.repr_table("x^3 + x^2"))
+----------------+-------------------+--------------+---------+
|     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 : int¶

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]: galois.GF(2).characteristic
Out[1]: 2

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

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

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

property default_ufunc_mode : Literal['jit-lookup', 'jit-calculate', 'python-calculate']¶

The default ufunc compilation mode for this Galois field array class.

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'

property degree : int¶

The extension 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

property display_mode : Literal['int', 'poly', 'power']¶

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

See Field Element Representation for a further discussion.

Examples

The default display mode is the integer representation.

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

In [2]: x = GF.Elements(); x
Out[2]: GF([0, 1, 2, 3, 4, 5, 6, 7, 8], order=3^2)

In [3]: GF.display_mode
Out[3]: 'int'

Permanently modify the display mode by calling display().

In [4]: GF.display("poly");

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

In [6]: GF.display_mode
Out[6]: 'poly'

property dtypes : List[numpy.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.

For finite fields whose elements cannot be represented with numpy.int64, the only valid data type is numpy.object_.

Examples

Some data types are too small for certain finite fields, such as numpy.int16 for \(\mathrm{GF}(7^5)\).

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

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

Large fields must use numpy.object_ which uses Python int for its unlimited size.

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

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

property irreducible_poly : galois.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))

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.

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

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.

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

property is_primitive_poly : bool¶

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

The default irreducible polynomial is a Conway polynomial, see galois.conway_poly(), which is a primitive polynomial. However, finite fields may be constructed from non-primitive, irreducible polynomials.

Examples

The default \(\mathrm{GF}(2^8)\) field uses a primitive polynomial.

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

In [2]: print(GF)
Galois Field:
  name: 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.is_primitive_poly
Out[3]: True

The \(\mathrm{GF}(2^8)\) field from AES uses a non-primitive polynomial.

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

In [5]: print(GF)
Galois Field:
  name: 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 [6]: GF.is_primitive_poly
Out[6]: False

property name : str¶

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

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)'

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.

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

property prime_subfield : galois.FieldClass¶

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

Examples

In [1]: galois.GF(2).prime_subfield
Out[1]: <class 'numpy.ndarray over GF(2)'>

In [2]: galois.GF(2**8).prime_subfield
Out[2]: <class 'numpy.ndarray over GF(2)'>

In [3]: galois.GF(31).prime_subfield
Out[3]: <class 'numpy.ndarray over GF(31)'>

In [4]: galois.GF(7**5).prime_subfield
Out[4]: <class 'numpy.ndarray over GF(7)'>

property primitive_element : galois.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}\}\).

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)

property primitive_elements : galois.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}\}\).

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)

property quadratic_non_residues : galois.FieldArray¶

All quadratic non-residues in the Galois field.

An element \(x\) in \(\mathrm{GF}(p^m)\) is a quadratic non-residue if there does not exist a \(y\) such that \(y^2 = x\) in the field.

In fields with characteristic 2, no elements are quadratic non-residues. In fields with characteristic greater than 2, exactly half of the nonzero elements are quadratic non-residues.

See also FieldArray.is_quadratic_residue().

Examples

In [1]: GF = galois.GF(11)

In [2]: GF.quadratic_non_residues
Out[2]: GF([ 2,  6,  7,  8, 10], order=11)

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

In [4]: GF.quadratic_non_residues
Out[4]: GF([], order=2^4)

property quadratic_residues : galois.FieldArray¶

All quadratic residues in the finite field.

An element \(x\) in \(\mathrm{GF}(p^m)\) is a quadratic residue if there exists a \(y\) such that \(y^2 = x\) in the field.

In fields with characteristic 2, every element is a quadratic residue. In fields with characteristic greater than 2, exactly half of the nonzero elements are quadratic residues (and they have two unique square roots).

See also FieldArray.is_quadratic_residue().

Examples

In [1]: GF = galois.GF(11)

In [2]: x = GF.quadratic_residues; x
Out[2]: GF([0, 1, 3, 4, 5, 9], order=11)

In [3]: r = np.sqrt(x); r
Out[3]: GF([0, 1, 5, 2, 4, 3], order=11)

In [4]: r ** 2
Out[4]: GF([0, 1, 3, 4, 5, 9], order=11)

In [5]: (-r) ** 2
Out[5]: GF([0, 1, 3, 4, 5, 9], order=11)

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

In [7]: x = GF.quadratic_residues; x
Out[7]: 
GF([ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14, 15],
   order=2^4)

In [8]: r = np.sqrt(x); r
Out[8]: 
GF([ 0,  1,  5,  4,  2,  3,  7,  6, 10, 11, 15, 14,  8,  9, 13, 12],
   order=2^4)

In [9]: r ** 2
Out[9]: 
GF([ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14, 15],
   order=2^4)

In [10]: (-r) ** 2
Out[10]: 
GF([ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14, 15],
   order=2^4)

property ufunc_mode : Literal['jit-lookup', 'jit-calculate', 'python-calculate']¶

The current ufunc compilation mode. The ufuncs can be recompiled with compile().

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'

property ufunc_modes : List[str]¶

All supported ufunc compilation 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']