fhelium.experimental.bootstrap

CKKS bootstrap components and full-slot bootstrap execution.

The package exposes independently replaceable polynomial, linear-transform, and modular-reduction mechanisms plus one full-slot callable configured for one Engine. Preconfigured constructors live in fhelium.experimental.bootstrap.presets.

BalancedPowerEvaluator

class View source

BalancedPowerEvaluator(skip_near_zero: float = 0.0)

Evaluate a power series through a shared balanced product tree.

To construct $x^n$, the evaluator recursively multiplies $x^{\lfloor n/2\rfloor }$ by $x^{\lceil n/2\rceil }$. Every exponent is cached for one call, so terms share intermediate ciphertexts. Terms are depth-aligned using a basis scale recurrence anchored at the input. Each active coefficient multiplication consumes one final depth.

evaluate consumes a two-component coefficient-domain, standard-RNS Q ciphertext representing the basis coordinate $x$. Its dense payload axes are [component, *batch, limb, coefficient]; all batch members share depth, scale, and prime_ids. The method is functional. Each ciphertext product converts operands to NTT/Montgomery form, multiplies to three components, relinearizes back to two coefficient-domain standard components, and rescales by the complete Q group product while retaining actual scale. The final result is coefficient-domain standard RNS over Q at ciphertext.depth + required_depths(polynomial), with the corresponding prime_ids, unchanged batch shape, two components, and the coefficient-product target scale.

Attributes

Name	Type	Default/value
skip_near_zero	float	0.0

operation_inventory

method

def operation_inventory(polynomial: PolynomialApproximation) -> dict[str, int]: ...

Return multiplying operations executed by evaluate.

Coefficient multiplication counts only active nonconstant terms. Alignment multiplication counts every multiply-by-one depth advance, including advances used inside the shared power tree and before term addition. Additions and plaintext encoding are not multiplications.

required_depths

method

def required_depths(polynomial: PolynomialApproximation) -> int: ...

Count the deepest balanced-product path and coefficient product.

evaluate

method

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

Evaluate $p(x)=\sum _n{a}_n{x}^n$ at a common CKKS depth.

Coefficients with magnitude at or below skip_near_zero are omitted. A constant-only polynomial still consumes one depth by multiplying the input by zero; this keeps the execution behavior equal to the declared one-depth cost. Inputs are not mutated and output storage does not alias an input.

BootstrapArithmetic

class View source

BootstrapArithmetic(engine: Engine, constant_cache: MutableMapping[object, object] | None = None, retain_ntt: bool = True)

Execute Bootstrap CKKS arithmetic with depth-dependent scale targets.

target_scales gives an inspectable multiplication schedule derived from Q group products. Scalar and diagonal products select their plaintext scales to reach that schedule; ciphertext products retain actual scales. constant_cache retains prepared scalar and monomial plaintexts for reuse across evaluation calls. retain_ntt=False selects coefficient-domain results for callers that compose Bootstrap without NTT-retaining Eager operations. FullSlotBootstrap creates this owner internally; custom compositions pass it to linear, polynomial, and periodic-reduction evaluators.

Attributes

Name	Type	Default/value
engine	Engine
constant_cache	MutableMapping[object, object] | None	None
retain_ntt	bool	True

target_scales

property

target_scales: tuple[float, ...]

Return the selected per-depth arithmetic scales.

The default selection is computed backward from the terminal default scale using $s_d^2/M_d=s_{d+1}$. for_input follows an actual input scale forward over the requested depths. scaled_targets instead describes coefficient accumulators multiplied by unscaled basis nodes.

for_input

method

def for_input(ciphertext: Ciphertext, required_depths: int) -> BootstrapArithmetic: ...

Follow $s_{d+1}=s_d^2/M_d$ from the input's actual scale.

Polynomial basis nodes use this recurrence through their required depths; coefficient products may select a different output scale.

scaled_targets

