`fhelium.eager`

Construct and execute CKKS operations with runtime-owned resources.

Engine accepts a CKKS configuration and creates device-local arithmetic and random resources when a call first selects each device. Source factories use PyTorch's default device unless the caller supplies device. The Engine owns key lifecycles and does not copy key material across devices unless automatic replication is enabled. Evaluator calls dispatch from operand placement, update public metadata, and invoke registered Tensor operations. Program compilation and execution belong to Backend and its Compile callers.

`Engine`

class View source

python

Engine(ckks_config: CkksConfig | Preset | dict[str, object] | None=None, *, ntt_backend: str | None=None, rns_dtype: torch.dtype | None=None, rng_seed: int | None=None, rng_nonce: int | None=None, allow_automatic_key_generation: bool=True, allow_automatic_key_replication: bool=False)

Own eager CKKS configuration and per-device execution resources.

Cheon-Kim-Kim-Song (CKKS) ciphertexts encode approximate complex slot values as polynomials. A two-component ciphertext (CT2) has phase $c_{0} + c_{1} s$ ; a three-component ciphertext (CT3) has phase $c_{0} + c_{1} s + c_{2} s^{2}$ for secret polynomial $s$ . The residue number system (RNS) stores a polynomial row modulo each active ciphertext prime in Q. QP adds the special P primes used by hybrid key switching. The number-theoretic transform (NTT) turns negacyclic polynomial products into pointwise products. Montgomery representation stores residue $x_{i}$ as $x_{i} R_{i} mod q_{i}$ so modular products avoid division. Hybrid key switching groups Q rows into digits, extends each digit to QP, multiplies it by evaluation-key components, and removes P. Each plaintext and ciphertext records its own actual scale $Δ$ , which maps encoded integers to approximate slot values.

Source factories use PyTorch's default device when the caller omits device. Tensor-consuming operations dispatch from operand placement and do not move operands implicitly. A boundary device= authorizes movement of that boundary's public value. Key material is not copied between devices unless the caller places it there or enables automatic key replication. Each used device owns its arithmetic tables, random stream, direct-dispatch entries, and key bindings.

`rotation_key_steps`

method

python

def rotation_key_steps(step: int) -> tuple[int, ...]: ...

Describe a rotation's key path without generating or moving keys.

A direct installed key takes precedence. When automatic generation is enabled, a missing direct key is represented by its normalized step. Otherwise the path is decomposed using installed rotation steps only. A zero rotation requires no key.

`config`

property

python

config: CkksConfig

Return the Engine's fixed CKKS configuration.

`galois_generator`

property

python

galois_generator: int

Return the Engine's Galois generator.

`ntt_backend_name`

method

python

def ntt_backend_name(device: torch.device | str) -> str: ...

Return the NTT backend selected for one concrete device.

`ring_dimension`

property

python

ring_dimension: int

Return the Engine's polynomial ring dimension.

`depth0_qp_prime_ids`

property

python

depth0_qp_prime_ids: tuple[int, ...]

Return the depth-zero QP prime identifiers.

`key_digit_count`

property

python

key_digit_count: int

Return the hybrid key-switch digit count.

`dtype`

property

python

dtype: torch.dtype

Return the Engine's RNS storage dtype.

`max_depth`

property

python

max_depth: int

Return the greatest public CKKS depth in this Engine.

`depth_remaining`

method

python

def depth_remaining(value: Ciphertext | Plaintext | int) -> int: ...

Return how many public rescale transitions remain.

`num_slots`

property

python

num_slots: int

Return the number of complex slots in one CKKS polynomial.

`create_secret_key`

method

python

def create_secret_key(*, modulus_basis: Literal['Q', 'QP']='QP', device: torch.device | str | None=None) -> SecretKey: ...

Sample the secret polynomial and materialize its RNS transforms.

The key generator samples ternary coefficients $s_{j} \in {- 1, 0, 1}$ , reduces them modulo every depth-zero Q row and optional P row, and stores $NTT (s) R$ in Montgomery form. This factory delegates to CkksKeyGenerator.create_secret_key.

`create_public_key`

method

python

def create_public_key(secret_key: SecretKey, *, modulus_basis: Literal['Q', 'QP']='Q', device: torch.device | str | None=None) -> PublicKey: ...

Generate a public-key pair for a secret polynomial.

For a sampled uniform polynomial $a$ and error $e$ , the returned $(k_{0}, k_{1}) = (- a s + e, a)$ satisfies $k_{0} + k_{1} s = e$ modulo each selected depth-zero Q or QP prime. Components are stored in NTT/Montgomery form by CkksKeyGenerator.create_public_key.

`create_key_switch_key`

method

python

def create_key_switch_key(source_secret_key: SecretKey, destination_secret_key: SecretKey, *, uniform_component_by_key_digit: torch.Tensor | None=None, device: torch.device | str | None=None) -> KeySwitchKey: ...

Generate hybrid-RNS material from one secret relation to another.

For source and destination secrets $s_{s r c}$ and $s_{d s t}$ , key digit $d$ satisfies $k_{d, 0} + k_{d, 1} s_{d s t} = P s_{s r c} + e_{d}$ on that digit's embedded source rows, where $P$ is the product of special primes. The generator returns [digit, component=2, QP row, NTT index] data in NTT/Montgomery form.

`create_relinearization_key`

method

python

def create_relinearization_key(secret_key: SecretKey, *, device: torch.device | str | None=None) -> RelinearizationKey: ...

Generate key-switch material from $s^{2}$ to $s$ .

This is the evaluation key used to replace the $c_{2} s^{2}$ phase term of a CT3 product by two CT2 correction components. The QP key digits are generated by CkksKeyGenerator.create_relinearization_key in NTT/Montgomery form.

`create_rotation_key`

method

python

