[!WARNING] This library was made with the help of AI. Audit the code yourself, or with your own agent before using.

fgf — Faster Galois Fields

fgf provides finite-field arithmetic and fast bulk operations over packed byte buffers. It is the arithmetic layer beneath erasure codes, proof systems, and other workloads that repeatedly scale, combine, and reconstruct rows of field elements.

• Fields: binary fields from GF(2) to GF(2^64) — polynomial bases, ordered (normal and Cantor) bases, and quadratic towers, including custom ones — plus the Mersenne31, Goldilocks, and QM31 prime fields, and bit-packed GF(2).
• One element type: Elem<F> is the element of every field, with const arithmetic, so coefficients and matrices can be built at compile time.
• Bulk operations: ops provides checked AXPY, scaling, scatter, gather, matrix, and elementwise operations over unaligned little-endian buffers, with prepared coefficients for allocation-free repeated use.
• Runtime SIMD: the best available backend is selected once per process, with a portable fallback everywhere.
• Embeddings: Embedding<S, T> maps one binary field into a larger one, with Frobenius, trace, and norm.

fgf is an arithmetic library, not a codec: it does not build coding matrices, manage shards, or implement a recovery protocol.

Usage

[dependencies]
fgf = "3.0.0"

Scalar arithmetic is const:

use fgf::{Binary, Elem, Polynomial, poly::AES};

type Gf2P8 = Binary<8, Polynomial<AES>>;

const A: Elem<Gf2P8> = Elem::<Gf2P8>::from_raw(0x53);
const B: Elem<Gf2P8> = Elem::<Gf2P8>::from_raw(0xCA);

assert_eq!(A.mul(B), Elem::<Gf2P8>::ONE);
assert_eq!(A.mul(B).div(B), A);

Bulk operations take the field as a type parameter and work on packed bytes:

use fgf::{Binary, Elem, Polynomial, poly::AES, ops};

type Gf2P8 = Binary<8, Polynomial<AES>>;

let src = [0x01u8, 0x02, 0x03, 0x04];
let mut dst = [0u8; 4];

// dst += 0x03 * src
ops::mul_add::<Gf2P8>(&mut dst, Elem::<Gf2P8>::from_raw(0x03), &src);
assert_eq!(dst, [0x03, 0x06, 0x05, 0x0c]);

The examples/ directory has self-contained programs covering field arithmetic, shard recovery, streaming encoding, GF(2) syndromes, extension fields, embeddings, and prime-field vectors:

cargo run --example shard_recovery

The API reference is on docs.rs; guides and background are on the wiki. Changes and migration from 2.x are in CHANGELOG.md.

Features

With default-features = false, fgf is no_std and runs the portable implementation.

Platforms

fgf::backend() reports the selected backend. Setting SIMD_BACKEND (for example SIMD_BACKEND=scalar) at process start requests a weaker backend; requests the host cannot support are ignored.

Safety

• Not constant-time. Table lookups and data-dependent work leak timing. Do not use fgf with secret elements, coefficients, or buffers without your own audit.
• The public API is safe Rust. Operations validate lengths and row geometry before running and panic on invalid input.
• Unsafe code is confined to SIMD kernels, with each use documented at its site.
• Inversion and division are total: inv(0) == 0 and x / 0 == 0.

Building

The minimum supported Rust version is 1.93.

cargo build
cargo test --all-features

The repository uses just for its full check suite; just validate runs it.

License

MIT — see LICENSE.