fhelium.engine.rns.runtime

RnsRuntime

class View source

RnsRuntime(ckks_config: CkksConfig, device: str | torch.device | None=None, ntt_backend: str | None=None)

Own one engine's dense RNS parameters and representation transitions.

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 canonical parameter id is prime_ids[j]. Public full-basis calls derive those ids from level and internal calls supply parameter_row_start for an exact 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. Forward NTT maps coefficient index to NTT index and inverse NTT maps it back, independently for every batch item and prime row.

rns_basis_level_count

property

rns_basis_level_count: int

Number of RNS row-suffix levels, including private structural levels.

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 engine 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 canonical local RNS rows.

row_parameters

method

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

Return immutable host/device parameters for exact prime_ids.

basis_parameters

method

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

Return parameters for the exact Q or QP rows active at level.

twice_modulus_for_basis

method

def twice_modulus_for_basis(level: 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(level: int, *, include_p: bool=False) -> list[int]: ...

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

to_montgomery_

method

def to_montgomery_(a: torch.Tensor, *, include_p: bool=False) -> 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 is aligned with the same exact prime rows. Both inputs use one integral dtype and Montgomery form; polynomial domain is preserved and the result is lazy in $[0,2q_i)$.

montgomery_mul_row_scalars_canonical

method

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

Return canonical $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 exact prime rows. Polynomial domain is preserved. Output has canonical Montgomery residues 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, exact 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, exact 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) -> None: ...

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

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

canonicalize_residues_

method

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

Reduce lazy $[0,2q_i)$ residues to canonical $[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 canonical 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 canonical standard residues. 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 exact 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, level: 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(level, 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, level: 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_canonical

method

def add_canonical(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 canonical $[0,q_i)$ form.

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

add_canonical_

method

def add_canonical_(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 canonical form.

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

sub_canonical

method

def sub_canonical(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 canonical $[0,q_i)$ form.

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

sub_canonical_

method

def sub_canonical_(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 canonical form.

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

forward_montgomery_

method

def forward_montgomery_(a: torch.Tensor, *, include_p: bool=False, parameter_row_start: int | None=None) -> None: ...

Apply the negacyclic forward NTT to Montgomery residues in place.

a maps from [*batch, limb, coefficient] to the same storage viewed as [*batch, limb, ntt_index]. For row $i$ it evaluates the polynomial modulo $X^N+1$ and $q_i$ at the backend's canonical NTT points. Integral CUDA dtype, exact prime rows, Montgomery form, and lazy $[0,2q_i)$ range are preserved.

forward_to_montgomery_

method

def forward_to_montgomery_(a: torch.Tensor, *, include_p: bool=False, parameter_row_start: int | None=None) -> None: ...

Apply forward NTT and standard-to-Montgomery conversion in place.

The state transition is coefficient + standard to ntt + montgomery on unchanged [*batch, limb, N] integral storage and exact prime rows; output is lazy in $[0,2q_i)$.

forward_to_montgomery

method

def forward_to_montgomery(a: torch.Tensor, *, include_p: bool=False, parameter_row_start: int | None=None) -> torch.Tensor: ...

Return the non-aliasing forward NTT/Montgomery transition.

inverse_montgomery_

method

def inverse_montgomery_(a: torch.Tensor, *, include_p: bool=False, parameter_row_start: int | None=None) -> None: ...

Apply normalized inverse NTT while retaining Montgomery form.

Per prime row normalization multiplies by $N^{-1}Rmod{q}_i$ under Montgomery reduction. The integral tensor changes from NTT indices to coefficients in place; exact rows, storage, Montgomery representation, and lazy $[0,2q_i)$ range remain.

inverse_to_standard_lazy_

method

def inverse_to_standard_lazy_(a: torch.Tensor, *, include_p: bool=False, parameter_row_start: int | None=None) -> None: ...

Inverse NTT to coefficient/standard lazy $[0,2q_i)$ in place.

inverse_to_standard_

method

def inverse_to_standard_(a: torch.Tensor, *, include_p: bool=False, parameter_row_start: int | None=None) -> None: ...

Inverse NTT to canonical coefficient/standard $[0,q_i)$ in place.

inverse_to_centered_

method

def inverse_to_centered_(a, *, include_p: bool=False, parameter_row_start: int | None=None) -> None: ...

Inverse NTT to centered coefficient/standard residues in place.