Skip to main content

poulpy_cpu_portable/
lib.rs

1#![feature(portable_simd, hint_prefetch, associated_type_defaults)]
2#![allow(clippy::too_many_arguments)]
3
4//! Portable CPU backend for the Poulpy lattice cryptography library.
5//!
6//! This crate provides two backends for [`poulpy_hal`]:
7//!
8//! - [`FFT64Portable`]: scalar `f64` FFT arithmetic — see the [`fft64`] module.
9//! - [`NTT4x30Portable`]: scalar Q120 NTT arithmetic (CRT over four ~30-bit primes) — see the [`ntt4x30`] module.
10//!
11//! Both are portable across all CPU architectures, in plain Rust (`std::simd` for normalization), and
12//! their scalar kernels, in [`kernels`], back the SIMD backends too.
13//!
14//! Both are generic over the ring, standard by default: [`FFT64CIPortable`] and [`NTT4x30CIPortable`]
15//! are their conjugate invariant instantiations.
16//!
17//! # Features
18//!
19//! The crate implements the [`poulpy_hal`] extension points unconditionally. The
20//! higher layers are opt-in:
21//!
22//! - `enable-core`: implements the `poulpy-core` extension points, so
23//!   `Module<FFT64Portable>` / `Module<NTT4x30Portable>` gain the scheme-level traits
24//!   (`GLWEKeyswitch`, `Automorphism`, ...). Without it those traits do not
25//!   resolve, and the failure reads as a missing impl rather than a missing
26//!   feature. Required to use this crate on either side of a cross-backend
27//!   comparison.
28//! - `enable-ckks`: implies `enable-core` and adds the `poulpy-ckks` layer.
29//! - `enable-blas`: implies `enable-ckks` and wires the enabled backends into `poulpy-blas`.
30//!
31//! # Platform support
32//!
33//! Compiles and runs on any target supported by the Rust standard library.
34//! No platform-specific intrinsics or assembly are used.
35
36mod backend_defaults;
37
38#[cfg(feature = "enable-blas")]
39mod blas_impl;
40#[cfg(feature = "enable-ckks")]
41pub mod ckks_encoding;
42#[cfg(feature = "enable-ckks")]
43mod ckks_impl;
44#[cfg(feature = "enable-ckks")]
45pub mod ckks_paco;
46#[cfg(feature = "enable-ckks")]
47pub mod ckks_ship;
48#[cfg(feature = "enable-core")]
49#[doc(hidden)]
50pub mod core_impl;
51pub mod fft64;
52pub mod hal_defaults;
53mod hal_impl;
54#[cfg(feature = "enable-mhe")]
55mod mhe_impl;
56pub mod ntt4x30;
57mod sampling;
58mod scalar_znx_fill;
59
60pub mod capabilities;
61pub mod kernels;
62pub mod table_cache;
63pub mod test_suite;
64
65#[cfg(test)]
66mod tests;
67
68pub use poulpy_hal::cast_mut;
69
70pub mod api {
71    pub use poulpy_hal::api::*;
72}
73
74pub mod layouts {
75    pub use poulpy_hal::layouts::*;
76}
77
78pub mod source {
79    pub use poulpy_hal::source::*;
80}
81
82pub use scalar_znx_fill::ScalarZnxFill;
83
84pub use fft64::FFT64Portable;
85pub use ntt4x30::{NTT4x30Portable, NTT4x30PortableHandle};
86
87#[cfg(test)]
88crate::conjugate_invariant_test_suite!(
89    ci_fft64portable,
90    crate::FFT64CIPortable,
91    crate::FFT64Portable,
92    reference = poulpy_cpu_oracle::FFT64CIOracle,
93    large_radix_reference = poulpy_cpu_oracle::NTT4x30CIOracle
94);
95
96#[cfg(test)]
97crate::conjugate_invariant_test_suite!(
98    ci_ntt4x30portable,
99    crate::NTT4x30CIPortable,
100    crate::NTT4x30Portable,
101    reference = poulpy_cpu_oracle::FFT64CIOracle,
102    large_radix_reference = poulpy_cpu_oracle::NTT4x30CIOracle
103);
104
105#[cfg(all(test, feature = "enable-core"))]
106crate::conjugate_invariant_core_test_suite!(
107    ci_core_fft64portable,
108    crate::FFT64CIPortable,
109    crate::FFT64Portable,
110    reference = poulpy_cpu_oracle::FFT64CIOracle
111);
112
113#[cfg(all(test, feature = "enable-core"))]
114crate::conjugate_invariant_core_test_suite!(
115    ci_core_ntt4x30portable,
116    crate::NTT4x30CIPortable,
117    crate::NTT4x30Portable,
118    reference = poulpy_cpu_oracle::FFT64CIOracle
119);
120
121#[cfg(all(test, feature = "enable-ckks"))]
122poulpy_ckks::conjugate_invariant_ckks_test_suite!(
123    ckks_ci_fft64portable,
124    crate::FFT64CIPortable,
125    crate::FFT64Portable,
126    poulpy_ckks::test_suite::BASE19_PARAMS_F64
127);
128
129#[cfg(all(test, feature = "enable-ckks"))]
130poulpy_ckks::conjugate_invariant_ckks_test_suite!(
131    ckks_ci_ntt4x30portable,
132    crate::NTT4x30CIPortable,
133    crate::NTT4x30Portable,
134    poulpy_ckks::test_suite::BASE52_PARAMS_F64
135);
136
137#[cfg(feature = "enable-ckks")]
138mod ckks_comparison;
139
140/// [`FFT64Portable`] over the conjugate invariant ring.
141#[cfg_attr(
142    feature = "enable-core",
143    doc = r"
144The Galois trace serves both rings:
145```
146use poulpy_core::GLWETrace;
147use poulpy_cpu_portable::FFT64CIPortable;
148use poulpy_hal::layouts::Module;
149fn trace<M: GLWETrace<FFT64CIPortable>>(_: &M) {}
150fn check(module: &Module<FFT64CIPortable>) { trace(module); }
151```
152Monomial rotation is standard-only:
153```
154use poulpy_core::GLWERotate;
155use poulpy_cpu_portable::FFT64Portable;
156use poulpy_hal::layouts::Module;
157fn rotate<M: GLWERotate<FFT64Portable>>(_: &M) {}
158fn check(module: &Module<FFT64Portable>) { rotate(module); }
159```
160```compile_fail
161use poulpy_core::GLWERotate;
162use poulpy_cpu_portable::FFT64CIPortable;
163use poulpy_hal::layouts::Module;
164fn rotate<M: GLWERotate<FFT64CIPortable>>(_: &M) {}
165fn check(module: &Module<FFT64CIPortable>) { rotate(module); }
166```
167So are the embedding and trace between the two rings:
168```
169use poulpy_core::{GLWECITrace, GLWECIEmbed};
170use poulpy_cpu_portable::FFT64Portable;
171use poulpy_hal::layouts::Module;
172fn maps<M: GLWECIEmbed<FFT64Portable> + GLWECITrace<FFT64Portable>>(_: &M) {}
173fn check(module: &Module<FFT64Portable>) { maps(module); }
174```
175```compile_fail
176use poulpy_core::GLWECIEmbed;
177use poulpy_cpu_portable::FFT64CIPortable;
178use poulpy_hal::layouts::Module;
179fn embed<M: GLWECIEmbed<FFT64CIPortable>>(_: &M) {}
180fn check(module: &Module<FFT64CIPortable>) { embed(module); }
181```"
182)]
183pub type FFT64CIPortable = FFT64Portable<poulpy_hal::layouts::ConjugateInvariant>;
184
185/// [`NTT4x30Portable`] over the conjugate invariant ring.
186#[cfg_attr(
187    feature = "enable-core",
188    doc = r"
189Prepared keys retain their backend type:
190```
191use poulpy_cpu_portable::NTT4x30CIPortable;
192use poulpy_core::layouts::{GetTensorKey, GLWETensorKeyPrepared};
193use poulpy_hal::AlignedBuf;
194fn accepts_ci(_: &impl GetTensorKey<NTT4x30CIPortable>) {}
195fn prepared(key: &GLWETensorKeyPrepared<AlignedBuf, NTT4x30CIPortable>) { accepts_ci(key); }
196```
197```compile_fail
198use poulpy_cpu_portable::{NTT4x30CIPortable, NTT4x30Portable};
199use poulpy_core::layouts::{GetTensorKey, GLWETensorKeyPrepared};
200use poulpy_hal::AlignedBuf;
201fn accepts_ci(_: &impl GetTensorKey<NTT4x30CIPortable>) {}
202fn prepared(key: &GLWETensorKeyPrepared<AlignedBuf, NTT4x30Portable>) { accepts_ci(key); }
203```"
204)]
205pub type NTT4x30CIPortable = NTT4x30Portable<poulpy_hal::layouts::ConjugateInvariant>;
206
207/// The names of this crate's backends before it was renamed from `poulpy-cpu-ref`.
208#[deprecated(note = "renamed to `FFT64Portable`")]
209pub type FFT64Ref<R = poulpy_hal::layouts::Standard> = FFT64Portable<R>;
210#[deprecated(note = "renamed to `NTT4x30Portable`")]
211pub type NTT4x30Ref<R = poulpy_hal::layouts::Standard> = NTT4x30Portable<R>;
212/// Former CKKS encoding transform, now [`EncodingFFTTable`](ckks_encoding::EncodingFFTTable).
213#[cfg(feature = "enable-ckks")]
214#[deprecated(note = "use `ckks_encoding::EncodingFFTTable`, which encodes byte identically on every CPU backend")]
215pub type FFT64ReimTable<F> = ckks_encoding::EncodingFFTTable<F>;
216
217#[cfg(feature = "enable-bin-fhe")]
218mod bin_fhe_impl;