fhelium.experimental.bootstrap.full_slot

Full-slot CKKS bootstrap composition configured for one Engine.

The composition accepts and returns two-component, coefficient-domain, standard-residue Q RNS values. Temporary NTT/Montgomery values are confined to ordinary engine arithmetic. Ciphertext payload axes are [component, *batch, limb, coefficient]; linear-map diagonal payloads use [slot] with $S=N/2$.

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, modulus_raising: ModulusRaising | None=None, source_depth: int | None=None, input_depth: int | None=None, input_scale: float | None=None, target_scales: Sequence[float] | None=None, modup_method: Literal['exact', 'crt', 'normalized_crt']='exact', normalization_stage: int | None=None, retain_diagonals: bool=False, compress_diagonals: bool=True, message_domain: Literal['complex', 'real']='complex', 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 primitive key references selected from an application-owned inventory.

compress_diagonals=True selects the minimum lossless contiguous storage of each encoded NTT diagonal. retain_diagonals keeps these materials 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.

source_depth selects the Q suffix consumed by modulus raising. input_depth may equal it or its preceding group; the latter entry multiplies by an integer and rescales into the source basis. Defaults use the terminal basis and its preceding group. modulus_raising selects centered extension or an intermediate-secret construction.

Let ${\mathrm{\Delta }}_0$ be input_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 followed by multiplication by $1/S$ produces $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}})).$$

message_domain="complex" uses this two-branch map. For real-valued slot messages, message_domain="real" requires the generator-5 radix-2 STC compiler and evaluates only $r_{\mathrm{R}}$. With $H=\mathrm{diag}(1/2,1,\dots ,1)$, it reconstructs $a_{\mathrm{o}\mathrm{u}\mathrm{t}}=z+\bar{z}$ from $z={\alpha }_{T}T(H\rho (r_{\mathrm{R}}))$. The first STC stage absorbs $H$ into a new diagonal plan. The final conjugation/addition preserves depth and actual scale; branch batching applies only to the complex composition.

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.

remaining_depth

property

remaining_depth: int

Return Q depth transitions available after this Bootstrap.

refresh_window

property

refresh_window: int

Return transitions from the refreshed output to the next entry depth.

required_rotations

property

required_rotations: tuple[int, ...]

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

key_steps

method

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

Return the standalone rotation basis requested by a generation strategy.

signed_power_of_two stores the signed-power components needed to compose the transform rotations. signed_power_of_two_with_baby_steps adds direct keys for every BSGS baby step. all_required stores a direct key for every required transform rotation.

An existing inventory can satisfy signed-power requests with more direct paths. all_required still requires direct transform keys; signed_power_of_two_with_baby_steps requires direct baby keys. Baby decomposition sharing additionally requires compatible stored layouts and the evaluator's hoist_baby_rotations choice.

Parameters

• rotation_key_strategy: Rotation-key inventory to enumerate.

Raises

• ValueError: If the rotation-key strategy is not supported.

evaluation_key_requirements

method

def evaluation_key_requirements(rotation_key_strategy: str='all_required') -> EvaluationKeyRequirements: ...

Return the capability description of the standalone rotation basis.

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. Reuse from a shared inventory can replace composed paths with available direct keys.

create_evaluation_keys

method

def create_evaluation_keys(secret_key: SecretKey, *, into: EvaluationKeySet | None=None, rotation_key_strategy: str='all_required', device: torch.device | str | None=None) -> EvaluationKeySet: ...

Populate a shared inventory with evaluation keys for this composition.

The default all_required strategy provisions direct transform keys. Existing paths satisfying the selected direct-key requirements are reused by reference. Missing rotations are generated from a consumer-wide layout choice accounting for shared steps and additional key storage. Relinearization and conjugation capabilities are provisioned through the engine's primitive factories. The returned inventory is into when supplied; other members remain available to their consumers. The caller supplies keys for one secret relation and mathematical parameter context.

cached_diagonal_bytes

property

cached_diagonal_bytes: int

Return encoded diagonal bytes retained by ordinary evaluations.

cached_constant_bytes

property

cached_constant_bytes: int

Return scalar and monomial bytes retained by ordinary evaluations.

clear_cache

method

def clear_cache() -> None: ...

Release this callable's ordinary caches.

PreparedBootstrapCore objects own separate dictionaries and retain their materials independently. Close Graphs using ordinary evaluations first.

entry

method

def entry(ciphertext: Ciphertext) -> tuple[Ciphertext, float]: ...

Return source-basis coordinates and their output scale compensation.

For entry group product M, integer k=max(1, ceil(MDelta0/Delta_in)) gives Delta_b=kDelta_in/M after nearest rescale. Direct source-basis entry instead uses Delta_b=Delta_in without this transition. The returned payload is interpreted at Delta0; tau=Delta_b/Delta0 restores the original message coordinate in finish. The input is preserved.

core

method

def core(coordinate: Ciphertext, *, evaluation_keys: EvaluationKeySet) -> Ciphertext: ...

Evaluate the normalized core with the ordinary retention controls.

coordinate is the source-basis result of entry. Use prepare_core to bind retained materials before repeated execution or CUDA capture.

finish

method

def finish(core_result: Ciphertext, entry_scale_ratio: float) -> Ciphertext: ...

Return a fresh envelope with scale Delta_out * entry_scale_ratio.

Payload storage is shared with core_result. Its original metadata remains unchanged, including when it is a borrowed Graph output.

prepare

method

def prepare(example_input: Ciphertext, *, evaluation_keys: EvaluationKeySet) -> PreparedBootstrap: ...

Bind a complete refresh for Eager execution or callable Compile.

Preparation follows the existing core material discovery once. Newly encoded materials consume the encoding RNG; later calls and Compile capture only read those materials. The prototype payload is not retained.

prepare_core

method

def prepare_core(coordinate: Ciphertext, *, evaluation_keys: EvaluationKeySet) -> PreparedBootstrapCore: ...

Bind and prepare a core for the post-entry input's state and device.

Preparation executes the core once to discover and retain its diagonal, scalar and structural materials. It performs real arithmetic and advances the encoding RNG for new materials. The temporary output and prototype payload are released; only the signature, selected component objects, key values and prepared materials are retained. Call before CUDA capture.