Galois Fields for NumPy

0.4.10 · active · verified Thu Apr 16

The `galois` library is a performant Python package that extends NumPy arrays to operate over finite fields (Galois fields) for various mathematical and cryptographic applications. It leverages Numba and LLVM for just-in-time compilation to optimize finite field arithmetic, often outperforming native NumPy operations for modular arithmetic. It supports all Galois fields GF(p^m), offering functionalities for linear algebra, polynomials, forward error correction codes (BCH, Reed-Solomon), and number theoretic functions. Currently at version 0.4.10, the library maintains an active release cadence, with updates typically arriving monthly or bi-monthly.

Common errors

```
AttributeError: module 'galois' has no attribute 'Field'
```
cause Attempting to use the `galois.Field()` class factory after it has been removed in a future version (v0.5.0).

fix Replace `galois.Field(...)` with `galois.GF(...)`.
```
TypeError: galois.GF() takes no positional arguments for 'irreducible_poly'
```
cause Passing keyword-only arguments like `irreducible_poly` or `primitive_element` positionally to `galois.GF()` (or `galois.Field()`) since v0.3.0.

fix Ensure all such arguments are passed by keyword, e.g., `galois.GF(2**8, irreducible_poly=poly)`.
```
TypeError: arithmetic operation between FieldArray instances with different irreducible polynomials of order GF(p^m)
```
cause Performing arithmetic between two `FieldArray` instances that represent elements from different Galois fields. Even if they have the same order (p^m), they must be defined with the exact same irreducible polynomial to be compatible.

fix Ensure both `FieldArray` instances are created from the *exact same* `GF` class. If necessary, explicitly cast one array to the field of the other using `GF_target(array_source)` if the conversion is meaningful and defined.
```
ImportError: DLL load failed while importing unicodedata: The specified module could not be found.
```
cause This issue was specifically reported with Python 3.10.1, likely due to a specific incompatibility between Numba's compiled components and that Python patch version.

fix If on Python 3.10.1, try upgrading to a later Python 3.10.x release, Python 3.11+, or downgrading to Python 3.9. Ensure Numba and NumPy are also updated to their latest compatible versions.

Warnings

breaking The `galois.Field()` class factory function was deprecated in `galois` v0.4.10 and is scheduled for removal in v0.5.0.
Fix: Migrate all calls from `galois.Field()` to `galois.GF()`. They are functionally equivalent.
breaking As of `galois` v0.3.0, several keyword arguments for `galois.GF()` and `galois.Field()` (e.g., `irreducible_poly`, `primitive_element`, `verify`, `compile`, `repr`) can no longer be passed as positional arguments.
Fix: Always pass these specific arguments by keyword, not by position. For example, use `galois.GF(p**m, irreducible_poly=poly)` instead of `galois.GF(p**m, poly)`.
gotcha The algorithms implemented in `galois` are designed for performance, not constant-time execution. This means the library could be vulnerable to side-channel timing attacks.
Fix: Do not use `galois` for production security-sensitive applications where constant-time arithmetic is a requirement. It is intended for research, development, cryptanalysis, and education.
gotcha `galois` depends heavily on Numba, which has historically had tight and sometimes incompatible dependencies with specific NumPy versions. This can lead to issues during installation or runtime if the installed NumPy and Numba versions are not compatible.
Fix: If encountering `ImportError` or other runtime issues related to NumPy/Numba, check the official `galois` documentation for its recommended `numpy` and `numba` versions. Consider installing `numpy` and `numba` first, or using a virtual environment to isolate dependencies.

Install

pip install galois Install latest stable release

Imports

galois
```
import galois
```
GF
wrong:
```
GF = galois.Field(p**m)
```
correct:
```
GF = galois.GF(p**m)
```
`galois.Field()` was deprecated in v0.4.10 and is slated for removal in v0.5.0. Use `galois.GF()` instead.
Poly
```
P = galois.Poly([1, 0, 1], field=GF)
```

Quickstart

This quickstart demonstrates how to define a Galois field, create `FieldArray` instances which inherit from NumPy arrays, and perform basic arithmetic operations within that finite field. The `galois.GF()` factory function is used to create the field class.

import galois
import numpy as np

# Define a Galois field, e.g., GF(3^5)
GF = galois.GF(3**5)
print(f"Galois Field properties:\n{GF.properties}")

# Create FieldArray instances (which are subclasses of np.ndarray)
x = GF([236, 87, 38, 112])
y = GF(np.array([109, 201, 2, 45]))

print(f"\nx (type: {type(x)}): {x}")
print(f"y (type: {type(y)}): {y}")

# Perform arithmetic operations in the finite field
result_add = x + y
result_mul = x * y

print(f"\nx + y: {result_add}")
print(f"x * y: {result_mul}")

view raw JSON →