CKKS¶

Generated API reference for looking up CKKS classes and functions. Start with CKKS workflow for a runnable path, or CKKS concepts for the level, scale, and key model.

Core objects¶

`CKKSContext` `dataclass` ¶

Active CKKS parameter and key context.

Use with ctx: around operations that need parameter lookup, encryption, decryption, key switching, rotations, or level transitions. A context may hold only public key material for encryption/evaluation, or secret key material for local tests and decryption.

`get_galois_key(galois_elt)` ¶

Returns a Galois key for the given galois_elt.

`generate_relin_keys(rng=None)` ¶

Generate relinearization keys for all levels.

Pre-generates keys that enable ciphertext multiplication. Keys are stored in self.rlk.

`generate_rotation_keys(*, rotation_amounts_and_levels, rng=None)` ¶

Generate rotation keys.

Each (step, ks_level_index) pair generates a rotation by step whose key covers level ks_level_index (i.e. moduli levels[ks_level_index].moduli).

When the same step appears with multiple ks_level_index values, the largest level wins (it dominates: it can also serve operands at any smaller level).

`generate_conjugation_key(rng=None)` ¶

Generate conjugation key (always at bootstrap level).

`realize()` ¶

Realize all polynomials in this context (keys, etc).

`__reduce_ex__(protocol)` ¶

Realize all key material together before pickle reduces each poly one by one, so each Poly.__reduce__ hits the already-realized fast path instead of scheduling a separate realize per key poly.

Why __reduce_ex__ and not __reduce__: super().__reduce__() routes to object.__reduce__, which always uses pickle's protocol-0 reducer -- it reads state only from __dict__ or a class-defined __getstate__. This dataclass is slots=True (no __dict__) and, being non-frozen, gets no auto-generated __getstate__ (only frozen slotted dataclasses do), so that path raises TypeError unless we hand-write __getstate__/__setstate__. super().__reduce_ex__ avoids that boilerplate: it honors protocol and uses the modern, slots-aware reducer at protocol >= 2.

`precompute_bootstrap()` ¶

Precompute and realize bootstrap transform plans.

`Plaintext` `dataclass` ¶

Encoded CKKS slot vector backed by one polynomial.

Plaintexts carry the encoded polynomial plus scale/noise metadata. Most operations that read scale or level need an active CKKSContext.

`encrypt(rng=None)` ¶

Encrypt using the current context.

`to_level(level)` ¶

Drops a plaintext's level to the specified level, adjusting the scale accordingly.

Drops to one level above the target via CRT truncation (no rescaling), then multiplies by the appropriate integer factor and rescales once down to the target level.

`to_ciphertext()` ¶

Returns a trivial encryption of this plaintext.

`rotate(steps)` ¶

Rotate plaintext by the given number of steps.

Positive slot_count rotates left (slot[i] -> slot[i-slot_count]). Negative slot_count rotates right (slot[i] -> slot[i+slot_count]).

`Ciphertext` `dataclass` ¶

Bases: RLWECiphertext

Encrypted CKKS value backed by two polynomial components.

Ren names the components a and b. Ciphertexts also carry scale, level, and noise metadata used by arithmetic, alignment, and diagnostics.

`const(val, level=None)` `classmethod` ¶

Returns a trivial encryption of a constant value.

`zero(level=None)` `classmethod` ¶

Returns a trivial encryption of 0.

`one(level=None)` `classmethod` ¶

Returns a trivial encryption of 1.

`sum(cts)` `staticmethod` ¶

Sum a sequence of ciphertexts, possibly at mixed levels.

See :func:ren.schemes.ckks.arithmetic_ops.sum_ciphertexts.

`multiply(cts)` `staticmethod` ¶

Compute the product of multiple ciphertexts.

See :func:ren.schemes.ckks.arithmetic_ops.multiply_ciphertexts.

`dot(left, right)` `staticmethod` ¶

Heterogeneous dot product sum_i left[i] * right[i].

See :func:ren.schemes.ckks.arithmetic_ops.dot.

`to_level(level)` ¶

Drops a ciphertext's level to the specified level.

`rotate(step, *, max_ks=None)` ¶

rotate(step: int, *, max_ks: int | None = None) -> Ciphertext

rotate(step: list[int], *, max_ks: int | None = None) -> list[Ciphertext]

Rotate ciphertext by the given number of steps, or by a list of step amounts.

Positive slot_count rotates left (slot[i] -> slot[i-slot_count]). Negative slot_count rotates right (slot[i] -> slot[i+slot_count]).

`conjugate()` ¶

Returns a ciphertext encrypting the complex conjugate of what an input ciphertext was encrypting.

