galois.GFMeta¶

class galois.GFMeta(name, bases, namespace, **kwargs)[source]¶

Defines a metaclass for all galois.GFArray classes.

This metaclass gives galois.GFArray classes returned from galois.GF() class methods and properties relating to its Galois field.

Constructors

Methods

`compile`(mode[, target])	Recompile the just-in-time compiled numba ufuncs with a new calculation mode or target.
`display`([mode, poly_var])	Sets the display mode for all Galois field arrays of this type.

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"` or `"poly"`.
`display_poly_var`	The polynomial indeterminate for the polynomial representation of the field elements.
`dtypes`	List of valid integer `numpy.dtype` objects that are compatible with this Galois field.
`ground_field`	The ground field \(\mathrm{GF}(p)\) of the extension field \(\mathrm{GF}(p^m)\).
`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)\).
`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 formmatted string displaying relevant properties of the Galois field.
`ufunc_mode`	The mode for ufunc compilation, either `"jit-lookup"`, `"jit-calculate"`, `"python-calculate"`.
`ufunc_modes`	All supported ufunc modes for this Galois field array class.
`ufunc_target`	The numba target for the JIT-compiled ufuncs, either `"cpu"`, `"parallel"`, or `"cuda"`.
`ufunc_targets`	All supported ufunc targets for this Galois field array class.

compile(mode, target='cpu')[source]¶

Recompile the just-in-time compiled numba ufuncs with a new calculation mode or target.

Parameters

mode (str) – The method of field computation, either "jit-lookup", "jit-calculate", "python-calculate". The “jit-lookup” mode will use Zech log, log, and anti-log lookup tables for speed. The “jit-calculate” mode will not store any lookup tables, but perform field arithmetic on the fly. The “jit-calculate” mode is designed for large fields that cannot store lookup tables in RAM. Generally, “jit-calculate” is slower than “jit-lookup”. The “python-calculate” mode is reserved for extremely large fields. In this mode the ufuncs are not JIT-compiled, but are pur python functions operating on python ints. The list of valid modes for this field is in galois.GFMeta.ufunc_modes.
target (str, optional) – The target keyword argument from numba.vectorize, either "cpu", "parallel", or "cuda". The default is "cpu". For extremely large fields the only supported target is "cpu" (which doesn’t use numba it uses pure python to calculate the field arithmetic). The list of valid targets for this field is in galois.GFMeta.ufunc_targets.

display(mode='int', poly_var='α')[source]¶

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

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

Parameters

mode (str, optional) – The field element display mode, either "int" (default) or "poly".
poly_var (str, optional) – The polynomial representation’s variable. The default is "α".

Examples

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

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

In [120]: a = GF.Random(); a
Out[120]: GF(219, order=2^8)

In [121]: GF.display("poly"); a
Out[121]: GF(α^7 + α^6 + α^4 + α^3 + α + 1, order=2^8)

# Reset to the default display mode
In [122]: GF.display(); a
Out[122]: GF(219, order=2^8)

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

# The original display mode
In [123]: a
Out[123]: GF(219, order=2^8)

# The new display context
In [124]: with GF.display("poly"):
   .....:     print(a)
   .....: 
GF(α^7 + α^6 + α^4 + α^3 + α + 1, order=2^8)

# Returns to the default display mode
In [125]: a
Out[125]: GF(219, order=2^8)

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 [126]: GF = galois.GF(2**8)

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

In [128]: a = GF.Random(); a
Out[128]: GF(47, order=2^8)

In [129]: a * GF.characteristic
Out[129]: GF(0, order=2^8)

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

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

In [132]: a = GF.Random(); a
Out[132]: GF(0, order=31)

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

Type: int

property default_ufunc_mode¶

The default ufunc arithmetic mode for this Galois field.

Examples

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

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

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

In [137]: galois.GF(2**100).default_ufunc_mode
Out[137]: '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 [138]: galois.GF(2).degree
Out[138]: 1

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

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

# galois.GF(7**5).degree

Type: int

property display_mode¶

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

Examples

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

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

