fhelium.core.keys

Tensor-backed CKKS key value types.

SecretKey

class View source

SecretKey(data: torch.Tensor, context_id: str, prime_ids: tuple[int, ...], polynomial_domain: PolynomialDomain = 'ntt', modulus_basis: ModulusBasis = 'QP', residue_representation: ResidueRepresentation = 'montgomery')

Bases: TensorResident

RNS storage for the secret polynomial $s(X)$.

data is a dense integral [limb, coefficient_or_ntt_index] tensor; row $i$ is modulo prime_ids[i]. Engine-generated keys are level-zero Q or QP values in NTT domain and Montgomery form on the engine device, with final extent $N$. Direct construction retains the supplied tensor storage. clone allocates independent storage; residency views may alias their source. The key carries context and representation metadata but no device owner or persistence policy.

Attributes

Name	Type	Default/value
data	torch.Tensor
context_id	str
prime_ids	tuple[int, ...]
polynomial_domain	PolynomialDomain	'ntt'
modulus_basis	ModulusBasis	'QP'
residue_representation	ResidueRepresentation	'montgomery'

clone

method

def clone() -> SecretKey: ...

Return the same key value in independent tensor storage.

PublicKey

class View source

PublicKey(data: torch.Tensor, context_id: str, prime_ids: tuple[int, ...], polynomial_domain: PolynomialDomain = 'ntt', modulus_basis: ModulusBasis = 'Q', residue_representation: ResidueRepresentation = 'montgomery')

Bases: TensorResident

Public encryption key for one destination secret polynomial.

data is a dense integral [key_component=2, limb, coefficient_or_ntt_index] tensor. In each RNS row the generated components satisfy

$$k_0(X)+k_1(X)s(X)=e(X)(\mathrm{mod}{B}_0),$$

where $B_0$ is Q or QP according to modulus_basis. Row $i$ is modulo prime_ids[i]; generated keys are level-zero NTT-domain Montgomery residues on one device. The object does not record a symbolic key-lineage identifier, so callers must keep the key paired with its destination secret key. Direct construction and component access retain/share storage; clone allocates independent storage.

Attributes

Name	Type	Default/value
data	torch.Tensor
context_id	str
prime_ids	tuple[int, ...]
polynomial_domain	PolynomialDomain	'ntt'
modulus_basis	ModulusBasis	'Q'
residue_representation	ResidueRepresentation	'montgomery'

k0

property

k0: torch.Tensor

k1

property

k1: torch.Tensor

component

method

def component(component_id: int) -> torch.Tensor: ...

Return a storage-sharing [limb, ntt_index] component view.

clone

method

def clone() -> PublicKey: ...

KeySwitchKey

class View source

KeySwitchKey(data: torch.Tensor, context_id: str, prime_ids: tuple[int, ...], polynomial_domain: PolynomialDomain = 'ntt', modulus_basis: ModulusBasis = 'QP', residue_representation: ResidueRepresentation = 'montgomery')

Bases: TensorResident

Hybrid-RNS material for one source-to-destination key relation.

A key generated from $s_{\mathrm{src}}(X)$ and $s_{\mathrm{dst}}(X)$ converts a source phase

$$c_0(X)+c_1(X)s_{\mathrm{src}}(X)$$

to an equivalent destination phase

$$c_0^{\prime }(X)+c_1^{\prime }(X)s_{\mathrm{dst}}(X),$$

up to configured key-switch error. The object does not store symbolic source/destination identifiers; the caller must preserve that direction.

data is a dense integral [key_digit, key_component=2, limb, coefficient_or_ntt_index] tensor. key_digit is stable key-storage identity, not the local active digit_index used at a later level. Limb row $i$ is modulo prime_ids[i]. Generated keys use the complete level-zero QP basis, NTT domain, Montgomery form, the engine integral dtype, and one engine device. Direct construction and digit/component access retain/share storage; clone allocates independent storage.

Attributes

Name	Type	Default/value
data	torch.Tensor
context_id	str
prime_ids	tuple[int, ...]
polynomial_domain	PolynomialDomain	'ntt'
modulus_basis	ModulusBasis	'QP'
residue_representation	ResidueRepresentation	'montgomery'

digit_count

property

digit_count: int

digit

method

def digit(key_digit_index: int) -> torch.Tensor: ...

Return a storage-sharing [key_component, limb, index] view.

digit_component

method

def digit_component(key_digit_index: int, component_id: int) -> torch.Tensor: ...

Return a storage-sharing [limb, index] key-component view.

clone

method

def clone(): ...

RotationKey

class View source

