galois.GF¶

galois.GF(order, irreducible_poly=None, primitive_element=None, verify=True, compile=None, display=None)¶

Creates a Galois field array class for \(\mathrm{GF}(p^m)\).

See Galois Field Classes for a detailed discussion of the relationship between galois.FieldClass and galois.FieldArray.

Parameters¶

order : int¶

The order \(p^m\) of the field \(\mathrm{GF}(p^m)\). The order must be a prime power.

irreducible_poly : Optional[Union[int, str, Sequence[int], ndarray, FieldArray, Poly]]¶

Optionally specify an irreducible polynomial of degree \(m\) over \(\mathrm{GF}(p)\) that will define the Galois field arithmetic.

• None (default): Uses the Conway polynomial \(C_{p,m}\). See galois.conway_poly().

• int: The integer representation of the irreducible polynomial.

• str: The irreducible polynomial expressed as a string, e.g. "x^2 + 1".

• tuple, list, numpy.ndarray: The irreducible polynomial coefficients in degree-descending order.

• galois.Poly: The irreducible polynomial as a polynomial object.

primitive_element : Optional[Union[int, str, Sequence[int], ndarray, FieldArray, Poly]]¶

Optionally specify a primitive element of the field. This value is used when building the exponential and logarithm lookup tables and when computing numpy.log. A primitive element is a generator of the multiplicative group of the field.

Prime fields

For prime fields \(\mathrm{GF}(p)\), the primitive element must be an integer and is a primitive root modulo \(p\).

• None (default): Uses the minimal primitive root modulo \(p\). See galois.primitive_root().

• int: A primitive root modulo \(p\).

Extension fields

For extension fields \(\mathrm{GF}(p^m)\), the primitive element is a polynomial of degree less than \(m\) over \(\mathrm{GF}(p)\).

• None (default): Uses the lexicographically-minimal primitive element. See galois.primitive_element().

• int: The integer representation of the primitive element.

• str: The primitive element expressed as a string, e.g. "x + 1".

• tuple, list, numpy.ndarray: The primitive element’s polynomial coefficients in degree-descending order.

• galois.Poly: The primitive element as a polynomial object.

verify : bool¶

Indicates whether to verify that the user-specified irreducible polynomial is in fact irreducible and that the user-specified primitive element is in fact a generator of the multiplicative group. The default is True.

For large fields and irreducible polynomials that are already known to be irreducible (which may take a while to verify), this argument may be set to False.

The default irreducible polynomial and primitive element are never verified because they are known to be irreducible and a multiplicative generator.

compile : Optional[Literal['auto', 'jit-lookup', 'jit-calculate', 'python-calculate']]¶

The ufunc calculation mode. This can be modified after class construction with the galois.FieldClass.compile() method. See Compilation Modes for a further discussion.

• None (default): For newly-created classes, None corresponds to "auto". For Galois field array classes of this type that were previously created, None does not modify the current ufunc compilation 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 : Optional[Literal['int', 'poly', 'power']]¶

The field element display representation. This can be modified after class construction with the galois.FieldClass.display() method. See Field Element Representation for a further discussion.

• None (default): For newly-created classes, None corresponds to "int". For Galois field array classes of this type that were previously created, None does not modify the current display mode.

• "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 Galois field array class for \(\mathrm{GF}(p^m)\). If this class has already been created, a reference to that class is returned.

Return type¶

Type[FieldArray]

Notes

The created Galois field array class is a subclass of galois.FieldArray and an instance of galois.FieldClass. The galois.FieldArray inheritance provides the numpy.ndarray functionality and some additional methods on Galois field arrays. The galois.FieldClass metaclass provides a variety of class attributes and methods relating to the finite field.

Galois field array classes of the same type (order, irreducible polynomial, and primitive element) are singletons. So, calling this class factory with arguments that correspond to the same class will return the same class object.

Examples

Create a Galois field array class for each type of finite field.

GF(2)

Construct the binary field.

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

In [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

GF(p)

Construct a prime field.

In [3]: GF = galois.GF(31)

In [4]: print(GF)
Galois Field:
  name: GF(31)
  characteristic: 31
  degree: 1
  order: 31
  irreducible_poly: x + 28
  is_primitive_poly: True
  primitive_element: 3

GF(2^m)

Construct a binary extension field. Notice the default irreducible polynomial is primitive and \(x\) is a primitive element.

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

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

GF(p^m)

Construct a prime extension field. Notice the default irreducible polynomial is primitive and \(x\) is a primitive element.

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

In [8]: print(GF)
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 Galois field array class for extension fields and specify their irreducible polynomial.

GF(2^m)

Construct the \(\mathrm{GF}(2^8)\) field that is used in AES. Notice the irreducible polynomial is not primitive and \(x\) is not a primitive element.

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

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

GF(p^m)

Construct \(\mathrm{GF}(3^5)\) with an irreducible, but not primitive, polynomial. Notice that \(x\) is not a primitive element.

In [11]: GF = galois.GF(3**5, irreducible_poly="x^5 + 2x + 2")

In [12]: print(GF)
Galois Field:
  name: GF(3^5)
  characteristic: 3
  degree: 5
  order: 243
  irreducible_poly: x^5 + 2x + 2
  is_primitive_poly: False
  primitive_element: 2x

Arbitrarily-large finite fields are also supported.

GF(p)

Construct an arbitrarily-large prime field.

In [13]: GF = galois.GF(36893488147419103183)

In [14]: print(GF)
Galois Field:
  name: GF(36893488147419103183)
  characteristic: 36893488147419103183
  degree: 1
  order: 36893488147419103183
  irreducible_poly: x + 36893488147419103180
  is_primitive_poly: True
  primitive_element: 3

GF(2^m)

Construct an arbitrarily-large binary extension field.

In [15]: GF = galois.GF(2**100)

In [16]: print(GF)
Galois Field:
  name: GF(2^100)
  characteristic: 2
  degree: 100
  order: 1267650600228229401496703205376
  irreducible_poly: x^100 + x^57 + x^56 + x^55 + x^52 + x^48 + x^47 + x^46 + x^45 + x^44 + x^43 + x^41 + x^37 + x^36 + x^35 + x^34 + x^31 + x^30 + x^27 + x^25 + x^24 + x^22 + x^20 + x^19 + x^16 + x^15 + x^11 + x^9 + x^8 + x^6 + x^5 + x^3 + 1
  is_primitive_poly: True
  primitive_element: x

GF(p^m)

Construct an arbitrarily-large prime extension field.

In [17]: GF = galois.GF(109987**4)

In [18]: print(GF)
Galois Field:
  name: GF(109987^4)
  characteristic: 109987
  degree: 4
  order: 146340800268433348561
  irreducible_poly: x^4 + 3x^2 + 100525x + 3
  is_primitive_poly: True
  primitive_element: x