ffspaces 0.2.0__tar.gz

ffspaces-0.2.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: ffspaces
+Version: 0.2.0
+Summary: A computational laboratory for finite field vector spaces, Hamming balls, and sumset structural analysis.
+Author: Nathan Hoehndorf
+Project-URL: Homepage, https://github.com/nathanhoehndorf/finite-field-spaces
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+
+# Finite-Field Spaces (`ffspaces`)
+
+`ffspaces` is a lightweight Python toolkit for working with vectors over finite fields $\mathbb{F}_p^n$, with a focus on sumset analysis, linear-subspace structure, and Hamming-ball geometry.
+
+The package is designed for small-to-medium computational experiments in additive combinatorics, coding theory, and related discrete geometry settings. It provides both direct implementations and faster specialized routines for common operations over finite fields.
+
+## Current functionality
+
+- **Finite-field vector spaces:** generate the full vector space $\mathbb{F}_p^n$ or construct random invertible basis changes.
+- **Finite-field rank:** compute matrix rank over $\mathbb{F}_p$ using modular Gaussian elimination.
+- **Sumsets:** compute $S+S$ for a set of vectors over $\mathbb{F}_p^n$, including a direct reference method and a faster FWHT-based implementation.
+- **Subspace detection:** find the largest linear subspace contained in a sumset, with both greedy and exhaustive search modes.
+- **Hamming-ball geometry:** generate standard Hamming balls, compute Hamming weights, and build balls under arbitrary linear transforms.
+- **Cover constructions:** build unions of Hamming balls and compute complements relative to a universe.
+
+## Features
+
+- **NumPy-based operations:** vectorized generation and manipulation of finite-field vectors.
+- **Field-aware linear algebra:** rank and invertibility checks performed over $\mathbb{F}_p$, not over the reals.
+- **Flexible geometry tools:** support for binary and higher-characteristic experiments.
+- **Reusable experiment helpers:** scripts and utilities in the `experiments/` directory for one-off analysis.
+
+## Installation
+
+Clone the repository and install it in editable mode:
+
+```bash
+git clone https://github.com/nathanhoehndorf/finite-field-spaces
+cd finite-field-spaces
+pip install -e .
+```
+
+The package requires Python 3.10+ and NumPy.
+
+## Mathematical background
+
+This package works in the vector space $\mathbb{F}_p^n$, where each coordinate is taken modulo a prime $p$. In particular, $\mathbb{F}_2^n$ is the set of binary vectors of length $n$, with addition done coordinatewise modulo $2$.
+
+- **What is $\mathbb{F}_p^n$?** A finite-dimensional vector space over the finite field with $p$ elements. For $p=2$, this is the space of binary vectors.
+- **What is $S+S$?** For a set $S \subseteq \mathbb{F}_p^n$, the sumset $S+S$ is the set of all pairwise sums $x+y$ with $x,y \in S$, taken modulo $p$.
+- **What is a Hamming ball?** A Hamming ball is the set of vectors within a given distance from a center, where distance is the number of coordinates in which two vectors differ (known as Hamming weight, or the Hamming metric).
+- **What is the covering problem?** A covering problem asks whether a collection of balls (or other subsets) can be chosen so that their union contains all points in a given universe, or perhaps all points of a particular structure.
+- **Why does this matter?** These objects are central in additive combinatorics, coding theory, and discrete geometry, and they provide a natural setting for studying how small sets expand under addition or how geometric configurations cover a space.
+
+
+## Quick example
+
+```python
+import numpy as np
+from ffspaces import generate_space, compute_sumset, find_maximum_subspace_dimension
+
+space = generate_space(3, p=2)
+subset = space[[0, 1, 2, 4]]
+sumset = compute_sumset(subset, p=2)
+dimension = find_maximum_subspace_dimension(sumset, p=2)
+print(dimension)
+```
+
+## Experiments
+
+One-off analysis and experiment scripts live in the `experiments/` directory so they stay separate from the installable package code in `src/`.

ffspaces-0.2.0/README.md

