FHElium

fhelium.backend.ckks ​

CKKS codecs, cryptography, arithmetic, and key-switch composition.

Numerical implementations consume Tensor operands and supplied sampling handles. Data-provision APIs construct parameter tables and cryptographic key values.

RANDOM_STREAM_RESOURCE_KIND ​

constant View source

python
RANDOM_STREAM_RESOURCE_KIND = 'ckks-random-stream'

RANDOM_STREAM_RESOURCE_SYMBOL ​

constant View source

python
RANDOM_STREAM_RESOURCE_SYMBOL = 'ckks-random-stream'

CkksDeviceResources ​

class View source

python
CkksDeviceResources(*, config: CkksConfig, device: str | torch.device, rns_layout: RnsLayout | None=None, ntt_backend: str | None=None, rng_seed: int | None=None, rng_nonce: int | None=None, rns_dtype: torch.dtype | None=None)

Own lazily constructed CKKS resources for one concrete device.

The default RNS layout follows the configuration's Q depth groups and hybrid decomposition. Callers can supply an existing layout for reuse.

rns_context ​

property

python
rns_context: RnsContext

Return the device's RNS arithmetic context.

ntt_context ​

property

python
ntt_context: NttContext

Return the NTT context composed with this device's RNS context.

rng ​

property

python
rng: Csprng

Return the stateful random stream assigned to this device.

key_generation ​

property

python
key_generation: KeyGenerationResource

Return the resources used to generate keys on this device.

periodic_encode_operands ​

method

python
def periodic_encode_operands(period: int, depth: int, basis: str): ...

Return compact tables and the existing live rounding stream.

encode_operands ​

method

python
def encode_operands() -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]: ...

Return the inverse-embedding permutation, twister, and live rounding state.

decode_operands ​

method

python
def decode_operands() -> tuple[torch.Tensor, torch.Tensor]: ...

Return the coefficient-embedding permutation and skewer.

key_switch_operands ​

method

python
def key_switch_operands(depth: int, *, moddown_rounding: str='nearest', modup_method: str='exact', rescale: bool=False, rescale_rounding: str='nearest', output_domain: str='coefficient', key_prime_ids: tuple[int, ...] | None=None, digit_prime_ids: tuple[tuple[int, ...], ...] | None=None) -> tuple[dict[str, torch.Tensor], dict[str, object]]: ...

Prepare Tensor views and digit ranges for a hybrid key switch.

rotation_sum_tables ​

method

python
def rotation_sum_tables(depth: int, *, rescale: bool=False, rounding: str='nearest', modup_method: str='exact', key_prime_ids: tuple[int, ...] | None=None, digit_prime_ids: tuple[tuple[int, ...], ...] | None=None) -> RotationSumTables: ...

Prepare and retain deterministic rotation-sum quotient tables.

modulus_raise_operands ​

method

python
def modulus_raise_operands(source_depth: int, target_depth: int) -> tuple[dict[str, torch.Tensor], dict[str, object]]: ...

Prepare centered-extension operands on this configuration's Q chain.

encapsulated_modulus_raise_operands ​

method

python
def encapsulated_modulus_raise_operands(source_depth: int, target_depth: int, low_p_moduli: tuple[int, ...], return_prime: int, return_p_moduli: tuple[int, ...], *, rounding: str='nearest') -> tuple[dict[str, torch.Tensor], dict[str, object]]: ...

Prepare low-switch, centered extension and return-switch operands.

rescale_operands ​

method

python
def rescale_operands(row_count: int, drop_count: int, *, include_p: bool=False, input_domain: str='coefficient') -> tuple[dict[str, torch.Tensor], dict[str, object]]: ...

Prepare quotient and transform tables for one rescale group.

reconstruction_operands ​

method

python
def reconstruction_operands(depth: int) -> tuple[torch.Tensor, ...]: ...

Prepare Q parameters and centered mixed-radix reconstruction tables.

bindings ​

property

python
bindings: ResourceBindings

Return this device's bindable random-stream execution resource.

materialize ​

method

python
def materialize(requirements: tuple[ResourceRequirement, ...], /) -> ResourceBindings: ...

Return all constructible missing resources in one batch.

CkksKeyGenerator ​

class View source

python
CkksKeyGenerator()

Construct CKKS keys from caller-supplied device resources and secret relations.