In [143]: a = GF.Random(); a
Out[143]: GF(218, order=2^8)

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

Type: str

property display_poly_var¶

The polynomial indeterminate for the polynomial representation of the field elements. The default is "α". This can be changed with display().

Examples

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

In [146]: GF.display_mode, GF.display_poly_var
Out[146]: ('int', 'α')

In [147]: a = GF.Random(); a
Out[147]: GF(44, order=2^8)

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

Type: str

property dtypes¶

List of valid integer numpy.dtype objects that are compatible with this Galois field. Valid data types are signed and unsinged integers that can represent decimal values in \([0, p^m)\).

Examples

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

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

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

# galois.GF(7**5).dtypes

For field’s with orders that cannot be represented by numpy.int64, the only valid dtype is numpy.object_.

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

In [153]: galois.GF(36893488147419103183).dtypes
Out[153]: [numpy.object_]

Type: list

property ground_field¶

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

Examples

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

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

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

# print(galois.GF(7**5).ground_field.properties)

Type: galois.GFMeta

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 [157]: galois.GF(2).irreducible_poly
Out[157]: Poly(x + 1, GF(2))

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

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

# galois.GF(7**5).irreducible_poly

Type: galois.Poly

property is_extension_field¶

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

Examples

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

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

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

# galois.GF(7**5).is_extension_field

Type: bool

property is_prime_field¶

Indicates if the field’s order is prime.

Examples

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

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

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

# galois.GF(7**5).is_prime_field

Type: bool

property is_primitive_poly¶

Indicates whether the irreducible_poly is a primitive polynomial.

Examples

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

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

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

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

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

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

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

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

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

In [175]: GF.is_primitive_poly
Out[175]: False

Type: bool

property name¶

The Galois field name.

Examples

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

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

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

# galois.GF(7**5).name

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

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

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

# galois.GF(7**5).order

Type: int

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^1, \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 [182]: galois.GF(2).primitive_element
Out[182]: GF(1, order=2)

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

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

# galois.GF(7**5).primitive_element

Type: int

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^1, \alpha^2, \dots, \alpha^{p^m - 2}\}\).

Examples

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

In [186]: galois.GF(2**8).primitive_elements
Out[186]: 
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 [187]: galois.GF(31).primitive_elements
Out[187]: GF([ 3, 11, 12, 13, 17, 21, 22, 24], order=31)

# galois.GF(7**5).primitive_elements

Type: int

property properties¶

A formmatted string displaying relevant properties of the Galois field.

Examples

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

In [189]: print(galois.GF(2**8).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 [190]: print(galois.GF(31).properties)
GF(31):
  characteristic: 31
  degree: 1
  order: 31
  irreducible_poly: Poly(x + 28, GF(31))
  is_primitive_poly: True
  primitive_element: GF(3, order=31)

# print(galois.GF(7**5).properties)

Type: str

property ufunc_mode¶

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

Examples

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

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

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

# galois.GF(7**5).ufunc_mode

Type: str

property ufunc_modes¶

All supported ufunc modes for this Galois field array class.

Examples

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

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

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

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

Type: list

property ufunc_target¶

The numba target for the JIT-compiled ufuncs, either "cpu", "parallel", or "cuda".

Examples

In [198]: galois.GF(2).ufunc_target
Out[198]: 'cpu'

In [199]: galois.GF(2**8).ufunc_target
Out[199]: 'cpu'

In [200]: galois.GF(31).ufunc_target
Out[200]: 'cpu'

# galois.GF(7**5).ufunc_target

Type: str

property ufunc_targets¶

All supported ufunc targets for this Galois field array class.

Examples

In [201]: galois.GF(2).ufunc_targets
Out[201]: ['cpu', 'parallel', 'cuda']

In [202]: galois.GF(2**8).ufunc_targets
Out[202]: ['cpu', 'parallel', 'cuda']

In [203]: galois.GF(31).ufunc_targets
Out[203]: ['cpu', 'parallel', 'cuda']

In [204]: galois.GF(2**100).ufunc_targets
Out[204]: ['cpu']

Type: list