@@ -0,0 +1,61 @@
+# Finite-Field Spaces (`ffspaces`)
+
+`ffspaces` is a lightweight Python toolkit for working with vectors over finite fields $\mathbb{F}_p^n$, with a focus on sumset analysis, linear-subspace structure, and Hamming-ball geometry.
+
+The package is designed for small-to-medium computational experiments in additive combinatorics, coding theory, and related discrete geometry settings. It provides both direct implementations and faster specialized routines for common operations over finite fields.
+
+## Current functionality
+
+- **Finite-field vector spaces:** generate the full vector space $\mathbb{F}_p^n$ or construct random invertible basis changes.
+- **Finite-field rank:** compute matrix rank over $\mathbb{F}_p$ using modular Gaussian elimination.
+- **Sumsets:** compute $S+S$ for a set of vectors over $\mathbb{F}_p^n$, including a direct reference method and a faster FWHT-based implementation.
+- **Subspace detection:** find the largest linear subspace contained in a sumset, with both greedy and exhaustive search modes.
+- **Hamming-ball geometry:** generate standard Hamming balls, compute Hamming weights, and build balls under arbitrary linear transforms.
+- **Cover constructions:** build unions of Hamming balls and compute complements relative to a universe.
+
+## Features
+
+- **NumPy-based operations:** vectorized generation and manipulation of finite-field vectors.
+- **Field-aware linear algebra:** rank and invertibility checks performed over $\mathbb{F}_p$, not over the reals.
+- **Flexible geometry tools:** support for binary and higher-characteristic experiments.
+- **Reusable experiment helpers:** scripts and utilities in the `experiments/` directory for one-off analysis.
+
+## Installation
+
+Clone the repository and install it in editable mode:
+
+```bash
+git clone https://github.com/nathanhoehndorf/finite-field-spaces
+cd finite-field-spaces
+pip install -e .
+```
+
+The package requires Python 3.10+ and NumPy.
+
+## Mathematical background
+
+This package works in the vector space $\mathbb{F}_p^n$, where each coordinate is taken modulo a prime $p$. In particular, $\mathbb{F}_2^n$ is the set of binary vectors of length $n$, with addition done coordinatewise modulo $2$.
+
+- **What is $\mathbb{F}_p^n$?** A finite-dimensional vector space over the finite field with $p$ elements. For $p=2$, this is the space of binary vectors.
+- **What is $S+S$?** For a set $S \subseteq \mathbb{F}_p^n$, the sumset $S+S$ is the set of all pairwise sums $x+y$ with $x,y \in S$, taken modulo $p$.
+- **What is a Hamming ball?** A Hamming ball is the set of vectors within a given distance from a center, where distance is the number of coordinates in which two vectors differ (known as Hamming weight, or the Hamming metric).
+- **What is the covering problem?** A covering problem asks whether a collection of balls (or other subsets) can be chosen so that their union contains all points in a given universe, or perhaps all points of a particular structure.
+- **Why does this matter?** These objects are central in additive combinatorics, coding theory, and discrete geometry, and they provide a natural setting for studying how small sets expand under addition or how geometric configurations cover a space.
+
+
+## Quick example
+
+```python
+import numpy as np
+from ffspaces import generate_space, compute_sumset, find_maximum_subspace_dimension
+
+space = generate_space(3, p=2)
+subset = space[[0, 1, 2, 4]]
+sumset = compute_sumset(subset, p=2)
+dimension = find_maximum_subspace_dimension(sumset, p=2)
+print(dimension)
+```
+
+## Experiments
+
+One-off analysis and experiment scripts live in the `experiments/` directory so they stay separate from the installable package code in `src/`.

ffspaces-0.2.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ffspaces"
+version = "0.2.0"
+authors = [{name="Nathan Hoehndorf"}]
+description = "A computational laboratory for finite field vector spaces, Hamming balls, and sumset structural analysis."
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Mathematics"]
+dependencies = ["numpy>=1.24.0"]
+optional-dependencies = { test = ["pytest>=7.0"] }
+[project.urls]
+"Homepage" = "https://github.com/nathanhoehndorf/finite-field-spaces"
+
+[tool.setuptools]
+license-files = []
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["ffspaces*"]

ffspaces-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ffspaces-0.2.0/src/ffspaces/__init__.py

@@ -0,0 +1,27 @@
+from .core import generate_space, generate_random_basis, is_invertible
+from .fwht_operators import vectors_to_ints, ints_to_vectors, compute_sumset_fwht
+from .operators import (
+    _compute_sumset_original,
+    compute_sumset,
+    compare_sumset_methods,
+    find_maximum_subspace_dimension,
+)
+from .covers import generate_covering, complement
+from .geometries import compute_hamming_weight, generate_hamming_ball, generate_standard_ball
+
+__all__ = [
+    "generate_space",
+    "generate_random_basis",
+    "is_invertible",
+    "vectors_to_ints",
+    "ints_to_vectors",
+    "compute_sumset_fwht",
+    "_compute_sumset_original",
+    "compute_sumset",
+    "compare_sumset_methods",
+    "find_maximum_subspace_dimension",
+    "generate_covering",
+    "complement",
+    "compute_hamming_weight",
+    "generate_hamming_ball",
+]

ffspaces-0.2.0/src/ffspaces/core.py