def create_rotation_key(rotation_step: int, secret_key: SecretKey, *, device: torch.device | str | None=None) -> RotationKey: ...

Generate key-switch material from $σ_{g} (s)$ to $s$ .

The signed slot displacement is normalized modulo the slot count and mapped to an odd Galois element $g$ . The ring automorphism $σ_{g} : X \mapsto X^{g}$ rotates the slots while changing the secret relation; the returned QP key digits restore the original relation.

`create_conjugation_key`

method

python

def create_conjugation_key(secret_key: SecretKey, *, device: torch.device | str | None=None) -> ConjugationKey: ...

Generate key-switch material from $σ_{2 N - 1} (s)$ to $s$ .

The automorphism $X \mapsto X^{- 1}$ gives complex conjugation under the CKKS embedding. CkksKeyGenerator.create_conjugation_key returns the QP NTT/Montgomery key digits needed to restore the original secret relation.

`plaintext`

method

python

def plaintext(message: Sequence[object] | torch.Tensor | complex | float | int, *, depth: int=0, scale: float | None=None, device: torch.device | str | None=None) -> Plaintext: ...

Wrap ordered public slots with planned CKKS depth and actual scale.

This method stores the message tensor without applying the CKKS embedding. encode later maps the slots to a polynomial. scale defaults to the configuration's planning value but is stored on this plaintext as its own actual scale.

`encode`

method

python

def encode(message: Sequence[object] | torch.Tensor | complex | float | int, *, depth: int=0, scale: float | None=None, device: torch.device | str | None=None) -> Plaintext: ...

Encode ordered CKKS slots as scaled integer coefficients.

For the configured embedding $σ$ , message $m$ , and this value's actual scale $Δ$ , the returned polynomial is $a = RandRound (Δ σ^{- 1} (m))$ . The method dispatches ckks.EncodeOp to native-ckks-encode and returns coefficient-domain integer_coefficients state at depth; no RNS prime rows exist yet.

`prepare_compressed_plaintext`

method

python

def prepare_compressed_plaintext(message: Sequence[object] | torch.Tensor | complex | float | int, *, depth: int=0, scale: float | None=None, modulus_basis: Literal['Q', 'QP']='Q', polynomial_domain: Literal['coefficient', 'ntt']='ntt', device: torch.device | str | None=None) -> CompressedPlaintext: ...

Prepare compact Montgomery plaintext from one period of slots.

The last message axis is repeated semantically to fill N/2 slots. For U=2r (at least four with generator 3) and R=N/U, p(X)=a(X^R) is encoded using only U coefficients and U values per prime row. Random rounding uses the full-ring coefficient word positions and advances by N words per batch item. Coefficient output stores U coefficients with zero implicit rows in strided-sparse layout. NTT output stores U values in contiguous layout, each representing R repeated evaluations. Depth, selected Q/QP rows and actual scale are retained. The reduced FFT can differ in floating-point roundoff from encoding a fully expanded message near quantization thresholds.

`integer_coefficients_to_rns`

method

python

def integer_coefficients_to_rns(plaintext: Plaintext, *, modulus_basis: Literal['Q', 'QP']='Q') -> Plaintext: ...

Reduce an integer plaintext polynomial into active prime rows.

At plaintext depth $ℓ$ , every coefficient $a_{j}$ becomes $a_{j} mod q_{i}$ in each active Q row and, for QP, $a_{j} mod p_{i}$ in each special P row. ckks.IntegerCoefficientsToRnsOp dispatches to native-ckks-integer-coefficients-to-rns. The result is coefficient-domain standard RNS with unchanged depth and actual scale.

`prepare_plaintext_for_addition`

method

python

def prepare_plaintext_for_addition(plaintext: Plaintext, *, modulus_basis: Literal['Q', 'QP']='Q', polynomial_domain: PolynomialDomain='coefficient') -> Plaintext: ...

Prepare a plaintext for modular addition to component zero.

The method first issues ckks.IntegerCoefficientsToRnsOp as needed, then rns.StandardToMontgomeryOp. polynomial_domain="ntt" also transforms the prepared polynomial for direct addition to an NTT/Montgomery ciphertext. Message, depth, actual scale, and requested Q or QP rows are unchanged.

`prepare_plaintext_for_multiplication`

method

python

def prepare_plaintext_for_multiplication(plaintext: Plaintext, *, modulus_basis: Literal['Q', 'QP']='Q') -> Plaintext: ...

Prepare a plaintext for pointwise NTT ciphertext multiplication.

After addition preparation, the method dispatches ntt.CoefficientMontgomeryToNttMontgomeryOp. Every active-prime polynomial is transformed while retaining its Montgomery factor. Depth and plaintext actual scale remain unchanged for the eventual rns.MultiplyPlaintextOp.

`prepare_public_operand`

method

python

def prepare_public_operand(public: object, ciphertext: Ciphertext, *, operation: Literal['add', 'multiply'], source_role: Literal['message', 'plaintext', 'static'], scale_mode: Literal['runtime_plaintext_scale', 'default_scale', 'ciphertext_scale']) -> Plaintext: ...

Prepare a typed public value for encrypted addition or multiplication.

Addition selects the ciphertext actual scale so the prepared plaintext can be added to component zero. Multiplication retains a supplied plaintext scale or uses the configured default for a message/static value; its scale later multiplies the ciphertext scale. This Eager method composes ckks.EncodeOp and registered RNS/NTT transitions.

`decode`

method

python

def decode(plaintext: Plaintext, *, is_real: bool=False, device: torch.device | str | None=None) -> torch.Tensor: ...

Decode coefficient data into the configured CKKS slot order.

For coefficient polynomial $a$ at actual scale $Δ$ , the result is $σ (a / Δ)$ , restricted to the configured number of slots. is_real takes the real part after embedding. The method dispatches ckks.DecodeOp to native-ckks-decode; RNS plaintexts must first be reconstructed to bounded coefficient data.

