galois.FieldMeta¶

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

Defines a metaclass for all galois.FieldArray classes.

This metaclass gives galois.FieldArray 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])	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"`, `"poly"`, or `"power"`.
`dtypes`	List of valid integer `numpy.dtype` objects that are compatible with this group, ring, or 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 group, ring, or field.
`short_name`	The abbreviated name of the finite group, ring, or field.
`structure`	The algebraic structure of the array class.
`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')¶

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.FieldMeta.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.FieldMeta.ufunc_targets.

display(mode='int')[source]¶

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.

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

Parameters: mode (str, optional) – The field element display mode, either "int" (default), "poly", or "power".

Examples

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

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

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

# Change the display mode going forward
In [82]: GF.display("poly"); a
Out[82]: GF(α^7 + α^5 + α^3, order=2^8)

In [83]: GF.display("power"); a
Out[83]: GF(α^144, order=2^8)

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

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

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

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

In [86]: print(GF.properties)
GF(2^8):
  structure: Finite Field
  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 [87]: a = GF.Random(); a
Out[87]: GF(141, order=2^8)

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

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

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

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

In [91]: print(GF.properties)
GF(2^8):
  structure: Finite Field
  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)

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

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

In [94]: with GF.display("power"):
   ....:     print(a)
   ....: 
GF(α^121, 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 [95]: GF = galois.GF(2**8)

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

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

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

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

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

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

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

Type: int

property default_ufunc_mode¶

The default ufunc arithmetic mode for this Galois field.

Examples

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

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

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

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

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

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

In [110]: galois.GF(7**5).degree
Out[110]: 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 \(x \in \mathrm{GF}(p)[x]\) the polynomial indeterminate used is α.

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

In [112]: print(GF.properties)
GF(2^8):
  structure: Finite Field
  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 [113]: a = GF.Random(); a
Out[113]: GF(146, order=2^8)

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

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

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

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

In [117]: print(GF.properties)
GF(2^8):
  structure: Finite Field
  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)

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

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

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

Type: str

property dtypes¶

List of valid integer numpy.dtype objects that are compatible with this group, ring, or field.

Examples

In [121]: G = galois.Group(16, "+"); G.dtypes
Out[121]: 
[numpy.uint8,
 numpy.uint16,
 numpy.uint32,
 numpy.int8,
 numpy.int16,
 numpy.int32,
 numpy.int64]

In [122]: G = galois.Group(16, "*"); G.dtypes
Out[122]: 
[numpy.uint8,
 numpy.uint16,
 numpy.uint32,
 numpy.int8,
 numpy.int16,
 numpy.int32,
 numpy.int64]

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

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

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

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

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

In [127]: G = galois.Group(10**20, "*"); G.dtypes
Out[127]: [numpy.object_]

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

In [129]: GF = galois.GF(36893488147419103183); GF.dtypes
Out[129]: [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 [130]: galois.GF(2).irreducible_poly
Out[130]: Poly(x + 1, GF(2))

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

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

In [133]: galois.GF(7**5).irreducible_poly
Out[133]: 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 [134]: galois.GF(2).is_extension_field
Out[134]: False

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

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

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

Type: bool

property is_prime_field¶

Indicates if the field’s order is prime.

Examples

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

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

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

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

Type: bool

property is_primitive_poly¶

Indicates whether the irreducible_poly is a primitive polynomial.

Examples

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

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

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

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

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

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

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

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

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

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

Type: bool

property name¶

The Galois field name.

Examples

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

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

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

In [155]: galois.GF(7**5).name
Out[155]: '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 [156]: galois.GF(2).order
Out[156]: 2

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

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

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

Type: int

property prime_subfield¶

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

Examples

In [160]: print(galois.GF(2).prime_subfield.properties)
GF(2):
  structure: Finite Field
  characteristic: 2
  degree: 1
  order: 2

In [161]: print(galois.GF(2**8).prime_subfield.properties)
GF(2):
  structure: Finite Field
  characteristic: 2
  degree: 1
  order: 2

In [162]: print(galois.GF(31).prime_subfield.properties)
GF(31):
  structure: Finite Field
  characteristic: 31
  degree: 1
  order: 31

In [163]: print(galois.GF(7**5).prime_subfield.properties)
GF(7):
  structure: Finite Field
  characteristic: 7
  degree: 1
  order: 7

Type: galois.FieldMeta

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

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

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

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

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 [168]: galois.GF(2).primitive_elements
Out[168]: GF([1], order=2)

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

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

Type: int

property properties¶

A formatted string displaying relevant properties of group, ring, or field.

Examples

In [172]: G = galois.Group(16, "+"); print(G.properties)
(ℤ/16ℤ)+:
  structure: Finite Additive Group
  modulus: 16
  order: 16
  generator: 1
  is_cyclic: True
  is_abelian: True

In [173]: G = galois.Group(16, "*"); print(G.properties)
(ℤ/16ℤ)*:
  structure: Finite Multiplicative Group
  modulus: 16
  order: 8
  generator: None
  is_cyclic: False
  is_abelian: True

In [174]: GF = galois.GF(2); print(GF.properties)
GF(2):
  structure: Finite Field
  characteristic: 2
  degree: 1
  order: 2

In [175]: GF = galois.GF(2**8); print(GF.properties)
GF(2^8):
  structure: Finite Field
  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 [176]: GF = galois.GF(31); print(GF.properties)
GF(31):
  structure: Finite Field
  characteristic: 31
  degree: 1
  order: 31

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

Type: str

property short_name¶

The abbreviated name of the finite group, ring, or field.

Examples

In [178]: G = galois.Group(16, "+"); G.short_name
Out[178]: 'ℤn+'

In [179]: G = galois.Group(16, "*"); G.short_name
Out[179]: 'ℤn*'

In [180]: GF = galois.GF(2**4); GF.short_name
Out[180]: 'GF'

Type: str

property structure¶

The algebraic structure of the array class.

Examples

In [181]: G = galois.Group(16, "+"); G.structure
Out[181]: 'Finite Additive Group'

In [182]: G = galois.Group(16, "*"); G.structure
Out[182]: 'Finite Multiplicative Group'

In [183]: GF = galois.GF(2**4); GF.structure
Out[183]: 'Finite Field'

Type: str

property ufunc_mode¶

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

Examples

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

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

In [186]: galois.GF(31).ufunc_mode
Out[186]: '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 [187]: galois.GF(2).ufunc_modes
Out[187]: ['jit-calculate']

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

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

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

Type: list

property ufunc_target¶

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

Examples

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

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

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

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

Type: str

property ufunc_targets¶

All supported ufunc targets for this Galois field array class.

Examples

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

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

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

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

Type: list