@@ -0,0 +1,75 @@
+import itertools
+
+import numpy as np
+
+
+def generate_space(n: int, p: int = 2) -> np.ndarray:
+    """
+    Generates all p^n vectors in the vector space F_p^n.
+    Returns a 2D numpy array of shape (p^n, n).
+    """
+    elements = list(itertools.product(range(p), repeat=n))
+    return np.array(elements, dtype=np.int8)
+
+def rank_mod_p(matrix, p: int = 2) -> int:
+    """
+    Computes the rank of `matrix` over the finite field F_p using Guassian elimination
+    with modular arithmetic. Works for any prime p; matrix need not be square
+    """
+    if p<=1:
+        raise ValueError("p must be a prime greater than 1")
+    
+    A = np.array(matrix, dtype=np.int64, copy=True) % p
+    if A.ndim != 2:
+        raise ValueError("matrix must be 2-dimensional")
+    
+    m, n = A.shape
+    rank = 0
+    for col in range(n):
+        pivot_row = None
+        for row in range(rank, m):
+            if A[row, col] % p != 0:
+                pivot_row = row
+                break
+        if pivot_row is None:
+            continue
+                
+        if pivot_row != rank:
+            A[[rank, pivot_row], :] = A[[pivot_row, rank], :]
+
+        pivot_inverse = pow(int(A[rank, col]), -1, p)
+        for row in range(m):
+            if row == rank:
+                continue
+            factor = (A[row, col] * pivot_inverse) % p
+            if factor != 0:
+                A[row, :] = (A[row, :] - factor * A[rank, :]) % p
+
+        rank += 1
+        if rank == min(m, n):
+            break
+
+    return rank
+
+def is_invertible(matrix: np.ndarray, p: int = 2) -> bool:
+    """Checks if an n x n matrix is invertible over the finite field F_p."""
+    matrix = np.asarray(matrix)
+    if matrix.ndim != 2 or matrix.shape[0] != matrix.shape[1]:
+        return False
+    return rank_mod_p(matrix, p) == matrix.shape[0]
+
+
+def generate_random_basis(n: int, p: int = 2, rng=None) -> np.ndarray:
+    """Generates a random invertible n x n matrix over F_p to represent a basis change."""
+    if rng is None:
+        rng = np.random.default_rng()
+
+    while True:
+        matrix = rng.integers(0, p, size=(n, n)).astype(np.int8)
+        if is_invertible(matrix, p):
+            return matrix
+        
+
+
+
+            

ffspaces-0.2.0/src/ffspaces/covers.py

@@ -0,0 +1,120 @@
+from typing import Optional, Sequence
+
+import numpy as np
+
+from .fwht_operators import vectors_to_ints
+from .geometries import generate_hamming_ball
+
+
+def _generate_weight_ball(n: int, radius: int) -> np.ndarray:
+    """
+    Generate all binary vectors in F_2^n with Hamming weight <= radius.
+    """
+    import itertools
+
+    vectors = []
+    for weight in range(radius + 1):
+        for combo in itertools.combinations(range(n), weight):
+            vec = np.zeros(n, dtype=np.int8)
+            vec[list(combo)] = 1
+            vectors.append(vec)
+    if len(vectors) == 0:
+        return np.empty((0, n), dtype=np.int8)
+    return np.array(vectors, dtype=np.int8)
+
+
+def generate_covering(
+    centers: Sequence[np.ndarray],
+    radii,
+    bases: Optional[Sequence[np.ndarray]] = None,
+    p: int = 2,
+    universe: Optional[np.ndarray] = None,
+) -> np.ndarray:
+    """
+    Produce the union of Hamming balls defined by `centers`, `radii` and `bases`.
+
+    - `centers`: sequence of center vectors (each length n)
+    - `radii`: either a single int or sequence matching centers
+    - `bases`: either None, a single linear transform, or sequence of linear transforms
+    - `universe`: optional full universe array; when provided `generate_hamming_ball`
+      will be used (supports arbitrary p). When omitted and p==2 a combinatorial
+      weight-based generation is used for speed.
+
+    Returns a numpy array of unique covered vectors (dtype=int8) with shape (M,n).
+    """
+    if isinstance(radii, int):
+        radii = [radii] * len(centers)
+    if bases is None:
+        bases = [None] * len(centers)
+    if not (len(centers) == len(radii) == len(bases)):
+        raise ValueError("centers, radii and bases must have the same length")
+
+    centers = [np.array(c, dtype=np.int8) for c in centers]
+    n = centers[0].size if len(centers) > 0 else 0
+
+    covered_ints = None
+    covered_rows = []
+
+    if universe is None and p == 2:
+        weight_balls = {}
+        for c, r, B in zip(centers, radii, bases):
+            if r not in weight_balls:
+                weight_balls[r] = _generate_weight_ball(n, r)
+            W_r = weight_balls[r]
+            if B is None:
+                A = W_r.copy()
+            else:
+                A = (W_r @ B.T) % 2
+            ball = (A ^ c).astype(np.int8)
+            ints = vectors_to_ints(ball)
+            if covered_ints is None:
+                covered_ints = ints
+            else:
+                covered_ints = np.concatenate([covered_ints, ints])
+
+        if covered_ints is None:
+            return np.empty((0, n), dtype=np.int8)
+
+        unique_ints = np.unique(covered_ints)
+        from .fwht_operators import ints_to_vectors
+
+        return ints_to_vectors(unique_ints, n)
+
+    for c, r, B in zip(centers, radii, bases):
+        ball = generate_hamming_ball(universe, c, r, B, p)
+        covered_rows.append(ball.astype(np.int8))
+
+    if len(covered_rows) == 0:
+        return np.empty((0, n), dtype=np.int8)
+
+    all_covered = np.vstack(covered_rows)
+    if p == 2:
+        ints = vectors_to_ints(all_covered)
+        unique_ints = np.unique(ints)
+        from .fwht_operators import ints_to_vectors
+
+        return ints_to_vectors(unique_ints, all_covered.shape[1])
+    else:
+        return np.unique(all_covered, axis=0)
+
+
+def complement(universe: np.ndarray, covered: np.ndarray) -> np.ndarray:
+    """
+    Return rows of `universe` that are not in `covered`.
+    Both inputs are arrays of vectors (rows). Result preserves order from `universe`.
+    """
+    if len(universe) == 0:
+        return universe.copy()
+    if len(covered) == 0:
+        return universe.copy()
+
+    n = universe.shape[1]
+    try:
+        covered_ints = vectors_to_ints(covered)
+        universe_ints = vectors_to_ints(universe)
+        covered_set = set(covered_ints.tolist())
+        mask = [i not in covered_set for i in universe_ints.tolist()]
+        return universe[np.array(mask, dtype=bool)]
+    except Exception:
+        covered_set = {tuple(row) for row in covered}
+        return np.array([row for row in universe if tuple(row) not in covered_set], dtype=np.int8)