`encrypt`

method

python

def encrypt(plaintext: Plaintext, public_key: PublicKey | None=None, *, device: torch.device | str | None=None, output_domain: PolynomialDomain='coefficient') -> Ciphertext: ...

Encrypt an integer coefficient plaintext under a public key.

For public key $(k_{0}, k_{1})$ , sampled binary $v$ , and errors $e_{0}, e_{1}$ , ckks.EncryptOp computes $(c_{0}, c_{1}) = (k_{0} v + a + e_{0}, k_{1} v + e_{1})$ modulo each active prime. The native-ckks-encrypt implementation returns a CT2 Q or QP ciphertext with the plaintext's depth and actual scale. output_domain selects coefficient/standard or NTT/Montgomery output. NTT output transforms the error-and-message terms and adds them directly to the public-key products.

`decrypt`

method

python

def decrypt(ciphertext: Ciphertext, secret_key: SecretKey | None=None, *, device: torch.device | str | None=None) -> Plaintext: ...

Evaluate the ciphertext phase and reconstruct bounded coefficients.

For CT2 the phase is $c_{0} + c_{1} s$ ; for CT3 it is $c_{0} + c_{1} s + c_{2} s^{2}$ , evaluated in every active prime. Both component counts may use coefficient/standard or NTT/Montgomery input. NTT input is summed before one inverse transform; coefficient input transforms each nonconstant term for multiplication by the matching secret power. The returned approximate-coefficient plaintext retains depth and actual scale.

`encrypt_message`

method

python

def encrypt_message(message: Sequence[object] | torch.Tensor | complex | float | int, public_key: PublicKey | None=None, *, depth: int=0, scale: float | None=None, device: torch.device | str | None=None, output_domain: PolynomialDomain='coefficient') -> Ciphertext: ...

Encode slots and encrypt the resulting polynomial.

This composes encode and encrypt: it forms $a = RandRound (Δ σ^{- 1} (m))$ , then encrypts $a$ as a randomized CT2 value through ckks.EncodeOp and ckks.EncryptOp. The output records the selected depth, actual scale, public-key basis, and coefficient/standard representation.

`decrypt_message`

method

python

def decrypt_message(ciphertext: Ciphertext, secret_key: SecretKey | None=None, *, is_real: bool=False, device: torch.device | str | None=None) -> torch.Tensor: ...

Decrypt a ciphertext phase and decode its CKKS slots.

This composes ckks.DecryptOp with ckks.DecodeOp. It reconstructs an approximate coefficient polynomial $a$ , then returns $σ (a / Δ)$ using the ciphertext's actual scale $Δ$ . is_real projects the decoded slots to their real parts.

`zero_plaintext_like`

method

python

def zero_plaintext_like(plaintext: Plaintext) -> Plaintext: ...
def zero_plaintext_like(plaintext: CompressedPlaintext) -> CompressedPlaintext: ...

Create independent zero storage in the input's represented state.

Compact explicit entries and sparse implicit rows are both zeroed. Depth, scale, layout, prime rows, domain and residue form are retained.

`encrypt_zero_like`

method

python

def encrypt_zero_like(ciphertext: Ciphertext, public_key: PublicKey | None=None) -> Ciphertext: ...

Return a randomized encryption of zero in a ciphertext's represented state.

The method encodes and encrypts a zero slot vector at the reference depth and actual scale, then applies the same registered NTT transition if the reference is in NTT/Montgomery form. The result decrypts to encryption noise around zero and has matching Q or QP rows and representation.

`install_evaluation_key`

method

python

def install_evaluation_key(symbol: str, key: KeySwitchKey) -> None: ...

Install one validated evaluation key under an inventory name.

`remove_evaluation_key`

method

python

def remove_evaluation_key(symbol: str) -> None: ...

Remove one installed evaluation-key binding if present.

`secret_key`

property

python

secret_key: SecretKey

Return the installed secret key, generating one when permitted.

`set_secret_key`

method

python

def set_secret_key(key: SecretKey | None) -> None: ...

Install or remove the secret key and invalidate dependent keys.

`public_key`

property

python

public_key: PublicKey

Return the installed public key, generating one when absent.

`set_public_key`

method

python

def set_public_key(key: PublicKey | None) -> None: ...

Install or remove the public encryption key.

`relinearization_key`

property

python

relinearization_key: RelinearizationKey

Return installed relinearization material, generating it when absent.

`set_relinearization_key`

method

python

def set_relinearization_key(key: RelinearizationKey | None) -> None: ...

Install or remove relinearization material.

`rotation_keys`

property

python

rotation_keys: dict[int, RotationKey]

Return the normalized rotation-key map.

`rotation_key`

method

python

def rotation_key(step: int) -> RotationKey: ...

Return rotation material for step, generating it when permitted.

`set_rotation_key`

method

python

def set_rotation_key(key: RotationKey) -> None: ...

Install a key under its normalized self-described rotation step.

`conjugation_key`

property

python

conjugation_key: ConjugationKey | None

Return installed conjugation material, if any.

`set_conjugation_key`

method

python

def set_conjugation_key(key: ConjugationKey | None) -> None: ...

Install or remove conjugation material.

`validate_ciphertext`

method

python

def validate_ciphertext(value: Ciphertext) -> None: ...

Validate a ciphertext against this runtime's complete RNS layout.

`validate_public_key`

method

python

def validate_public_key(key: PublicKey) -> None: ...

Validate public encryption material against this runtime.

`validate_secret_key`

method

python

def validate_secret_key(key: SecretKey) -> None: ...

Validate secret-key storage and context against this runtime.

`validate_key_switch_key`

method

python

def validate_key_switch_key(key: KeySwitchKey) -> None: ...

