Getting Started¶
The Getting Started guide is intended to assist the user with installing the library, creating two example arrays, and performing basic array arithmetic. See Basic Usage for more detailed discussions and examples.
Install the package¶
The latest version of galois
can be installed from PyPI using pip
.
$ python3 -m pip install galois
Import the galois
package in Python.
In [1]: import galois
In [2]: galois.__version__
Out[2]: '0.4.2.dev5+gc945356'
Create a FieldArray
subclass¶
Next, create a FieldArray
subclass for the specific finite field you’d like to work in. This is created using
the GF()
class factory. In this example, we are working in \(\mathrm{GF}(3^5)\).
In [3]: GF = galois.GF(3**5)
In [4]: print(GF.properties)
Galois Field:
name: GF(3^5)
characteristic: 3
degree: 5
order: 243
irreducible_poly: x^5 + 2x + 1
is_primitive_poly: True
primitive_element: x
The FieldArray
subclass GF
is a subclass of ndarray
that performs all arithmetic in the Galois field
\(\mathrm{GF}(3^5)\), not in \(\mathbb{R}\).
In [5]: issubclass(GF, galois.FieldArray)
Out[5]: True
In [6]: issubclass(GF, np.ndarray)
Out[6]: True
See Array Classes for more details.
Create two FieldArray
instances¶
Next, create a new FieldArray
x
by passing an ArrayLike
object to GF
’s constructor.
In [7]: x = GF([236, 87, 38, 112]); x
Out[7]: GF([236, 87, 38, 112], order=3^5)
The array x
is an instance of FieldArray
and also an instance of ndarray
.
In [8]: isinstance(x, galois.FieldArray)
Out[8]: True
In [9]: isinstance(x, np.ndarray)
Out[9]: True
Create a second FieldArray
y
by converting an existing NumPy array (without copying it) by invoking
.view()
. When finished working in the finite field, view it back as a NumPy array with .view(np.ndarray)
.
# y represents an array created elsewhere in the code
In [10]: y = np.array([109, 17, 108, 224]); y
Out[10]: array([109, 17, 108, 224])
In [11]: y = y.view(GF); y
Out[11]: GF([109, 17, 108, 224], order=3^5)
See Array Creation for more details.
Change the element representation¶
The representation of finite field elements can be set to either the integer ("int"
), polynomial ("poly"
),
or power ("power"
) representation. The default representation is the integer representation since integers are natural when
working with integer NumPy arrays.
Set the element representation by passing the repr
keyword argument to GF()
or by calling the repr()
classmethod. Choose whichever element representation is most convenient.
# The default is the integer representation
In [12]: x
Out[12]: GF([236, 87, 38, 112], order=3^5)
In [13]: GF.repr("poly"); x
Out[13]:
GF([2α^4 + 2α^3 + 2α^2 + 2, α^4 + 2α,
α^3 + α^2 + 2, α^4 + α^3 + α + 1], order=3^5)
In [14]: GF.repr("power"); x
Out[14]: GF([α^204, α^16, α^230, α^34], order=3^5)
# Reset to the integer representation
In [15]: GF.repr("int");
See Element Representation for more details.
Perform array arithmetic¶
Once you have two Galois field arrays, nearly any arithmetic operation can be performed using normal NumPy arithmetic. The traditional NumPy broadcasting rules apply.
Standard element-wise array arithmetic – addition, subtraction, multiplication, and division – are easily preformed.
In [16]: x + y
Out[16]: GF([ 18, 95, 146, 0], order=3^5)
In [17]: x - y
Out[17]: GF([127, 100, 173, 224], order=3^5)
In [18]: x * y
Out[18]: GF([ 21, 241, 179, 82], order=3^5)
In [19]: x / y
Out[19]: GF([ 67, 47, 192, 2], order=3^5)
More complicated arithmetic, like square root and logarithm base \(\alpha\), are also supported.
In [20]: np.sqrt(x)
Out[20]: GF([ 51, 135, 40, 16], order=3^5)
In [21]: np.log(x)
Out[21]: array([204, 16, 230, 34])
See Array Arithmetic for more details.