Scale and level lifecycle

Scale and level are independently tracked coordinates of CKKS value state in FHElium. The application chooses encoding scales and state transitions. Evaluator operations validate their input state and record the resulting scale, level, and active modulus rows.

This page defines the public scale and level coordinates, valid public levels, transition laws, compatibility requirements, and transition queries.

Scale-level transition state

A scale- or level-changing operation is described by the tuple

$$\mathcal{T}(v)=(\ell (v),\mathrm{\Delta }(v),I(v),B(v)),$$

where:

• $\ell (v)$ is the public Q-chain level stored as value.level;
• $\mathrm{\Delta }(v)$ is the positive finite binary64 actual scale stored as value.scale;
• $I(v)$ is the ordered tuple value.prime_ids that maps each dense limb row to one canonical parameter prime;
• $B(v)$ is the modulus basis, either $Q_{\ell }$ or $Q_{\ell }P$.

level and scale are independent coordinates. Level selects the active Q suffix, basis independently selects Q or QP, and prime_ids records the resulting RNS rows. Complete operation compatibility also includes context, shape, polynomial domain, residue representation, component count, dtype, and device.

Default scale and actual scale

config.default_scale is the default encoding and planning value

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

engine.plaintext, engine.encode, and engine.encrypt_message select ${\mathrm{\Delta }}_0$ when their scale argument is None. Once a value exists, its scale field is the actual scale used by subsequent arithmetic and decoding.

The configured scale primes are close to ${\mathrm{\Delta }}_0$, but they are distinct integers selected from the prime catalog. Consequently, a default-scale product followed by rescale normally has

$$\frac{{\mathrm{\Delta }}_0^2}{q_{\mathrm{drop}}}\ne {\mathrm{\Delta }}_0.$$

FHElium records the binary64 quotient by the actual dropped prime.

All public scale entry points and value constructors require a value that can be represented as a finite Python float and satisfies

$$0<\mathrm{\Delta }(v)<\mathrm{\infty }.$$

NaN, infinity, zero, negative values, booleans, and strings are rejected with InvalidScaleError. A scale multiplication or division that overflows or underflows the finite-positive range is rejected at the operation that produces it.

Level addresses active Q rows

Let a configuration contain $C=\mathtt{config}\mathtt{.}\mathtt{num}\mathtt{\_}\mathtt{scale}\mathtt{\_}\mathtt{primes}$ scale primes followed by one structural base Q prime:

$$Q_0=[q_0,q_1,\dots ,q_{C-1},q_b].$$

The complete ordinary-prime count is therefore

$$\mathtt{config}\mathtt{.}\mathtt{num}\mathtt{\_}\mathtt{q}\mathtt{\_}\mathtt{primes}=C+1.$$

At public level $\ell$, the active Q basis is the suffix

$$Q_{\ell }=[q_{\ell },q_{\ell +1},\dots ,q_{C-1},q_b],0\le \ell <C.$$

In the current canonical layout, a complete Q value has

value.prime_ids == engine.rns_layout.prime_ids(value.level)

and a QP value at the same level appends every special P prime ID. level selects the canonical Q suffix, and prime_ids maps each dense limb to its modulus. QP is the auxiliary basis at that level.

Expanded diagram

100%

engine.public_level_count is $C$, and engine.final_public_level is $C-1$. Public value creation accepts levels in [0, engine.final_public_level]. Public rescale_to_next_level and mod_switch_to_next_level require a following public level, so from level $\ell$ the number of remaining public one-level transitions is

$$\mathtt{engine}\mathtt{.}\mathtt{final}\mathtt{\_}\mathtt{public}\mathtt{\_}\mathtt{level}-\ell .$$

The built-in bootstrap entry consumes the final public level and performs the private transition to [q_b]. Its compiled scale policy is documented in Composable CKKS bootstrap.

Scale-level transition laws

The following laws define multiplication, rescale, modulus switch, and scale reinterpretation.

Expanded diagram

100%

Multiplication preserves level and multiplies scale

For compatible ciphertext operands,

$$\mathrm{\Delta }(c_{\mathrm{out}})=\mathrm{\Delta }(c_a)\mathrm{\Delta }(c_b),\ell (c_{\mathrm{out}})=\ell (c_a)=\ell (c_b).$$

multiply_plaintext applies the same scale-product law to a ciphertext and an operation-ready plaintext. Both multiplication primitives require and return NTT/Montgomery ciphertext state, preserve the active Q basis, and expose domain transitions separately from scale arithmetic.

Rescale changes level, scale, rows, and payload