method

def scaled_targets(factor: float) -> BootstrapArithmetic: ...

Use a common scale factor for polynomial coefficient accumulators.

plaintext_scale

method

def plaintext_scale(input_scale: float, depth: int) -> float: ...

Choose $s_{d+1}{M}_d/\mathrm{\Delta }$ for a plaintext product and rescale.

multiply_by_monomial

method

def multiply_by_monomial(ciphertext: Ciphertext, exponent: int) -> Ciphertext: ...

Return $X^{e}c(X)mod(X^N+1)$ without changing CKKS metadata.

align_depths

method

def align_depths(lhs: Ciphertext, rhs: Ciphertext) -> tuple[Ciphertext, Ciphertext]: ...

Advance the shallower value to the deeper value's Q depth.

advance_depth

method

def advance_depth(ciphertext: Ciphertext) -> Ciphertext: ...

Advance one Q group and return at the next target scale.

multiply_relinearize_rescale

method

def multiply_relinearize_rescale(lhs: Ciphertext, rhs: Ciphertext, *, relinearization_key: RelinearizationKey) -> Ciphertext: ...

Return relinearized $c_{lhs}{c}_{rhs}$ after one Q rescale.

multiply_scalar

method

def multiply_scalar(ciphertext: Ciphertext, scalar: complex) -> Ciphertext: ...

Multiply by one encoded scalar, rescale, and return target scale.

weighted_scalar_sum

method

def weighted_scalar_sum(terms: Sequence[tuple[Ciphertext, complex]]) -> Ciphertext: ...

Return $\sum _j{a}_j{c}_j$ with one shared coefficient rescale.

add_scalar

method

def add_scalar(ciphertext: Ciphertext, scalar: complex) -> Ciphertext: ...

Add a scalar without changing depth, scale, domain, or RNS basis.

BinaryDecompositionChebyshevEvaluator

class View source

BinaryDecompositionChebyshevEvaluator(skip_near_zero: float = 0.0)

Evaluate a Chebyshev series through shared doubling identities.

The evaluator builds only basis elements required by nonzero terms. It recursively uses

$$T_{2n}(x)=2T_n(x{)}^2-1,T_{2n+1}(x)=2T_n(x)T_{n+1}(x)-T_1(x),$$

caching every required $T_n$ and each depth-specific $T_1$ for one call. Basis-node scales follow the input scale through each product and group rescale; the advanced copies of $T_1$ use that same recurrence. Coefficient products built from basis values at one depth are accumulated before one shared rescale; the resulting depth groups are then aligned and added. This keeps intermediate inputs near the approximation's bounded domain and exposes the critical-path depth.

The coordinate, tensor axes, arithmetic-state preconditions, functional behavior, per-product transitions, output depth, active prime_ids, and depth-dependent scale schedule match BalancedPowerEvaluator; only the polynomial basis and multiplication DAG differ.

Attributes

Name	Type	Default/value
skip_near_zero	float	0.0

operation_inventory

method

def operation_inventory(polynomial: PolynomialApproximation) -> dict[str, int]: ...

Return multiplying operations executed by evaluate.

Alignment includes operand advancement within odd recurrences, the shared depth chain for $T_1=x$, and advancement between coefficient depth groups. rescale_operations counts one coefficient rescale per occupied basis depth rather than one per coefficient product.

required_depths

method

def required_depths(polynomial: PolynomialApproximation) -> int: ...

Count the deepest required recurrence plus coefficient product.

evaluate

method

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

Build required $T_n(x)$ values, align term depths, and sum them.

Terms at or below skip_near_zero are omitted. As in the power evaluator, the constant-only case deliberately consumes one depth so its execution agrees with required_depths. The method is functional and returns a two-component coefficient-domain standard-RNS Q value at the arithmetic owner's target scale.

ChebyshevInterpolator

class View source

ChebyshevInterpolator(degree: int, error_samples: int = 8193)

