fhelium.backend.rns.context

Build device-local RNS parameter views and execute residue arithmetic.

RnsContext

class View source

RnsContext(ckks_config: CkksConfig, device: str | torch.device | None=None, *, rns_layout: RnsLayout | None=None, dtype: torch.dtype | None=None)

Own dense RNS parameters and residue-representation arithmetic.

Unless a method states otherwise, an RNS operand is an integral tensor with shape [*batch, limb, coefficient_or_ntt_index] and final extent $N$. Limb row j represents the modulus whose parameter id is prime_ids[j]. Public full-basis calls derive those ids from depth and internal calls supply parameter_row_start for a contiguous row interval. include_p is only this internal row selector; it is not public modulus_basis metadata.

Functional methods allocate non-aliasing output. A trailing underscore mutates the operand and preserves its storage. Standard and Montgomery conversions do not change polynomial domain.

basis_count

property

basis_count: int

Number of public CKKS basis positions, excluding the structural basis.

materialize_parameter_rows

method

def materialize_parameter_rows(variable) -> torch.Tensor: ...

Select this rank's QP row order into one tensor.

integer_scalar_parameters

method

def integer_scalar_parameters(scalar: int) -> torch.Tensor: ...

Return the reusable QP row vector $kRmod{q}_i$ for integer $k$.

parameter_row_start_for

method

def parameter_row_start_for(tensor: torch.Tensor, *, include_p: bool, rns_dimension: int=-2, parameter_row_start: int | None=None) -> int: ...

Resolve the context row interval used by a physical RNS operand.

rns_parameters_for

method

def rns_parameters_for(tensor: torch.Tensor, *, include_p: bool=False, rns_dimension: int=-2, parameter_row_start: int | None=None) -> torch.Tensor: ...

Return [parameter, limb] parameters aligned with an RNS operand.

The result is a zero-copy CUDA view with the context integral dtype. Column j describes tensor[..., j, :] exactly; this method does not mutate or alias the operand itself.

rns_parameters_for_prime_ids

method

def rns_parameters_for_prime_ids(prime_ids: tuple[int, ...]) -> torch.Tensor: ...

Return a zero-copy parameter view for contiguous local RNS rows.

row_parameters

method

def row_parameters(key) -> RnsRowParameters: ...

Return immutable host/device parameters for prime_ids.

basis_parameters

method

def basis_parameters(depth: int, *, include_p: bool=False) -> RnsRowParameters: ...

Return parameters for the Q or QP rows active at depth.

twice_modulus_for_basis

method

def twice_modulus_for_basis(depth: int, *, include_p: bool=False) -> torch.Tensor: ...

Return integral row vector $[2q_i]$ for the active basis.

moduli_for_basis

method

def moduli_for_basis(depth: int, *, include_p: bool=False) -> list[int]: ...

Return host integers in the active basis's prime_ids order.

to_montgomery_

method

def to_montgomery_(a: torch.Tensor, *, include_p: bool=False, prime_ids: tuple[int, ...] | None=None) -> None: ...

Replace each standard residue $x_i$ by $x_{i}Rmod{q}_i$.

a is coefficient- or NTT-domain [*batch, limb, N] in the lazy interval $[0,2q_i)$. The integral tensor is mutated in place and remains lazy Montgomery RNS with unchanged axes and prime rows.

montgomery_mul_row_scalars_

method

def montgomery_mul_row_scalars_(a: torch.Tensor, b: torch.Tensor, *, include_p: bool=False) -> None: ...

Mutate a[..., i, :] to $a_i{b}_i{R}^{-1}mod{q}_i$.

b has shape [limb] and stores Montgomery scalars aligned with the same prime rows. The operation preserves whether a uses standard or Montgomery residues, preserves polynomial domain, and returns a lazy representative in $[0,2q_i)$.

montgomery_mul_row_scalars_standard

method

def montgomery_mul_row_scalars_standard(a: torch.Tensor, b: torch.Tensor, *, include_p: bool=False) -> torch.Tensor: ...

Return least nonnegative $a_i{b}_i{R}^{-1}mod{q}_i$ row products.

a is integral [*batch, limb, index] and b is the aligned Montgomery [limb] scalar vector for the same prime rows. The operation preserves a's standard or Montgomery representation and polynomial domain. Output lies in $[0,q_i)$ and aliases neither input.

montgomery_mul

method

def montgomery_mul(a: torch.Tensor, b: torch.Tensor, *, include_p: bool=False, prime_ids: tuple[int, ...] | None=None) -> torch.Tensor: ...

Return $a_i{b}_i{R}^{-1}mod{q}_i$ without mutating either input.

Operands have equal [*batch, limb, N] layouts, integral dtype, prime-row mapping, polynomial domain, and Montgomery form. The output has the same state, is lazy in $[0,2q_i)$, and aliases neither input.

montgomery_mul_cyclic_compressed

method

def montgomery_mul_cyclic_compressed(a: torch.Tensor, compressed_b: torch.Tensor, *, include_p: bool=False, prime_ids: tuple[int, ...] | None=None) -> torch.Tensor: ...

Multiply by a cyclically repeated compact Montgomery operand.

a is integral [*batch, limb, N] and compressed_b is [*compressed_batch, limb, unique_index] on the same device, domain, prime rows, and Montgomery form. The compact final axis repeats cyclically to extent $N$. After leading axes are collapsed, the compact batch count must equal the dense batch count or be one; no other broadcasting occurs. Output is lazy Montgomery RNS and aliases neither input.

montgomery_mul_contiguous_compressed

method

