galois.GF2¶

class galois.GF2(array, dtype=None, copy=True, order='K', ndmin=0)[source]¶

Bases: galois.gf.GFArray

Create an array over \(\mathrm{GF}(2)\).

Note

This Galois field class is a pre-made subclass of galois.GFArray. It is included in the package because of the ubiquity of \(\mathrm{GF}(2)\) fields.

# The pre-made GF(2) class
In [9]: print(galois.GF2)
<class 'numpy.ndarray' over GF(2)>

# The GF class factory for an order of 2 returns `galois.GF2`
In [10]: GF2 = galois.GF(2); print(GF2)
<class 'numpy.ndarray' over GF(2)>

In [11]: GF2 is galois.GF2
Out[11]: True

Parameters

array (array_like) – The input array to be converted to a Galois field array. The input array is copied, so the original array is unmodified by changes to the Galois field array. Valid input array types are numpy.ndarray, list, tuple, or int.
dtype (numpy.dtype, optional) – The numpy.dtype of the array elements. The default is numpy.int64.

Returns

The copied input array as a \(\mathrm{GF}(2)\) field array.

Return type

galois.GF2

Examples

Various Galois field properties are accessible as class attributes.

In [12]: print(galois.GF2)
<class 'numpy.ndarray' over GF(2)>

In [13]: galois.GF2.characteristic
Out[13]: 2

In [14]: galois.GF2.degree
Out[14]: 1

In [15]: galois.GF2.order
Out[15]: 2

In [16]: galois.GF2.prim_poly
Out[16]: Poly(x + 1, GF(2))

Construct arrays over \(\mathrm{GF}(2)\).

In [17]: a = galois.GF2([1,0,1,1]); a
Out[17]: GF([1, 0, 1, 1], order=2)

In [18]: b = galois.GF2([1,1,1,1]); b
Out[18]: GF([1, 1, 1, 1], order=2)

Perform array arithmetic over \(\mathrm{GF}(2)\).

# Element-wise addition
In [19]: a + b
Out[19]: GF([0, 1, 0, 0], order=2)

# Element-wise subtraction
In [20]: a - b
Out[20]: GF([0, 1, 0, 0], order=2)

# Element-wise multiplication
In [21]: a * b
Out[21]: GF([1, 0, 1, 1], order=2)

# Element-wise division
In [22]: a / b
Out[22]: GF([1, 0, 1, 1], order=2)

Constructors

`Elements`([dtype])	Create a Galois field array of the field’s elements \(\{0, \dots, p^m-1\}\).
`Ones`(shape[, dtype])	Create a Galois field array with all ones.
`Random`([shape, low, high, dtype])	Create a Galois field array with random field elements.
`Range`(start, stop[, step, dtype])	Create a Galois field array with a range of field elements.
`Zeros`(shape[, dtype])	Create a Galois field array with all zeros.

Methods

`display`([mode, poly_var])	Sets the printing mode for arrays.
`target`(target)	Retarget the just-in-time compiled `numba` ufuncs.

Attributes

`alpha`	The primitive element \(\alpha\) of the Galois field \(\mathrm{GF}(p^m)\).
`characteristic`	The prime characteristic \(p\) of the Galois field \(\mathrm{GF}(p^m)\).
`degree`	The prime characteristic’s degree \(m\) of the Galois field \(\mathrm{GF}(p^m)\).
`dtypes`	List of valid integer `numpy.dtype` objects that are compatible with this Galois field.
`order`	The order \(p^m\) of the Galois field \(\mathrm{GF}(p^m)\).
`prim_poly`	The primitive polynomial \(p(x)\) of the Galois field \(\mathrm{GF}(p^m)\).
`ufunc_mode`	The mode for ufunc compilation, either `"lookup"`, `"calculate"`, `"object"`.
`ufunc_target`	The numba target for the JIT-compiled ufuncs, either `"cpu"`, `"parallel"`, `"cuda"`, or `None`.

classmethod Elements(dtype=None)¶

Create a Galois field array of the field’s elements \(\{0, \dots, p^m-1\}\).

Parameters: dtype (numpy.dtype, optional) – The numpy.dtype of the array elements. The default is None which represents the smallest valid dtype for this field class, i.e. cls.dtypes[0].
Returns: A Galois field array of all the field’s elements.
Return type: galois.GFArray

Examples

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

In [24]: GF.Elements()
Out[24]: 
GF([ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14, 15, 16,
    17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30], order=31)

classmethod Ones(shape, dtype=None)¶

Create a Galois field array with all ones.

Parameters

shape (tuple) – A numpy-compliant shape tuple, see numpy.ndarray.shape. An empty tuple () represents a scalar. A single integer or 1-tuple, e.g. N or (N,), represents the size of a 1-dim array. An n-tuple, e.g. (M,N), represents an n-dim array with each element indicating the size in each dimension.
dtype (numpy.dtype, optional) – The numpy.dtype of the array elements. The default is None which represents the smallest valid dtype for this field class, i.e. cls.dtypes[0].

Returns

A Galois field array of ones.

Return type

galois.GFArray

Examples

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

In [26]: GF.Ones((2,5))
Out[26]: 
GF([[1, 1, 1, 1, 1],
    [1, 1, 1, 1, 1]], order=31)

classmethod Random(shape=(), low=0, high=None, dtype=None)¶