Fit a degree-limited Chebyshev series at first-kind nodes.

degree controls both the number of interpolation nodes and the highest returned term $T_d$. error_samples controls only the dense grid used to report max_error; that sampled value is not a proof of the uniform error between grid points.

Attributes

Name	Type	Default/value
degree	int
error_samples	int	8193

approximate

method

def approximate(function: Callable[[np.ndarray], np.ndarray], *, domain: tuple[float, float]=(-1.0, 1.0), name: str='polynomial') -> PolynomialApproximation: ...

Interpolate after mapping physical $t\in [a,b]$ to $x\in [-1,1]$.

If domain=(a, b), first-kind nodes $x_j$ are evaluated physically at

$$t_j=a+(x_j+1)(b-a)/2.$$

Coefficients in the returned object are functions of normalized $x$, not directly of physical $t$. The consuming evaluator must therefore normalize its ciphertext to $x$ and account for any depth spent on that affine map.

max_error is measured on error_samples equally spaced normalized coordinates after fitting. Approximation runs on CPU binary64/complex128 arrays and returns no encrypted tensor.

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.

DiagonalBSGSEvaluator

class View source

DiagonalBSGSEvaluator(baby_step: int, hoist_baby_rotations: bool = True, aggregate_groups: bool = False, baby_steps_by_transform: Mapping[str, int] | None = None)

Evaluate the same diagonal map with a BSGS rotation schedule.

An offset $k$ is split as $k=g+b$, where $g$ is a multiple of baby_step. Baby rotations of the input are shared across giant groups. Each group's diagonals are shifted to compensate for the final giant rotation, its plaintext products are accumulated and rescaled, and then the group result is giant-rotated into place.

Algebraically, each term is unchanged because

$${\mathrm{Rot}}_g({\mathrm{Rot}}_b(x)\odot {\mathrm{Rot}}_{-g}(d_{g+b}))={\mathrm{Rot}}_{g+b}(x)\odot d_{g+b}.$$

Thus direct and BSGS evaluators implement the same map and depth/scale/state transition; different grouping and CKKS rounding need not produce bit-identical residues. hoist_baby_rotations uses engine.rotate_many_with_keys only when direct baby-step keys are available. Compact power-of-two inventories compose rotations through the private key-aware evaluation helper. baby_steps_by_transform may override the fallback step for named compiled transforms, keeping a stage-specific BSGS schedule inspectable without changing the transform representation. aggregate_groups applies all giant-group plaintext rows to the shared baby ciphertexts in one represented RNS operation; it changes execution grouping but not the BSGS partition or arithmetic.

Attributes

Name	Type	Default/value
baby_step	int
hoist_baby_rotations	bool	True
aggregate_groups	bool	False
baby_steps_by_transform	Mapping[str, int] | None	None

required_depths

method

def required_depths(transform: Any) -> int: ...

Return the single rescale consumed by one BSGS stage.

baby_step_for

method

def baby_step_for(transform: DiagonalLinearTransform) -> int: ...

Return the caller-selected BSGS step for one compiled transform.

required_rotation_offsets

method

def required_rotation_offsets(transform: Any) -> tuple[int, ...]: ...

Return the union of nonzero baby and giant rotations.

evaluate

method

def evaluate(arithmetic: BootstrapArithmetic, ciphertext: Ciphertext, transform: Any, *, rotation_keys: RotationKeySet, rotate: Callable[[Ciphertext, int], Ciphertext], encode_diagonal: Callable[..., Plaintext]) -> Ciphertext: ...

Execute shared baby rotations, group sums, and giant rotations.

Each giant-group accumulator is rescaled before its giant rotation, so all group results have common depth and actual scale

$${\mathrm{\Delta }}_{\mathrm{o}\mathrm{u}\mathrm{t}}=\frac{{\mathrm{\Delta }}_{\mathrm{i}\mathrm{n}}{\mathrm{\Delta }}_p}{M_d}.$$