def montgomery_mul_contiguous_compressed(a: torch.Tensor, compressed_b: torch.Tensor, *, include_p: bool=False, prime_ids: tuple[int, ...] | None=None) -> torch.Tensor: ...

Multiply by a block-repeated compact Montgomery operand.

Tensor state and broadcasting match montgomery_mul_cyclic_compressed, but each compact value is repeated in one contiguous block along the expanded extent-$N$ axis. Output is lazy Montgomery RNS and aliases neither input.

from_montgomery_

method

def from_montgomery_(a: torch.Tensor, *, include_p: bool=False, prime_ids: tuple[int, ...] | None=None) -> None: ...

Replace $x_{i}Rmod{q}_i$ by standard $x_{i}mod{q}_i$ in place.

Shape, integral dtype, prime rows, polynomial domain, and storage are preserved. The output is lazy in $[0,2q_i)$.

reduce_to_standard_

method

def reduce_to_standard_(a: torch.Tensor, *, include_p: bool=False) -> None: ...

Reduce lazy $[0,2q_i)$ residues to $[0,q_i)$ in place.

Axes, integral dtype, prime rows, polynomial domain, residue representation, and storage are unchanged.

center_residues_

method

def center_residues_(a: torch.Tensor, *, include_p: bool=False) -> None: ...

Map $[0,q_i)$ residues to centered representatives in place.

Per prime row, $x_i>\lfloor q_i/2\rfloor$ maps to $x_i-q_i$; other residues remain unchanged. Input must be standard residues in $[0,q_i)$. Shape, integral dtype, prime rows, polynomial domain, and storage are preserved.

shift_residues_positive_

method

def shift_residues_positive_(a: torch.Tensor, *, include_p: bool=False) -> None: ...

Add $q_i$ to every centered representative in place.

This storage-preserving operation consumes the centered interval $[-\lfloor q_i/2\rfloor ,\lfloor q_i/2\rfloor ]$ and returns congruent positive lazy representatives in approximately $[q_i/2,3q_i/2]$; axes, integral dtype, prime rows, and polynomial domain remain.

add_lazy

method

def add_lazy(a: torch.Tensor, b: torch.Tensor, *, include_p: bool=False, prime_ids: tuple[int, ...] | None=None) -> torch.Tensor: ...

Return $(a_i+b_i)mod2q_i$ as lazy residues.

Equal-shape integral operands use the same domain, representation, and prime rows and lie in $[0,2q_i)$. Output has the same shape and state, lies in $[0,2q_i)$, and aliases neither input.

sub_lazy

method

def sub_lazy(a: torch.Tensor, b: torch.Tensor, *, include_p: bool=False) -> torch.Tensor: ...

Return $(a_i-b_i)mod2q_i$ as non-aliasing lazy residues.

lift_centered_coefficients

method

def lift_centered_coefficients(a: torch.Tensor, depth: int=0, *, include_p: bool=False) -> torch.Tensor: ...

Lift [*batch, coefficient] integers into coefficient RNS.

The input is an integral tensor of final extent $N$ with $-q_i<x<q_i$ for every selected prime. Output is [*batch, limb, coefficient] in standard representation with limb order rns_layout.prime_ids(depth, include_p=include_p) and lazy range $[0,2q_i)$. The functional result does not alias a.

lift_integer_coefficients_exact

method

def lift_integer_coefficients_exact(coefficients: torch.Tensor, depth: int=0, *, include_p: bool=False, max_abs: int | None=None) -> torch.Tensor: ...

Lift signed compact coefficients without a one-prime assumption.

For row $i$, the native centered lift stores $x+q_i$ as a lazy residue, so it is valid only while $-q_i<x<q_i$ for every active modulus. Wider machine integers require an actual remainder for each RNS row.

add_standard

method

def add_standard(a: torch.Tensor, b: torch.Tensor, *, include_p: bool=False, prime_ids: tuple[int, ...] | None=None) -> torch.Tensor: ...

Return $(a_i+b_i)mod{q}_i$ in $[0,q_i)$.

Equal-shape integral operands have layout [*batch, limb, coefficient_or_ntt_index], identical domain and residue representation, and the same prime rows. Output preserves that state and aliases neither input.

add_standard_

method

def add_standard_(a: torch.Tensor, b: torch.Tensor, *, include_p: bool=False, prime_ids: tuple[int, ...] | None=None) -> None: ...

Replace a by $(a_i+b_i)mod{q}_i$ in $[0,q_i)$.

The tensor layout and state requirements match add_standard; a storage is mutated in place, while b is read-only.

sub_standard

method

def sub_standard(a: torch.Tensor, b: torch.Tensor, *, include_p: bool=False, prime_ids: tuple[int, ...] | None=None) -> torch.Tensor: ...

Return $(a_i-b_i)mod{q}_i$ in $[0,q_i)$.

Equal-shape integral operands have layout [*batch, limb, coefficient_or_ntt_index], identical domain and residue representation, and the same prime rows. Output preserves that state and aliases neither input.

sub_standard_

method

def sub_standard_(a: torch.Tensor, b: torch.Tensor, *, include_p: bool=False, prime_ids: tuple[int, ...] | None=None) -> None: ...

Replace a by $(a_i-b_i)mod{q}_i$ in $[0,q_i)$.

The tensor layout and state requirements match sub_standard; a storage is mutated in place, while b is read-only.

lift_integer_coefficients_exact

function View source

def lift_integer_coefficients_exact(coefficients: torch.Tensor, twice_modulus: torch.Tensor, *, min_modulus: int, max_abs: int | None=None) -> torch.Tensor: ...

Lift machine integers into standard RNS rows, retaining native lazy representatives.