fhelium.experimental.bootstrap.reduction

Periodic functions that remove approximate CKKS carries.

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)

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

input_bound is the positive integer $B$ bounding the raw coordinate $r$. The fitted polynomial always consumes the normalized coordinate $x=r/B\in [-1,1]$. With $R=$ double_angle_iterations, the 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$. 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

polynomial

property

polynomial: PolynomialApproximation

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

For $R=$ double_angle_iterations, the returned Chebyshev or power series approximates

$${\pi }^{-1/2^R}\cos (\frac{\pi Bx}{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$ for fused $x=r/B$, or $1$ for explicit division.

required_depths

property

required_depths: int

Count explicit division, polynomial depth, and recurrence depth.

evaluate

method

def evaluate(arithmetic: BootstrapArithmetic, ciphertext: Ciphertext, *, relinearization_key: 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.

ExponentialSquaringReduction

class View source

ExponentialSquaringReduction(input_bound: int, degree: int, evaluator: Any = BalancedPowerEvaluator(), fuse_input_normalization: bool = False)

Reduce one real branch through a truncated exponential and squaring.

Let $B=$ input_bound, $x=r/B\in [-1,1]$, and $K={\log }_{2}B$. A power-basis polynomial first approximates

$$z_0(x)=\exp (i\pi x).$$

Repeated squaring computes $z_K\approx \exp (i\pi Bx)$, and

$$\frac{z_K-\overline{z_K}}{2i\pi }\approx \frac{\sin (\pi Bx)}{\pi }={\rho }_B(x).$$

reference(values) always consumes normalized $x$. evaluate(...) consumes raw $r$ and divides by $B$ when fuse_input_normalization=False; with fusion enabled its caller must provide $x$ directly. The raw range $|r|\le B$ is a caller precondition and is not inspected in ciphertexts.

The ciphertext state, axes, functional behavior, depth transition, and depth-dependent scale schedule are the same as for CosineDoubleAngleReduction. This strategy additionally requires a conjugation key. It returns a two-component coefficient-domain, standard-RNS Q ciphertext at ciphertext.depth + required_depths, with the corresponding active prime_ids and the arithmetic owner's target scale.

Attributes

Name	Type	Default/value
requires_relinearization		True
input_bound	int
degree	int
evaluator	Any	BalancedPowerEvaluator()
fuse_input_normalization	bool	False

polynomial

property

polynomial: PolynomialApproximation

Return ascending power coefficients for $\exp (i\pi x)$.

Entry $n$ is $(i\pi {)}^n/n!$, so the stored polynomial is $\sum _{n=0}^d(i\pi {)}^n{x}^n/n!$ in normalized coordinate $x$.

squaring_iterations

property

squaring_iterations: int

Return ${\log }_{2}B$, the repeated-squaring count.

fused_input_divisor

property

fused_input_divisor: float

Return $B$ for fused $x=r/B$, or $1$ for explicit division.

required_depths

property

required_depths: int

Count normalization, polynomial DAG, squarings, and sine scaling.

evaluate

method

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

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

Non-fused evaluation first maps raw $r$ to $x=r/B$. After evaluating the power series, ${\log }_{2}B$ ciphertext squarings restore frequency. Finally $(z-\bar{z})/(2i\pi )$ isolates and scales the sine branch. The result represents $\sin (\pi r)/\pi$; input storage is unchanged.

reference

method

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

Evaluate the plaintext oracle on normalized coordinates $x$.

The input shape is preserved. This method never divides by $B$; pass raw coordinates as values / input_bound. It models polynomial truncation and repeated squaring but not CKKS error.