Key payloads use configured integral dtype and prime-row order. Secret-key data is [limb, ntt_index]; public keys are [key_component, limb, ntt_index]; key-switch keys are [key_digit, key_component, limb, ntt_index]. Returned keys are always NTT/Montgomery/lazy at depth zero in the stated Q or QP basis and own their payload storage. Local digit_index is resolved to stable key_digit_index before key tensor indexing.

convert_secret_key ​

method

python
def convert_secret_key(resources: KeyGenerationResource, target: KeyGenerationResource, secret_key: SecretKey) -> SecretKey: ...

Re-express the centered secret polynomial in another RNS basis.

Inverse NTT, centered CRT extension and target NTT preserve the polynomial modulo the target primes. The original source basis defines its centered representative. Destination storage and Montgomery radix belong to target; no sampling or input mutation occurs.

prepare_secret_key ​

method

python
def prepare_secret_key(resources: KeyGenerationResource, coefficients: torch.Tensor, *, modulus_basis: ModulusBasis='QP') -> SecretKey: ...

Lift caller-supplied integer coefficients and compute NTT(s)R.

coefficients has shape [N] on the resource device and uses an integral dtype. The returned key owns Q or QP storage. This operation does not sample, infer a secret distribution, or alter the source.

create_secret_key ​

method

python
def create_secret_key(resources: KeyGenerationResource, *, modulus_basis: ModulusBasis='QP', hamming_weight: int | None=None) -> SecretKey: ...

Sample ternary s and return its depth-zero NTT/Montgomery RNS.

With no weight, coefficients are independent uniform {-1,0,1}. A supplied h selects a uniform h-element support with independent uniform signs. Sorting distinct 64-bit CSPRNG labels samples a uniform permutation; collisions cause the labels to be resampled. Both label and sign sampling consume the supplied cryptographic random stream. The output owns [limb, ntt_index] storage on its resource device.

create_public_key ​

method

python
def create_public_key(resources: KeyGenerationResource, secret_key: SecretKey, *, modulus_basis: ModulusBasis='Q', uniform_component: torch.Tensor | None=None, error_coefficients: torch.Tensor | None=None) -> PublicKey: ...

Generate (k_0,k_1) satisfying k0+k1s=e modulo the basis.

Output is integral [key_component=2, limb, ntt_index] in depth-zero NTT/Montgomery form with Q or QP rows. secret_key and optional sampled uniform/error coefficients are read-only and never alias the returned stacked tensor. When error coefficients are omitted, the generator samples its configured discrete Gaussian.

create_key_switch_key ​

method

python
def create_key_switch_key(resources: KeyGenerationResource, source_secret_key: SecretKey, destination_secret_key: SecretKey, *, uniform_component_by_key_digit: torch.Tensor | None=None, digit_prime_ids: tuple[tuple[int, ...], ...] | None=None, p_prime_ids: tuple[int, ...] | None=None, source_depth: int=0, source_multiplier: int=1, error_coefficients_by_key_digit: torch.Tensor | None=None) -> KeySwitchKey: ...

Create a hybrid-RNS key from source to destination secret relation.

Each hybrid digit is constructed through a public-key encryption.

Stable key digit d satisfies, on that digit's embedded source rows, kd,0+kd,1sdst=Pmssrc+ed. Here m is source_multiplier. Caller-supplied digit_prime_ids partition the active Q rows in order. At source_depth zero, omission uses the configured hybrid decomposition; at later depths it partitions active Q by the same product-below-P rule. Execution must use the same digit partition and source relation. Output is integral [key_digit, key_component=2, QP_limb, ntt_index] in NTT/Montgomery lazy form and source-depth Q followed by the selected P. Omitted p_prime_ids preserves the original auxiliary basis. Supplied auxiliary IDs select distinct catalog primes outside active Q; all planes are newly sampled for that P relation. Input keys and optional sampled uniform/error coefficients are not mutated or aliased.

create_encapsulation_keys ​

method

python
def create_encapsulation_keys(resources: KeyGenerationResource, source_secret_key: SecretKey, intermediate_secret_key: SecretKey, *, source_depth: int, low_p_moduli: tuple[int, ...], return_prime: int, return_p_moduli: tuple[int, ...]) -> tuple[KeySwitchKey, KeySwitchKey]: ...

Generate low s→t digits and one guard-scaled t→s return hint.