RotationKey(data: torch.Tensor, context_id: str, prime_ids: tuple[int, ...], polynomial_domain: PolynomialDomain = 'ntt', modulus_basis: ModulusBasis = 'QP', residue_representation: ResidueRepresentation = 'montgomery', *, rotation_step: int)

Bases: KeySwitchKey

Key-switch material from ${\sigma }_g(s(X))$ back to $s(X)$.

rotation_step is the canonical signed user-visible displacement $r$, not the Galois element $g$. Applying the matching automorphism and this key produces slots $m_j^{\prime }=m_{(j-r)modS}$, matching torch.roll(m, shifts=r).

Attributes

Name	Type	Default/value
rotation_step	int

canonical_step

method

def canonical_step(step: int, *, ring_dimension: int) -> int: ...

Map a step modulo $S=N/2$ to [-S/2, S/2).

clone

method

def clone() -> RotationKey: ...

RelinearizationKey

class View source

RelinearizationKey(data: torch.Tensor, context_id: str, prime_ids: tuple[int, ...], polynomial_domain: PolynomialDomain = 'ntt', modulus_basis: ModulusBasis = 'QP', residue_representation: ResidueRepresentation = 'montgomery')

Bases: KeySwitchKey

Key-switch material from source key $s(X{)}^2$ to $s(X)$.

It replaces the $d_2(X)s(X{)}^2$ term of a three-component product with two corrections, preserving level and actual scale up to key-switch error.

ConjugationKey

class View source

ConjugationKey(data: torch.Tensor, context_id: str, prime_ids: tuple[int, ...], polynomial_domain: PolynomialDomain = 'ntt', modulus_basis: ModulusBasis = 'QP', residue_representation: ResidueRepresentation = 'montgomery')

Bases: KeySwitchKey

Key-switch material from ${\sigma }_{-1}(s(X))$ back to $s(X)$.

After the conjugation automorphism it restores the original key relation, producing semantic slots $m_j^{\prime }=\overline{m_j}$ up to CKKS approximation.

RotationKeySet

class View source

RotationKeySet(table: dict[int, RotationKey] = field(default_factory=dict))

Bases: MutableMapping[int, RotationKey]

Mapping from canonical signed rotation steps to matching local keys.

Attributes

Name	Type	Default/value
table	dict[int, RotationKey]	field(default_factory=dict)

add

method

def add(key: RotationKey) -> RotationKeySet: ...

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

EvaluationKeyRequirements

class View source

EvaluationKeyRequirements(rotation_steps: frozenset[int] = frozenset(), requires_relinearization: bool = False, requires_conjugation: bool = False)

Evaluation-key roles and rotations required by one evaluator.

This is a value-independent capability description. It contains no key tensors, device placement, generation policy, or secret-key material. Consumers derive requirements; applications decide how to generate, load, distribute, and retain matching keys.

Attributes

Name	Type	Default/value
rotation_steps	frozenset[int]	frozenset()
requires_relinearization	bool	False
requires_conjugation	bool	False

EvaluationKeySet

class View source

EvaluationKeySet(rotations: RotationKeySet = field(default_factory=RotationKeySet), relinearization: RelinearizationKey | None = None, conjugation: ConjugationKey | None = None)

Validated inventory of evaluator-only CKKS key capabilities.

The inventory contains rotation, relinearization, and conjugation keys. It deliberately excludes PublicKey and SecretKey: encryption, decryption, and key generation are separate capabilities from public evaluation. The set is not a TensorResident and does not move or serialize its members as one large value, so residency policies may continue to manage individual keys and rotation windows independently.

Construction and validate reject mixed structural key states. Key tensors remain ordinary primitive values and may still be passed directly to low-level engine operations.

Attributes

Name	Type	Default/value
rotations	RotationKeySet	field(default_factory=RotationKeySet)
relinearization	RelinearizationKey | None	None
conjugation	ConjugationKey | None	None

validate

method

def validate() -> EvaluationKeySet: ...

Validate all current members and return this inventory.

RotationKeySet is intentionally mutable for application-owned key planning, so consumers call this method again before use. The check re-establishes capability-role types, exact rotation mapping, and one shared context/prime/domain/basis/residue/ring/digit/dtype/device structure. It does not select or validate an evaluator engine.

require

method

def require(requirements: EvaluationKeyRequirements) -> EvaluationKeySet: ...

Validate and require every evaluator capability in requirements.

Required rotations are canonicalized with the inventory's ring dimension when at least one rotation key is present. The method checks capability presence only; a consuming engine must separately preflight context, device, and native key compatibility. It returns this mutable inventory for fluent validation.

Raises

• TypeError: If requirements or a current capability role has an invalid type.
• ValueError: If members are structurally inconsistent or a required rotation/relinearization/conjugation capability is absent.