fhelium.core.plaintext

Level-specific CKKS plaintext values.

Plaintext

class View source

Plaintext(message: torch.Tensor | None, level: int, scale: float, data: torch.Tensor | None = None, context_id: str | None = None, representation: PlaintextRepresentation = 'slots', polynomial_domain: PolynomialDomain | None = None, modulus_basis: ModulusBasis | None = None, residue_representation: ResidueRepresentation | None = None, prime_ids: tuple[int, ...] = ())

Bases: TensorResident

One homogeneous CKKS plaintext or dense batch at one exact state tuple.

The state fields describe tensor layout and arithmetic form independently:

• representation="slots" stores a scalar (repeated to all slots during encoding) or [*batch, slot] real/complex semantic messages. Encoding has not occurred; data and all RNS-state metadata are absent.
• representation="integer_coefficients" stores an exact integral [*batch, coefficient] tensor for $p(X)\in R$, before RNS reduction.
• representation="approximate_coefficients" stores the bounded binary64 [*batch, coefficient] tail-Q reconstruction produced by decryption. It is valid only for decoding and cannot be encrypted or reduced back to RNS; it is not an exact full-$Q_{\ell }$ CRT inverse.
• representation="rns" stores a dense integral [*batch, limb, coefficient_or_ntt_index] tensor. Limb row $i$ is modulo the exact parameter prime prime_ids[i]. The last axis indexes coefficients of $R=\mathbb{Z}[X]/(X^N+1)$ in "coefficient" domain or NTT evaluations in "ntt" domain. modulus_basis selects $Q_{\ell }$ or $Q_{\ell }P$, and residue_representation distinguishes standard from Montgomery residues.

Tensor payloads retain their input dtype, device, and storage at direct construction; validation requires dense strided storage and the dtype constraints above. Engine operations additionally require the engine's configured integral dtype, device, ring dimension, and complete ordered prime_ids. Construction does not clone an input tensor. clone allocates independent storage, while batch selection and unbinding return storage-sharing views.

A program that needs the same semantic message in multiple arithmetic states constructs separate values. The object owns no engine, cache, placement, or persistence reference. scale is the positive finite actual scale $\mathrm{\Delta }(v)$; level identifies $Q_{\ell }$ but never substitutes for exact prime_ids.

Attributes

Name	Type	Default/value
message	torch.Tensor | None
level	int
scale	float
data	torch.Tensor | None	None
context_id	str | None	None
representation	PlaintextRepresentation	'slots'
polynomial_domain	PolynomialDomain | None	None
modulus_basis	ModulusBasis | None	None
residue_representation	ResidueRepresentation | None	None
prime_ids	tuple[int, ...]	()

is_slots

property

is_slots: bool

is_integer_coefficients

property

is_integer_coefficients: bool

is_approximate_coefficients

property

is_approximate_coefficients: bool

is_rns

property

is_rns: bool

batch_shape

property

batch_shape: torch.Size

Logical homogeneous batch dimensions for the active form.

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.

clone

method

def clone() -> Plaintext: ...

Return a metadata-equivalent value with independent tensor storage.

stack_batch

method

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

Allocate and copy compatible plaintexts into one new batch axis.

Scalar slots plaintexts are rejected because stacking them would change their repeat-to-all-slots meaning; materialize slot vectors first. Inputs must have identical representation, state, exact prime_ids, shape, dtype, and device. The result does not alias an input.

select_batch

method

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

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

unbind_batch

method

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

Return storage-sharing views along one logical batch axis.