The implementation is very similar to the rotation method implementation.

`times_i()` ¶

Multiplies a ciphertext by i.

`clone(device=None)` ¶

Return a value-equivalent ciphertext backed by fresh polynomial storage.

Functions¶

`keygen(params, rng=None)` ¶

Generate a local CKKS context with secret, public, and switching keys.

`derive_context(params, sk=None, pk=None, generate_keys=True, rng=None)` ¶

Build a CKKS context from existing secret or public key material.

Provide a secret key when the caller needs decryption or local key generation. Provide only a public key when the caller should encrypt and compute without decrypting.

Parameters:

Name	Type	Description	Default
`params`	`CKKSParams`	CKKS parameter set that defines rings, levels, scales, and key requirements.	required
`sk`	`SecretKey \| None`	Optional secret key.	`None`
`pk`	`PublicKey \| None`	Optional public key.	`None`
`generate_keys`	`bool`	Generate relin, rotation, and conjugation keys when a secret key is available.	`True`
`rng`	`Random \| None`	Optional randomness source for generated keys.	`None`

Returns:

Type	Description
`CKKSContext`	A context ready to use with `with ctx:`.

`encode(values, *, msg_bound, level=None)` ¶

Encode Python values into a CKKS plaintext.

Slot i is placed at evaluation point ζ^(5^i), ensuring that the Galois automorphism σ_5 (x -> x^5) corresponds to slot rotation by 1.

Parameters:

Name	Type	Description	Default
`values`	`Sequence[complex] \| ndarray \| complex`	The values to encode. If a scalar, it is encoded as a constant polynomial, or equivalently as a polynomial with that value in every slot.	required
`msg_bound`	`float`	An upper bound on max(abs(value) for value in values), if values is a sequence, or on abs(values) if values is a scalar.	required
`level`	`int \| None`	Optional CKKS level. Defaults to the context's fresh-encryption level.	`None`

Returns:

Type	Description
`Plaintext`	A plaintext at the selected level.

Public metadata

msg_bound is public metadata. Do not compute it from secret values.

`decode(pt, length=None)` ¶

Decode a CKKS plaintext back to Python complex slot values.

`encrypt(pt, ring=None, rng=None)` ¶

Encrypt a plaintext using the active CKKS context.

The context must provide either a secret key or public key. When plaintext tracking is enabled on the parameter set, the returned ciphertext keeps local diagnostic values for tests and examples.

`decrypt(ct)` ¶

Decrypt a ciphertext using the active CKKS context's secret key.

`rerandomize(ct, rng=None)` ¶

Rerandomize a ciphertext by adding a random ciphertext of zero.

`bootstrap(ct_in, log_bound=None)` ¶

Bootstrap a ciphertext. In high precision mode, a log on the bound of the message must be provided, while in regular mode, it is not needed.

Parameters¶

`CKKSParams` `dataclass` ¶

Parameters for CKKS encryption.

CKKS now uses one explicit level model:

levels[level] gives the active moduli and nominal scale at that level
default_level is the highest normal compute / fresh-encryption level
highest_level is the highest level in the full schedule
levels above default_level are the bootstrap tail

A prefix schedule is one valid instance of this model.

Construction split:

from_levels(...) is the explicit constructor for hand-authored schedules, including u32 schedules.
generate_prefix(...) builds a generated prefix schedule.

`top_ks_level_bootstrap` `property` ¶

KS level over the full bootstrap-tail Q (relin, conj, bootstrap rotations).

`top_ks_level_compute` `property` ¶

KS level at fresh-encryption Q (compute-only rotation keys).

`mod_one_interval_length` `property` ¶

This function returns the length of the mod_one interval needed for bootstrapping to work with a negligible failure property (which is specified in the bootstrapping parameters).

To derive this, observe that the ModRaise step will modify all coefficients by some multiple of q=q_0. The goal is to find a bound on this multiple such that the bound is exceeded with probability at most p (failure probability).

Each coefficient of the raised polynomial is a sum of h numbers sampled uniformly from the interval [-q/2, q/2]. We want K for which

P(max_i |c_i| > K*q) < p

which is equivalent to

P(N(0, h*q^2/12) > K*q) < p/(2N)

which is equivalent to

P(N(0, 1) > K*sqrt(12/h)) < p/(2N)

Using the Mills Ratio P(Z > z) approx e^(-z^2/2) / (z*sqrt(2pi)) gives

P(Z > z) ~~ e^(-z^2/2)/(z*sqrt(2pi))
e^(-6K^2/h) * sqrt(h/(24pi)) / K = p/(2N)

