galois.FieldArray¶

class galois.FieldArray(array, dtype=None, copy=True, order='K', ndmin=0)¶

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

Warning

galois.FieldArray is an abstract base class for all Galois field array classes and cannot be instantiated directly. Instead, galois.FieldArray subclasses are created using the class factory galois.GF().

Parameters

array (int, str, tuple, list, numpy.ndarray, galois.FieldArray) –
The input array-like object to be converted to a Galois field array. See the examples section for demonstations of array creation using each input type. See see galois.FieldClass.display() and galois.FieldClass.display_mode for a description of the “integer” and “polynomial” representation of Galois field elements.
- int: A single integer, which is the “integer representation” of a Galois field element, creates a 0-D array.
- str: A single string, which is the “polynomial representation” of a Galois field element, creates a 0-D array.
- tuple, list: A list or tuple (or nested lists/tuples) of ints or strings (which can be mix-and-matched) creates an array of Galois field elements from their integer or polynomial representations.
- numpy.ndarray, galois.FieldArray: An array of ints creates a copy of the array over this specific field.
dtype (numpy.dtype, optional) – The numpy.dtype of the array elements. The default is None which represents the smallest unsigned dtype for this class, i.e. the first element in galois.FieldClass.dtypes.
copy (bool, optional) – The copy keyword argument from numpy.array(). The default is True which makes a copy of the input 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 Galois field array over \(\mathrm{GF}(p^m)\).

Return type

galois.FieldArray

Notes

galois.FieldArray is an abstract base class and cannot be instantiated directly. Instead, the user creates a galois.FieldArray subclass for the field \(\mathrm{GF}(p^m)\) by calling the class factory galois.GF(), e.g. GF = galois.GF(p**m). In this case, GF is a subclass of galois.FieldArray and an instance of galois.FieldClass, a metaclass that defines special methods and attributes related to the Galois field.

galois.FieldArray, and GF, is a subclass of numpy.ndarray and its constructor x = GF(array_like) has the same syntax as numpy.array(). The returned galois.FieldArray instance x is a numpy.ndarray that is acted upon like any other numpy array, except all arithmetic is performed in \(\mathrm{GF}(p^m)\) not in \(\mathbb{Z}\) or \(\mathbb{R}\).

Examples

Construct the Galois field class for \(\mathrm{GF}(2^8)\) using the class factory galois.GF() and then display some relevant properties of the field. See galois.FieldClass for a complete list of Galois field array class methods and attributes.

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

In [2]: GF256
Out[2]: <class 'numpy.ndarray over GF(2^8)'>

In [3]: print(GF256.properties)
GF(2^8):
  characteristic: 2
  degree: 8
  order: 256
  irreducible_poly: x^8 + x^4 + x^3 + x^2 + 1
  is_primitive_poly: True
  primitive_element: x

Depending on the field’s order, only certain numpy dtypes are supported. See galois.FieldClass.dtypes for more details.

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

Galois field arrays can be created from existing numpy arrays.

In [5]: x = np.array([155, 232, 162, 159,  63,  29, 247, 141,  75, 189], dtype=int)

# Explicit Galois field array creation (a copy is performed)
In [6]: GF256(x)
Out[6]: GF([155, 232, 162, 159,  63,  29, 247, 141,  75, 189], order=2^8)

# Or view an existing numpy array as a Galois field array (no copy is performed)
In [7]: x.view(GF256)
Out[7]: GF([155, 232, 162, 159,  63,  29, 247, 141,  75, 189], order=2^8)

Galois field arrays can also be created explicitly by converting an “array-like” object.

# A scalar GF(2^8) element from its integer representation
In [8]: GF256(37)
Out[8]: GF(37, order=2^8)

# A scalar GF(2^8) element from its polynomial representation
In [9]: GF256("x^5 + x^2 + 1")
Out[9]: GF(37, order=2^8)

# A GF(2^8) array from a list of elements in their integer representation
In [10]: GF256([[142, 27], [92, 253]])
Out[10]: 
GF([[142,  27],
    [ 92, 253]], order=2^8)

# A GF(2^8) array from a list of elements in their integer and polynomial representations
In [11]: GF256([[142, "x^5 + x^2 + 1"], [92, 253]])
Out[11]: 
GF([[142,  37],
    [ 92, 253]], order=2^8)

There’s also an alternate constructor Vector() (and accompanying vector() method) to convert an array of coefficients over \(\mathrm{GF}(p)\) with last dimension \(m\) into Galois field elements in \(\mathrm{GF}(p^m)\).

