fhelium.core.compressed_plaintext

Exact operation-ready CKKS plaintexts with repeated encoded values.

COMPRESSED_PLAINTEXT_FORMAT_VERSION

constant View source

COMPRESSED_PLAINTEXT_FORMAT_VERSION = 1

CompressedPlaintext

class View source

CompressedPlaintext(data: torch.Tensor, ring_dimension: int, compression_layout: CompressedPlaintextLayout, level: int, scale: float, context_id: str, polynomial_domain: PolynomialDomain, modulus_basis: ModulusBasis, residue_representation: ResidueRepresentation, prime_ids: tuple[int, ...], implicit_data: torch.Tensor | None = None, compression_format_version: int = COMPRESSED_PLAINTEXT_FORMAT_VERSION)

Bases: TensorResident

An exact operation-ready RNS plaintext with compressed storage.

data is a dense integral tensor with layout [*batch, limb, unique_index] rather than the dense [*batch, limb, coefficient_or_ntt_index] layout used by Plaintext. Limb row $i$ is modulo the prime identified by prime_ids[i] in $Q_{\ell }$ or $Q_{\ell }P$; polynomial_domain determines whether the expanded last axis indexes coefficients or NTT evaluations. Operation-ready compressed values always use Montgomery residues. compression_layout defines the exact, lossless expansion of each compact row:

• "cyclic" expands [a, b] as [a, b, a, b, ...];
• "contiguous" expands [a, b] as [a, ..., a, b, ..., b].
• "strided_sparse": compact values occupy positions separated by $N/U$, where $N$ is ring_dimension and $U$ is unique_count; all other positions use the stored per-batch/per-limb implicit_data value.

These modes describe the encoded polynomial/NTT tensor axis, not the user-visible CKKS slot order. CKKS encoding permutes slots, and coefficient rounding can destroy repetition that exists only in semantic slot space. Construct this type from a dense operation-ready plaintext with from_plaintext; that conversion verifies exact representability.

implicit_data is absent except for "strided_sparse", where it has layout [*batch, limb] and the same integral dtype and device as data. Direct construction retains supplied storage. clone and decompression allocate independent storage; batch selection and unbinding return storage-sharing views. All batch entries share level, actual scale $\mathrm{\Delta }(p)$, domain, basis, residue form, and exact prime_ids. The value has no engine, cache, placement, or persistence policy.

Attributes

Name	Type	Default/value
data	torch.Tensor
ring_dimension	int
compression_layout	CompressedPlaintextLayout
level	int
scale	float
context_id	str
polynomial_domain	PolynomialDomain
modulus_basis	ModulusBasis
residue_representation	ResidueRepresentation
prime_ids	tuple[int, ...]
implicit_data	torch.Tensor | None	None
compression_format_version	int	COMPRESSED_PLAINTEXT_FORMAT_VERSION

unique_count

property

unique_count: int

Number of physically stored values per RNS row.

repeat_count

property

repeat_count: int

Number of dense positions represented by each stored extent.

batch_shape

property

batch_shape: torch.Size

Logical homogeneous batch dimensions.

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.

from_plaintext

method

def from_plaintext(plaintext: Plaintext, *, unique_count: int, compression_layout: CompressedPlaintextLayout) -> CompressedPlaintext: ...

Losslessly compress one operation-ready dense RNS plaintext.

The encoded last axis is checked bit-for-bit. The compact tensor is cloned so it does not retain the dense input's backing storage. Level, actual scale, domain, basis, residue form, dtype, device, and exact prime_ids are preserved.

decompress_data

method

def decompress_data() -> torch.Tensor: ...

Materialize the exact dense RNS encoded tensor.

The output layout is [*batch, limb, coefficient_or_ntt_index] with last extent ring_dimension. It preserves dtype, device, domain, basis, residue form, and limb-to-prime_ids mapping and does not alias compact storage.

to_plaintext

method

def to_plaintext() -> Plaintext: ...

Materialize the exact equivalent dense RNS Plaintext.

"Standard" here means the ordinary dense value type; the returned residue representation remains exactly self.residue_representation.

clone

method

def clone() -> CompressedPlaintext: ...

with_data

method

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

Return the same exact metadata around replacement tensor storage.

with_storage

method

def with_storage(data: torch.Tensor, implicit_data: torch.Tensor | None) -> CompressedPlaintext: ...

Return the same metadata around complete replacement storage.

stack_batch

method

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

Allocate and copy compatible values into one new batch axis.

select_batch

method

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

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

unbind_batch

method

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

Return storage-sharing views along one logical batch axis.