galois.GF¶
-
class
galois.
GF
(array, dtype=None)[source]¶ Bases:
numpy.ndarray
Create an array over \(\mathrm{GF}(p^m)\).
Warning
This is an abstract base class for all Galois field array classes.
galois.GF
cannot be instantiated directly. Instead, Galois field array classes are created usinggalois.GF_factory
.For example, one can create the \(\mathrm{GF}(7)\) field array class as follows:
In [5]: GF7 = galois.GF_factory(7, 1) In [6]: print(GF7) <Galois Field: GF(7^1), prim_poly = x + 4 (11 decimal)>
This subclass can then be used to instantiate arrays over \(\mathrm{GF}(7)\).
In [7]: GF7([3,5,0,2,1]) Out[7]: GF([3, 5, 0, 2, 1], order=7) In [8]: GF7.Random((2,5)) Out[8]: GF([[5, 2, 1, 2, 6], [4, 4, 0, 2, 2]], order=7)
- 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
, orint
.dtype (numpy.dtype, optional) – The
numpy.dtype
of the array elements. The default isnumpy.int64
.
- Returns
The copied input array as a \(\mathrm{GF}(p^m)\) field array.
- Return type
Examples
Construct various kinds of Galois fields using
galois.GF_factory
.# Construct a GF(2^m) class In [9]: GF256 = galois.GF_factory(2, 8); print(GF256) <Galois Field: GF(2^8), prim_poly = x^8 + x^4 + x^3 + x^2 + 1 (285 decimal)> # Construct a GF(p) class In [10]: GF571 = galois.GF_factory(571, 1); print(GF571) <Galois Field: GF(571^1), prim_poly = x + 568 (1139 decimal)> # Construct a very large GF(2^m) class In [11]: GF2m = galois.GF_factory(2, 100); print(GF2m) <Galois Field: GF(2^100), prim_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 (1267650600228486663289456659305 decimal)> # Construct a very large GF(p) class In [12]: GFp = galois.GF_factory(36893488147419103183, 1); print(GFp) <Galois Field: GF(36893488147419103183^1), prim_poly = x + 36893488147419103180 (73786976294838206363 decimal)>
Depending on the field’s order (size), only certain
dtype
values will be supported.In [13]: GF256.dtypes Out[13]: [numpy.uint8, numpy.uint16, numpy.uint32, numpy.int16, numpy.int32, numpy.int64] In [14]: GF571.dtypes Out[14]: [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 asdtype=np.object_
.In [15]: GF2m.dtypes Out[15]: [numpy.object_] In [16]: GFp.dtypes Out[16]: [numpy.object_]
Newly-created arrays will use the smallest, valid dtype.
In [17]: a = GF256.Random(10); a Out[17]: GF([118, 8, 55, 98, 95, 41, 42, 114, 149, 126], order=2^8) In [18]: a.dtype Out[18]: dtype('uint8')
This can be explicitly set by specifying the
dtype
keyword argument.In [19]: a = GF256.Random(10, dtype=np.uint32); a Out[19]: GF([ 76, 173, 184, 211, 5, 8, 113, 199, 74, 40], order=2^8) In [20]: a.dtype Out[20]: dtype('uint32')
Arrays can be created explicitly by converting an “array-like” object.
# Construct a Galois field array from a list In [21]: l = [142, 27, 92, 253, 103]; l Out[21]: [142, 27, 92, 253, 103] In [22]: GF256(l) Out[22]: GF([142, 27, 92, 253, 103], order=2^8) # Construct a Galois field array from an existing numpy array In [23]: x_np = np.array(l, dtype=np.int64); x_np Out[23]: array([142, 27, 92, 253, 103]) In [24]: GF256(l) Out[24]: GF([142, 27, 92, 253, 103], order=2^8)
Arrays can also be created by “view casting” from an existing numpy array in memory. This avoids a copy operation, which is especially useful for large data already brought into memory.
In [25]: a = x_np.view(GF256); a Out[25]: GF([142, 27, 92, 253, 103], order=2^8) # Changing `x_np` will change `a` In [26]: x_np[0] = 0; x_np Out[26]: array([ 0, 27, 92, 253, 103]) In [27]: a Out[27]: 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
The primitive element of the Galois field \(\mathrm{GF}(p^m)\).
The prime characteristic \(p\) of the Galois field \(\mathrm{GF}(p^m)\).
The prime characteristic’s degree \(m\) of the Galois field \(\mathrm{GF}(p^m)\).
List of valid integer
numpy.dtype
objects that are compatible with this Galois field.The order \(p^m\) of the Galois field \(\mathrm{GF}(p^m)\).
The primitive polynomial \(p(x)\) of the Galois field \(\mathrm{GF}(p^m)\).
The mode for ufunc compilation, either
"lookup"
or"calculate"
.The numba target for the JIT-compiled ufuncs, either
"cpu"
,"parallel"
, or"cuda"
.-
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 isNone
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
Examples
In [28]: GF = galois.GF_factory(31, 1) In [29]: GF.Elements() Out[29]: 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, seenumpy.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 isNone
which represents the smallest valid dtype for this field class, i.e.cls.dtypes[0]
.
- Returns
A Galois field array of ones.
- Return type
Examples
In [30]: GF = galois.GF_factory(31, 1) In [31]: GF.Ones((2,5)) Out[31]: 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, seenumpy.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 isNone
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
Examples
In [32]: GF = galois.GF_factory(31, 1) In [33]: GF.Random((2,5)) Out[33]: GF([[28, 20, 16, 21, 21], [15, 11, 20, 12, 8]], 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 isNone
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
Examples
In [34]: GF = galois.GF_factory(31, 1) In [35]: GF.Range(10,20) Out[35]: 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, seenumpy.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 isNone
which represents the smallest valid dtype for this field class, i.e.cls.dtypes[0]
.
- Returns
A Galois field array of zeros.
- Return type
Examples
In [36]: GF = galois.GF_factory(31, 1) In [37]: GF.Zeros((2,5)) Out[37]: 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
Examples
Change the display mode by calling the
galois.GF.display
method.In [38]: GF = galois.GF_factory(2, 3) In [39]: a = GF.Random(4); a Out[39]: GF([1, 6, 1, 2], order=2^3) In [40]: GF.display("poly"); a Out[40]: GF([1, x^2 + x, 1, x], order=2^3) In [41]: GF.display("poly", "r"); a Out[41]: GF([1, r^2 + r, 1, r], order=2^3) # Reset the print mode In [42]: GF.display(); a Out[42]: GF([1, 6, 1, 2], order=2^3)
The
galois.GF.display
method can also be used as a context manager.# The original display mode In [43]: print(a) GF([1, 6, 1, 2], order=2^3) # The new display context In [44]: with GF.display("poly"): ....: print(a) ....: GF([1, x^2 + x, 1, x], order=2^3) # Returns to the original display mode In [45]: print(a) GF([1, 6, 1, 2], order=2^3)
-
classmethod
target
(target, mode, rebuild=False)[source]¶ Retarget the just-in-time compiled numba ufuncs.
-
alpha
= None¶ The primitive element 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
-
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
-
degree
= None¶ The prime characteristic’s degree \(m\) of the Galois field \(\mathrm{GF}(p^m)\). The degree is a positive integer.
- Type
-
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
-
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
-
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