Here Delta_p is the selected diagonal plaintext scale and M_d is the dropped Q-group product.

The input and output tensor/state requirements are identical to DirectDiagonalEvaluator; evaluation is functional.

DiagonalLinearTransform

class View source

DiagonalLinearTransform(diagonals: Mapping[int, ArrayLike], slots: int, name: str = 'diagonal_linear_transform')

An immutable cyclic-diagonal linear map over packed CKKS slots.

The map is

$$y=\sum _k{d}_k\odot {\mathrm{Rot}}_k(x).$$

Each stored diagonal is a CPU complex128 NumPy vector with shape [slot]; reference accepts and returns the same one-dimensional shape. This object contains no choice of execution algorithm. The matching evaluator independently decides whether to use direct diagonals, BSGS, hoisting, distribution, or a user implementation. Offsets are cyclic modulo $S$; duplicate representatives such as -1 and slots - 1 are combined by normalized_diagonals.

Attributes

Name	Type	Default/value
diagonals	Mapping[int, ArrayLike]
slots	int
name	str	'diagonal_linear_transform'

normalized_diagonals

method

def normalized_diagonals() -> dict[int, np.ndarray]: ...

Map every offset to $kmodS$ and combine equal rotations.

The stored arrays remain immutable. A new mapping is returned because two input offsets can normalize to the same cyclic key and must then be added elementwise. Returned vectors retain shape [slot].

reference

method

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

Apply $L(x)=\sum _k{d}_k\odot {\mathrm{Rot}}_k(x)$ in NumPy.

values must have shape [slot]. The returned CPU complex128 array has shape [slot]. This plaintext oracle does not encode, rescale, consume depths, or model CKKS error.

DirectDiagonalEvaluator

class View source

DirectDiagonalEvaluator()

Evaluate each cyclic diagonal independently, then rescale once.

For every nonzero offset this strategy rotates the input, multiplies it by the corresponding encoded diagonal, and adds the product to an accumulator. All products have pending scale ${\mathrm{\Delta }}_{\mathrm{i}\mathrm{n}}{\mathrm{\Delta }}_p$, so the sum is rescaled only after every diagonal has been accumulated. It is simple but can require one direct rotation key for every nonzero diagonal.

The input is a two-component coefficient-domain standard-RNS Q ciphertext with data axes [component, *batch, limb, coefficient], ring extent $N$, and one homogeneous prime_ids tuple. If the removed Q group has product $M_d$, the functional result has the same component and batch axes, depth $\ell +1$, scale

$${\mathrm{\Delta }}_{\mathrm{o}\mathrm{u}\mathrm{t}}=\frac{{\mathrm{\Delta }}_{\mathrm{i}\mathrm{n}}{\mathrm{\Delta }}_p}{M_d},$$

and Q prime_ids with the complete group removed. The output remains in coefficient domain with standard residues; temporary diagonal plaintexts are NTT-domain Montgomery RNS. The result does not alias an input.

required_depths

method

def required_depths(transform: Any) -> int: ...

Return the single rescale consumed by one diagonal stage.

required_rotation_offsets

method

def required_rotation_offsets(transform: Any) -> tuple[int, ...]: ...

Return direct non-zero diagonal offsets.

evaluate

method

def evaluate(arithmetic: BootstrapArithmetic, ciphertext: Ciphertext, transform: Any, *, rotation_keys: RotationKeySet, rotate: Callable[[Ciphertext, int], Ciphertext], encode_diagonal: Callable[..., Plaintext]) -> Ciphertext: ...

Apply $L(x)$ directly and consume one Q rescale depth.

The input must match the engine's slot count. For offset zero the input is reused directly; every other term requests one rotation through the supplied rotation-key strategy. Each diagonal is encoded at the input depth, multiplied into its rotated ciphertext, and accumulated at pending scale. A single final rescale advances the output by one depth.

