fhelium.config.ckks

Define CKKS parameter presets and the validated configuration model.

Preset

class View source

Preset()

Bases: Enum

Maintained CKKS parameter baselines.

Each member name records the complex slot capacity, default scale-prime bit width, number of public levels, and integral tensor dtype in its baseline configuration. int32 members use the 30-bit residue buffer; int64 members use the 62-bit residue buffer. All baselines select the 128-bit classical security category, Gaussian error standard deviation 3.19, uniform-ternary secret sampling, and a ring-specific P-prime count. CkksConfig.parse accepts keyword overrides when an application needs a derived configuration.

Attributes

Name	Type	Default/value
slots8192_scale30_levels9_int64		'slots8192-scale30-levels9-int64'
slots8192_scale40_levels7_int64		'slots8192-scale40-levels7-int64'
slots8192_scale50_levels5_int64		'slots8192-scale50-levels5-int64'
slots16384_scale30_levels21_int64		'slots16384-scale30-levels21-int64'
slots16384_scale40_levels16_int64		'slots16384-scale40-levels16-int64'
slots16384_scale50_levels12_int64		'slots16384-scale50-levels12-int64'
slots32768_scale30_levels45_int64		'slots32768-scale30-levels45-int64'
slots32768_scale40_levels34_int64		'slots32768-scale40-levels34-int64'
slots32768_scale50_levels27_int64		'slots32768-scale50-levels27-int64'
slots65536_scale30_levels95_int64		'slots65536-scale30-levels95-int64'
slots65536_scale40_levels72_int64		'slots65536-scale40-levels72-int64'
slots65536_scale50_levels58_int64		'slots65536-scale50-levels58-int64'
slots8192_scale25_levels14_int32		'slots8192-scale25-levels14-int32'
slots16384_scale25_levels29_int32		'slots16384-scale25-levels29-int32'
slots32768_scale25_levels24_int32		'slots32768-scale25-levels24-int32'
slots65536_scale25_levels14_int32		'slots65536-scale25-levels14-int32'

CkksConfig

class View source

CkksConfig(*, buffer_bit_length: int=62, scale_bits: int=40, base_prime_bits: int | None=None, logN: int=15, num_scale_primes: int | None=16, num_p_primes: int=2, sigma: float=3.19, security_bits: int=128, enforce_security_budget: bool=True)

Immutable CKKS mathematical and security parameters.

The configuration defines CKKS over $R=\mathbb{Z}[X]/(X^N+1)$, where $N=2^{\mathtt{logN}}$ and the complex slot count is $S=N/2$. Compatible values and keys share this cryptographic context.

At public level $\ell$, the active ordinary ciphertext modulus is $Q_{\ell }=\prod _{i\in I_{\ell }}{q}_i$. num_scale_primes is the positive number of scale-prime rows selected into the Q chain and the number of public levels. The final public level contains the last scale prime and the structural base Q prime, so level zero has num_scale_primes - 1 public one-level transitions. num_q_primes includes the additional structural base. The bootstrap-entry transition produces the one-prime structural basis. The key-switch modulus is $P=\prod _j{p}_j$.

scale_bits selects ordinary scale primes and the default encoding/planning scale ${\mathrm{\Delta }}_0=2^{\mathtt{scale}\mathtt{\_}\mathtt{bits}}$. Value creation selects ${\mathrm{\Delta }}_0$ when the scale argument is omitted. Each live plaintext and ciphertext carries its actual scale $\mathrm{\Delta }(v)$. base_prime_bits independently selects the structural base Q prime. An omitted value selects the message-prime catalog width. The packaged catalog accepts a provided value equal to scale_bits.

total_modulus_bits covers the complete QP parameter modulus, both $Q_0$ and $P$, and maximum_modulus_bits is the corresponding security budget. The exact built-in table supports Gaussian error standard deviation sigma=3.19 and classical categories 128, 192, and 256. Engine construction checks the complete QP product before native initialization when enforce_security_budget is true. Disabling that check transfers parameter and sampler assessment to the caller.