Validate key-switch material against this runtime.

`reconstruct_q_coefficients`

method

python

def reconstruct_q_coefficients(residues: torch.Tensor, ciphertext: Ciphertext) -> torch.Tensor: ...

Reconstruct centered coefficients from all active Q rows.

The active Q basis represents each coefficient modulo its product $M$ . Mixed-radix reconstruction returns its centered representative in $(- M / 2, M / 2]$ . This utility delegates to the decryption reconstruction routine and does not decode slots or divide by the CKKS scale.

`add`

method

python

def add(lhs: Ciphertext, rhs: Ciphertext, *, inplace: bool=False) -> Ciphertext: ...

Add ciphertext components modulo every active prime.

Inputs have matching component, row, polynomial-domain, residue, and scale state, with residues in each prime's standard storage range. For each component $j$ , row $q_{i}$ , and stored position, $c_{j}^{'} = c_{j}^{(l h s)} + c_{j}^{(r h s)} (\mod q_{i})$ . The method dispatches rns.AddStandardOp to native-rns-linear. Component count, depth, prime rows, polynomial domain, residue representation, and actual scale are preserved; inplace=True writes the same result into lhs.

`add_`

method

python

def add_(lhs: Ciphertext, rhs: Ciphertext) -> Ciphertext: ...

Add $r h s$ componentwise into $l h s$ and return $l h s$ .

This is the in-place form of add and dispatches rns.AddStandardOp. All represented state is preserved.

`add_scalar`

method

python

def add_scalar(ciphertext: Ciphertext, scalar: int | float, *, scalar_scale: float | None=None) -> Ciphertext: ...

Add a quantized real scalar to the constant coefficient of $c_{0}$ .

For scalar $u$ and scalar scale $δ$ , ckks.AddScalarOp samples $k = RandRound (u δ)$ and adds $k mod q_{i}$ to component zero's constant coefficient in every active row. The ciphertext actual scale $Δ$ stays unchanged, so its decoded increment is $k / Δ$ ; $δ = Δ$ approximates addition by $u$ .

`sum_ciphertexts`

method

python

def sum_ciphertexts(ciphertexts: Sequence[Ciphertext]) -> Ciphertext: ...

Sum a non-empty sequence by repeated modular ciphertext addition.

The method clones the first value and repeatedly dispatches rns.AddStandardOp. Mathematically each output component is $\sum_{t} c_{j}^{(t)} (\mod q_{i})$ . Compatible depth, rows, representation, component count, and actual scale are preserved.

`sum_ciphertext_batch`

method

python

def sum_ciphertext_batch(batch: Ciphertext, *, dim: int=0) -> Ciphertext: ...

Reduce one batch axis by modular ciphertext addition.

rns.SumStandardBatchOp computes, for every component $j$ , prime row $q_{i}$ , and coefficient, the sum of the selected axis with each partial sum reduced to $[0, q_{i})$ : $c_{j}^{'} = \sum_{k} c_{j}^{(k)} mod q_{i}$ . The operation equals any association order of standard modular additions. Pairing changes evaluation order but not modular addition. The selected batch axis is removed; CKKS depth, actual scale, rows, and representation remain unchanged.

`subtract`

method

python

def subtract(lhs: Ciphertext, rhs: Ciphertext, *, inplace: bool=False) -> Ciphertext: ...

Subtract ciphertext components modulo every active prime.

Inputs have matching component, row, polynomial-domain, residue, and scale state, with residues in each prime's standard storage range. For each component $j$ and row $q_{i}$ , $c_{j}^{'} = c_{j}^{(l h s)} - c_{j}^{(r h s)} (\mod q_{i})$ . The method dispatches rns.SubtractStandardOp to native-rns-linear and preserves depth, scale, prime rows, component count, polynomial domain, and residue representation. inplace=True writes into lhs.

`subtract_`

method

python

def subtract_(lhs: Ciphertext, rhs: Ciphertext) -> Ciphertext: ...

Subtract $r h s$ componentwise from $l h s$ and return $l h s$ .

This in-place form dispatches rns.SubtractStandardOp and retains the ciphertext's represented state.

`negate`

method

python

def negate(value: Ciphertext, *, inplace: bool=False) -> Ciphertext: ...

Negate every ciphertext component modulo its active primes.

Residues may describe coefficient polynomials or NTT values but must be in each prime's standard storage range. For each component and prime row, rns.NegateStandardOp computes $c_{j}^{'} = - c_{j} (\mod q_{i})$ through native-rns-linear. The result decrypts to the additive inverse and preserves depth, actual scale, rows, component count, and representation.

`negate_`

method

python

def negate_(value: Ciphertext) -> Ciphertext: ...

Negate every component of $v a l u e$ in place and return it.

This is the in-place rns.NegateStandardOp path; all represented state is unchanged.

`coefficient_domain_to_ntt_domain`

method

python

def coefficient_domain_to_ntt_domain(value: Ciphertext, *, inplace: bool=False) -> Ciphertext: ...
def coefficient_domain_to_ntt_domain(value: Plaintext, *, inplace: bool=False) -> Plaintext: ...

Apply the forward negacyclic NTT to every RNS polynomial.

For ciphertext standard residues, each component dispatches ntt.CoefficientStandardToNttMontgomeryOp and stores $NTT (c_{j}) R$ . For plaintext Montgomery residues, the method dispatches ntt.CoefficientMontgomeryToNttMontgomeryOp. Depth, prime rows, basis, component shape, and actual scale are preserved; the result state is NTT/Montgomery.

`coefficient_domain_to_ntt_domain_`

method

python

def coefficient_domain_to_ntt_domain_(value: Ciphertext) -> Ciphertext: ...
def coefficient_domain_to_ntt_domain_(value: Plaintext) -> Plaintext: ...