and the goal is to solve for K. Equivalently,

-6K^2/h + 0.5*ln(h/(24pi)) - ln(K) = ln(p/(2N))
6K^2/h + ln(K) = ln((2N)/p) + 0.5*ln(h/(24pi))

A reasonable first approximation for K is

K ~~ sqrt(h/6 * (ln((2N)/p) + 0.5*ln(h/(24pi))))

and a better approximation is

K ~~ sqrt(h/6 * (ln((2N)/p) + 0.5*ln(h/(24pi)) - 0.5*ln(h/6 * (ln((2N)/p) + 0.5*ln(h/(24pi))))))

`from_levels(*, n, dtype, levels, ks_primes, boot_base_level=None, default_level=None, boot_params=None, meta_boot_params=None, multiparty_params=None, noise_dist=None, secret_key_dist=None, rotation_amounts_and_levels=None, can_conjugate=True, security=128, track_plaintext_values=None, strict_noise_bounds=True, boot_scale_correction=1.0)` `classmethod` ¶

Construct params from an explicit scheduled level list.

dtype is a property of the whole parameter set, not of individual levels. Every derived ring in this parameter set uses that one dtype.

bootstrap_rotation_amounts is always derived from boot_params via get_bootstrapping_rotation_amounts (empty if boot_params is None).

`generate_prefix(*, log_n, depth, log_precision, log_range, dtype, boot_params=None, meta_boot_params=None, multiparty_params=None, p_prime_count=2, rotation_amounts=set(), can_conjugate=True, noise_dist=None, security=128, strict_noise_bounds=True)` `classmethod` ¶

Build params from a generated prefix schedule.

`python_test(*, strict_noise_bounds=True)` `cached` `classmethod` ¶

Toy CKKS parameters for python tests (small and fast). Not secure.

`cuda_test(*, strict_noise_bounds=True)` `cached` `classmethod` ¶

Toy CKKS parameters for cuda tests (medium and fast). Not secure.

`default(*, track_plaintext_values=False, strict_noise_bounds=True)` `cached` `classmethod` ¶

Default CKKS parameters. These should achieve 128-bit security, but only if track_plaintext_values is False.

`high_precision_default(*, track_plaintext_values=False, strict_noise_bounds=True)` `cached` `classmethod` ¶

Default CKKS parameters for high precision.

`CKKSLevel` `dataclass` ¶

One scheduled CKKS level.

Parameters:

Name	Type	Description	Default
`moduli`	`tuple[int, ...]`	Active coefficient moduli at this level.	required
`scale`	`Scale`	Nominal plaintext scale at this level.	required

`CKKSTransition` `dataclass` ¶

A level transition in a CKKS parameter schedule.

Parameters:

Name	Type	Description	Default
`src_level`	`int`	Source level index.	required
`dst_level`	`int`	Destination level index.	required
`src_moduli`	`tuple[int, ...]`	Active moduli before the transition.	required
`dst_moduli`	`tuple[int, ...]`	Active moduli after the transition.	required
`src_scale`	`Scale`	Nominal scale before the transition.	required
`dst_scale`	`Scale`	Nominal scale after the transition.	required

`rescale_step(*, current_scale=None, correction_factor=1.0)` ¶

Return a :class:RescaleStep describing the rescale (m * k).rescale(...) that performs this transition.

If correction_factor is not provided, the post-transition ciphertext encrypts the same plaintext values as the pre-transition ciphertext. If correction_factor is provided, the post-transition ciphertext encrypts the pre-transition plaintext values multiplied by correction_factor.

The multiplier rounds to an integer, so the realized message-value ratio diverges slightly from correction_factor; tracking it via :attr:RescaleStep.message_ratio lets a chain of transitions stay scale-exact.

`BootstrappingParams` `dataclass` ¶

CKKS bootstrapping parameters.

Parameters:

Name	Type	Description	Default
`fft_depth`	`int`	Depth of coeff-to-slots and slots-to-coeffs.	required
`exp_degree`	`int`	Degree of the exponential approximation.	required
`squaring_count`	`int`	Number of repeated squaring steps in eval-mod.	required
`sk_hamming_weight`	`int`	Number of non-zero secret-key coefficients.	required
`failure_probability`	`float`	Target bootstrapping failure probability.	required

CKKS¶

Core objects¶

CKKSContext dataclass ¶

get_galois_key(galois_elt) ¶

generate_relin_keys(rng=None) ¶

generate_rotation_keys(*, rotation_amounts_and_levels, rng=None) ¶

generate_conjugation_key(rng=None) ¶

realize() ¶

__reduce_ex__(protocol) ¶

precompute_bootstrap() ¶

