FHElium

fhelium.values.plaintext ​

Depth-specific CKKS plaintext values.

Plaintext ​

class View source

python
Plaintext(message: torch.Tensor | None, depth: int, scale: float, data: torch.Tensor | 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 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 integral [*batch, coefficient] tensor for p(X)∈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 a full-Qℓ CRT inverse.
  • representation="rns" stores a dense integral [*batch, limb, coefficient_or_ntt_index] tensor. Limb row i is modulo the parameter prime prime_ids[i]. The last axis indexes coefficients of R=Z[X]/(XN+1) in "coefficient" domain or NTT evaluations in "ntt" domain. modulus_basis selects Qℓ or QℓP, and residue_representation distinguishes standard from Montgomery residues.

Tensor payloads retain their input dtype, device, and storage at direct construction; encoded payloads require dense strided storage and the dtype constraints above. Engine operations additionally require the engine's configured integral dtype, device, ring dimension, and matching prime-row parameters. Row-local operations can use a sliced RNS interval; operations requiring the complete active basis must receive every required row. 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. scale is the positive finite actual scale Δ(v); depth identifies Qℓ but never substitutes for prime_ids.

Attributes ​

NameTypeDefault/value
messagetorch.Tensor | None
depthint
scalefloat
datatorch.Tensor | NoneNone
representationPlaintextRepresentation'slots'
polynomial_domainPolynomialDomain | NoneNone
modulus_basisModulusBasis | NoneNone
residue_representationResidueRepresentation | NoneNone
prime_idstuple[int, ...]()

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

is_rns ​

property

python
is_rns: bool

limb_count ​

property

python
limb_count: int

Number of represented RNS rows; zero for non-RNS representations.

batch_shape ​

property

python
batch_shape: torch.Size

Logical homogeneous batch dimensions for the active form.

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.

clone ​

method

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

Return a metadata-equivalent value with independent tensor storage.

slice_limbs ​

method

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

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

[start, stop) indexes stored limb positions, not global prime IDs. All batch axes, depth, scale, and representation state are preserved; the result represents part of the same basis, not a rescaled value. Slots and non-RNS coefficient representations have no limb axis.

stack_batch ​

method

python
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, prime_ids, shape, dtype, and device. The result does not alias an input.

slice_batch ​

method

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

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 active slots, coefficient, or RNS representation is preserved. Depth, scale, prime IDs, and representation state are unchanged.

select_batch ​

method

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

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

unbind_batch ​

method

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

Return storage-sharing views along one logical batch axis.