fhelium.experimental.bootstrap.reduction.cosine

Cosine-seed periodic reduction with double-angle reconstruction.

CosineDoubleAngleReduction

class View source

CosineDoubleAngleReduction(input_bound: int, double_angle_iterations: int, approximator: Any, evaluator: Any, fuse_input_normalization: bool = False, retain_ntt: bool = False, maximum_plaintext_error: float = 0.001, seed_shift: float = 0.0)

Reduce one real branch with a cosine seed and double-angle chain.

input_bound is the positive integer $B$ bounding the raw coordinate $r$. Reduction uses normalized coordinate $x=r/B\in [-1,1]$; seed_shift places its seed polynomial at a shifted coordinate. With $R=$ double_angle_iterations, the unshifted seed is

$$z_0(x)\approx {\pi }^{-1/2^R}\cos (\frac{\pi Bx}{2^R}-\frac{\pi }{2^{R+1}}),$$

and iteration $j=1,\dots ,R$ computes

$$z_j=2z_{j-1}^2-{\pi }^{-1/2^{R-j}}.$$

Thus $z_R\approx {\rho }_B(x)=\sin (\pi Bx)/\pi$. seed_shift=c evaluates the seed at z=x+c and subtracts the same shift in its fitted phase. The periodic map is unchanged. For c=-1/(2B), the fitted seed is even; its odd Chebyshev coefficients are zero. Approximation and homomorphic evaluation are separate components.

reference(values) always takes normalized $x$ coordinates and applies no input division. evaluate(...) takes raw $r$ when fuse_input_normalization=False, dividing by $B$ homomorphically. When fusion is enabled, the caller must already have divided by $B$; the built-in full-slot callable folds that factor into CoeffsToSlots.

The homomorphic input is a two-component Q ciphertext in either coefficient/standard or NTT/Montgomery representation, with payload axes [component, *batch, limb, coefficient], active prime_ids, and actual scale matching the arithmetic owner's target at the input depth. Evaluation is functional. With retain_ntt=True, a coefficient input is transformed once and the polynomial and double-angle chain retain NTT/Montgomery form until one final inverse transform. Otherwise each multiplication returns to the input representation. Rescale removes one Q group and divides actual scale by its product. The output uses the input representation, batch and component axes, Q basis, and context; its depth advances by required_depths, its limb axis contains the corresponding suffix of prime_ids, and its actual scale follows the arithmetic owner's depth schedule.

More iterations reduce the seed frequency but each iteration costs one ciphertext multiplication, relinearization, and rescale depth. Neither the class nor evaluate measures the encrypted branch range; the caller must establish $|r|\le B$.

Attributes

Name	Type	Default/value
requires_relinearization		True
input_bound	int
double_angle_iterations	int
approximator	Any
evaluator	Any
fuse_input_normalization	bool	False
retain_ntt	bool	False
maximum_plaintext_error	float	0.001
seed_shift	float	0.0

polynomial

property

polynomial: PolynomialApproximation

Fit the low-frequency seed in normalized coordinate $x$.

For $R=$ double_angle_iterations, the returned Chebyshev or power series in z=x+seed_shift approximates

$${\pi }^{-1/2^R}\cos (\frac{\pi B(z-c)}{2^R}-\frac{\pi }{2^{R+1}})\text{on }[-1,1].$$

Its coefficient basis is selected by approximator; coefficients use that basis's ascending-degree convention.

approximation_error

property

approximation_error: float

Sample $|\mathrm{reference}(x)-{\rho }_B(x)|$ on a fixed grid.

The grid spans normalized $x\in [-1,1]$. This is a fail-fast construction check, not a certified supremum bound and not a CKKS evaluation-error measurement.

fused_input_divisor

property

fused_input_divisor: float

Return $B$ when normalization is fused into the input transform, or $1$ when evaluation divides by $B$.

required_depths

property

required_depths: int

Count normalization, polynomial-evaluation, and recurrence depths.

relinearization_depths

method

def relinearization_depths(*, input_depth: int=0) -> tuple[int, ...] | None: ...

Compose normalization, polynomial products and double-angle products.

evaluate

method

def evaluate(arithmetic: BootstrapArithmetic, ciphertext: Ciphertext, *, relinearization_key: RelinearizationKey | EvaluationKeySet | Mapping[int, RelinearizationKey] | None, conjugation_key: ConjugationKey | None=None) -> Ciphertext: ...

Evaluate ${\rho }_B$ homomorphically under the class coordinate convention.

With non-fused normalization the input represents raw $r$ and the first depth computes $x=r/B$. With fused normalization it already represents $x$. Each recurrence iteration squares and relinearizes the current ciphertext, rescales one Q group, doubles it by addition, and subtracts the stage constant. The output represents ${\rho }_B(x)=\sin (\pi r)/\pi$ at ciphertext.depth + required_depths. Input storage is not mutated or aliased by the result.

reference

method

def reference(values: np.ndarray) -> np.ndarray: ...

Evaluate the plaintext oracle on normalized coordinates $x$.

values may have any NumPy-broadcastable shape and that shape is preserved. Unlike non-fused evaluate, this method never divides by $B$; pass raw coordinates as values / input_bound. The target is ${\rho }_B(x)=\sin (\pi Bx)/\pi$ and CKKS rounding is not modeled.