galois.GFArray¶

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

Bases: numpy.ndarray

Create an array over \(\mathrm{GF}(p^m)\).

The galois.GFArray class is a parent class for all Galois field array classes. Any Galois field \(\mathrm{GF}(p^m)\) with prime characteristic \(p\) and positive integer \(m\), can be constructed by calling the class factory galois.GF(p**m).

Warning

This is an abstract base class for all Galois field array classes. galois.GFArray cannot be instantiated directly. Instead, Galois field array classes are created using galois.GF.

For example, one can create the \(\mathrm{GF}(7)\) field array class as follows:

In [41]: GF7 = galois.GF(7)

In [42]: print(GF7)
<class 'numpy.ndarray' over GF(7)>

This subclass can then be used to instantiate arrays over \(\mathrm{GF}(7)\).

In [43]: GF7([3,5,0,2,1])
Out[43]: GF([3, 5, 0, 2, 1], order=7)

In [44]: GF7.Random((2,5))
Out[44]: 
GF([[0, 0, 6, 1, 0],
    [5, 5, 0, 5, 4]], order=7)

galois.GFArray is a subclass of numpy.ndarray. The galois.GFArray constructor has the same syntax as numpy.array. The returned galois.GFArray object is an array that can be acted upon like any other numpy array.

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 copy keyword argument from numpy.array. Setting dtype will explicitly set the data type of each element. The default is None which represents the smallest valid dtype for this field class, i.e. cls.dtypes[0].
copy (bool, optional) – The copy keyword argument from numpy.array. The default is True which makes a copy of the input object is it’s an array.
order (str, optional) – The order keyword argument from numpy.array. Valid values are "K" (default), "A", "C", or "F".
ndmin (int, optional) – The ndmin keyword argument from numpy.array. The minimum number of dimensions of the output. The default is 0.

Returns

The copied input array as a \(\mathrm{GF}(p^m)\) field array.

Return type

galois.GFArray

Examples

Construct various kinds of Galois fields using galois.GF.

# Construct a GF(2^m) class
In [45]: GF256 = galois.GF(2**8); print(GF256)
<class 'numpy.ndarray' over GF(2^8)>

# Construct a GF(p) class
In [46]: GF571 = galois.GF(571); print(GF571)
<class 'numpy.ndarray' over GF(571)>

# Construct a very large GF(2^m) class
In [47]: GF2m = galois.GF(2**100); print(GF2m)
<class 'numpy.ndarray' over GF(2^100)>

# Construct a very large GF(p) class
In [48]: GFp = galois.GF(36893488147419103183); print(GFp)
<class 'numpy.ndarray' over GF(36893488147419103183)>

Depending on the field’s order (size), only certain dtype values will be supported.

In [49]: GF256.dtypes
Out[49]: 
[numpy.uint8,
 numpy.uint16,
 numpy.uint32,
 numpy.int16,
 numpy.int32,
 numpy.int64]

In [50]: GF571.dtypes
Out[50]: [numpy.uint16, numpy.uint32, numpy.int16, numpy.int32, numpy.int64]

Very large fields, which can’t be represented using np.int64, can only be represented as dtype=np.object_.

In [51]: GF2m.dtypes
Out[51]: [numpy.object_]

In [52]: GFp.dtypes
Out[52]: [numpy.object_]

Newly-created arrays will use the smallest, valid dtype.

In [53]: a = GF256.Random(10); a
Out[53]: GF([ 50, 168,  53, 108, 103, 218, 207, 249, 247, 127], order=2^8)

In [54]: a.dtype
Out[54]: dtype('uint8')

This can be explicitly set by specifying the dtype keyword argument.

In [55]: a = GF256.Random(10, dtype=np.uint32); a
Out[55]: GF([ 25,   7, 145, 246, 214, 138, 193, 133,  37,   4], order=2^8)

In [56]: a.dtype
Out[56]: dtype('uint32')

Arrays can also be created explicitly by converting an “array-like” object.

# Construct a Galois field array from a list
In [57]: l = [142, 27, 92, 253, 103]; l
Out[57]: [142, 27, 92, 253, 103]

In [58]: GF256(l)
Out[58]: GF([142,  27,  92, 253, 103], order=2^8)

# Construct a Galois field array from an existing numpy array
In [59]: x_np = np.array(l, dtype=np.int64); x_np
Out[59]: array([142,  27,  92, 253, 103])

In [60]: GF256(l)
Out[60]: GF([142,  27,  92, 253, 103], order=2^8)

Arrays can also be created by “view casting” from an existing numpy array. This avoids a copy operation, which is especially useful for large data already brought into memory.

In [61]: a = x_np.view(GF256); a
Out[61]: GF([142,  27,  92, 253, 103], order=2^8)

# Changing `x_np` will change `a`
In [62]: x_np[0] = 0; x_np
Out[62]: array([  0,  27,  92, 253, 103])

In [63]: a
Out[63]: GF([  0,  27,  92, 253, 103], order=2^8)

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, mode[, rebuild])	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)[source]¶

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 [64]: GF = galois.GF(31)

In [65]: GF.Elements()
Out[65]: 
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)[source]¶

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 [66]: GF = galois.GF(31)

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

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

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 [68]: GF = galois.GF(31)

In [69]: GF.Random((2,5))
Out[69]: 
GF([[15, 23, 17,  0, 18],
    [21, 27,  5, 17,  7]], order=31)

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

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 [70]: GF = galois.GF(31)

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

classmethod Zeros(shape, dtype=None)[source]¶

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 [72]: GF = galois.GF(31)

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

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

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

In [75]: a = GF.Random(4); a
Out[75]: GF([2, 7, 6, 2], order=2^3)

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

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

# Reset the print mode
In [78]: GF.display(); a
Out[78]: GF([2, 7, 6, 2], order=2^3)

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

# The original display mode
In [79]: print(a)
GF([2, 7, 6, 2], order=2^3)

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

# Returns to the original display mode
In [81]: print(a)
GF([2, 7, 6, 2], order=2^3)

classmethod target(target, mode, rebuild=False)[source]¶: Retarget the just-in-time compiled numba ufuncs.

alpha = None¶

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 = None¶

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 = None¶

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

Type: int

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

Type: list

order = None¶

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 = None¶

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 = None¶

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

Type: str

ufunc_target = None¶

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

Type: str