Low digits encrypt P_lowE_js under t. The return digit encrypts guardP_returnt under s across [guard,Q,P_return]. Both secrets are supplied by the caller; this factory samples only public-key randomness and error on the shared CSPRNG. It returns ordinary KeySwitchKey values.

create_relinearization_key ​

method

python
def create_relinearization_key(resources: KeyGenerationResource, secret_key: SecretKey, *, source_depth: int=0, digit_prime_ids: tuple[tuple[int, ...], ...] | None=None, p_prime_ids: tuple[int, ...] | None=None) -> RelinearizationKey: ...

Return QP key material that switches the s2 phase term to s.

The returned state and layout equal create_key_switch_key; the input secret key remains NTT/Montgomery QP and is not mutated.

create_rotation_key ​

method

python
def create_rotation_key(resources: KeyGenerationResource, rotation_step: int, *, uniform_component_by_key_digit: torch.Tensor | None=None, secret_key: SecretKey, source_depth: int=0, digit_prime_ids: tuple[tuple[int, ...], ...] | None=None, p_prime_ids: tuple[int, ...] | None=None) -> RotationKey: ...

Construct QP key material from σg(s) back to s.

rotation_step follows signed slot displacement and is stored as metadata. The distinct galois_element g selects polynomial automorphism σg. Output uses key-switch-key axes and NTT/Montgomery QP state; input secret/uniform tensors are not mutated.

create_conjugation_key ​

method

python
def create_conjugation_key(resources: KeyGenerationResource, secret_key: SecretKey, *, source_depth: int=0, digit_prime_ids: tuple[tuple[int, ...], ...] | None=None, p_prime_ids: tuple[int, ...] | None=None) -> ConjugationKey: ...

Construct QP key material from σ2N−1(s) back to s.

Output uses key-switch-key axes and NTT/Montgomery QP state; the input secret key remains unchanged.

NativeDecodeImplementation ​

class View source

python
NativeDecodeImplementation()

Decode coefficients on the operation input device.

Attributes ​

NameTypeDefault/value
name'native-ckks-decode'
operation_types(ckks.DecodeOp,)
supports_in_placeFalse

resource_requirements ​

method

python
def resource_requirements(invocation: OperationInvocation) -> tuple[ResourceRequirement, ...]: ...

execute ​

method

python
def execute(invocation: OperationInvocation, inputs: tuple[torch.Tensor, ...], resources: tuple[BoundResource, ...], *, in_place: bool) -> tuple[torch.Tensor, ...]: ...

NativeDecryptImplementation ​

class View source

python
NativeDecryptImplementation(name: str = 'native-ckks-decrypt', supports_in_place: bool = False, operation_types: tuple[type[Operation], ...] = (ckks.DecryptOp,))

Execute decryption with Tensor key, transform, and reconstruction operands.

Attributes ​

NameTypeDefault/value
namestr'native-ckks-decrypt'
supports_in_placeboolFalse
operation_typestuple[type[Operation], ...](ckks.DecryptOp,)

resource_requirements ​

method

python
def resource_requirements(invocation: OperationInvocation) -> tuple[ResourceRequirement, ...]: ...

execute ​

method

python
def execute(invocation: OperationInvocation, inputs: tuple[torch.Tensor, ...], resources: tuple[BoundResource, ...], *, in_place: bool) -> tuple[torch.Tensor, ...]: ...

DecryptReconstructionTables ​

class View source

python
DecryptReconstructionTables(source_prime_ids_by_depth: tuple[tuple[int, ...], ...], normalizers_by_depth: tuple[torch.Tensor, ...], propagation_by_depth: tuple[torch.Tensor, ...], device: torch.device, half_digits_by_depth: tuple[torch.Tensor, ...])

Hold device tables for centered reconstruction of the complete active Q basis.

Attributes ​

NameTypeDefault/value
source_prime_ids_by_depthtuple[tuple[int, ...], ...]
normalizers_by_depthtuple[torch.Tensor, ...]
propagation_by_depthtuple[torch.Tensor, ...]
devicetorch.device
half_digits_by_depthtuple[torch.Tensor, ...]

tensor_operands ​

method

python
def tensor_operands(context: RnsContext, depth: int) -> tuple[torch.Tensor, ...]: ...

Return the Q parameters and mixed-radix reconstruction tables.

create ​

method

python
def create(context: RnsContext) -> DecryptReconstructionTables: ...

