fhelium.core.ciphertext

Tensor-backed CKKS ciphertext value type.

Ciphertext

class View source

Ciphertext(data: torch.Tensor, level: int, scale: float, context_id: str, prime_ids: tuple[int, ...], polynomial_domain: PolynomialDomain = 'coefficient', modulus_basis: ModulusBasis = 'Q', residue_representation: ResidueRepresentation = 'standard')

Bases: TensorResident

One homogeneous process-local CKKS ciphertext tensor or dense batch.

data is a dense integral tensor with layout [component, *batch, limb, coefficient_or_ntt_index]. The component extent is two or three for

$$u(X)=\sum _{j=0}^{d-1}{c}_j(X)s(X{)}^j.$$

Limb row $i$ is modulo the exact parameter prime prime_ids[i]. The final extent indexes coefficients in $R=\mathbb{Z}[X]/(X^N+1)$ or NTT evaluations according to polynomial_domain. modulus_basis selects $Q_{\ell }$ or $Q_{\ell }P$; valid operation states pair coefficient domain with standard residues and NTT domain with Montgomery residues. scale is the positive finite actual scale $\mathrm{\Delta }(c)$.

Every member of batch_shape shares the exact level, scale, component count, domain, basis, residue form, context, and ordered prime_ids. Direct construction retains the input dtype, device, and storage; engine operations additionally require the engine's configured integral dtype, device, ring dimension, and expected row interval. clone owns new storage, while limb slices and batch selections are views. Methods ending in _ mutate this object and are visible through aliases.

Distribution and communication are deliberately not encoded in this value: an SPMD program decides what each rank stores and which collectives it executes.

Attributes

Name	Type	Default/value
data	torch.Tensor
level	int
scale	float
context_id	str
prime_ids	tuple[int, ...]
polynomial_domain	PolynomialDomain	'coefficient'
modulus_basis	ModulusBasis	'Q'
residue_representation	ResidueRepresentation	'standard'

component_count

property

component_count: int

limb_count

property

limb_count: int

ring_dimension

property

ring_dimension: int

batch_shape

property

batch_shape: torch.Size

Logical homogeneous batch dimensions, excluding CKKS axes.

batch_size

property

batch_size: int

Flattened logical batch size; one for an unbatched value.

is_batched

property

is_batched: bool

Whether this value has at least one logical batch dimension.

component

method

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

Return the storage-sharing [*batch, limb, index] component view.

c0

property

c0: torch.Tensor

c1

property

c1: torch.Tensor

c2

property

c2: torch.Tensor

is_ntt_domain

property

is_ntt_domain: bool

is_coefficient_domain

property

is_coefficient_domain: bool

includes_p

property

includes_p: bool

assert_state

method

def assert_state(*, polynomial_domain: PolynomialDomain | None=None, residue_representation: ResidueRepresentation | None=None, modulus_basis: ModulusBasis | None=None, components: int | None=None) -> Ciphertext: ...

clone

method

def clone() -> Ciphertext: ...

Return a metadata-equivalent ciphertext with independent storage.

with_data

method

def with_data(data: torch.Tensor) -> Ciphertext: ...

Construct the same semantic layout around replacement storage.

The payload is not cloned; the result aliases data exactly.

slice_limbs

method

def slice_limbs(start: int, stop: int) -> Ciphertext: ...

Return a storage-sharing view over [start:stop] RNS limbs.

This is a local tensor operation, not a placement decision. In-place arithmetic on the returned value also modifies the corresponding rows of this ciphertext.

stack_batch

method

def stack_batch(values: tuple[Ciphertext, ...] | list[Ciphertext]) -> Ciphertext: ...

Allocate and copy compatible values into one new batch dimension.

Stacking separately allocated values cannot be zero-copy. This named constructor makes that cost visible rather than hiding a torch.stack inside an engine operation. The new logical batch axis is inserted before any batch axes already owned by each value.

context_id does not identify an encryption key. The caller must ensure every value has the same effective key lineage, applying an key switch first when necessary.

select_batch

method

def select_batch(index: int, *, dim: int=0) -> Ciphertext: ...

Return a storage-sharing view selected from one batch axis.

unbind_batch

method

def unbind_batch(*, dim: int=0) -> tuple[Ciphertext, ...]: ...

Return storage-sharing views along one logical batch axis.

replace_

method

def replace_(other: Ciphertext) -> Ciphertext: ...

Replace this value without changing its Python object identity.

The result aliases other.data; prior aliases of self.data keep the old allocation. All observable CKKS state fields are replaced.