Transform $v a l u e$ to NTT/Montgomery form in place.

This dispatches the same registered NTT operation as coefficient_domain_to_ntt_domain and returns the input object with unchanged depth, prime rows, and actual scale.

`ntt_domain_to_coefficient_domain`

method

python

def ntt_domain_to_coefficient_domain(value: Ciphertext, *, inplace: bool=False) -> Ciphertext: ...
def ntt_domain_to_coefficient_domain(value: Plaintext, *, inplace: bool=False) -> Plaintext: ...

Apply the inverse negacyclic NTT to every RNS polynomial.

Ciphertext components dispatch ntt.NttMontgomeryToCoefficientStandardOp and end in coefficient/standard form. A plaintext dispatches ntt.NttMontgomeryToCoefficientMontgomeryOp and ends in coefficient/Montgomery form. The ring element, depth, Q or QP rows, component shape, and actual scale are preserved.

`ntt_domain_to_coefficient_domain_`

method

python

def ntt_domain_to_coefficient_domain_(value: Ciphertext) -> Ciphertext: ...
def ntt_domain_to_coefficient_domain_(value: Plaintext) -> Plaintext: ...

Transform $v a l u e$ from NTT form in place and return it.

The method dispatches the ciphertext or plaintext inverse NTT operation used by ntt_domain_to_coefficient_domain; it does not alter depth, rows, or actual scale.

`standard_residues_to_montgomery_residues`

method

python

def standard_residues_to_montgomery_residues(plaintext: Plaintext, *, inplace: bool=False) -> Plaintext: ...
def standard_residues_to_montgomery_residues(plaintext: CompressedPlaintext, *, inplace: bool=False) -> CompressedPlaintext: ...

Multiply each coefficient residue by its Montgomery radix.

rns.StandardToMontgomeryOp maps $x_{i}$ to $x_{i} R_{i} mod q_{i}$ through native-rns-transition. The plaintext remains in coefficient domain with unchanged polynomial, Q or QP rows, depth, and actual scale.

`standard_residues_to_montgomery_residues_`

method

python

def standard_residues_to_montgomery_residues_(plaintext: Plaintext) -> Plaintext: ...
def standard_residues_to_montgomery_residues_(plaintext: CompressedPlaintext) -> CompressedPlaintext: ...

Convert plaintext rows to Montgomery representation in place.

This dispatches rns.StandardToMontgomeryOp and returns the input plaintext; its polynomial, depth, prime rows, and actual scale do not change.

`montgomery_residues_to_standard_residues`

method

python

def montgomery_residues_to_standard_residues(plaintext: Plaintext, *, inplace: bool=False) -> Plaintext: ...
def montgomery_residues_to_standard_residues(plaintext: CompressedPlaintext, *, inplace: bool=False) -> CompressedPlaintext: ...

Remove the Montgomery factor from each coefficient residue.

rns.MontgomeryToStandardOp maps $x_{i} R_{i}$ to $x_{i} mod q_{i}$ through native-rns-transition. The plaintext polynomial, coefficient domain, Q or QP rows, depth, and actual scale are preserved.

`montgomery_residues_to_standard_residues_`

method

python

def montgomery_residues_to_standard_residues_(plaintext: Plaintext) -> Plaintext: ...
def montgomery_residues_to_standard_residues_(plaintext: CompressedPlaintext) -> CompressedPlaintext: ...

Convert plaintext rows to standard residues in place.

This dispatches rns.MontgomeryToStandardOp and returns the input plaintext without changing its polynomial, depth, rows, or actual scale.

`rescale_divisor`

method

python

def rescale_divisor(*, depth: int) -> int: ...

Return the active Q divisor removed at depth.

rescale_to_next_depth divides each ciphertext coefficient and its actual scale by the product of the Q rows assigned to this transition.

`rescale_output_scale`

method

python

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

Compute the per-value actual scale after one rescale.

