Crate poulpy_hal 

poulpy-hal

A trait-based Hardware Abstraction Layer (HAL) for lattice-based polynomial arithmetic over the cyclotomic ring Z[X]/(X^N + 1).

This crate provides backend-agnostic data layouts and a trait-based API for polynomial operations commonly used in lattice-based cryptography (LWE/Module-LWE ciphertexts, key-switching matrices, external products, etc.). It is designed so that cryptographic schemes can be written once against the api traits and then executed on any backend (CPU with AVX2/AVX-512, GPU, FPGA, …) that implements the oep (Open Extension Point) traits.

Core Concepts

Ring: All polynomials live in Z[X]/(X^N + 1) where N is a power of two (the ring degree). A layouts::Module encapsulates N together with an optional backend-specific handle (e.g. precomputed FFT twiddle factors).

Limbed representation (base-2^k): Large coefficients are decomposed into a vector of size limbs, each carrying at most base2k bits. This is the bivariate view Z[X, Y] with Y = 2^{-k}, central to gadget decomposition and normalization.

Layout types (layouts):

• layouts::ScalarZnx – single polynomial with i64 coefficients.
• layouts::VecZnx – vector of cols polynomials, each with size limbs.
• layouts::MatZnx – matrix of polynomials (rows x cols_in, each entry a layouts::VecZnx of cols_out polynomials).
• layouts::VecZnxBig – vector of polynomials with backend-specific large-coefficient scalars (result accumulator).
• layouts::VecZnxDft – vector of polynomials in DFT/NTT domain (backend-specific prepared scalars).
• layouts::SvpPPol – prepared scalar polynomial for scalar-vector products.
• layouts::VmpPMat – prepared matrix for vector-matrix products.
• layouts::CnvPVecL, layouts::CnvPVecR – prepared left/right operands for bivariate convolution.
• layouts::ScratchArena, layouts::ScratchOwned – aligned scratch memory for temporary workspace.

All layout types are generic over a data container D (owned Vec<u8>, borrowed &[u8] / &mut [u8]), enabling zero-copy views and arena-style allocation via layouts::ScratchArena.

Architecture

The crate is organized into a four-layer stack:

1. api – Safe, user-facing trait definitions (e.g. api::VecZnxAddIntoBackend, api::VmpApplyDftToDft). Scheme authors program against these.
2. oep – Unsafe extension-point layer of per-family backend traits. Backend crates implement only the families they own and may reuse helper macros or defaults where convenient.
3. delegates – Blanket impl glue that connects each api trait to the corresponding backend family method on layouts::Module.
4. Reference implementations live in the poulpy-cpu-ref crate, which provides the portable default backend used by tests and benchmarks.

Testing and Benchmarking

The test_suite module provides fully generic, backend-parametric test functions. Backend crates instantiate these via the backend_test_suite! and cross_backend_test_suite! macros to validate correctness against the reference implementation in poulpy-cpu-ref.

Analogous Criterion-based benchmark harnesses live in the separate poulpy-bench crate.

Safety Contract

All oep extension points are unsafe to implement. Implementors must uphold the contract documented in doc::backend_safety, covering memory domains, alignment, scratch lifetime, synchronization, aliasing, and numerical exactness.

Non-Goals

• This crate does not provide a complete cryptographic scheme. It is a low-level arithmetic layer consumed by higher-level crates such as poulpy-core and poulpy-bin-fhe.
• It does not perform constant-time enforcement. Side-channel resistance is the responsibility of the backend and the caller.

Compatibility

• Requires nightly Rust (uses #![feature(trait_alias)]).
• All memory allocations are aligned to DEFAULTALIGN (64 bytes).
• Types matching the API of spqlios-arithmetic.

Modules

api

Safe, user-facing trait definitions for polynomial arithmetic operations.

delegates

Criterion-based benchmark harnesses, generic over any backend. Blanket implementations connecting api traits to oep traits on layouts::Module.

doc

Embedded safety contract documentation for backend implementors.

layouts

Backend-agnostic data layout types for polynomials, vectors, matrices, and prepared (DFT-domain) representations.

oep

Open Extension Points: the unsafe backend extension layer of per-family backend traits.

source

Deterministic pseudorandom number generation based on ChaCha8.

test_suite

Fully generic, backend-parametric test functions.

Macros

backend_test_suite

cross_backend_test_suite

impl_backend_from

Implement a backend marker by forwarding all storage- and handle-level behavior to an existing backend.

Constants

DEFAULTALIGN

Default memory alignment in bytes for all allocated buffers.

GALOISGENERATOR

Default generator of the Galois group (Z/2NZ)* for the cyclotomic ring Z[X]/(X^N + 1).

Functions

alloc_aligned

Allocates a zero-initialized Vec<T> aligned to DEFAULTALIGN bytes.

alloc_aligned_custom

Allocates a zero-initialized Vec<T> with custom alignment.

assert_alignement

Deprecated spelling variant. Use assert_alignment instead.

assert_alignment

Panics if ptr is not aligned to DEFAULTALIGN bytes.

cast

Reinterprets a &[T] as a &[V].

cast_mut

Reinterprets a &mut [T] as a &mut [V].

is_aligned

Returns true if ptr is aligned to DEFAULTALIGN bytes.