dumps

method

def dumps() -> dict[str, object]: ...

Serialize to a dictionary for easy saving or logging.

parse

method

def parse(src: Mapping[str, Any] | Preset, **overrides: Any) -> 'CkksConfig': ...

Resolve a parameter baseline into a CKKS configuration.

src is either a maintained Preset or a mapping accepted by CkksConfig. Keyword overrides replace fields from that baseline before configuration validation and derived-value evaluation.

N

property

N: int

Ring dimension $N=2^{\mathtt{logN}}$ for $R$.

The corresponding complex CKKS slot count is $S=N/2$.

inverse_ntt_scale

property

inverse_ntt_scale: tuple[int, ...]

Return $N^{-1}modm$ for every Q/P modulus row $m$.

The result follows moduli order: ordinary $q_i$ rows followed by special $p_j$ rows. Each value is the normalization factor used by the inverse NTT for that row.

int_scale

property

int_scale: int

Integer default scale ${\mathrm{\Delta }}_0=2^{\mathtt{scale}\mathtt{\_}\mathtt{bits}}$.

default_scale

property

default_scale: float

Binary64 default encoding and planning scale ${\mathrm{\Delta }}_0$.

Value creation selects this scale when its scale argument is omitted. Arithmetic reads and updates the actual scale stored on each value.

torch_dtype

property

torch_dtype: Any

message_bits

property

message_bits: int

Legacy message-prime catalog width used for structural Q and P.

This name does not denote CKKS message precision. Renaming the catalog selector and its packaged resources requires a separate versioned catalog migration.

maximum_modulus_bits

property

maximum_modulus_bits: int

Exact built-in budget for the complete QP modulus bit width.

Raises

• SecurityParametersUnsupportedError: If this configuration does not match an exact table row.

security_assessment

property

security_assessment: SecurityAssessment

Structured exact-table assessment of the complete QP modulus.

num_scale_primes

property

num_scale_primes: int

Number of selected scale-prime rows and ordinary public levels.

Public levels are [0, num_scale_primes). The final public level retains one scale prime plus the structural base, giving num_scale_primes - 1 public transitions from level zero. The count is at least one. A configured count is validated against catalog capacity when moduli is constructed. An omitted count is filled greedily within the security-table modulus-bit budget.

Raises

• ValueError: If automatic derivation cannot fit one scale prime in the security budget.

moduli

property

moduli: tuple[int, ...]

Complete ordered QP parameter-modulus list.

The order is [scale_q_primes, structural_q_prime, p_primes]. The ordinary rows form $Q_0=\prod _i{q}_i$, and the special rows form $P=\prod _j{p}_j$.

q_moduli

property

q_moduli: tuple[int, ...]

Ordered ordinary-prime rows whose level subsets form $Q_{\ell }$.

p_moduli

property

p_moduli: tuple[int, ...]

Ordered special-prime rows whose product is $P$.

num_q_primes

property

num_q_primes: int

Number of ordinary Q primes, including one structural base prime.

Therefore $\mathtt{num}\mathtt{\_}\mathtt{q}\mathtt{\_}\mathtt{primes}=\mathtt{num}\mathtt{\_}\mathtt{scale}\mathtt{\_}\mathtt{primes}+1$.

total_num_primes

property

total_num_primes: int

Number of rows in the complete QP parameter basis.

total_modulus_bits

property

total_modulus_bits: int

Bit width $\lceil {\log }_2(Q_{0}P)\rceil$ of the complete QP modulus.

This value covers both ordinary Q primes and special P primes; it is not the width of Q alone.

validate_security_budget

method

def validate_security_budget() -> SecurityAssessment: ...

Require an exact supported assessment that meets its QP budget.

Returns

The immutable structured assessment when the budget is met.

Raises

• SecurityParametersUnsupportedError: If no exact built-in row matches this configuration.
• SecurityBudgetExceededError: If the complete QP modulus exceeds the matching table budget.