For input scale $Δ$ and depth-group product $M_{d}$ , the result is $Δ^{'} = Δ / M_{d}$ . This helper performs no residue arithmetic.

`rescale_to_next_depth`

method

python

def rescale_to_next_depth(value: Ciphertext, *, rounding: Literal['nearest', 'floor']='nearest', inplace: bool=False) -> Ciphertext: ...

Divide by the current Q depth-group modulus and consume one depth.

A depth group may contain multiple RNS primes. The operation removes every row in that group, advances depth once, and divides the value's actual scale by the complete group product.

`rescale_to_next_depth_`

method

python

def rescale_to_next_depth_(value: Ciphertext, *, rounding: Literal['nearest', 'floor']='nearest') -> Ciphertext: ...

Rescale $v a l u e$ by its leading Q group in place and return it.

The underlying row operations remove every prime in the group; the public value advances one depth and divides scale by the group product.

`mod_switch_to_depth`

method

python

def mod_switch_to_depth(value: Ciphertext, target_depth: int, *, inplace: bool=False) -> Ciphertext: ...

Discard Q rows until target_depth without quotient scaling.

If the source rows are $(q_{ℓ}, \dots, q_{L})$ , the result retains the suffix $(q_{t}, \dots, q_{L})$ ; P rows are retained for QP values. Surviving residues and actual scale $Δ$ are unchanged. Eager performs this tensor-row selection directly, with the same mathematical transition represented in IR by rns.RestrictDepthOp/ckks.ModSwitchOp.

`mod_switch_to_next_depth`

method

python

def mod_switch_to_next_depth(value: Ciphertext, *, inplace: bool=False) -> Ciphertext: ...

Discard the next Q depth group and advance one depth.

This calls mod_switch_to_depth for $ℓ + 1$ . Unlike rescaling, it does not divide coefficients or actual scale and does not dispatch a Backend operation in Eager.

`mod_switch_to_next_depth_`

method

python

def mod_switch_to_next_depth_(value: Ciphertext) -> Ciphertext: ...

Discard the next Q depth group in place and return $v a l u e$ .

The actual scale and surviving residues are unchanged; only depth and row metadata advance.

`mod_switch_to_depth_`

method

python

def mod_switch_to_depth_(value: Ciphertext, target_depth: int) -> Ciphertext: ...

Restrict $v a l u e$ in place to target_depth and return it.

The method performs direct row selection, preserving actual scale and every surviving residue.

`reinterpret_at_scale`

method

python

def reinterpret_at_scale(value: Ciphertext, target_scale: float, *, max_relative_change: float | None=None, inplace: bool=False) -> Ciphertext: ...

Replace actual-scale metadata without arithmetic.

The payload, depth, prime rows, polynomial domain, and Montgomery state are copied unchanged while scale $Δ$ becomes target_scale $Δ^{'}$ . Decoding therefore interprets the same coefficients as $x / Δ^{'}$ . Eager performs the metadata change directly; IR represents it with ckks.ReinterpretScaleOp/rns.ReinterpretScaleOp.

`reinterpret_at_scale_`

method

python

def reinterpret_at_scale_(value: Ciphertext, target_scale: float, *, max_relative_change: float | None=None) -> Ciphertext: ...

Replace $v a l u e$ 's actual-scale metadata in place and return it.

No residues or rows change. max_relative_change limits the permitted ratio between the old and new scale.

`multiply`

method

python

def multiply(lhs: Ciphertext, rhs: Ciphertext) -> Ciphertext: ...

Multiply two CT2 ciphertexts into one CT3 ciphertext.

Both inputs are two-component NTT/Montgomery ciphertexts with matching depth and active prime rows. For $a = (a_{0}, a_{1})$ and $b = (b_{0}, b_{1})$ , ckks.MultiplyOp computes $(a_{0} b_{0}, a_{0} b_{1} + a_{1} b_{0}, a_{1} b_{1})$ in each active-prime negacyclic ring. The native-ct2-convolution implementation consumes NTT/Montgomery inputs. Depth and rows are retained, and actual scale becomes $Δ_{a} Δ_{b}$ ; relinearization and rescaling remain separate calls.

`multiply_scalar`

method

python

def multiply_scalar(ciphertext: Ciphertext, scalar: int | float, *, scalar_scale: float | None=None) -> Ciphertext: ...

Multiply a ciphertext by a stochastically quantized real scalar.

For scalar $u$ and scalar scale $δ$ , ckks.MultiplyScalarOp samples $k = RandRound (u δ)$ and multiplies every component by $k$ modulo all active primes. The result actual scale is $Δ δ$ , so it represents multiplication by approximately $u$ . Depth, rows, component count, and representation are preserved.

`multiply_integer_scalar`

method

python

def multiply_integer_scalar(ciphertext: Ciphertext, scalar: int) -> Ciphertext: ...

Multiply every ciphertext component by an integer $k$ .

ckks.MultiplyIntegerScalarOp computes $c_{j}^{'} = k c_{j}$ modulo each active prime through native-ckks-scalar-arithmetic. Because $k$ is unscaled, actual scale, depth, rows, component count, and representation do not change.

`add_plaintext`

method

python

def add_plaintext(ciphertext: Ciphertext, plaintext: Plaintext | CompressedPlaintext, *, inplace: bool=False) -> Ciphertext: ...

Add a prepared plaintext polynomial to ciphertext component zero.

For ordinary RNS plaintext $p$ , rns.AddPlaintextOp computes $(c_{0} + p, c_{1}, \dots)$ through native-plaintext-arithmetic. Compressed input dispatches ckks.AddCompressedPlaintextOp and expands the same values logically. Matching depth, prime rows, and actual scale are required; output state and later components are preserved.

`add_plaintext_`

method

python

def add_plaintext_(ciphertext: Ciphertext, plaintext: Plaintext | CompressedPlaintext) -> Ciphertext: ...

Add prepared plaintext $p$ into ciphertext component zero in place.

This is the in-place ordinary/compressed plaintext addition path and returns the input ciphertext with unchanged represented state.

`multiply_plaintext`

method

python

def multiply_plaintext(ciphertext: Ciphertext, plaintext: Plaintext | CompressedPlaintext, *, inplace: bool=False) -> Ciphertext: ...

Multiply each ciphertext component by a prepared plaintext.

For NTT/Montgomery plaintext $p$ , rns.MultiplyPlaintextOp computes $c_{j}^{'} = c_{j} p$ pointwise modulo every active prime. Compressed input dispatches ckks.MultiplyCompressedPlaintextOp for the same expanded polynomial. Depth, rows, and component count remain; actual scale becomes $Δ_{c} Δ_{p}$ , with no implicit rescale.

`multiply_plaintext_`

method

python

def multiply_plaintext_(ciphertext: Ciphertext, plaintext: Plaintext | CompressedPlaintext) -> Ciphertext: ...

Replace a ciphertext by its prepared-plaintext product.

The method uses the ordinary or compressed registered multiplication path, updates actual scale to $Δ_{c} Δ_{p}$ , and returns the input object.

`sum_plaintext_products`

method

python

def sum_plaintext_products(ciphertexts: Sequence[Ciphertext], plaintexts: Sequence[Plaintext | CompressedPlaintext]) -> Ciphertext: ...

Compute a sum of prepared-plaintext products in one operation.

For equally sized sequences, the result is

y = \sum_{t = 0}^{T - 1} c_{t} p_{t} .

Every ciphertext must have the same NTT/Montgomery Q or QP state, depth, active rows, component shape, and actual scale. Every prepared plaintext must match those rows and have a common actual scale. The result preserves the ciphertext state and has scale $Δ_{c} Δ_{p}$ . The registered RNS implementation may fuse the products and modular accumulation without materializing each product.

`sum_plaintext_product_groups`

method

python

def sum_plaintext_product_groups(ciphertexts: Sequence[Ciphertext], plaintext_groups: Sequence[Sequence[Plaintext | CompressedPlaintext]]) -> Ciphertext: ...

Apply several prepared-plaintext rows to shared ciphertext terms.

For $T$ ciphertexts and a caller-supplied $G \times T$ matrix of prepared plaintexts, batch result $g$ is

y_{g} = \sum_{t = 0}^{T - 1} c_{t} p_{g, t} .

Every operand follows sum_plaintext_products' matching NTT/Montgomery state, depth, row, shape, and scale requirements. Each result has scale $Δ_{c} Δ_{p}$ and preserves the ciphertext state. The output inserts the group axis as its first batch axis, so Ciphertext.unbind_batch recovers separate results. The operation executes the supplied rectangular matrix; it does not choose how a caller partitions a linear transform. A Backend implementation may reuse a ciphertext load across plaintext rows without stacking the inputs or materializing individual products.

`sum_rotated_plaintext_product_groups`

method

python

def sum_rotated_plaintext_product_groups(ciphertext: Ciphertext, rotation_keys: Sequence[RotationKey | None], plaintext_groups: Sequence[Sequence[Plaintext | CompressedPlaintext]]) -> Ciphertext: ...

Apply prepared-plaintext rows to one direct rotation group.

A None key denotes the unrotated input; each other entry supplies its own signed rotation step. For $T$ entries and a caller-supplied $G \times T$ plaintext matrix, output batch $g$ is

y_{g} = \sum_{t = 0}^{T - 1} p_{g, t} {Rot}_{b_{t}} (c) .

The input is coefficient/standard Q CT2. Every direct rotation completes hybrid key switching and ModDown before its NTT/Montgomery plaintext product. The output inserts a first batch axis of length $G$ , remains at the input depth, and has scale $Δ_{c} Δ_{p}$ . The caller supplies the group membership and key inventory; Backend execution may reuse digit preparation and ciphertext loads within these supplied groups.

`relinearize`

method

python

def relinearize(value: Ciphertext, key: RelinearizationKey | None=None, *, output_domain: PolynomialDomain='coefficient') -> Ciphertext: ...

Map a CT3 product phase back to two components.

The input is a three-component NTT/Montgomery product. For phase $c_{0} + c_{1} s + c_{2} s^{2}$ , the relinearization key switches the $c_{2} s^{2}$ term into corrections $(d_{0}, d_{1})$ . ckks.RelinearizeOp dispatches to native-relinearize-streaming and returns $(c_{0} + d_{0}, c_{1} + d_{1})$ . output_domain="ntt" retains $c_{0}, c_{1}$ and the corrections in NTT/Montgomery form; the default returns coefficient/standard Q rows. Depth and actual scale are unchanged.

`switch_key`

method

python

def switch_key(value: Ciphertext, key: KeySwitchKey, *, output_domain: PolynomialDomain='coefficient') -> Ciphertext: ...

Switch a CT2 ciphertext from a source secret to a destination secret.

The input is a two-component coefficient/standard Q ciphertext. For $c_{0} + c_{1} s_{s r c}$ , hybrid key switching maps the second term to corrections $(d_{0}, d_{1})$ under $s_{d s t}$ , producing $(c_{0} + d_{0}, d_{1})$ . ckks.SwitchKeyOp dispatches the whole operation through one streaming hybrid-RNS implementation, which shares its QP accumulator across decomposition digits. output_domain="ntt" combines $c_{0}$ with its correction before the forward transform. Depth, Q rows, actual scale, and CT2 shape are preserved.

`rotate_with_key`

method

python

def rotate_with_key(value: Ciphertext, key: RotationKey, *, output_domain: PolynomialDomain='coefficient') -> Ciphertext: ...

Apply the slot displacement carried by a direct rotation key.

The input is a two-component coefficient/standard or NTT/Montgomery Q ciphertext. The call dispatches ckks.RotateOp to native-rotate-streaming. Its Galois automorphism $σ_{g} : X \mapsto X^{g}$ rotates encoded slots and hybrid key switching restores secret $s$ from $σ_{g} (s)$ . CT2 shape, depth, active Q rows and actual scale are preserved. output_domain="ntt" requests NTT/Montgomery output. For NTT input and output, the automorphism and unchanged component-zero contribution remain in NTT form while only component one is inverted for key switching.

`rotate_by_step`

method

python

def rotate_by_step(value: Ciphertext, rotation_step: int) -> Ciphertext: ...

Cyclically rotate CKKS slots by a signed displacement.

The step is normalized modulo the slot count. A zero step clones the input; an installed direct key issues one ckks.RotateOp and a decomposed key path issues successive rotations whose displacements sum modulo the slot count. Each stage preserves CT2 shape, depth, Q rows, and actual scale.

`rotate_many_by_steps`

method

python

def rotate_many_by_steps(value: Ciphertext, rotation_steps: Sequence[int], *, use_hoisting: bool=True) -> list[Ciphertext]: ...

Return the requested cyclic slot rotations in caller order.

Each normalized step denotes the same mathematical result as rotate_by_step. Direct single-key rotations may be grouped into one ckks.RotateManyOp dispatched to native-rotate-many-hoisted; hoisting shares digit decomposition and Q-to-QP basis extension but does not regroup or alter outputs. Multi-key paths remain successive ckks.RotateOp calls.

`rotate_many_with_keys`

method

python

def rotate_many_with_keys(value: Ciphertext, keys: Sequence[RotationKey], *, use_hoisting: bool=True, output_domain: PolynomialDomain='coefficient') -> list[Ciphertext]: ...

Apply each supplied rotation key and preserve its output order.

With hoisting, one ckks.RotateManyOp shares key-switch preparation while each result equals the corresponding independent ckks.RotateOp. Without hoisting, keys dispatch separately. Every output keeps CT2 shape, depth, active Q rows and actual scale. output_domain="ntt" returns NTT/Montgomery results, equivalent to transforming each coefficient result. The hoisted implementation retains Q evaluations during ModDown; independent rotations combine c0 with the coefficient correction before its forward NTT.

`rotate_by_step_`

method

python

def rotate_by_step_(value: Ciphertext, rotation_step: int) -> Ciphertext: ...

Replace $v a l u e$ with its cyclic slot rotation and return it.

The method uses rotate_by_step and therefore dispatches the required ckks.RotateOp sequence while preserving depth, rows, and actual scale.

`conjugate`

method

python

def conjugate(value: Ciphertext, key: ConjugationKey | None=None, *, output_domain: PolynomialDomain='coefficient') -> Ciphertext: ...

Apply complex conjugation to every CKKS slot.

The input is a two-component coefficient/standard Q ciphertext. The method dispatches ckks.ConjugateOp to a whole-operation implementation. It applies $g = 2 N - 1$ , which substitutes $X \mapsto X^{- 1}$ , then uses the streaming hybrid-RNS key-switch path to return from $σ_{g} (s)$ to $s$ . output_domain selects coefficient/standard or NTT/Montgomery output. CT2 shape, depth, Q rows, and actual scale remain unchanged.

fhelium.eager ​

Engine ​

rotation_key_steps ​

config ​

galois_generator ​

ntt_backend_name ​

ring_dimension ​

depth0_qp_prime_ids ​

key_digit_count ​

dtype ​

max_depth ​

depth_remaining ​

num_slots ​

create_secret_key ​

create_public_key ​

create_key_switch_key ​

create_relinearization_key ​

create_rotation_key ​

create_conjugation_key ​

plaintext ​

encode ​

prepare_compressed_plaintext ​

integer_coefficients_to_rns ​

prepare_plaintext_for_addition ​

prepare_plaintext_for_multiplication ​

prepare_public_operand ​

decode ​

encrypt ​

decrypt ​

encrypt_message ​

decrypt_message ​

zero_plaintext_like ​

encrypt_zero_like ​

install_evaluation_key ​

remove_evaluation_key ​

secret_key ​

set_secret_key ​

public_key ​

set_public_key ​

relinearization_key ​

set_relinearization_key ​

rotation_keys ​

rotation_key ​

set_rotation_key ​

conjugation_key ​

set_conjugation_key ​

validate_ciphertext ​

validate_public_key ​

validate_secret_key ​

validate_key_switch_key ​

reconstruct_q_coefficients ​

add ​

add_ ​

add_scalar ​

sum_ciphertexts ​

sum_ciphertext_batch ​

subtract ​

subtract_ ​

negate ​

negate_ ​

coefficient_domain_to_ntt_domain ​

coefficient_domain_to_ntt_domain_ ​

ntt_domain_to_coefficient_domain ​

ntt_domain_to_coefficient_domain_ ​

standard_residues_to_montgomery_residues ​

standard_residues_to_montgomery_residues_ ​

montgomery_residues_to_standard_residues ​

montgomery_residues_to_standard_residues_ ​

rescale_divisor ​

rescale_output_scale ​

rescale_to_next_depth ​

rescale_to_next_depth_ ​

mod_switch_to_depth ​

mod_switch_to_next_depth ​

mod_switch_to_next_depth_ ​

mod_switch_to_depth_ ​

reinterpret_at_scale ​

reinterpret_at_scale_ ​

multiply ​

multiply_scalar ​

`fhelium.eager`

`Engine`

`rotation_key_steps`

`config`

`galois_generator`

`ntt_backend_name`

`ring_dimension`

`depth0_qp_prime_ids`

`key_digit_count`

`dtype`

`max_depth`

`depth_remaining`

`num_slots`

`create_secret_key`

`create_public_key`

`create_key_switch_key`

`create_relinearization_key`

`create_rotation_key`

`create_conjugation_key`

`plaintext`

`encode`

`prepare_compressed_plaintext`

`integer_coefficients_to_rns`

`prepare_plaintext_for_addition`

`prepare_plaintext_for_multiplication`

`prepare_public_operand`

`decode`

`encrypt`

`decrypt`

`encrypt_message`

`decrypt_message`

`zero_plaintext_like`

`encrypt_zero_like`

`install_evaluation_key`

`remove_evaluation_key`

`secret_key`

`set_secret_key`

`public_key`

`set_public_key`

`relinearization_key`

`set_relinearization_key`

`rotation_keys`

`rotation_key`

`set_rotation_key`

`conjugation_key`

`set_conjugation_key`

`validate_ciphertext`

`validate_public_key`

`validate_secret_key`

`validate_key_switch_key`

`reconstruct_q_coefficients`

`add`

`add_`

`add_scalar`

`sum_ciphertexts`

`sum_ciphertext_batch`

`subtract`

`subtract_`

`negate`

`negate_`

`coefficient_domain_to_ntt_domain`

`coefficient_domain_to_ntt_domain_`

`ntt_domain_to_coefficient_domain`

`ntt_domain_to_coefficient_domain_`

`standard_residues_to_montgomery_residues`

`standard_residues_to_montgomery_residues_`

`montgomery_residues_to_standard_residues`

`montgomery_residues_to_standard_residues_`

`rescale_divisor`

`rescale_output_scale`

`rescale_to_next_depth`

`rescale_to_next_depth_`

`mod_switch_to_depth`

`mod_switch_to_next_depth`

`mod_switch_to_next_depth_`

`mod_switch_to_depth_`

`reinterpret_at_scale`

`reinterpret_at_scale_`

`multiply`

`multiply_scalar`