fhelium.config

CKKS parameter, NTT-policy, and security-assessment interfaces.

Public modules are named for the configured subject: ckks owns the CKKS parameter model, ntt owns NTT execution policies, and security assesses complete modulus sets against the published table built into FHElium. Private resource mechanisms use a leading underscore, as in _prime_catalog.

DEFAULT_CPU_NTT_BACKEND

constant View source

DEFAULT_CPU_NTT_BACKEND: Final[str] = 'radix2_indexed'

DEFAULT_NTT_BACKEND

constant View source

DEFAULT_NTT_BACKEND: Final[str] = 'radix2_compact_group8_smem8'

SUPPORTED_NTT_BACKENDS

constant View source

SUPPORTED_NTT_BACKENDS: Final = tuple(NTT_BACKEND_POLICIES)

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.

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'

SecurityAssessment

class View source

SecurityAssessment(status: Literal['meets', 'exceeds', 'unsupported'], ring_dimension: int, target_bits: int, secret_distribution: str, error_stddev: float, modulus_bits: int, maximum_modulus_bits: int | None, modulus_margin_bits: int | None, reason: str | None)

Immutable result of one exact built-in parameter assessment.

status is "meets" when $\lceil {\log }_{2}q\rceil$ is at most the exact table budget, "exceeds" when it is larger, and "unsupported" when no exact table row matches the assumptions. An unsupported result has None for maximum_modulus_bits and modulus_margin_bits. A negative modulus margin reports how far a supported parameter tuple exceeds its modulus budget; it is not a bit-security margin.

Attributes

Name	Type	Default/value
status	Literal['meets', 'exceeds', 'unsupported']
ring_dimension	int
target_bits	int
secret_distribution	str
error_stddev	float
modulus_bits	int
maximum_modulus_bits	int | None
modulus_margin_bits	int | None
reason	str | None

assess_config_security

function View source

def assess_config_security(config: CkksConfig) -> SecurityAssessment: ...

Assess a fhelium.config.CkksConfig complete QP modulus.

assess_security

function View source

def assess_security(ring_dimension: int, *, modulus: int | None=None, moduli: Sequence[int] | None=None, target_bits: int=128, secret_distribution: str='ternary', error_stddev: float=_TABLE_ERROR_STANDARD_DEVIATION) -> SecurityAssessment: ...

Assess a complete modulus against one exact built-in budget row.

Parameters

• ring_dimension: Polynomial-ring dimension N.
• modulus: Exact complete parameter modulus q. For CKKS hybrid key switching this is Q * P.
• moduli: Exact factors of the complete parameter modulus. Specify this or modulus, but not both.
• target_bits: Classical security category.
• secret_distribution: Exact table secret distribution, "ternary" or "gaussian".
• error_stddev: Gaussian error standard deviation. The built-in budgets support exactly 3.19.

Returns

A structured assessment with status, exact integer modulus-bit width, budget, margin, and an unsupported reason when applicable. Parameters without an exact row return status="unsupported"; this function never interpolates or extrapolates.

Raises

• TypeError: If an input has the wrong structural type.
• ValueError: If a numeric input is non-positive or non-finite, or the modulus inputs are missing or ambiguous.

compatible_ntt_backends

function View source

def compatible_ntt_backends(log_ring_dimension: int) -> tuple[str, ...]: ...

Return canonical policy names executable for one logN.

Names retain registry order. Strict fixed-radix policies whose digit width does not divide log_ring_dimension are omitted; grouped radix-2 policies remain available for every supported ring dimension. A non-positive dimension raises ValueError.