# A scalar GF(2^8) element from its vector representation
In [12]: GF256.Vector([0, 0, 1, 0, 0, 1, 0, 1])
Out[12]: GF(37, order=2^8)

# A GF(2^8) array from a list of elements in their vector representation
In [13]: GF256.Vector([[[1, 0, 0, 0, 1, 1, 1, 0], [0, 0, 0, 1, 1, 0, 1, 1]], [[0, 1, 0, 1, 1, 1, 0, 0], [1, 1, 1, 1, 1, 1, 0, 1]]])
Out[13]: 
GF([[142,  27],
    [ 92, 253]], order=2^8)

Newly-created arrays will use the smallest unsigned dtype, unless otherwise specified.

In [14]: a = GF256([66, 166, 27, 182, 125]); a
Out[14]: GF([ 66, 166,  27, 182, 125], order=2^8)

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

In [16]: b = GF256([66, 166, 27, 182, 125], dtype=np.int64); b
Out[16]: GF([ 66, 166,  27, 182, 125], order=2^8)

In [17]: b.dtype
Out[17]: dtype('int64')

Constructors

`Elements`([dtype])	Creates a 1-D Galois field array of the field’s elements \(\{0, \dots, p^m-1\}\).
`Identity`(size[, dtype])	Creates an \(n \times n\) Galois field identity matrix.
`Ones`(shape[, dtype])	Creates a Galois field array with all ones.
`Random`([shape, low, high, dtype])	Creates a Galois field array with random field elements.
`Range`(start, stop[, step, dtype])	Creates a 1-D Galois field array with a range of field elements.
`Vandermonde`(a, m, n[, dtype])	Creates an \(m \times n\) Vandermonde matrix of \(a \in \mathrm{GF}(p^m)\).
`Vector`(array[, dtype])	Creates a Galois field array over \(\mathrm{GF}(p^m)\) from length-\(m\) vectors over the prime subfield \(\mathrm{GF}(p)\).
`Zeros`(shape[, dtype])	Creates a Galois field array with all zeros.

Methods

`lu_decompose`()	Decomposes the input array into the product of lower and upper triangular matrices.
`lup_decompose`()	Decomposes the input array into the product of lower and upper triangular matrices using partial pivoting.
`row_reduce`([ncols])	Performs Gaussian elimination on the matrix to achieve reduced row echelon form.
`vector`([dtype])	Converts the Galois field array over \(\mathrm{GF}(p^m)\) to length-\(m\) vectors over the prime subfield \(\mathrm{GF}(p)\).

Special Methods

`__add__`(other)	Adds two Galois field arrays element-wise.
`__divmod__`(other)	Divides two Galois field arrays element-wise and returns the quotient and remainder.
`__floordiv__`(other)	Divides two Galois field arrays element-wise.
`__mod__`(other)	Divides two Galois field arrays element-wise and returns the remainder.
`__mul__`(other)	Multiplies two Galois field arrays element-wise.
`__pow__`(other)	Exponentiates a Galois field array element-wise.
`__sub__`(other)	Subtracts two Galois field arrays element-wise.
`__truediv__`(other)	Divides two Galois field arrays element-wise.

classmethod Elements(dtype=None)¶

Creates a 1-D 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 unsigned dtype for this class, i.e. the first element in galois.FieldClass.dtypes.
Returns: A 1-D Galois field array of all the field’s elements.
Return type: galois.FieldArray

Examples

In [1]: GF = galois.GF(2**4)

In [2]: GF.Elements()
Out[2]: 
GF([ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14, 15],
   order=2^4)

As usual, Galois field elements can be displayed in either the “integer” (default), “polynomial”, or “power” representation. This can be changed by calling galois.FieldClass.display().

# Permanently set the display mode to "poly"
In [3]: GF.display("poly");

In [4]: GF.Elements()
Out[4]: 
GF([0, 1, α, α + 1, α^2, α^2 + 1, α^2 + α, α^2 + α + 1, α^3, α^3 + 1,
    α^3 + α, α^3 + α + 1, α^3 + α^2, α^3 + α^2 + 1, α^3 + α^2 + α,
    α^3 + α^2 + α + 1], order=2^4)

# Temporarily set the display mode to "power"
In [5]: with GF.display("power"):
   ...:     print(GF.Elements())
   ...: 
GF([0, 1, α, α^4, α^2, α^8, α^5, α^10, α^3, α^14, α^9, α^7, α^6, α^13,
    α^11, α^12], order=2^4)