Raises

• TypeError: If transform uses another stage representation.
• ValueError: If slot count or diagonal content is invalid.

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.

FullSlotBootstrap

class View source

FullSlotBootstrap(engine: Engine, *, coeffs_to_slots_compiler: Any, coeffs_to_slots_evaluator: Any, modular_reduction: Any, slots_to_coeffs_compiler: Any, slots_to_coeffs_evaluator: Any, modulus_raise_target_depth: int=0, retain_diagonals: bool=False, retain_constants: bool=False, batch_modular_branches: bool=False)

Full-slot refresh callable with prepared transforms and replaceable components.

Construction configures transform compilers/evaluators and modular reduction for one engine. Calling the object executes the visible full-slot algorithm with one validated evaluator-only key inventory.

retain_diagonals keeps operation-ready transform plaintexts between calls. retain_constants similarly keeps the scalar, entry, and monomial constants used by the circuit between calls. If batch_modular_branches is true, the real and imaginary periodic reductions share one dense branch-batch execution before being unpacked.

input_depth selects the penultimate Q group. The entry rescale reaches the ordinary terminal basis, which this composition uses for centered ModRaise. It reserves no private CKKS depth.

Let ${\mathrm{\Delta }}_0$ be engine.config.default_scale, $q_b$ the structural Q-basis product, $S=N/2$, $C$ the unscaled CoeffsToSlots map, and $T$ the unscaled SlotsToCoeffs map with $T(C(a))=Sa$. Let $B$ be the modular reduction's input_bound and let $D$ be fused_input_divisor, equal to $B$ when input normalization is fused and $1$ otherwise. The constructor compiles numerical transform factors

$${\alpha }_C=\frac{{\mathrm{\Delta }}_0}{q_{b}D},{\alpha }_T=\frac{q_b}{2{\mathrm{\Delta }}_0}.$$

If $a$ is the coefficient-coordinate value represented by the centered ModRaised ciphertext at metadata scale ${\mathrm{\Delta }}_0$, define

$$w=\frac{{\mathrm{\Delta }}_0}{S{q}_b}C(a),r_{\mathrm{R}}=2\mathrm{Re}(w),r_{\mathrm{I}}=2\mathrm{Im}(w).$$

The encrypted transform and explicit $1/S$ multiplication produce $w/D$. Conjugation and monomial correction expose either raw $r_{\mathrm{R}},r_{\mathrm{I}}$ when $D=1$, or normalized $r_{\mathrm{R}}/B,r_{\mathrm{I}}/B$ when $D=B$. With

$$\rho (r)=\frac{\sin (\pi r)}{\pi },$$

the idealized nonlinear and inverse-transform portion is

$$a_{\mathrm{o}\mathrm{u}\mathrm{t}}={\alpha }_{T}T(\rho (r_{\mathrm{R}})+i\rho (r_{\mathrm{I}})).$$

Polynomial approximation, CKKS arithmetic, and key switching perturb this idealized map. The caller must establish the reducer's raw-coordinate precondition $|r_{\mathrm{R}}|,|r_{\mathrm{I}}|\le B$; encrypted execution cannot inspect it.

required_rotations

property

required_rotations: tuple[int, ...]

Return normalized signed ${\mathrm{Rot}}_r$ steps for both maps.

key_steps

method

def key_steps(strategy: str='direct') -> tuple[int, ...]: ...

Return the rotation-key inventory for one composition strategy.

direct returns every logical transform step as a direct key. power_of_two returns the deduplicated signed-power steps whose compositions cover those transforms. The latter therefore describes actual inventory entries, not the original transform offsets.

Raises

• ValueError: If strategy is not direct or power_of_two.

evaluation_key_requirements

method

def evaluation_key_requirements(rotation_strategy: str='power_of_two') -> EvaluationKeyRequirements: ...