ffspaces-0.2.0/src/ffspaces/fwht_operators.py

@@ -0,0 +1,97 @@
+import numpy as np
+
+
+def vectors_to_ints(vectors: np.ndarray, p: int = 2) -> np.ndarray:
+    """
+    Converts a matrix of Z_p^n vectors (shape M x n) to a 1d array of integers.
+    """
+    if len(vectors) == 0:
+        return np.array([], dtype=np.int64)
+
+    if p <= 1:
+        raise ValueError("p must be at least 2")
+
+    n = vectors.shape[1]
+    if np.any(vectors < 0) or np.any(vectors >= p):
+        raise ValueError("All vector entries must lie in {0, ..., p-1}")
+
+    powers = p ** np.arange(n - 1, -1, -1, dtype=np.int64)
+    return np.dot(vectors.astype(np.int64), powers).astype(np.int64)
+
+
+def ints_to_vectors(ints: np.ndarray, n: int, p: int = 2) -> np.ndarray:
+    """
+    Converts a 1d array of integers back to a matrix of Z_p^n vectors.
+    """
+    if p <= 1:
+        raise ValueError("p must be at least 2")
+
+    if len(ints) == 0:
+        return np.empty((0, n), dtype=np.int8)
+
+    ints_expanded = ints.astype(np.int64)[:, np.newaxis]
+    digits = np.empty((len(ints), n), dtype=np.int8)
+    remaining = ints_expanded.copy()
+
+    for axis in range(n - 1, -1, -1):
+        digits[:, axis] = (remaining[:, 0] % p).astype(np.int8)
+        remaining = remaining // p
+
+    return digits
+
+
+def fwht(a: np.ndarray) -> np.ndarray:
+    """
+    In-place Fast Walsh-Hadamard Transform of 1d array `a`.
+    Array size must be exactly 2^n. Fully vectorized in NumPy.
+    """
+    n_elements = len(a)
+    n_bits = int(np.log2(n_elements))
+
+    if 1 << n_bits != n_elements:
+        raise ValueError("Array length must be a power of 2")
+
+    res = a.astype(np.float64)
+
+    for d in range(n_bits):
+        half_step = 1 << d
+        shape = (-1, 2, half_step)
+        res_reshaped = res.reshape(shape)
+
+        a0 = res_reshaped[:, 0, :].copy()
+        a1 = res_reshaped[:, 1, :].copy()
+
+        res_reshaped[:, 0, :] = a0 + a1
+        res_reshaped[:, 1, :] = a0 - a1
+
+    return res
+
+
+def compute_sumset_fwht(set_elements: np.ndarray, p: int = 2) -> np.ndarray:
+    """
+    Computes S+S over Z_p^n using the Fourier transform on the finite abelian group.
+    Time Complexity: O(p^n * n * log p) for a dense transform over the universe size p^n.
+    Space Complexity: O(p^n)
+    """
+    if len(set_elements) == 0:
+        return np.empty((0, set_elements.shape[1]), dtype=np.int8)
+
+    if p <= 1:
+        raise ValueError("p must be at least 2")
+
+    n = set_elements.shape[1]
+    universe_size = p ** n
+
+    ints = vectors_to_ints(set_elements, p=p)
+
+    indicator = np.zeros((p,) * n, dtype=np.complex128)
+    indicator.reshape(-1)[ints] = 1.0
+
+    transformed = np.fft.fftn(indicator, axes=tuple(range(n)))
+    transformed_squared = transformed * transformed
+
+    convolution = np.fft.ifftn(transformed_squared, axes=tuple(range(n))).real
+    sumset_ints = np.flatnonzero(np.rint(convolution).astype(np.int64) > 0)
+    sumset_vectors = ints_to_vectors(sumset_ints, n, p=p)
+
+    return sumset_vectors

ffspaces-0.2.0/src/ffspaces/geometries.py

