# CKKS workflow

Use this page to choose a parameter set, create a context, encode values, encrypt, compute, decrypt, and decode. Read [CKKS concepts](<https://ren-docs.pages.dev/concepts/ckks-model/index.md>) for levels, scale, keys, and bootstrapping.

CKKS is an approximate-number homomorphic encryption scheme. It packs real or complex values into encrypted slots, then lets code add, multiply, rotate, and combine those slots without decrypting them. Ciphertexts carry scale, level, and noise metadata, and CKKS operations update that metadata while Ren schedules the underlying polynomial work.

flowchart TB A\["CKKSParams"\] B\["CKKSKeySet"\] C\["CKKSContext"\] D\["encode(values)"\] E\["encrypt(plaintext)"\] F\["encrypted compute"\] G\["decrypt(ciphertext)"\] H\["decode(plaintext)"\] A --\> B --\> C --\> D --\> E --\> F --\> G --\> H

## First computation

```python
import numpy as np

from ren.schemes.ckks import CKKSParams, decode, decrypt, encode, encrypt, keygen


params = CKKSParams.python_test()
keys = keygen(params)
ctx = keys.context()

values = np.array([0.25, 0.5, 0.75, 1.0])

with ctx:
    pt = encode(values, msg_bound=1.0)
    ct = encrypt(pt)
    result = ct + 1
    level = result.level
    decoded = decode(decrypt(result), length=len(values))

print("level:", level)
print("slots:", [round(z.real, 3) for z in decoded])
```

```
level: 5
slots: [1.25, 1.5, 1.75, 2.0]
```

The example decodes the first four slots: `[0.25, 0.5, 0.75, 1.0]` becomes `[1.25, 1.5, 1.75, 2.0]`. Sequence encoding pads the remaining CKKS slots with zeros, and scalar constants apply to every slot, including that padded tail. The level stays at the fresh-encryption level because adding an integer scalar does not rescale.

`CKKSParams.python_test()` gives you a small, non-secure local-test parameter set. Use it for examples, unit tests, and CPU-only local experiments. For production or user-data workloads, choose parameters after reviewing security, precision, depth, and bootstrap requirements.

## Encode and decode slots

Encoding is the boundary between Python values and CKKS plaintext slots. A sequence shorter than `params.slot_count` fills the first slots and pads the rest with zeros; a scalar encodes the same value in every slot. `decode(pt, length=...)` returns a prefix of the decoded slot vector, while omitting `length` returns the full vector.

```python
import numpy as np

from ren.schemes.ckks import CKKSParams, decode, encode, keygen


params = CKKSParams.python_test()
keys = keygen(params)
ctx = keys.context()
values = np.array([0.25, 0.5, 0.75, 1.0])

with ctx:
    pt = encode(values, msg_bound=1.0)
    decoded = decode(pt, length=len(values))

print("decoded:", [round(float(x.real), 3) for x in decoded])
```

```
decoded: [0.25, 0.5, 0.75, 1.0]
```

## Basic workflow

A local CKKS run has these steps:

```python
from ren.schemes.ckks import CKKSParams, decode, decrypt, encode, encrypt, keygen


params = CKKSParams.python_test()
keys = keygen(params)
ctx = keys.context()

with ctx:
    pt = encode([1.0, 2.0, 3.0], msg_bound=4)
    ct = encrypt(pt)
    out = (ct + 1) * 0.5
    values = decode(decrypt(out), length=3)

print("slots:", [round(z.real, 3) for z in values])
```

```
slots: [1.0, 1.5, 2.0]
```

The `with ctx:` block makes `ctx` active. The active context provides parameters and key material for encode, encrypt, decrypt, arithmetic alignment, key switching, rotations, and level transitions.

> [!WARNING]
>
> **Message bounds are public**
>
> `msg_bound` must be independent of secret data. Do not compute it from secret values, such as `max(abs(v) for v in secret_values)`. Choose a bound from the public input contract.

## Objects you will see

`CKKSParams` describes the slot count, explicit level schedule, nominal scales, key-switching primes, and optional bootstrapping parameters. `levels[level]` gives the active modulus basis and nominal scale at that level; `bootstrap_output_level` is where bootstrapping returns ciphertexts; `highest_level` is the top scheduled level; and `highest_ring` is both the ring at that level and the canonical Q basis owned by key material. Every scheduled ring is a contiguous window of `highest_ring`, but it need not be a prefix. When bootstrapping is enabled, `bootstrap_output_level` is derived from the highest level and the depth consumed by the bootstrap. `log_range` bounds ordinary messages by `2**log_range`; for bootstrapping parameters it is also the maximum accepted bootstrap `log_bound`.

`CKKSKeySet` owns device-resident key material. `CKKSKeySet.generate(params)` creates the secret, public, and relinearization keys plus any Galois keys requested through `rotations=` or `conjugation=`; bootstrapping requirements are included automatically, and `hoist_bootstrap_rotations=True` adds a direct key per bootstrap baby- and giant-step rotation so the linear transforms double-hoist, at a cost of a few times more rotation-key memory. `keygen(params)` is a convenience wrapper for the same operation. Pass `secret_key` to either function to generate keys from an existing secret, or construct `CKKSKeySet(...)` directly when assembling existing material without generating anything. `keys.context()` creates the runtime context for those keys.

`CKKSContext` is the active runtime view of a key set. Access its key material through `ctx.keyset`, for example `ctx.keyset.sk` or `ctx.keyset.get_galois_key(...)`. Entering it selects the key set's device for values created inside the block. Runtime policy lives on the context, not on the parameters: `keys.context(track_plaintext_values=True)` keeps diagnostic slot values on plaintexts and ciphertexts for tests and examples, and `keys.context(strict_noise_bounds=True)` raises when a tracked message bound exceeds q/2 instead of saturating it to unbounded. Contexts are not serialized; serialize the key set and create a fresh context after loading it.

Use Python's `pickle` for local snapshots of parameters, plaintexts, ciphertexts, key sets, and DKG state. Ren does not promise pickle compatibility across versions or define a stable serialization format. Only load pickles from trusted sources.

```python
import pickle

from ren.schemes.ckks import CKKSParams, keygen


params = CKKSParams.python_test()
keys = keygen(params)

payload = pickle.dumps(keys)
restored_keys = pickle.loads(payload)
ctx = restored_keys.context()
```

Pickling realizes lazy polynomials and stores their values, ring, and domain. Constants stay compact. Diagnostic plaintext tracking values and runtime contexts are not saved. A key-set pickle includes its secret key when present; use `keys.public()` to save only public material. DKG checkpoints include private participant state.

## Devices

`CKKSKeySet.generate(...)` and `keygen(...)` use the ambient `DEV` device by default. Pass `device` to select one explicitly, for example `keygen(params, device="cuda:1")`. When `secret_key` is provided, its device determines placement.

When an explicit RNG is provided, its device determines key placement. Passing both `device` and `rng` requires them to match.

`keys.context()` always uses the key set's device, regardless of the ambient device when the context is created. Entering the context selects that device for new plaintexts, ciphertexts, and polynomials, then restores the previous device on exit.

Move an existing key set before creating its context with `cuda_keys = keys.to("cuda:1")`.

Device placement is runtime state and is not serialized. Pickles load onto the active device; use `with Device.scope("cuda:1"):` around `pickle.loads(payload)` to select it.

Pass multiple device names to the example below, such as `uv run docs/examples/ckks-devices.py cuda:0 cuda:1`, to create one resident key set and context per GPU. Each `with contexts[device]:` block runs on that device; this does not split a single CKKS operation across devices.

```python
import sys

from ren.schemes.ckks import CKKSParams, decode, decrypt, encode, encrypt, keygen


devices = tuple(sys.argv[1:]) or ("python",)
params = CKKSParams.python_test()
keys = keygen(params, device=devices[0]).realize()
contexts = {device: keys.to(device).realize().context() for device in devices}

for device, ctx in contexts.items():
    with ctx:
        ciphertext = encrypt(encode([1.0, 2.0], msg_bound=2)).realize()
        decoded = decode(decrypt(ciphertext), length=2)

    values = [round(float(value.real), 3) for value in decoded]
    print(f"{device}: ciphertext={ciphertext.device}, values={values}")
```

```
python: ciphertext=python, values=[1.0, 2.0]
```

`Plaintext` wraps one encoded slot vector in the `Poly` field `m`.

`Ciphertext` wraps an encrypted value in two `Poly` fields, `a` and `b`, plus scale/noise metadata. Ren uses the `a`/`b` field names consistently; do not read them as a universal notation requirement outside this codebase. `Ciphertext` inherits `PolyContainer` for shared polynomial mapping, replacement and realization.

## Common operations

- `encode(values, msg_bound=...)` turns Python values into a CKKS `Plaintext`, padding any unused slots with zeros.
- `decode(pt, length=...)` converts a decrypted plaintext back to Python complex values. Pass `length` to read a prefix, or omit it to read all slots.
- `encrypt(pt)` turns a plaintext into a `Ciphertext` using the active context.
- `decrypt(ct)` returns a `Plaintext` using the active context's secret key.
- `ct + other`, `ct - other`, and `ct * other` build encrypted arithmetic over ciphertexts, plaintexts, or scalars.
- `pt + other`, `pt - other`, `-pt`, and `pt * other` build plaintext arithmetic over plaintexts or scalars. As with ciphertexts, a plaintext-plaintext or plaintext-float multiply rescales and consumes a level, because a plaintext's scale is fixed by its ring; multiplying by an integer does not.
- `Ciphertext.sum(...)`, `Ciphertext.multiply(...)`, and `Ciphertext.dot(...)` provide higher-level reductions.
- `ct.rotate(step)` rotates packed slots when the context has the required rotation key.
- `ct.to_level(level)` drops a ciphertext to a lower level when operations need alignment. Quotient-only ranges use CRT truncation followed by one rescale when the working ring has enough capacity. Other ranges rescale directly to the destination ring and nominal scale.
- `ct.bootstrap(log_bound=...)` refreshes a ciphertext when the parameter set supports bootstrapping. The public bound must satisfy `abs(message) <= 2**log_bound`. Setting `BootstrappingParams(sparse_encapsulation_weight=h, ...)` uses an ephemeral sparse secret of weight `h` (down to 32) only around the bootstrap mod-raise, which shrinks the eval-mod interval and supports negligible failure probabilities ([Bossuat et al.](<https://eprint.iacr.org/2022/024>)). The scheme secret then defaults to dense, but a sparse one can still be requested with `generate_prefix(secret_key_dist=...)` — the interval is sized by `h` either way.

## Reusable circuit

Keep circuit code separate from local encode, encrypt, decrypt, and decode code. A reusable circuit should accept encrypted or plaintext Ren objects and return encrypted or plaintext Ren objects.

```python
from ren.schemes.ckks import CKKSParams, Ciphertext, decode, decrypt, encode, encrypt, keygen


def score(features: Ciphertext) -> Ciphertext:
    neighboring_sum = features + features.rotate(1)
    return (neighboring_sum * 0.25) + 0.5


params = CKKSParams.python_test()
keys = keygen(params, rotations={1})
ctx = keys.context()

inputs = [1.0, 2.0, 3.0, 4.0]

with ctx:
    encrypted = encrypt(encode(inputs, msg_bound=4))
    output = score(encrypted)
    decoded = decode(decrypt(output), length=len(inputs))
    level = output.level

print("level:", level)
print("slots:", [round(z.real, 3) for z in decoded])
```

```
level: 4
slots: [1.25, 1.75, 2.25, 1.5]
```

## Weighted sums

Use `Ciphertext.dot(...)` when you need a slotwise weighted sum across ciphertext, plaintext, scalar, or per-slot inputs.

```python
from ren.schemes.ckks import CKKSParams, Ciphertext, decode, decrypt, encode, encrypt, keygen


params = CKKSParams.python_test()
keys = keygen(params)
ctx = keys.context()

temperature = [1.0, 2.0, 3.0, 4.0]
humidity = [0.5, 1.0, 1.5, 2.0]
weights = [0.5, -0.25]

with ctx:
    encrypted_temperature = encrypt(encode(temperature, msg_bound=4))
    encrypted_humidity = encrypt(encode(humidity, msg_bound=2))
    weighted_sum = Ciphertext.dot([encrypted_temperature, encrypted_humidity], weights)
    decoded = decode(decrypt(weighted_sum), length=len(temperature))

print("weighted sum slots:", [round(z.real, 3) for z in decoded])
```

```
weighted sum slots: [0.375, 0.75, 1.125, 1.5]
```

## Rotations

Rotations move packed slots cyclically across the full CKKS slot vector. If an example decodes only a prefix, wrapped values may be outside the printed window. The context must have rotation key material for the steps your circuit uses.

```python
from ren.schemes.ckks import CKKSParams, decode, decrypt, encode, encrypt, keygen


params = CKKSParams.python_test()
keys = keygen(params, rotations={1})
ctx = keys.context()

values = [1.0, 2.0, 3.0, 4.0]

with ctx:
    encrypted = encrypt(encode(values, msg_bound=4))
    rotated = encrypted.rotate(1)
    window_sum = encrypted + rotated

    rotated_slots = decode(decrypt(rotated))
    sum_slots = decode(decrypt(window_sum))

rotated_slots = [round(z.real, 3) for z in rotated_slots]
sum_slots = [round(z.real, 3) for z in sum_slots]

print("rotated:", rotated_slots[:4], "...", rotated_slots[-1])
print("window sum:", sum_slots[:4], "...", sum_slots[-1])
```

```
rotated: [2.0, 3.0, 4.0, -0.0] ... 1.0
window sum: [3.0, 5.0, 7.0, 4.0] ... 1.0
```

## Levels and scale in practice

Fresh encryption starts at the context's `default_level`, which defaults to `params.default_level` and can be overridden at `keys.context(default_level=...)`. Addition keeps the level for aligned operands. Multiplication grows scale and noise. Ren uses rescale and level transitions to bring the represented value back to the level schedule. Level alignment converts to the requested destination without imposing intermediate rounding. An explicit sequence of rescale operations retains each rounding boundary, so it can produce different coefficients. Bootstrapping starts from the highest scheduled level and returns at `params.bootstrap_output_level`, which need not equal `default_level`.

A bootstrap base may use the same physical modulus ring as computation level 0 while assigning it a different logical scale. Ring-based scale lookup returns the scheduled computation scale; bootstrap code reads the distinct scale explicitly from `params.bootstrap_base_level.scale`.

Keep operands aligned before combining them. Most arithmetic paths align levels through the active `CKKSContext`; use `to_level(level)` when you want a specific boundary before a larger computation.

```python
from ren.schemes.ckks import CKKSParams, decode, decrypt, encode, encrypt, keygen


params = CKKSParams.python_test()
keys = keygen(params)
ctx = keys.context()

with ctx:
    x = encrypt(encode([1.0, 2.0, 3.0], msg_bound=3))
    y = encrypt(encode([0.5, 0.25, 0.125], msg_bound=1))

    product = x * y
    aligned_x = x.to_level(product.level)
    combined = product + aligned_x
    decoded = decode(decrypt(combined), length=3)

    print("fresh level:", x.level)
    print("product level:", product.level)
    print("combined level:", combined.level)
    print("slots:", [round(z.real, 3) for z in decoded])
```

```
fresh level: 5
product level: 4
combined level: 4
slots: [1.5, 2.5, 3.375]
```

In this example, `x` starts at level 5. The product `x * y` rescales to level 4, so `x.to_level(product.level)` drops the original ciphertext to level 4 before the addition. The first three decoded slots are approximately `x*y + x`: `[1*0.5 + 1, 2*0.25 + 2, 3*0.125 + 3]`, or `[1.5, 2.5, 3.375]`.

## Replay a CKKS circuit

Use `ren.jit` when you will call the same CKKS circuit repeatedly. The first matching call captures the circuit: it runs the Python function, realizes the output, and records the scheduled polynomial work. Ren pays that capture cost on the first call, so a one-off call is usually not worth jitting.

Later matching calls replay the recorded work with new ciphertext buffers. They run faster because Ren skips graph construction and scheduling.

```python
import ren
from ren.schemes.ckks import CKKSParams, Ciphertext, decode, decrypt, encode, encrypt, keygen


params = CKKSParams.python_test()
keys = keygen(params)
ctx = keys.context()
captures = 0


@ren.jit
def affine(x: Ciphertext) -> Ciphertext:
    global captures
    captures += 1
    return (x + 1) * 0.5


with ctx:
    x1 = encrypt(encode([1.0, 2.0, 3.0], msg_bound=4))
    y1 = affine(x1)
    print("captures after first call:", captures)
    print("first output:", [round(z.real, 3) for z in decode(decrypt(y1), length=3)])

    x2 = encrypt(encode([2.0, 3.0, 4.0], msg_bound=5))
    y2 = affine(x2)
    print("captures after second call:", captures)
    print("second output:", [round(z.real, 3) for z in decode(decrypt(y2), length=3)])
```

```
captures after first call: 1
first output: [1.0, 1.5, 2.0]
captures after second call: 1
second output: [1.5, 2.0, 2.5]
```

## CKKS and the engine

CKKS runs on the same polynomial runtime as raw `Poly` code. A ciphertext addition builds two polynomial additions, one for `a` and one for `b`. A ciphertext multiplication builds polynomial products, relinearization, and rescale work. Rotation builds automorphism and key-switching work. All of those operations enter the same lazy graph, scheduling, memory planning, backend lowering, and execution pipeline.

JIT sees the `Poly` fields inside CKKS objects. A jitted function can accept `Ciphertext` and `Plaintext` values directly or inside supported Python containers and records with stored slots or instance dictionaries. Neither annotations nor `PolyContainer` inheritance are required for traversal. JIT keys the contained `Poly` specs and binds their buffers during replay. The outer Python object's identity is not part of the cache key. See [`ren.jit` replay](<https://ren-docs.pages.dev/engine/jit/index.md>) for cache-key and replay rules.

This example prints the outer CKKS type, the contained component types, and the component root ops.

```python
from ren.schemes.ckks import CKKSParams, encode, encrypt, keygen


params = CKKSParams.python_test()
keys = keygen(params)
ctx = keys.context()

with ctx:
    encrypted = encrypt(encode([1.0, 2.0, 3.0], msg_bound=3)).realize()
    output = (encrypted + 1) * 0.5

print("ciphertext:", type(output).__name__)
print("components:", type(output.a).__name__, type(output.b).__name__)
print("a root:", output.a.node.op.name)
print("b root:", output.b.node.op.name)
```

```
ciphertext: Ciphertext
components: Poly Poly
a root: RESCALE
b root: RESCALE
```

Multiplying by `0.5` uses CKKS plaintext-scalar multiplication. Ren applies the multiply to both ciphertext components, then adds a `RESCALE` step to keep the ciphertext on the expected scale and level schedule. Both component root ops print as `RESCALE` for that reason. The printed root op hides lower nodes such as the scalar multiply; use scheduling traces when you need to debug lowering or materialization.

## Next pages

- [Build a CKKS circuit](<https://ren-docs.pages.dev/tutorials/ckks-circuit/index.md>) is the first reusable encrypted-computation tutorial.
- [CKKS concepts](<https://ren-docs.pages.dev/concepts/ckks-model/index.md>) explains levels, scales, message bounds, keys, and parameter presets.
- [Getting started](<https://ren-docs.pages.dev/getting-started/index.md>) gives the shortest local run path.
- [Execution pipeline](<https://ren-docs.pages.dev/engine/execution/index.md>) explains how the lazy polynomial graphs become scheduled calls.
- [CKKS reference](<https://ren-docs.pages.dev/reference/ckks/index.md>) lists the public CKKS classes and functions.

## Source links

- [`ren/schemes/ckks/__init__.py`](<https://github.com/fieldextension/ren-onboarding/blob/main/ren/schemes/ckks/__init__.py>)
- [`CKKSKeySet`](<https://github.com/fieldextension/ren-onboarding/blob/main/ren/schemes/ckks/keys.py>)
- [`CKKSContext`](<https://github.com/fieldextension/ren-onboarding/blob/main/ren/schemes/ckks/context.py>)
- [`Plaintext` and `Ciphertext`](<https://github.com/fieldextension/ren-onboarding/blob/main/ren/schemes/ckks/ckks.py>)
- [`CKKSParams`](<https://github.com/fieldextension/ren-onboarding/blob/main/ren/schemes/ckks/params.py>)
- [`bootstrap`](<https://github.com/fieldextension/ren-onboarding/blob/main/ren/schemes/ckks/bootstrap.py>)