Build reconstruction tables for one context-local RNS context.

NativeEncodeImplementation ​

class View source

python
NativeEncodeImplementation()

Encode slots with supplied embedding tables and advancing rounding state.

Attributes ​

NameTypeDefault/value
name'native-ckks-encode'
operation_types(ckks.EncodeOp,)
supports_in_placeFalse

resource_requirements ​

method

python
def resource_requirements(invocation: OperationInvocation) -> tuple[ResourceRequirement, ...]: ...

execute ​

method

python
def execute(invocation: OperationInvocation, inputs: tuple[torch.Tensor, ...], resources: tuple[BoundResource, ...], *, in_place: bool) -> tuple[torch.Tensor, ...]: ...

NativeEncryptImplementation ​

class View source

python
NativeEncryptImplementation(name: str = 'native-ckks-encrypt', supports_in_place: bool = False, operation_types: tuple[type[Operation], ...] = (ckks.EncryptOp,))

Execute encryption with data operands and a bound random stream.

Attributes ​

NameTypeDefault/value
namestr'native-ckks-encrypt'
supports_in_placeboolFalse
operation_typestuple[type[Operation], ...](ckks.EncryptOp,)

resource_requirements ​

method

python
def resource_requirements(invocation: OperationInvocation) -> tuple[ResourceRequirement, ...]: ...

execute ​

method

python
def execute(invocation: OperationInvocation, inputs: tuple[torch.Tensor, ...], resources: tuple[BoundResource, ...], *, in_place: bool) -> tuple[torch.Tensor, ...]: ...

NativeIntegerCoefficientsToRnsImplementation ​

class View source

python
NativeIntegerCoefficientsToRnsImplementation()

Reduce integer coefficients using the supplied twice-modulus rows.

Attributes ​

NameTypeDefault/value
name'native-ckks-integer-coefficients-to-rns'
operation_types(ckks.IntegerCoefficientsToRnsOp,)
supports_in_placeFalse

resource_requirements ​

method

python
def resource_requirements(invocation: OperationInvocation) -> tuple[ResourceRequirement, ...]: ...

execute ​

method

python
def execute(invocation: OperationInvocation, inputs: tuple[torch.Tensor, ...], resources: tuple[BoundResource, ...], *, in_place: bool) -> tuple[torch.Tensor, ...]: ...

NativeScalarArithmeticImplementation ​

class View source

python
NativeScalarArithmeticImplementation(name: str = 'native-ckks-scalar-arithmetic', supports_in_place: bool = False, operation_types: tuple[type[Operation], ...] = (ckks.AddScalarOp, ckks.MultiplyScalarOp, ckks.MultiplyIntegerScalarOp))

Execute scalar multiplication and addition using shared RNS primitives.

Attributes ​

NameTypeDefault/value
namestr'native-ckks-scalar-arithmetic'
supports_in_placeboolFalse
operation_typestuple[type[Operation], ...](ckks.AddScalarOp, ckks.MultiplyScalarOp, ckks.MultiplyIntegerScalarOp)

resource_requirements ​

method

python
def resource_requirements(invocation: OperationInvocation) -> tuple[ResourceRequirement, ...]: ...

execute ​

method

python
def execute(invocation: OperationInvocation, inputs: tuple[torch.Tensor, ...], resources: tuple[BoundResource, ...], *, in_place: bool) -> tuple[torch.Tensor, ...]: ...

KeyGenerationResource ​

class View source

python
KeyGenerationResource(config: CkksConfig, rng: Csprng, rns_context: RnsContext, ntt_context: NttContext, p_product_montgomery_q: torch.Tensor)

Bind context, arithmetic, and random resources for one key device.

Attributes ​

NameTypeDefault/value
configCkksConfig
rngCsprng
rns_contextRnsContext
ntt_contextNttContext
p_product_montgomery_qtorch.Tensor

create ​

method

python
def create(*, config: CkksConfig, rng: Csprng, rns_context: RnsContext, ntt_context: NttContext) -> KeyGenerationResource: ...

Build key-generation scalars on one concrete context device.

for_config ​

method

python
def for_config(config: CkksConfig, *, dtype: torch.dtype | None=None) -> KeyGenerationResource: ...

Prepare another modulus basis on this device and random stream.

device ​

property

python
device: torch.device

Return the concrete device shared by all key-generation resources.