@@ -0,0 +1,46 @@
+import itertools
+
+import numpy as np
+
+
+def generate_standard_ball(n: int, r: int) -> np.ndarray:
+    """
+    Generates all vectors in F_2^n with Hamming weight <= r.
+    """
+    vectors = []
+    for weight in range(r + 1):
+        for combo in itertools.combinations(range(n), weight):
+            vec = np.zeros(n, dtype=np.int8)
+            vec[list(combo)] = 1
+            vectors.append(vec)
+    return np.array(vectors, dtype=np.int8)
+
+
+def compute_hamming_weight(vectors: np.ndarray) -> np.ndarray:
+    """
+    Computes the Hamming weight for an array of vectors.
+    Input shape: (M, n) -> Output shape (M,)
+    """
+    return np.count_nonzero(vectors, axis=1)
+
+
+def generate_hamming_ball(
+    universe: np.ndarray,
+    center: np.ndarray,
+    radius: int,
+    linear_transform: np.ndarray,
+    p: int = 2,
+) -> np.ndarray:
+    """
+    Generates a Hamming ball centered at `center` with a given `radius`
+    under the basis defined by `linear_transform` over F_p^n.
+
+    B_{L}(v, r)= { x in F_p^n : weight( L(x-v) mod p ) <= r }
+    """
+    shifted = (universe - center) % p
+    transformed = (shifted @ linear_transform.T) % p
+
+    weights = compute_hamming_weight(transformed)
+    mask = weights <= radius
+
+    return universe[mask]

ffspaces-0.2.0/src/ffspaces/operators.py

@@ -0,0 +1,146 @@
+from itertools import combinations, product
+from typing import Optional, Tuple
+
+import numpy as np
+
+from .core import rank_mod_p
+from .fwht_operators import compute_sumset_fwht
+
+
+def _compute_sumset_original(set_elements: np.ndarray, p: int = 2) -> np.ndarray:
+    """
+    Computes the unique elements of the sumset S + S over F_p
+    using the direct broadcast-based approach.
+    """
+    if len(set_elements) == 0:
+        return np.empty((0, set_elements.shape[1]), dtype=np.int8)
+
+    broadcasted_sum = (set_elements[:, np.newaxis, :] + set_elements[np.newaxis, :, :]) % p
+    reshaped_sums = broadcasted_sum.reshape(-1, set_elements.shape[1])
+
+    return np.unique(reshaped_sums, axis=0)
+
+
+def compute_sumset(set_elements: np.ndarray, p: int = 2) -> np.ndarray:
+    """
+    Computes the unique elements of the sumset S + S over Z_p^n.
+    This uses the generalized Fourier-transform fast path for all p >= 2.
+    """
+    if p <= 1:
+        raise ValueError("p must be at least 2")
+
+    return compute_sumset_fwht(set_elements, p=p)
+
+
+def compare_sumset_methods(n: int = 6, subset_size: int = 10, seed: Optional[int] = None) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """
+    Generates a random subset of F_2^n and compares the FWHT-based sumset against
+    the original direct implementation.
+    """
+    if n < 1:
+        raise ValueError("n must be at least 1")
+    if subset_size < 1:
+        raise ValueError("subset_size must be at least 1")
+
+    universe = np.array(list(product([0, 1], repeat=n)), dtype=np.int8)
+    rng = np.random.default_rng(seed)
+    subset_indices = rng.choice(len(universe), size=subset_size, replace=False)
+    subset = universe[subset_indices]
+
+    fwht_sumset = compute_sumset(subset, p=2)
+    original_sumset = _compute_sumset_original(subset, p=2)
+
+    return subset, fwht_sumset, original_sumset
+
+
+def _find_maximum_subspace_dimension_greedy(sumset: np.ndarray, p: int = 2) -> int:
+    """Greedily build a maximal set of independent generators whose span is contained in sumset."""
+    n = sumset.shape[1]
+    sumset_set = {tuple(row) for row in sumset}
+    independent_generators = []
+
+    for candidate in sumset:
+        if np.all(candidate == 0):
+            continue
+
+        valid_generator = True
+        current_span = [np.zeros(n, dtype=np.int8)]
+
+        for gen in independent_generators:
+            current_span += [(gen * k + s) % p for k in range(1, p) for s in current_span]
+
+        for vec in current_span:
+            for k in range(1, p):
+                test_vec = (vec + k * candidate) % p
+                if tuple(test_vec) not in sumset_set:
+                    valid_generator = False
+                    break
+            if not valid_generator:
+                break
+
+        if valid_generator:
+            test_matrix = np.array(independent_generators + [candidate])
+            if rank_mod_p(test_matrix, p) == len(independent_generators) + 1:
+                independent_generators.append(candidate)
+
+    return len(independent_generators)
+
+
+def find_maximum_subspace_dimension(
+    sumset: np.ndarray,
+    p: int = 2,
+    exhaustive: bool = False,
+    max_combinations: Optional[int] = 10_000,
+) -> int:
+    """
+    Finds the dimension of the largest linear subspace completely contained within S+S.
+    By default uses a greedy iterative check of linearly independent generators. If
+    `exhaustive=True` it will search combinations of generators (starting from the
+    largest possible dimension) to find the maximum dimension whose span is fully
+    contained in `sumset`. A `max_combinations` limit can be supplied to avoid
+    combinatorial blowups in large experiments; if reached, the greedy result is returned.
+    """
+    n = sumset.shape[1]
+    sumset_set = {tuple(row) for row in sumset}
+
+    if tuple(np.zeros(n, dtype=np.int8)) not in sumset_set:
+        return -1
+
+    max_possible_d = 0
+    size = len(sumset)
+    if size > 0:
+        while p ** (max_possible_d + 1) <= size and max_possible_d < n:
+            max_possible_d += 1
+
+    greedy_dimension = _find_maximum_subspace_dimension_greedy(sumset, p)
+
+    if exhaustive:
+        checked_combinations = 0
+        for d in range(max_possible_d, 0, -1):
+            nonzero_rows = [row for row in sumset if not np.all(row == 0)]
+            for combo in combinations(nonzero_rows, d):
+                if max_combinations is not None and checked_combinations >= max_combinations:
+                    return greedy_dimension
+
+                checked_combinations += 1
+                mat = np.vstack(combo)
+                if rank_mod_p(mat, p) != d:
+                    continue
+
+                all_in_sumset = True
+                for coeffs in product(range(p), repeat=d):
+                    if all(c == 0 for c in coeffs):
+                        vec = tuple(np.zeros(n, dtype=np.int8))
+                    else:
+                        vec_arr = sum((coeffs[i] * mat[i]) for i in range(d)) % p
+                        vec = tuple(vec_arr.astype(np.int8))
+                    if vec not in sumset_set:
+                        all_in_sumset = False
+                        break
+
+                if all_in_sumset:
+                    return d
+
+        return 0
+
+    return greedy_dimension