Return all evaluator capabilities for one rotation strategy.

Rotation steps come from key_steps. Conjugation is always required by full-slot reconstruction; relinearization is required only when the selected modular reduction declares ciphertext products. The result contains no key tensors or key-generation policy.

create_rotation_keys

method

def create_rotation_keys(secret_key: SecretKey, *, rotation_strategy: str='power_of_two') -> RotationKeySet: ...

Generate only the selected bootstrap rotation-key inventory.

secret_key is consumed by primitive engine key generation and is not stored in the returned set. Relinearization and conjugation keys are intentionally not created here; applications construct those separate capabilities and assemble an EvaluationKeySet.

cached_diagonal_bytes

property

cached_diagonal_bytes: int

Return encoded diagonal tensor bytes retained by this evaluator.

cached_constant_bytes

property

cached_constant_bytes: int

Return tensor bytes retained for scalar and structural constants.

clear_cache

method

def clear_cache() -> None: ...

Release prepared constants, encoded diagonals, and arithmetic tables.

HornerPowerEvaluator

class View source

HornerPowerEvaluator()

Evaluate a power polynomial by a corrected depth-aware Horner chain.

For degree $d\ge 1$, evaluation starts with

$$r=c_{d}x+c_{d-1}$$

and then applies $r\leftarrow rx+c_i$ for $i=d-2,\dots ,0$. Thus the leading term remains $c_d{x}^d$. A depth-specific copy of $x$ is advanced once per ciphertext product and retained for that iteration, avoiding repeated advancement from the entry depth. The evaluator does not omit zero coefficients: the declared algebraic degree and execution schedule are stable properties of the coefficient tuple.

A constant polynomial deliberately consumes one depth by multiplying the input by zero. A linear polynomial consumes one coefficient-multiplication depth and requires no relinearization key. Degree $d\ge 2$ consumes exactly $d$ depths and requires one compatible QP relinearization key.

required_depths

method

def required_depths(polynomial: PolynomialApproximation) -> int: ...

Return one depth for constants or the declared power degree.

operation_inventory

method

def operation_inventory(polynomial: PolynomialApproximation) -> dict[str, int]: ...

Return the corrected-Horner multiplication inventory.

evaluate

method

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

Evaluate a power polynomial with a corrected Horner recurrence.

The input must be a complete two-component coefficient-domain, standard-RNS Q ciphertext at its recorded actual scale. The method validates all context, key, scale, and available-depth requirements before allocating encrypted temporaries. The functional output is in the same arithmetic state at ciphertext.depth + required_depths(polynomial) and the arithmetic owner's target scale.

PatersonStockmeyerPowerEvaluator

class View source

PatersonStockmeyerPowerEvaluator(baby_step: int)

Evaluate a power polynomial with one fixed baby-step size.

baby_step=k is part of the evaluator identity and is never selected at runtime. The evaluator writes

$$p(x)=\sum _g{q}_g(x)(x^k{)}^g,\mathrm{deg}{q}_g<k.$$

Balanced shared powers $x,\dots ,x^k$ are constructed once. Baby powers are advanced to one common depth before coefficient multiplication, then the $q_g$ values are combined by Horner evaluation in $x^k$. Depth-specific copies of shared powers are cached for the invocation. If the highest group is a constant, its first giant step is the plaintext product $c_d{x}^k$, not an encrypted-zero seed followed by a ciphertext product.

Basis powers follow the input's actual scale recurrence. Coefficient accumulators use a common multiple of those scales chosen so the final product reaches the requested output scale. This keeps additions coherent without changing the polynomial's coefficients or its input coordinate.

The declared coefficient tuple, including zero entries, fixes the schedule. baby_step therefore controls a reproducible DAG rather than an unreliable degree-only estimate.

Attributes

Name	Type	Default/value
baby_step	int

required_depths

method

def required_depths(polynomial: PolynomialApproximation) -> int: ...

