EP-0147: Optional Loop Pragmas & Free-Threaded Concurrency¶

Abstract¶

This proposal explores non-invasive loop parallelization in core operations (dot, einsum, dft, verify_semiring_laws) using comment-based pragmas (# LUCEN START / # LUCEN END). It enables zero-overhead multi-core scaling on GIL-less Python 3.13+ free-threaded builds while maintaining 100% pure-Python zero-dependency compatibility when executed on standard Python.

Motivation¶

algebrax operates directly on pure Python dictionaries. While dictionary operations are fast for sparse data, large matrix multiplications (\(N > 500\)) and batch property verifications are CPU-bound. Traditional multi-processing libraries (multiprocessing, joblib) require pickling complex nested dict structures, creating memory overhead that neutralizes speedups for small-to-medium matrices.

With the release of free-threaded Python (GIL-less 3.13/3.14) and tools like lucen (fcmv/lucen), loops can be parallelized via comment pragmas with zero API modifications and bit-identical mathematical invariants.

Specification¶

1. Comment Pragma Annotations (# LUCEN START / # LUCEN END)¶

Annotate independent outer loops in core bottleneck operations:

• algebrax.matrix.dot: Parallelize independent row inner products across threads.
• algebrax.tensor.einsum: Parallelize top-level tensor index contractions.
• algebrax.transforms.convolve & dft: Parallelize frequency/row slice calculations.
• algebrax.verification.verify_semiring_laws: Parallelize batch random element property checks.

# LUCEN START
for r, row_a in matrix_a.items():
    row_res = {}
    for k, val_a in row_a.items():
        if k in matrix_b:
            for c, val_b in matrix_b[k].items():
                # semiring accumulation...
                ...
# LUCEN END

2. Zero-Dependency Compatibility¶

Because comment pragmas are valid Python comments (#), environments running without lucen execute standard sequential loops. No external dependencies are added to pyproject.toml.

3. Multi-Domain Benchmark Infrastructure (benchmarks/print_benchmarks.py)¶

A dedicated report runner (benchmarks/print_benchmarks.py) measures performance across four primary computational domains across the density spectrum (\(5\%\) to \(75\%\)):

Falsifiable Invariants¶

• Parallelized execution produces bit-identical and order-identical dictionary outputs compared to sequential execution (res_seq == res_parallel).
• Running algebrax without lucen installed exhibits zero overhead and zero syntax errors.
• Free-threaded Python 3.13/3.14 builds achieve up to \(1.35\times\) speedups on 4-core CPUs for signal and matrix transforms.

Backwards Compatibility¶

100% backward-compatible. Comment pragmas are ignored by standard Python interpreters.

Change Log¶

• 2026-08-07: Integrated pragmas directly into core modules (matrix.core, semiring.algebraic, transforms, tensor), added benchmarks/print_benchmarks.py, and recorded empirical free-threaded measurements on Python 3.14t.