galois.GF

class galois.GF(order, irreducible_poly=None, primitive_element=None, verify=True, mode='auto')

Factory function to construct a Galois field array class for \(\mathrm{GF}(p^m)\).

The created class will be a subclass of galois.FieldArray and instance of galois.FieldClass. The galois.FieldArray inheritance provides the numpy.ndarray functionality. The galois.FieldClass metaclass provides a variety of class attributes and methods relating to the finite field.

Parameters

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

  • irreducible_poly (int, tuple, list, numpy.ndarray, galois.Poly, optional) – Optionally specify an irreducible polynomial of degree \(m\) over \(\mathrm{GF}(p)\) that will define the Galois field arithmetic. An integer may be provided, which is the integer representation of the irreducible polynomial. A tuple, list, or ndarray may be provided, which represents the polynomial coefficients in degree-descending order. The default is None which uses the Conway polynomial \(C_{p,m}\) obtained from galois.conway_poly().

  • primitive_element (int, tuple, list, numpy.ndarray, galois.Poly, optional) – Optionally specify a primitive element of the field \(\mathrm{GF}(p^m)\). A primitive element is a generator of the multiplicative group of the field. For prime fields \(\mathrm{GF}(p)\), the primitive element must be an integer and is a primitive root modulo \(p\). For extension fields \(\mathrm{GF}(p^m)\), the primitive element is a polynomial of degree less than \(m\) over \(\mathrm{GF}(p)\). An integer may be provided, which is the integer representation of the polynomial. A tuple, list, or ndarray may be provided, which represents the polynomial coefficients in degree-descending order. The default is None which uses galois.primitive_root(p) for prime fields and galois.primitive_element(irreducible_poly) for extension fields.

  • verify (bool, optional) – Indicates whether to verify that the specified irreducible polynomial is in fact irreducible and that the 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 (and may take a long time to verify), this argument can be set to False. If the default irreducible polynomial and primitive element are used, no verification is performed because the defaults are already guaranteed to be irreducible and a multiplicative generator, respectively.

  • mode (str, optional) – The type of field computation, either "auto", "jit-lookup", or "jit-calculate". The default is "auto". The “jit-lookup” mode will use Zech log, log, and anti-log lookup tables for efficient calculation. The “jit-calculate” mode will not store any lookup tables, but instead perform field arithmetic on the fly. The “jit-calculate” mode is designed for large fields that cannot or should not store lookup tables in RAM. Generally, “jit-calculate” mode will be slower than “jit-lookup”. The “auto” mode will determine whether to use “jit-lookup” or “jit-calculate” based on the field’s size. In “auto” mode, field’s with order <= 2**20 will use the “jit-lookup” mode.

Returns

A new Galois field array class that is a subclass of galois.FieldArray and instance of galois.FieldClass.

Return type

galois.FieldClass

Examples

Construct a Galois field array class with default irreducible polynomial and primitive element.

# Construct a GF(2^m) class
In [1]: GF256 = galois.GF(2**8)

# Notice the irreducible polynomial is primitive
In [2]: print(GF256.properties)
GF(2^8):
  characteristic: 2
  degree: 8
  order: 256
  irreducible_poly: Poly(x^8 + x^4 + x^3 + x^2 + 1, GF(2))
  is_primitive_poly: True
  primitive_element: GF(2, order=2^8)

In [3]: poly = GF256.irreducible_poly

Construct a Galois field specifying a specific irreducible polynomial.

# Field used in AES
In [4]: GF256_AES = galois.GF(2**8, irreducible_poly=galois.Poly.Degrees([8,4,3,1,0]))

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

# Construct a GF(p) class
In [6]: GF571 = galois.GF(571); print(GF571.properties)
GF(571):
  characteristic: 571
  degree: 1
  order: 571

# Construct a very large GF(2^m) class
In [7]: GF2m = galois.GF(2**100); print(GF2m.properties)
GF(2^100):
  characteristic: 2
  degree: 100
  order: 1267650600228229401496703205376
  irreducible_poly: 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, GF(2))
  is_primitive_poly: True
  primitive_element: GF(2, order=2^100)

# Construct a very large GF(p) class
In [8]: GFp = galois.GF(36893488147419103183); print(GFp.properties)
GF(36893488147419103183):
  characteristic: 36893488147419103183
  degree: 1
  order: 36893488147419103183

See galois.FieldArray for more examples of what Galois field arrays can do.