Return the critical-path depth cost for this fixed k.

operation_inventory

method

def operation_inventory(polynomial: PolynomialApproximation) -> dict[str, int]: ...

Return ciphertext, coefficient, and alignment counts.

evaluate

method

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

Evaluate with the fixed baby/giant schedule and depth caches.

PolynomialApproximation

class View source

PolynomialApproximation(basis: PolynomialBasis, coefficients: tuple[complex, ...], domain: tuple[float, float] = (-1.0, 1.0), name: str = 'polynomial', max_error: float | None = None)

An immutable polynomial produced independently of its evaluation DAG.

The coefficient convention is ascending degree. For basis="power",

$$p(x)=\sum _{n=0}^d{a}_n{x}^n,$$

while basis="chebyshev" means

$$p(x)=\sum _{n=0}^d{a}_n{T}_n(x),T_0(x)=1,T_1(x)=x.$$

domain=(a, b) records the physical interval used to design the approximation. The evaluator input is nevertheless normalized $x$ unless (a, b) == (-1, 1); the caller owns the affine map.

Attributes

• basis: Basis in which coefficients are expressed.
• coefficients: Ascending coefficients: entry i multiplies either $x^i$ or $T_i(x)$.
• domain: Plaintext interval on which the approximation was designed.
• name: Human-readable diagnostic name.
• max_error: Optional sampled or certified approximation error.

Attributes

Name	Type	Default/value
basis	PolynomialBasis
coefficients	tuple[complex, ...]
domain	tuple[float, float]	(-1.0, 1.0)
name	str	'polynomial'
max_error	float | None	None

degree

property

degree: int

Return the algebraic degree including trailing zero entries.

evaluate_plaintext

method

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

Evaluate $p(x)$ elementwise without homomorphic arithmetic.

values may have any NumPy-broadcastable shape, which is preserved in the output. They are coordinates in the polynomial's basis domain. For a Chebyshev approximation created on a physical interval other than $[-1,1]$, callers must first apply the same affine normalization described by the approximator. This method is a numerical oracle; it does not model CKKS rounding or depth consumption.

Radix2FourierTransformCompiler

class View source

Radix2FourierTransformCompiler(stage_count: int, imaginary_unit_correction: bool = False)

Synthesize CKKS basis transforms from radix-2 butterflies.

Let $C$ be the unscaled coeffs_to_slots map and $T$ the unscaled slots_to_coeffs map in the engine's cyclotomic slot order. The compiler's convention is

$$T(C(x))=Sx.$$

Consequently a plaintext round trip uses forward scale=1 and inverse scale=1/S. The supplied scale multiplies the numerical map; it is not a CKKS metadata scale and does not change the diagonal plaintext encoding scale selected later by the evaluator.

stage_count controls only algebraic layer collapse. A smaller value consumes fewer CKKS depths but materializes more diagonals in each stage; a larger value retains sparse butterflies but spends more depths. The choice of direct, BSGS, distributed, or custom execution remains independent.

Attributes

Name	Type	Default/value
stage_count	int
imaginary_unit_correction	bool	False

compile

method

def compile(*, slots: int, direction: TransformDirection, generator: int, scale: float=1.0) -> tuple[DiagonalLinearTransform, ...]: ...

Compile $C$ or $T$ into ordered cyclic-diagonal stages.

Compilation proceeds in four steps:

1. validate the cyclotomic slot orbit and build root tables;
2. construct one three-diagonal transform per radix-2 layer;
3. compose adjacent layers according to stage_count;
4. fold scale into the first forward stage or final inverse stage so the normalization is applied once in the complete transform.

slots is $S$ and every stored diagonal has axes [slot]. generator must enumerate $S$ distinct odd cyclotomic exponents modulo $4S$. direction chooses $C$ or $T$. Returns immutable CPU complex128 stages in online execution order; compilation performs no encryption.