At a non-final public level, let $q_{\mathrm{drop}}$ be the leading active Q prime. rescale_to_next_level computes

$$c^{\prime }=\mathrm{Round}\left(\frac{c}{q_{\mathrm{drop}}}\right)(\mathrm{mod}{B}_{\ell +1})$$

and records

$${\ell }^{\prime }=\ell +1,{\mathrm{\Delta }}^{\prime }=\frac{\mathrm{\Delta }}{q_{\mathrm{drop}}},I^{\prime }=I[1:].$$

For QP input, the leading Q row is removed and every P row is retained. rounding="nearest" and rounding="floor" select different quotient laws but have the same metadata transition.

Modulus switch advances level and preserves scale

For a target public level $t\ge \ell$, mod_switch_to_level restricts each residue polynomial to the target active basis:

$$c^{\prime }=c(\mathrm{mod}{B}_t),{\ell }^{\prime }=t,{\mathrm{\Delta }}^{\prime }=\mathrm{\Delta }.$$

The operation restricts residues to the target basis while preserving their coefficient representatives. Message preservation requires that the centered represented value remain within the smaller target modulus.

Scale reinterpretation changes metadata and decoded meaning

reinterpret_at_scale(ciphertext, target_scale) leaves every ciphertext residue unchanged and records the requested target scale:

$$c^{\prime }=c,{\ell }^{\prime }=\ell ,{\mathrm{\Delta }}^{\prime }={\mathrm{\Delta }}_{\mathrm{target}}.$$

Because decoding divides by the recorded scale, the interpreted message changes according to

$$m^{\prime }=m\frac{{\mathrm{\Delta }}_{\mathrm{old}}}{{\mathrm{\Delta }}_{\mathrm{target}}}.$$

Its optional max_relative_change argument bounds the symmetric ratio between the current and target scales. Addition requires scale compatibility before evaluation.

Addition and subtraction require compatible state

Addition and subtraction preserve level and scale, but only after the operands already satisfy their exact compatibility requirements:

$${\ell }_a={\ell }_b,\mathrm{\Delta }(a)=\mathrm{\Delta }(b)$$

with binary64 equality, together with equal context, shape, component count, domain, basis, residue representation, and exact prime IDs. A scale difference of one unit in the last place is a mismatch. add, subtract, sum_ciphertexts, and add_plaintext accept values that already satisfy this set of requirements.

Programs align the two axes separately:

1. choose encoding scales and multiplication histories that produce compatible actual scales;
2. use mod_switch_to_level when only the active Q level must advance;
3. apply guarded reinterpret_at_scale when the resulting message-ratio change is part of the numerical policy.

Scale and level effects by operation family

Operation family	Level requirements and effects	Scale requirements and effects
plaintext, encode, encrypt_message	Set the requested public level	Set the requested scale; an omitted argument selects config.default_scale
encrypt, decrypt	Preserve	Preserve
RNS, NTT, coefficient-domain, and residue conversions	Preserve	Preserve
add, subtract, sum_ciphertexts, add_plaintext	Require equality; preserve	Require binary64 equality; preserve
negate, relinearize, switch_key, rotations, conjugation	Preserve	Preserve
multiply, multiply_plaintext	Require equality; preserve	Record the product of operand scales
rescale_to_next_level	Advance by one	Divide by the actual dropped Q prime
mod_switch_to_next_level	Advance by one	Preserve
mod_switch_to_level	Set the requested reachable public level	Preserve
reinterpret_at_scale	Preserve	Replace with the requested scale

Exact signatures, representation preconditions, exceptions, result allocation, and in-place alias behavior are specified by the generated API reference and method docstrings. Primitive representation, domain, and residue conversions are defined in State transitions and orthogonality. Arithmetic, component-count, and key-dependent effects are described in Evaluator operation transitions.

Query the exact rescale transition

The engine exposes the same level-dependent divisor and binary64 quotient used by rescale_to_next_level:

q_drop = engine.rescale_to_next_drop_prime(level=ciphertext.level)
predicted_scale = engine.rescale_to_next_output_scale(
    input_scale=pre_rescale_scale,
    level=ciphertext.level,
)

assert predicted_scale == pre_rescale_scale / q_drop

These queries return the modulus and scale arithmetic of one transition from an provided source level and input scale.

Binary64 expression ordering is observable. Branches that will be added use a common scale calculation history so their scale metadata satisfies binary64 equality.

Continue

• Context and modulus chain
• Value model and identity
• State transitions and orthogonality
• Evaluator operation transitions
• Basic CKKS workflow
• Explicit scale-management tutorial
• Composable CKKS bootstrap
• Choose a preset and chain depth