ffspaces-0.2.0/src/ffspaces.egg-info/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: ffspaces
+Version: 0.2.0
+Summary: A computational laboratory for finite field vector spaces, Hamming balls, and sumset structural analysis.
+Author: Nathan Hoehndorf
+Project-URL: Homepage, https://github.com/nathanhoehndorf/finite-field-spaces
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+
+# Finite-Field Spaces (`ffspaces`)
+
+`ffspaces` is a lightweight Python toolkit for working with vectors over finite fields $\mathbb{F}_p^n$, with a focus on sumset analysis, linear-subspace structure, and Hamming-ball geometry.
+
+The package is designed for small-to-medium computational experiments in additive combinatorics, coding theory, and related discrete geometry settings. It provides both direct implementations and faster specialized routines for common operations over finite fields.
+
+## Current functionality
+
+- **Finite-field vector spaces:** generate the full vector space $\mathbb{F}_p^n$ or construct random invertible basis changes.
+- **Finite-field rank:** compute matrix rank over $\mathbb{F}_p$ using modular Gaussian elimination.
+- **Sumsets:** compute $S+S$ for a set of vectors over $\mathbb{F}_p^n$, including a direct reference method and a faster FWHT-based implementation.
+- **Subspace detection:** find the largest linear subspace contained in a sumset, with both greedy and exhaustive search modes.
+- **Hamming-ball geometry:** generate standard Hamming balls, compute Hamming weights, and build balls under arbitrary linear transforms.
+- **Cover constructions:** build unions of Hamming balls and compute complements relative to a universe.
+
+## Features
+
+- **NumPy-based operations:** vectorized generation and manipulation of finite-field vectors.
+- **Field-aware linear algebra:** rank and invertibility checks performed over $\mathbb{F}_p$, not over the reals.
+- **Flexible geometry tools:** support for binary and higher-characteristic experiments.
+- **Reusable experiment helpers:** scripts and utilities in the `experiments/` directory for one-off analysis.
+
+## Installation
+
+Clone the repository and install it in editable mode:
+
+```bash
+git clone https://github.com/nathanhoehndorf/finite-field-spaces
+cd finite-field-spaces
+pip install -e .
+```
+
+The package requires Python 3.10+ and NumPy.
+
+## Mathematical background
+
+This package works in the vector space $\mathbb{F}_p^n$, where each coordinate is taken modulo a prime $p$. In particular, $\mathbb{F}_2^n$ is the set of binary vectors of length $n$, with addition done coordinatewise modulo $2$.
+
+- **What is $\mathbb{F}_p^n$?** A finite-dimensional vector space over the finite field with $p$ elements. For $p=2$, this is the space of binary vectors.
+- **What is $S+S$?** For a set $S \subseteq \mathbb{F}_p^n$, the sumset $S+S$ is the set of all pairwise sums $x+y$ with $x,y \in S$, taken modulo $p$.
+- **What is a Hamming ball?** A Hamming ball is the set of vectors within a given distance from a center, where distance is the number of coordinates in which two vectors differ (known as Hamming weight, or the Hamming metric).
+- **What is the covering problem?** A covering problem asks whether a collection of balls (or other subsets) can be chosen so that their union contains all points in a given universe, or perhaps all points of a particular structure.
+- **Why does this matter?** These objects are central in additive combinatorics, coding theory, and discrete geometry, and they provide a natural setting for studying how small sets expand under addition or how geometric configurations cover a space.
+
+
+## Quick example
+
+```python
+import numpy as np
+from ffspaces import generate_space, compute_sumset, find_maximum_subspace_dimension
+
+space = generate_space(3, p=2)
+subset = space[[0, 1, 2, 4]]
+sumset = compute_sumset(subset, p=2)
+dimension = find_maximum_subspace_dimension(sumset, p=2)
+print(dimension)
+```
+
+## Experiments
+
+One-off analysis and experiment scripts live in the `experiments/` directory so they stay separate from the installable package code in `src/`.