# Reset the display mode to "int"
In [6]: GF.display();

classmethod Identity(size, dtype=None)¶

Creates an \(n \times n\) Galois field identity matrix.

Parameters

size (int) – The size \(n\) along one axis of the matrix. The resulting array has shape (size, size).
dtype (numpy.dtype, optional) – The numpy.dtype of the array elements. The default is None which represents the smallest unsigned dtype for this class, i.e. the first element in galois.FieldClass.dtypes.

Returns

A Galois field identity matrix of shape (size, size).

Return type

galois.FieldArray

Examples

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

In [2]: GF.Identity(4)
Out[2]: 
GF([[1, 0, 0, 0],
    [0, 1, 0, 0],
    [0, 0, 1, 0],
    [0, 0, 0, 1]], order=31)

classmethod Ones(shape, dtype=None)¶

Creates a Galois field array with all ones.

Parameters

shape (int, 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-D array. A 2-tuple, e.g. (M,N), represents a 2-D 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 unsigned dtype for this class, i.e. the first element in galois.FieldClass.dtypes.

Returns

A Galois field array of ones.

Return type

galois.FieldArray

Examples

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

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

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

Creates a Galois field array with random field elements.

Parameters

shape (int, 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-D array. A 2-tuple, e.g. (M,N), represents a 2-D array with each element indicating the size in each dimension.
low (int, optional) – The lowest value (inclusive) of a random field element in its integer representation. The default is 0.
high (int, optional) – The highest value (exclusive) of a random field element in its integer representation. 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 unsigned dtype for this class, i.e. the first element in galois.FieldClass.dtypes.

Returns

A Galois field array of random field elements.

Return type

galois.FieldArray

Examples

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

In [2]: GF.Random((2,5))
Out[2]: 
GF([[11,  1,  4, 24,  0],
    [27, 26,  0,  6, 18]], order=31)

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

Creates a 1-D Galois field array with a range of field elements.

Parameters

start (int) – The starting Galois field value (inclusive) in its integer representation.
stop (int) – The stopping Galois field value (exclusive) in its integer representation.
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 unsigned dtype for this class, i.e. the first element in galois.FieldClass.dtypes.

Returns

A 1-D Galois field array of a range of field elements.

Return type

galois.FieldArray

Examples

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

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

classmethod Vandermonde(a, m, n, dtype=None)¶

Creates an \(m \times n\) Vandermonde matrix of \(a \in \mathrm{GF}(p^m)\).

Parameters

a (int, galois.FieldArray) – An element of \(\mathrm{GF}(p^m)\).
m (int) – The number of rows in the Vandermonde matrix.
n (int) – The number of columns in the Vandermonde matrix.
dtype (numpy.dtype, optional) – The numpy.dtype of the array elements. The default is None which represents the smallest unsigned dtype for this class, i.e. the first element in galois.FieldClass.dtypes.

Returns

The \(m \times n\) Vandermonde matrix.

Return type

galois.FieldArray

Examples

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

In [2]: a = GF.primitive_element

In [3]: V = GF.Vandermonde(a, 7, 7)

In [4]: with GF.display("power"):
   ...:     print(V)
   ...: 
GF([[  1,   1,   1,   1,   1,   1,   1],
    [  1,   α, α^2, α^3, α^4, α^5, α^6],
    [  1, α^2, α^4, α^6,   α, α^3, α^5],
    [  1, α^3, α^6, α^2, α^5,   α, α^4],
    [  1, α^4,   α, α^5, α^2, α^6, α^3],
    [  1, α^5, α^3,   α, α^6, α^4, α^2],
    [  1, α^6, α^5, α^4, α^3, α^2,   α]], order=2^3)

classmethod Vector(array, dtype=None)¶

Creates a Galois field array over \(\mathrm{GF}(p^m)\) from length-\(m\) vectors over the prime subfield \(\mathrm{GF}(p)\).

This function is the inverse operation of the vector() method.

Parameters

array (array_like) – The input array with field elements in \(\mathrm{GF}(p)\) to be converted to a Galois field array in \(\mathrm{GF}(p^m)\). The last dimension of the input array must be \(m\). An input array with shape (n1, n2, m) has output shape (n1, n2). By convention, the vectors are ordered from highest degree to 0-th degree.
dtype (numpy.dtype, optional) – The numpy.dtype of the array elements. The default is None which represents the smallest unsigned dtype for this class, i.e. the first element in galois.FieldClass.dtypes.

Returns

A Galois field array over \(\mathrm{GF}(p^m)\).

Return type

galois.FieldArray

Examples

In [1]: GF = galois.GF(2**6)

In [2]: vec = galois.GF2.Random((3,6)); vec
Out[2]: 
GF([[1, 0, 1, 1, 0, 0],
    [1, 0, 1, 0, 0, 1],
    [0, 0, 1, 1, 0, 0]], order=2)

In [3]: a = GF.Vector(vec); a
Out[3]: GF([44, 41, 12], order=2^6)

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

In [5]: a.vector()
Out[5]: 
GF([[1, 0, 1, 1, 0, 0],
    [1, 0, 1, 0, 0, 1],
    [0, 0, 1, 1, 0, 0]], order=2)

classmethod Zeros(shape, dtype=None)¶

Creates a Galois field array with all zeros.

Parameters

shape (int, 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-D array. A 2-tuple, e.g. (M,N), represents a 2-D 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 unsigned dtype for this class, i.e. the first element in galois.FieldClass.dtypes.

Returns

A Galois field array of zeros.

Return type

galois.FieldArray

Examples

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

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

__add__(other)¶

Adds two Galois field arrays element-wise.

Broadcasting rules apply. Both arrays must be over the same Galois field.

Parameters: other (galois.FieldArray) – The other Galois field array.
Returns: The Galois field array self + other.
Return type: galois.FieldArray

Examples

In [1]: GF = galois.GF(7)

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

In [3]: b = GF.Random(5); b
Out[3]: GF([6, 1, 2, 6, 3], order=7)

In [4]: a + b
Out[4]: 
GF([[3, 5, 0, 0, 4],
    [6, 5, 1, 1, 4]], order=7)

__divmod__(other)¶

Divides two Galois field arrays element-wise and returns the quotient and remainder.

Broadcasting rules apply. Both arrays must be over the same Galois field. In Galois fields, true division and floor division are equivalent. In Galois fields, the remainder is always zero.

Parameters

other (galois.FieldArray) – The other Galois field array.

Returns

galois.FieldArray – The Galois field array self // other.
galois.FieldArray – The Galois field array self % other.

Examples

In [1]: GF = galois.GF(7)

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

In [3]: b = GF.Random(5, low=1); b
Out[3]: GF([1, 5, 6, 1, 5], order=7)

In [4]: q, r = divmod(a, b)

In [5]: q, r
Out[5]: 
(GF([[2, 5, 5, 5, 3],
     [4, 0, 0, 3, 4]], order=7),
 GF([[0, 0, 0, 0, 0],
     [0, 0, 0, 0, 0]], order=7))

In [6]: b*q + r
Out[6]: 
GF([[2, 4, 2, 5, 1],
    [4, 0, 0, 3, 6]], order=7)

__floordiv__(other)¶

Divides two Galois field arrays element-wise.

Broadcasting rules apply. Both arrays must be over the same Galois field. In Galois fields, true division and floor division are equivalent.

Parameters: other (galois.FieldArray) – The other Galois field array.
Returns: The Galois field array self // other.
Return type: galois.FieldArray

Examples

In [1]: GF = galois.GF(7)

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

In [3]: b = GF.Random(5, low=1); b
Out[3]: GF([4, 1, 1, 3, 2], order=7)

In [4]: a // b
Out[4]: 
GF([[4, 0, 3, 3, 2],
    [0, 1, 4, 3, 2]], order=7)

__mod__(other)¶

Divides two Galois field arrays element-wise and returns the remainder.

Broadcasting rules apply. Both arrays must be over the same Galois field. In Galois fields, true division and floor division are equivalent. In Galois fields, the remainder is always zero.

Parameters: other (galois.FieldArray) – The other Galois field array.
Returns: The Galois field array self % other.
Return type: galois.FieldArray

Examples

In [1]: GF = galois.GF(7)

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

In [3]: b = GF.Random(5, low=1); b
Out[3]: GF([5, 1, 6, 6, 6], order=7)

In [4]: a % b
Out[4]: 
GF([[0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0]], order=7)

__mul__(other)¶

Multiplies two Galois field arrays element-wise.

Broadcasting rules apply. Both arrays must be over the same Galois field.

Warning

When both multiplicands are galois.FieldArray, that indicates a Galois field multiplication. When one multiplicand is an integer or integer numpy.ndarray, that indicates a scalar multiplication (repeated addition). Galois field multiplication and scalar multiplication are equivalent in prime fields, but not in extension fields.

Parameters: other (numpy.ndarray, galois.FieldArray) – A numpy.ndarray of integers for scalar multiplication or a galois.FieldArray of Galois field elements for finite field multiplication.
Returns: The Galois field array self * other.
Return type: galois.FieldArray

Examples

In [1]: GF = galois.GF(7)

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

In [3]: b = GF.Random(5); b
Out[3]: GF([0, 0, 3, 6, 6], order=7)

In [4]: a * b
Out[4]: 
GF([[0, 0, 1, 1, 0],
    [0, 0, 6, 1, 6]], order=7)

When both multiplicands are Galois field elements, that indicates a Galois field multiplication.

In [5]: GF = galois.GF(2**4, display="poly")

In [6]: a = GF(7); a
Out[6]: GF(α^2 + α + 1, order=2^4)

In [7]: b = GF(2); b
Out[7]: GF(α, order=2^4)

In [8]: a * b
Out[8]: GF(α^3 + α^2 + α, order=2^4)

When one multiplicand is an integer, that indicates a scalar multiplication (repeated addition).

In [9]: a * 2
Out[9]: GF(0, order=2^4)

In [10]: a + a
Out[10]: GF(0, order=2^4)

__pow__(other)¶

Exponentiates a Galois field array element-wise.

Broadcasting rules apply. The first array must be a Galois field array and the second must be an integer or integer array.

Parameters: other (int, numpy.ndarray) – The exponent(s) as an integer or integer array.
Returns: The Galois field array self ** other.
Return type: galois.FieldArray

Examples

In [1]: GF = galois.GF(7)

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

In [3]: b = np.random.randint(0, 10, 5); b
Out[3]: array([4, 7, 0, 3, 6])

In [4]: a ** b
Out[4]: 
GF([[1, 1, 1, 6, 1],
    [0, 0, 1, 6, 1]], order=7)

__sub__(other)¶

Subtracts two Galois field arrays element-wise.

Broadcasting rules apply. Both arrays must be over the same Galois field.

Parameters: other (galois.FieldArray) – The other Galois field array.
Returns: The Galois field array self - other.
Return type: galois.FieldArray

Examples

In [1]: GF = galois.GF(7)

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

In [3]: b = GF.Random(5); b
Out[3]: GF([1, 5, 3, 2, 0], order=7)

In [4]: a - b
Out[4]: 
GF([[4, 0, 0, 0, 1],
    [6, 0, 5, 1, 4]], order=7)

__truediv__(other)¶

Divides two Galois field arrays element-wise.

Broadcasting rules apply. Both arrays must be over the same Galois field. In Galois fields, true division and floor division are equivalent.

Parameters: other (galois.FieldArray) – The other Galois field array.
Returns: The Galois field array self / other.
Return type: galois.FieldArray

Examples

In [1]: GF = galois.GF(7)

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

In [3]: b = GF.Random(5, low=1); b
Out[3]: GF([6, 1, 4, 2, 3], order=7)

In [4]: a / b
Out[4]: 
GF([[2, 6, 6, 2, 1],
    [6, 2, 2, 1, 3]], order=7)

lu_decompose()¶

Decomposes the input array into the product of lower and upper triangular matrices.

Returns

galois.FieldArray – The lower triangular matrix.
galois.FieldArray – The upper triangular matrix.

Examples

In [1]: GF = galois.GF(5)

# Not every square matrix has an LU decomposition
In [2]: A = GF([[2, 4, 4, 1], [3, 3, 1, 4], [4, 3, 4, 2], [4, 4, 3, 1]])

In [3]: L, U = A.lu_decompose()

In [4]: L
Out[4]: 
GF([[1, 0, 0, 0],
    [4, 1, 0, 0],
    [2, 0, 1, 0],
    [2, 3, 0, 1]], order=5)

In [5]: U
Out[5]: 
GF([[2, 4, 4, 1],
    [0, 2, 0, 0],
    [0, 0, 1, 0],
    [0, 0, 0, 4]], order=5)

# A = L U
In [6]: np.array_equal(A, L @ U)
Out[6]: True

lup_decompose()¶

Decomposes the input array into the product of lower and upper triangular matrices using partial pivoting.

Returns

galois.FieldArray – The lower triangular matrix.
galois.FieldArray – The upper triangular matrix.
galois.FieldArray – The permutation matrix.

Examples

In [1]: GF = galois.GF(5)

In [2]: A = GF([[1, 3, 2, 0], [3, 4, 2, 3], [0, 2, 1, 4], [4, 3, 3, 1]])

In [3]: L, U, P = A.lup_decompose()

In [4]: L
Out[4]: 
GF([[1, 0, 0, 0],
    [0, 1, 0, 0],
    [3, 0, 1, 0],
    [4, 3, 2, 1]], order=5)

In [5]: U
Out[5]: 
GF([[1, 3, 2, 0],
    [0, 2, 1, 4],
    [0, 0, 1, 3],
    [0, 0, 0, 3]], order=5)

In [6]: P
Out[6]: 
GF([[1, 0, 0, 0],
    [0, 0, 1, 0],
    [0, 1, 0, 0],
    [0, 0, 0, 1]], order=5)

# P A = L U
In [7]: np.array_equal(P @ A, L @ U)
Out[7]: True

row_reduce(ncols=None)¶

Performs Gaussian elimination on the matrix to achieve reduced row echelon form.

Row reduction operations

Swap the position of any two rows.
Multiply a row by a non-zero scalar.
Add one row to a scalar multiple of another row.

Parameters: ncols (int, optional) – The number of columns to perform Gaussian elimination over. The default is None which represents the number of columns of the input array.
Returns: The reduced row echelon form of the input array.
Return type: galois.FieldArray

Examples

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

In [2]: A = GF.Random((4,4)); A
Out[2]: 
GF([[29,  1,  1,  6],
    [ 4,  5, 24,  1],
    [11, 15, 12, 16],
    [25, 25,  9, 19]], order=31)

In [3]: A.row_reduce()
Out[3]: 
GF([[1, 0, 0, 0],
    [0, 1, 0, 0],
    [0, 0, 1, 0],
    [0, 0, 0, 1]], order=31)

In [4]: np.linalg.matrix_rank(A)
Out[4]: 4

One column is a linear combination of another.

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

In [6]: A = GF.Random((4,4)); A
Out[6]: 
GF([[12,  6, 12, 10],
    [17, 25,  7, 30],
    [29,  9, 12,  3],
    [17,  6, 30, 26]], order=31)

In [7]: A[:,2] = A[:,1] * GF(17); A
Out[7]: 
GF([[12,  6,  9, 10],
    [17, 25, 22, 30],
    [29,  9, 29,  3],
    [17,  6,  9, 26]], order=31)

In [8]: A.row_reduce()
Out[8]: 
GF([[ 1,  0,  0,  0],
    [ 0,  1, 17,  0],
    [ 0,  0,  0,  1],
    [ 0,  0,  0,  0]], order=31)

In [9]: np.linalg.matrix_rank(A)
Out[9]: 3

One row is a linear combination of another.

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

In [11]: A = GF.Random((4,4)); A
Out[11]: 
GF([[16,  4, 13, 18],
    [ 7, 16,  9, 23],
    [14, 23, 22,  3],
    [26,  4,  8,  4]], order=31)

In [12]: A[3,:] = A[2,:] * GF(8); A
Out[12]: 
GF([[16,  4, 13, 18],
    [ 7, 16,  9, 23],
    [14, 23, 22,  3],
    [19, 29, 21, 24]], order=31)

In [13]: A.row_reduce()
Out[13]: 
GF([[ 1,  0,  0, 15],
    [ 0,  1,  0, 22],
    [ 0,  0,  1,  0],
    [ 0,  0,  0,  0]], order=31)

In [14]: np.linalg.matrix_rank(A)
Out[14]: 3

vector(dtype=None)¶

Converts the Galois field array over \(\mathrm{GF}(p^m)\) to length-\(m\) vectors over the prime subfield \(\mathrm{GF}(p)\).

This function is the inverse operation of the Vector() constructor. For an array with shape (n1, n2), the output shape is (n1, n2, m). By convention, the vectors are ordered from highest degree to 0-th degree.

Parameters: dtype (numpy.dtype, optional) – The numpy.dtype of the array elements. The default is None which represents the smallest unsigned dtype for this class, i.e. the first element in galois.FieldClass.dtypes.
Returns: A Galois field array of length-\(m\) vectors over \(\mathrm{GF}(p)\).
Return type: galois.FieldArray

Examples

In [1]: GF = galois.GF(2**6)

In [2]: a = GF.Random(3); a
Out[2]: GF([16, 48, 60], order=2^6)

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

In [4]: vec = a.vector(); vec
Out[4]: 
GF([[0, 1, 0, 0, 0, 0],
    [1, 1, 0, 0, 0, 0],
    [1, 1, 1, 1, 0, 0]], order=2)

In [5]: GF.Vector(vec)
Out[5]: GF([16, 48, 60], order=2^6)