Add irreducible polynomials for GF(2^m)

- New script to create a irreducible polynomials database
- Add irreducible polynomials for GF(2^m for 2<=m<=10_000) using Gadiel Seroussi's table
- New IrreduciblePolyDatabase class to handle access to the database

pyproject.toml

@@ -55,6 +55,8 @@ dev = [
  "pytest-cov[toml]",
  "pytest-xdist",
  "pytest-benchmark >= 4.0.0",
+ "requests",
+ "pdfminer.six"
 ]
 
 [project.urls]

scripts/create_irreducible_polys_database.py

@@ -0,0 +1,111 @@
+"""
+A script to create a database of irreducible polynomials
+
+Sources:
+ - Gadiel Seroussi. Table of Low-Weight Binary Irreducible Polynomials (1998): https://www.hpl.hp.com/techreports/98/HPL-98-135.html
+
+"""
+from __future__ import annotations
+
+import os
+import sqlite3
+from pathlib import Path
+
+import requests
+import hashlib
+from pdfminer.high_level import extract_text
+
+
+def main():
+ """
+ The main routine to create a database of irreducible polynomials
+ """
+
+ database_file = Path(__file__).parent.parent / "src" / "galois" / "_databases" / "irreducible_polys.db"
+ conn, cursor = create_database(database_file)
+
+ _add_hpl_1998(conn, cursor)
+
+ conn.close()
+
+
+def create_database(file: Path) -> tuple[sqlite3.Connection, sqlite3.Cursor]:
+ """
+ Deletes the old database, makes a new one, and returns the database connection.
+ """
+ if file.exists():
+ os.remove(file)
+
+ conn = sqlite3.connect(file)
+ cursor = conn.cursor()
+ create_table(conn, cursor)
+
+ return conn, cursor
+
+
+def create_table(conn: sqlite3.Connection, cursor: sqlite3.Cursor):
+ """
+ Creates an empty 'polys' table.
+ """
+ cursor.execute(
+ """
+ CREATE TABLE polys (
+ characteristic INTEGER NOT NULL,
+ degree INTEGER NOT NULL,
+ nonzero_degrees TEXT NOT NULL,
+ nonzero_coeffs TEXT NOT NULL,
+ PRIMARY KEY (characteristic, degree)
+ )
+ """
+ )
+ conn.commit()
+
+
+def add_to_database(cursor: sqlite3.Cursor, characteristic: str, degree: str, nonzero_degrees: str, nonzero_coeffs: str):
+ """
+ Adds the given irreducible polynomial to the database.
+ """
+ cursor.execute(
+ """
+ INSERT INTO polys (characteristic, degree, nonzero_degrees, nonzero_coeffs)
+ VALUES (?,?,?,?)
+ """,
+ (int(characteristic), int(degree), nonzero_degrees, nonzero_coeffs),
+ )
+
+
+def _add_hpl_1998(conn, cursor):
+ """
+ Add Gadiel Seroussi's table to the database.
+ GF(2^m) for 2 <= m <= 10_000
+ """
+ url = "https://www.hpl.hp.com/techreports/98/HPL-98-135.pdf"
+ # There is an issue with the SSL certificate using CURL_CA_BUNDLE
+ # We don't validate https, but we do check the PDF's checksum
+ pdf = requests.get(url, stream=True, verify=False).content
+ sha256 = hashlib.sha256()
+ sha256.update(pdf)
+ assert sha256.hexdigest() == "78f02d84a0957ad261c53a0d1107adb2ff9d72f52ba5e10ea77eaa8cf766a0ee"
+
+ coefficients = []
+ print("Parsing Table of Low-Weight Binary Irreducible Polynomials (1998)...")
+ for page in range(3, 16):
+ text = extract_text(Path(__file__).parent / "HPL-98-135.pdf", page_numbers=[page])
+ # Tabs are parsed as \n\n, except when the irreducible poly is a pentanomial.
+ # In that case, there is only a space. First replace takes care of that.
+ # Second replace unifies tabs and changes of lines.
+ # Every page ends with the page number and the form feed \x0c, hence the [:-2].
+ coefficients += text.replace(" ", "\n").replace("\n\n", "\n").split("\n")[:-2]
+
+ for coeffs in coefficients:
+ degree = coeffs.split(",")[0]
+ nonzero_degrees = coeffs + ",0"
+ nonzero_coeffs = ("1," * len(nonzero_degrees.split(",")))[:-1]
+ print(f"Irreducible polynomial for GF(2^{degree})")
+ add_to_database(cursor, "2", str(degree), nonzero_degrees, nonzero_coeffs)
+
+ conn.commit()
+
+
+if __name__ == "__main__":
+ main()

src/galois/_databases/__init__.py

@@ -3,3 +3,4 @@
 """
 from ._conway import ConwayPolyDatabase
 from ._prime import PrimeFactorsDatabase
+from ._irreducible import IrreduciblePolyDatabase

src/galois/_databases/_irreducible.py

@@ -0,0 +1,46 @@
+"""
+A module that handles accessing the database of irreducible polynomials.
+"""
+import os
+import sqlite3
+
+DATABASE = None # Database singleton class
+DATABASE_FILE = os.path.join(os.path.dirname(__file__), "irreducible_polys.db")
+
+
+class IrreduciblePolyDatabase:
+ """
+ Class to interface with the irreducible polynomials database.
+ """
+
+ def __new__(cls):
+ global DATABASE
+ if DATABASE is None:
+ DATABASE = super().__new__(cls)
+ return DATABASE
+
+ def __init__(self):
+ self.conn = sqlite3.connect(DATABASE_FILE)
+ self.cursor = self.conn.cursor()
+
+ def fetch(self, characteristic, degree):
+ self.cursor.execute(
+ """
+ SELECT nonzero_degrees,nonzero_coeffs
+ FROM polys
+ WHERE characteristic=? AND degree=?""",
+ (int(characteristic), int(degree)),
+ )
+ result = self.cursor.fetchone()
+
+ if result is None:
+ raise LookupError(
+ f"The irreducible polynomials database does not contain an entry for GF({characteristic}^{degree}).\n\n"
+ "Alternatively, you can construct irreducible polynomials with `galois.irreducible_poly(p, m)` "
+ "or primitive polynomials with `galois.primitive_poly(p, m)`."
+ )
+
+ nonzero_degrees = [int(_) for _ in result[0].split(",")]
+ nonzero_coeffs = [int(_) for _ in result[1].split(",")]
+
+ return nonzero_degrees, nonzero_coeffs