ffspaces-0.2.0/src/ffspaces.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+src/ffspaces/__init__.py
+src/ffspaces/core.py
+src/ffspaces/covers.py
+src/ffspaces/fwht_operators.py
+src/ffspaces/geometries.py
+src/ffspaces/operators.py
+src/ffspaces.egg-info/PKG-INFO
+src/ffspaces.egg-info/SOURCES.txt
+src/ffspaces.egg-info/dependency_links.txt
+src/ffspaces.egg-info/requires.txt
+src/ffspaces.egg-info/top_level.txt
+tests/test_core_and_operators.py
+tests/test_fwht_sumset_equivalence.py
+tests/test_public_api.py

ffspaces-0.2.0/src/ffspaces.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ffspaces-0.2.0/src/ffspaces.egg-info/requires.txt

@@ -0,0 +1,4 @@
+numpy>=1.24.0
+
+[test]
+pytest>=7.0

ffspaces-0.2.0/src/ffspaces.egg-info/top_level.txt

@@ -0,0 +1 @@
+ffspaces

ffspaces-0.2.0/tests/test_core_and_operators.py

@@ -0,0 +1,142 @@
+import numpy as np
+import pytest
+
+from ffspaces.core import generate_space, generate_random_basis, is_invertible, rank_mod_p
+from ffspaces.operators import (
+    _compute_sumset_original,
+    compute_sumset,
+    find_maximum_subspace_dimension,
+)
+from ffspaces.geometries import generate_standard_ball
+
+
+@pytest.mark.parametrize(
+    ("n", "p", "expected"),
+    [
+        (0, 2, 1),
+        (1, 2, 2),
+        (2, 2, 4),
+        (3, 3, 27),
+    ],
+)
+def test_generate_space_edge_cases(n, p, expected):
+    space = generate_space(n, p=p)
+    assert space.shape == (expected, n)
+    assert np.array_equal(space[0], np.zeros(n, dtype=np.int8))
+
+
+def test_generate_space_full_space_contains_all_vectors():
+    space = generate_space(3, p=2)
+    assert set(map(tuple, space)) == {
+        (0, 0, 0),
+        (0, 0, 1),
+        (0, 1, 0),
+        (0, 1, 1),
+        (1, 0, 0),
+        (1, 0, 1),
+        (1, 1, 0),
+        (1, 1, 1),
+    }
+
+
+def test_is_invertible_edge_cases():
+    assert is_invertible(np.array([[1]], dtype=np.int8), p=2)
+    assert not is_invertible(np.array([[0]], dtype=np.int8), p=2)
+    assert not is_invertible(np.array([[1, 0], [0, 0]], dtype=np.int8), p=2)
+    assert is_invertible(np.array([[1, 1], [1, 0]], dtype=np.int8), p=2)
+
+
+def test_compute_sumset_handles_empty_and_singleton_sets():
+    empty = np.empty((0, 3), dtype=np.int8)
+    singleton = np.array([[1, 0, 1]], dtype=np.int8)
+
+    assert compute_sumset(empty, p=2).shape == (0, 3)
+    assert _compute_sumset_original(empty, p=2).shape == (0, 3)
+
+    expected_singleton = np.array([[0, 0, 0]], dtype=np.int8)
+    computed_singleton = compute_sumset(singleton, p=2)
+    assert computed_singleton.shape == (1, 3)
+    assert np.array_equal(computed_singleton, expected_singleton)
+
+
+def test_compute_sumset_full_space_matches_original():
+    full_space = generate_space(3, p=2)
+    computed = compute_sumset(full_space, p=2)
+    original = _compute_sumset_original(full_space, p=2)
+    assert set(map(tuple, computed)) == set(map(tuple, original))
+    assert set(map(tuple, computed)) == set(map(tuple, full_space))
+
+
+@pytest.mark.parametrize(
+    ("sumset", "p", "expected"),
+    [
+        (np.array([[0, 0]], dtype=np.int8), 2, 0),
+        (np.array([[0, 0], [1, 0]], dtype=np.int8), 2, 1),
+        (np.array([[0, 0], [1, 0], [0, 1], [1, 1]], dtype=np.int8), 2, 2),
+    ],
+)
+def test_find_maximum_subspace_dimension_edge_cases(sumset, p, expected):
+    assert find_maximum_subspace_dimension(sumset, p=p) == expected
+
+
+def test_find_maximum_subspace_dimension_exhaustive_matches_greedy():
+    sumset = np.array(
+        [
+            [0, 0, 0],
+            [1, 0, 0],
+            [0, 1, 0],
+            [1, 1, 0],
+            [0, 0, 1],
+            [1, 0, 1],
+            [0, 1, 1],
+            [1, 1, 1],
+        ],
+        dtype=np.int8,
+    )
+    assert find_maximum_subspace_dimension(sumset, p=2) == 3
+    assert find_maximum_subspace_dimension(sumset, p=2, exhaustive=True) == 3
+
+
+def test_find_maximum_subspace_dimension_uses_field_rank_over_f2():
+    sumset = np.array(
+        [
+            [0, 0, 0, 0],
+            [1, 1, 0, 0],
+            [1, 0, 1, 0],
+            [0, 1, 1, 0],
+        ],
+        dtype=np.int8,
+    )
+    assert find_maximum_subspace_dimension(sumset, p=2) == 2
+    assert find_maximum_subspace_dimension(sumset, p=2, exhaustive=True) == 2
+
+
+def test_find_maximum_subspace_dimension_exhaustive_respects_combinatorial_limit():
+    sumset = generate_space(6, p=2)
+    greedy = find_maximum_subspace_dimension(sumset, p=2)
+    assert find_maximum_subspace_dimension(sumset, p=2, exhaustive=True, max_combinations=10) == greedy
+
+
+def test_generate_standard_ball_regression_matches_expected_vectors():
+    ball = generate_standard_ball(3, 1)
+    expected = np.array(
+        [
+            [0, 0, 0],
+            [1, 0, 0],
+            [0, 1, 0],
+            [0, 0, 1],
+        ],
+        dtype=np.int8,
+    )
+    assert ball.shape == (4, 3)
+    assert np.array_equal(ball, expected)
+
+
+def test_generate_standard_ball_radius_zero_is_singleton_zero_vector():
+    ball = generate_standard_ball(4, 0)
+    assert ball.shape == (1, 4)
+    assert np.array_equal(ball, np.zeros((1, 4), dtype=np.int8))
+
+def test_rank_mod_p_catches_dependency_that_looks_indepenent_over_reals():
+    a, b, c = [1,1,0,0], [1,0,1,0], [0,1,1,0]
+    assert rank_mod_p(np.array([a,b,c]), p=2) == 2