Plaintext dataclass ¶

encrypt(rng=None) ¶

to_level(level) ¶

to_ciphertext() ¶

rotate(steps) ¶

Ciphertext dataclass ¶

const(val, level=None) classmethod ¶

zero(level=None) classmethod ¶

one(level=None) classmethod ¶

sum(cts) staticmethod ¶

multiply(cts) staticmethod ¶

dot(left, right) staticmethod ¶

to_level(level) ¶

rotate(step, *, max_ks=None) ¶

conjugate() ¶

times_i() ¶

clone(device=None) ¶

Functions¶

keygen(params, rng=None) ¶

derive_context(params, sk=None, pk=None, generate_keys=True, rng=None) ¶

encode(values, *, msg_bound, level=None) ¶

decode(pt, length=None) ¶

encrypt(pt, ring=None, rng=None) ¶

decrypt(ct) ¶

rerandomize(ct, rng=None) ¶

bootstrap(ct_in, log_bound=None) ¶

Parameters¶

CKKSParams dataclass ¶

top_ks_level_bootstrap property ¶

top_ks_level_compute property ¶

mod_one_interval_length property ¶

generate_prefix(*, log_n, depth, log_precision, log_range, dtype, boot_params=None, meta_boot_params=None, multiparty_params=None, p_prime_count=2, rotation_amounts=set(), can_conjugate=True, noise_dist=None, security=128, strict_noise_bounds=True) classmethod ¶

python_test(*, strict_noise_bounds=True) cached classmethod ¶

cuda_test(*, strict_noise_bounds=True) cached classmethod ¶

default(*, track_plaintext_values=False, strict_noise_bounds=True) cached classmethod ¶

high_precision_default(*, track_plaintext_values=False, strict_noise_bounds=True) cached classmethod ¶

CKKSLevel dataclass ¶

CKKSTransition dataclass ¶

rescale_step(*, current_scale=None, correction_factor=1.0) ¶

BootstrappingParams dataclass ¶

`CKKSContext` `dataclass` ¶

`get_galois_key(galois_elt)` ¶

`generate_relin_keys(rng=None)` ¶

`generate_rotation_keys(*, rotation_amounts_and_levels, rng=None)` ¶

`generate_conjugation_key(rng=None)` ¶

`realize()` ¶

`__reduce_ex__(protocol)` ¶

`precompute_bootstrap()` ¶

`Plaintext` `dataclass` ¶

`encrypt(rng=None)` ¶

`to_level(level)` ¶

`to_ciphertext()` ¶

`rotate(steps)` ¶

`Ciphertext` `dataclass` ¶

`const(val, level=None)` `classmethod` ¶

`zero(level=None)` `classmethod` ¶

`one(level=None)` `classmethod` ¶

`sum(cts)` `staticmethod` ¶

`multiply(cts)` `staticmethod` ¶

`dot(left, right)` `staticmethod` ¶

`to_level(level)` ¶

`rotate(step, *, max_ks=None)` ¶

`conjugate()` ¶

`times_i()` ¶

`clone(device=None)` ¶

`keygen(params, rng=None)` ¶

`derive_context(params, sk=None, pk=None, generate_keys=True, rng=None)` ¶

`encode(values, *, msg_bound, level=None)` ¶

`decode(pt, length=None)` ¶

`encrypt(pt, ring=None, rng=None)` ¶

`decrypt(ct)` ¶

`rerandomize(ct, rng=None)` ¶

`bootstrap(ct_in, log_bound=None)` ¶

`CKKSParams` `dataclass` ¶

`top_ks_level_bootstrap` `property` ¶

`top_ks_level_compute` `property` ¶

`mod_one_interval_length` `property` ¶

`generate_prefix(*, log_n, depth, log_precision, log_range, dtype, boot_params=None, meta_boot_params=None, multiparty_params=None, p_prime_count=2, rotation_amounts=set(), can_conjugate=True, noise_dist=None, security=128, strict_noise_bounds=True)` `classmethod` ¶

`python_test(*, strict_noise_bounds=True)` `cached` `classmethod` ¶

`cuda_test(*, strict_noise_bounds=True)` `cached` `classmethod` ¶

`default(*, track_plaintext_values=False, strict_noise_bounds=True)` `cached` `classmethod` ¶

`high_precision_default(*, track_plaintext_values=False, strict_noise_bounds=True)` `cached` `classmethod` ¶

`CKKSLevel` `dataclass` ¶

`CKKSTransition` `dataclass` ¶

`rescale_step(*, current_scale=None, correction_factor=1.0)` ¶

`BootstrappingParams` `dataclass` ¶