Create a Galois field array with random field elements.

Parameters

shape (tuple) – A numpy-compliant shape tuple, see numpy.ndarray.shape. An empty tuple () represents a scalar. A single integer or 1-tuple, e.g. N or (N,), represents the size of a 1-dim array. An n-tuple, e.g. (M,N), represents an n-dim array with each element indicating the size in each dimension.
low (int, optional) – The lowest value (inclusive) of a random field element. The default is 0.
high (int, optional) – The highest value (exclusive) of a random field element. The default is None which represents the field’s order \(p^m\).
dtype (numpy.dtype, optional) – The numpy.dtype of the array elements. The default is None which represents the smallest valid dtype for this field class, i.e. cls.dtypes[0].

Returns

A Galois field array of random field elements.

Return type

galois.GFArray

Examples

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

In [28]: GF.Random((2,5))
Out[28]: 
GF([[24, 16, 19, 25, 11],
    [29, 17, 13, 18,  8]], order=31)

classmethod Range(start, stop, step=1, dtype=None)¶

Create a Galois field array with a range of field elements.

Parameters

start (int) – The starting value (inclusive).
stop (int) – The stopping value (exclusive).
step (int, optional) – The space between values. The default is 1.
dtype (numpy.dtype, optional) – The numpy.dtype of the array elements. The default is None which represents the smallest valid dtype for this field class, i.e. cls.dtypes[0].

Returns

A Galois field array of a range of field elements.

Return type

galois.GFArray

Examples

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

In [30]: GF.Range(10,20)
Out[30]: GF([10, 11, 12, 13, 14, 15, 16, 17, 18, 19], order=31)

classmethod Zeros(shape, dtype=None)¶

Create a Galois field array with all zeros.

Parameters

shape (tuple) – A numpy-compliant shape tuple, see numpy.ndarray.shape. An empty tuple () represents a scalar. A single integer or 1-tuple, e.g. N or (N,), represents the size of a 1-dim array. An n-tuple, e.g. (M,N), represents an n-dim array with each element indicating the size in each dimension.
dtype (numpy.dtype, optional) – The numpy.dtype of the array elements. The default is None which represents the smallest valid dtype for this field class, i.e. cls.dtypes[0].

Returns

A Galois field array of zeros.

Return type

galois.GFArray

Examples

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

In [32]: GF.Zeros((2,5))
Out[32]: 
GF([[0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0]], order=31)

classmethod display(mode='int', poly_var='x')¶

Sets the printing mode for arrays.

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 "x".

Examples

Change the display mode by calling the galois.GFArray.display method.

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

In [34]: a = GF.Random(4); a
Out[34]: GF([1, 4, 5, 5], order=2^3)

In [35]: GF.display("poly"); a
Out[35]: GF([1, x^2, x^2 + 1, x^2 + 1], order=2^3)

In [36]: GF.display("poly", "r"); a
Out[36]: GF([1, r^2, r^2 + 1, r^2 + 1], order=2^3)

# Reset the print mode
In [37]: GF.display(); a
Out[37]: GF([1, 4, 5, 5], order=2^3)

The galois.GFArray.display method can also be used as a context manager.

# The original display mode
In [38]: print(a)
GF([1, 4, 5, 5], order=2^3)

# The new display context
In [39]: with GF.display("poly"):
   ....:     print(a)
   ....: 
GF([1, x^2, x^2 + 1, x^2 + 1], order=2^3)

# Returns to the original display mode
In [40]: print(a)
GF([1, 4, 5, 5], order=2^3)

classmethod target(target)[source]¶

Retarget the just-in-time compiled numba ufuncs.

Parameters: target (str) – The target keyword argument from numba.vectorize, either "cpu", "parallel", or "cuda".

alpha = GF(1, order=2)¶

The primitive element \(\alpha\) of the Galois field \(\mathrm{GF}(p^m)\). The primitive element is a root of the primitive polynomial \(p(x)\), such that \(p(\alpha) = 0\). The primitive element is also a multiplicative generator of the field, such that \(\mathrm{GF}(p^m) = \{0, 1, \alpha^1, \alpha^2, \dots, \alpha^{p^m - 2}\}\).

Type: int

characteristic = 2¶

The prime characteristic \(p\) of the Galois field \(\mathrm{GF}(p^m)\). Adding \(p\) copies of any element will always result in \(0\).

Type: int

degree = 1¶

The prime characteristic’s degree \(m\) of the Galois field \(\mathrm{GF}(p^m)\). The degree is a positive integer.

Type: int

dtypes = [<class 'numpy.uint8'>, <class 'numpy.uint16'>, <class 'numpy.uint32'>, <class 'numpy.int8'>, <class 'numpy.int16'>, <class 'numpy.int32'>, <class 'numpy.int64'>]¶

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)\).

Type: list

order = 2¶

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.

Type: int

prim_poly = Poly(x + 1, GF(2))¶

The primitive polynomial \(p(x)\) of the Galois field \(\mathrm{GF}(p^m)\). The primitive polynomial is of degree \(m\) in \(\mathrm{GF}(p)[x]\).

Type: galois.Poly

ufunc_mode = 'calculate'¶

The mode for ufunc compilation, either "lookup", "calculate", "object".

Type: str

ufunc_target = 'cpu'¶

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

Type: str