ffspaces-0.2.0/tests/test_fwht_sumset_equivalence.py

@@ -0,0 +1,50 @@
+import unittest
+import numpy as np
+
+from ffspaces.core import generate_random_basis, is_invertible
+from ffspaces.fwht_operators import compute_sumset_fwht
+from ffspaces.operators import _compute_sumset_original, compare_sumset_methods
+
+
+class SumsetFwhtComparisonTest(unittest.TestCase):
+    def test_random_subset_matches_fwht_and_original(self):
+        subset, fwht_sumset, original_sumset = compare_sumset_methods(n=6, subset_size=10, seed=7)
+
+        self.assertEqual(subset.shape[1], 6)
+        self.assertEqual(subset.shape[0], 10)
+        self.assertEqual({tuple(row) for row in fwht_sumset}, {tuple(row) for row in original_sumset})
+
+    def test_generate_random_basis_accepts_rng(self):
+        rng = np.random.default_rng(17)
+        basis = generate_random_basis(4, p=2, rng=rng)
+        basis_again = generate_random_basis(4, p=2, rng=np.random.default_rng(17))
+
+        self.assertEqual(basis.shape, (4, 4))
+        self.assertTrue(is_invertible(basis, p=2))
+        self.assertTrue(np.array_equal(basis, basis_again))
+
+    def test_general_fourier_sumset_matches_original_for_p3(self):
+        subset = np.array([
+            [0, 0],
+            [1, 0],
+            [0, 1],
+            [1, 1],
+            [2, 0],
+            [0, 2],
+        ], dtype=np.int8)
+
+        fwht_sumset = compute_sumset_fwht(subset, p=3)
+        original_sumset = _compute_sumset_original(subset, p=3)
+
+        self.assertEqual({tuple(row) for row in fwht_sumset}, {tuple(row) for row in original_sumset})
+
+    def test_is_invertible_uses_rank_over_f2(self):
+        invertible = np.array([[1, 1], [1, 0]], dtype=np.int8)
+        singular = np.array([[1, 1], [1, 1]], dtype=np.int8)
+
+        self.assertTrue(is_invertible(invertible, p=2))
+        self.assertFalse(is_invertible(singular, p=2))
+
+
+if __name__ == "__main__":
+    unittest.main()

ffspaces-0.2.0/tests/test_public_api.py

@@ -0,0 +1,6 @@
+import ffspaces
+
+
+def test_public_api_exposes_sumset_helpers_but_not_fwht():
+    assert hasattr(ffspaces, "compute_sumset_fwht")
+    assert not hasattr(ffspaces, "fwht")