FHElium

Appearance

fhelium.values.compressed_plaintext ​

Operation-ready CKKS plaintexts with repeated encoded values.

CompressedPlaintext ​

class View source

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

Bases: TensorResident

An RNS plaintext with compact polynomial or NTT 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ℓ or QℓP; polynomial_domain determines whether the expanded last axis indexes coefficients or NTT evaluations. Coefficient data may use standard or Montgomery residues; NTT data uses Montgomery residues, as in Plaintext. compression_layout defines the 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. from_plaintext verifies bit-for-bit representability of existing encoded data. Engine.prepare_compressed_plaintext prepares compact data directly from one periodic message; its rounding need not reproduce a prior full-ring encoding bit for bit.

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 depth, actual scale Δ(p), domain, basis, residue form, and prime_ids. The value has no engine, cache, placement, or persistence policy.

Attributes ​

NameTypeDefault/value
datatorch.Tensor
ring_dimensionint
compression_layoutCompressedPlaintextLayout
depthint
scalefloat
polynomial_domainPolynomialDomain
modulus_basisModulusBasis
residue_representationResidueRepresentation
prime_idstuple[int, ...]
implicit_datatorch.Tensor | NoneNone

representation ​

property

python
representation: Literal['rns']

The compact payload represents RNS polynomial rows.

is_rns ​

property

python
is_rns: bool

is_slots ​

property

python
is_slots: bool

is_integer_coefficients ​

property

python
is_integer_coefficients: bool

is_approximate_coefficients ​

property

python
is_approximate_coefficients: bool

unique_count ​

property

python
unique_count: int

Number of physically stored values per RNS row.

repeat_count ​

property

python
repeat_count: int

Number of dense positions represented by each stored extent.

limb_count ​

property

python
limb_count: int

Number of represented RNS rows.

batch_shape ​

property

python
batch_shape: torch.Size

Logical homogeneous batch dimensions.

batch_size ​

property

python
batch_size: int

Flattened logical batch size; one for an unbatched value.

is_batched ​

property

python
is_batched: bool

Whether this value has at least one logical batch dimension.

from_plaintext ​

method

python
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. Depth, actual scale, domain, basis, residue form, dtype, device, and prime_ids are preserved.

decompress_data ​

method

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

Materialize the 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

python
def to_plaintext() -> Plaintext: ...

Materialize the equivalent dense RNS Plaintext.

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

clone ​

method

python
def clone() -> CompressedPlaintext: ...

with_data ​

method

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

Return unchanged metadata around replacement tensor storage.

with_storage ​

method

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

Return the same metadata around complete replacement storage.

slice_limbs ​

method

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

Return a storage-sharing RNS row interval and its prime IDs.

[start, stop) indexes stored limb positions, not global prime IDs. Compact data and any implicit row values are sliced together. Batch axes, depth, scale, compression layout, and representation state are preserved; slicing does not rescale or change the compression format.

stack_batch ​

method

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

Allocate and copy compatible values into one new batch axis.

slice_batch ​

method

python
def slice_batch(start: int, stop: int, *, dim: int=0) -> CompressedPlaintext: ...

Return a storage-sharing interval along one logical batch axis.

[start, stop) must be a nonempty interval within the selected axis. dim indexes batch_shape and accepts negative dimensions. The axis is retained even for a one-item interval. The same interval selects both compact data and any implicit row values. Arithmetic state and compression metadata are unchanged.

select_batch ​

method

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

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

unbind_batch ​

method

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

Return storage-sharing views along one logical batch axis.