Skip to content

ren.jit replay

Overview

The @ren.jit decorator can make many computations faster. For example:

import random
from time import perf_counter

import ren
from ren.schemes.ckks import CKKSParams, Ciphertext, encode, encrypt, keygen


params = CKKSParams.default()


def time_fn(f):
    start = perf_counter()
    f()
    end = perf_counter()
    t = int((end - start) * 1e6)
    print(f"{t:6} μs")


def random_ciphertext():
    data = [random.uniform(-1, 1) for _ in range(params.slot_count)]
    return encrypt(encode(data, msg_bound=1.0))


def warmup():
    x = random_ciphertext()
    without_jit(x).realize()


def without_jit(x: Ciphertext) -> Ciphertext:
    for _ in range(10):
        x = 2 * x * x - 1
    return x


@ren.jit
def with_jit(x: Ciphertext) -> Ciphertext:
    for _ in range(10):
        x = 2 * x * x - 1
    return x


keys = keygen(params)
ctx = keys.context()
with ctx:
    warmup()

    funcs = ["without_jit", "with_jit"]
    for func_name in funcs:
        print(func_name)
        for _ in range(5):
            x = random_ciphertext()
            func = globals()[func_name]
            time_fn(lambda: func(x).realize())
        print()
without_jit
149741 μs
148751 μs
148410 μs
148255 μs
148288 μs

with_jit
904707 μs
  5169 μs
  4884 μs
  4761 μs
  4793 μs

Why are the second and subsequent calls to the function so much faster when it is decorated with @ren.jit? When the user performs a polynomial computation, the ren engine creates a plan for executing that computation, as explained in detail in the Execution pipeline and Runtime sections. Eager execution can reuse a scheduled graph template, but still binds its buffers and plans execution on each invocation. The @ren.jit decorator also stores the final execution plan for later reuse.

It is important to recognize that although the @ren.jit decorator is applied to a function, what it actually captures is a polynomial computation graph. In particular, the decorator only understands objects of type ren.poly.Poly, and of types like ren.schemes.ckks.Plaintext and ren.schemes.ckks.Ciphertext that are built from Poly.

import ren


@ren.jit
def non_poly(x: float) -> float:
    for _ in range(10):
        x = 2 * x * x - 1
    return x


try:
    non_poly(0.5)
except RuntimeError as e:
    print(repr(e))
RuntimeError('ren.jit: function must receive at least one Poly argument')

Therefore, the @ren.jit decorator should only be used on functions that can be represented by a polynomial computation graph. Applying the decorator to other functions can lead to runtime errors or even silent incorrect behavior. The decorator generally should not be applied to functions with side effects.

Reusable functions

@ren.function keeps a helper's polynomial graph as a separate body that the scheduler can reuse. Python still runs on every invocation with the actual arguments, so Python branches and non-polynomial return values are evaluated again.

import ren
from ren.poly import Poly
from ren.ring import RingSpec


@ren.function
def scale(x: Poly, factor: int, label: str):
    print("running Python:", label)
    return {"value": x * factor, "label": label}


ring = RingSpec(n=4, moduli=(17, 97))
x = Poly([1, 2, 3, 4], ring)
for factor, label in [(2, "first"), (2, "second"), (3, "third")]:
    result = scale(x, factor, label)
    print(result["label"], result["value"].tolist())
running Python: first
first [2, 4, 6, 8]
running Python: second
second [2, 4, 6, 8]
running Python: third
third [3, 6, 9, 12]

Changing label returns the new label while allowing the same polynomial body to reuse its schedule. Changing factor changes a constant in the body, so it can require a different schedule. Changing polynomial values alone can reuse the body when their ring, domain, storage, and device requirements match.

Ren has one function mode: schedule the body separately and reuse it for compatible calls. This is the behavior called precompile=True in tinygrad. It avoids repeating the body's compiler passes, but also prevents fusion across the function boundary. Compilation happens when the result is scheduled, not when the decorator is applied. Leave a helper undecorated when you want the scheduler to optimize its operations together with the caller.

Nested function schedules are expanded into one flat schedule before memory planning and CUDA graph construction. Each invocation gets its own buffer bindings and intermediate storage. A function can appear inside @ren.jit, but replay of that outer JIT skips the entire Python body, including the decorated helper. Changing a top-level scalar argument of an existing JIT specialization raises instead of rerunning Python.

Usage and limitations

Function arguments

The @ren.jit decorator has limited support for arguments of types that are not derived from Poly.

import ren
from ren.poly import Poly
from ren.ring import RingSpec
import random


ring = RingSpec(n=8, moduli=(17, 97))


def random_poly():
    arr = [random.randint(0, 10) for _ in range(8)]
    return Poly(arr, ring)


@ren.jit
def scalar_mul(x: Poly, y: int) -> Poly:
    print(f"building graph with y={y}")
    return x * y


x1 = random_poly()
# this call builds a graph for scalar_mul with y=2
scalar_mul(x1, 2).realize()
x2 = random_poly()
# this call reuses the graph
scalar_mul(x2, 2).realize()
x3 = random_poly()
try:
    # error: the graph cannot be reused because y changed
    scalar_mul(x3, 3).realize()
except RuntimeError as e:
    print(repr(e))
building graph with y=2
RuntimeError('ren.jit: non-Poly scalar arg changed (captured (2,), got (3,)); jit freezes it at capture. Wrap varying scalars as Plaintext.const(...), or clear_jit() to re-capture.')

The ren engine does not have the ability to build a graph that computes scalar_mul(x,y) for arbitrary x and y. However, it does know how to create a graph for any fixed y.

If you plan to call scalar_mul with a few different y-values (and you expect to use each y-value more than once), you can use clear_jit to forget the graph, or use functools.partial to create multiple functions and apply jit to each one.

import ren
from ren.poly import Poly
from ren.ring import RingSpec
import random
import functools

ring = RingSpec(n=8, moduli=(17, 97))


def random_poly():
    arr = [random.randint(0, 10) for _ in range(8)]
    return Poly(arr, ring)


@ren.jit
def scalar_mul(x: Poly, y: int) -> Poly:
    print(f"building graph with y={y}")
    return x * y


for y in (2, 3):
    for _ in range(5):
        x = random_poly()
        scalar_mul(x, y).realize()
    scalar_mul.clear_jit()


def scalar_mul_no_jit(x: Poly, y: int) -> Poly:
    print(f"building graph with y={y}")
    return x * y


for y in (2, 3):
    jitted = ren.jit(functools.partial(scalar_mul_no_jit, y=y))
    for _ in range(5):
        x = random_poly()
        jitted(x).realize()
building graph with y=2
building graph with y=3
building graph with y=2
building graph with y=3

Nested values

JIT finds Poly values inside lists, tuples, namedtuples, sets, dictionaries, mapping proxies, and Python records with stored slots or instance dictionaries. Dataclasses, attrs classes, and ordinary classes use the same traversal, without requiring annotations. Inheriting ren.PolyContainer adds operations such as map_polys(fn), replace(polys=...) and realize() but is not required for traversal. PolyContainer subclasses need not be dataclasses.

Traversal is eager and uses cached layouts for each runtime class. It reads initialized slots in base-first declaration order, followed by instance dictionary values in insertion order. It does not evaluate properties, attribute hooks, or annotations. Scalar values and NumPy arrays retain their identity. Object arrays accept supported scalar entries such as numbers and FLINT values, and reject nested objects and Polys. Structured arrays check their object-bearing field views. Mapping keys are metadata, must be orderable, and cannot contain Polys; values are visited in key order. Unsupported collection types and native storage, such as deque and iterators, raise TypeError unless their class defines __tree_reduce__. Traversal rejects cycles and is subject to Python's recursion limit.

A custom record or collection class can define __tree_reduce__(self) returning (rebuild, children). Tree traverses the tuple of children and calls rebuild(*new_children) to reconstruct the object. rebuild can be a class, classmethod, function, or closure, but must not retain the source instance or its polynomials: replay plans keep the callable. Scalars and NumPy arrays keep their built-in handling. The hook owns any custom storage-sharing and constructor behavior.

Namedtuple subclasses cannot add instance dictionary storage. Slot declarations must be strings, tuples, lists, or dictionaries; iterator-based declarations are rejected because class creation consumes them.

Capture prepares reconstruction steps once, so replay does not traverse or revalidate the output structure. Reconstructed records bypass __init__ and __post_init__, including records containing only scalar values; classes with __tree_reduce__ reconstruct through their rebuild instead. Shared containers remain shared within each result, and replace(polys=...) rebuilds only ancestors of changed polynomials. Named field replacements use copy.replace: dataclasses run their constructor, while custom classes can define __replace__ to control named changes. Classes without replacement support raise TypeError when named changes are requested. Polynomial-only replacement does not require __replace__.

Jitted methods

Each instance has its own plans for a jitted method. Two instances capture separately, even when their input specs match. If you change a non-Poly attribute that selects a Python branch or supplies a constant, call instance.method.clear_jit() before the next call; replay does not rerun Python to observe that change. Calling Class.method.clear_jit() clears the plans for all instances of that method.

instance.method(x), Class.method(instance, x), and Class.method(self=instance, x=x) use the same instance cache. The keyword receiver uses the method's declared parameter name, whether it is self, model, or another name.

Instances with jitted methods must support weak references so the JIT cache can release their plans when the instances are no longer used. For a slotted dataclass, use @dataclass(slots=True, weakref_slot=True). Ordinary classes without slots already support weak references.

With static_output=True, a captured result that contains its owning instance keeps that instance alive until the plan is cleared. Use Class.method.clear_jit() to release these plans when the instances are no longer needed.

Output lifetime

By default, replay returns an output structure backed by buffers that do not overwrite a previous result while it is still referenced. JIT can reuse a pooled output buffer after no Poly or lazy graph refers to it.

static_output=True skips the output rebuild and returns the captured output object on every call. Use it when the caller consumes each result before the next call. A later replay overwrites earlier references to that output.

import ren
from ren.poly import Poly
from ren.ring import RingSpec


ring = RingSpec(n=8, moduli=(17, 97))


def constant_poly(c: int) -> Poly:
    arr = [c] + [0] * 7
    return Poly(arr, ring)


@ren.jit
def mul(x: Poly, y: Poly) -> Poly:
    return x * y


one = constant_poly(1)
two = constant_poly(2)
z = constant_poly(0)
z += mul(one, one)
z += mul(two, two)
print(z.tolist())


@ren.jit(static_output=True)
def mul_static(x: Poly, y: Poly) -> Poly:
    return x * y


first = mul_static(one, one)
print(first.tolist())
second = mul_static(two, two)
print(first is second)
print(second.tolist())
[5, 0, 0, 0, 0, 0, 0, 0]
[1, 0, 0, 0, 0, 0, 0, 0]
True
[4, 0, 0, 0, 0, 0, 0, 0]

Realization and host reads

Explicit realize() calls are allowed inside a jitted function. Each call records and executes its scheduled work during capture; replay runs the recorded work without entering the Python function again. Realizing an intermediate creates a scheduling boundary, which can limit fusion.

import ren
from ren.poly import Poly
from ren.ring import RingSpec

ring = RingSpec(n=8, moduli=(17, 97))


@ren.jit
def add_two(x: Poly) -> Poly:
    y = x + 1
    y.realize()
    return y + 1


x = Poly([1, 2, 3, 4, 0, 0, 0, 0], ring)
print(add_two(x).tolist())
print(add_two(x + 1).tolist())
[3, 2, 3, 4, 0, 0, 0, 0]
[4, 2, 3, 4, 0, 0, 0, 0]

Reading polynomial data through data(), tobytes(), tolist(), to_centered_list(), or iteration is rejected during capture. Otherwise, a value read into Python could be frozen into the plan instead of changing with replay inputs.

Unsupported operations

Calling a jitted function from inside another jitted function is not allowed.

import ren
from ren.poly import Poly
from ren.ring import RingSpec


ring = RingSpec(n=8, moduli=(17, 97))
x = Poly([1, 2, 3, 4, 0, 0, 0, 0], ring)


@ren.jit
def inner(x: Poly) -> Poly:
    return x + 1


# nested jit is not allowed
@ren.jit
def outer(x: Poly) -> Poly:
    return inner(x) * 2


try:
    outer(x).realize()
except RuntimeError as e:
    print(repr(e))


# use .fn to get the non-jitted version of the inner function
@ren.jit
def outer_fixed(x: Poly) -> Poly:
    return inner.fn(x) * 2


outer_fixed(x).realize()
RuntimeError('ren.jit: nested jit is not supported')

As of this writing, @ren.jit does not support operations that use randomness. See issue #413. Note that ren.schemes.ckks.encrypt uses randomness.

import ren
from ren.poly import Poly
from ren.ring import RingSpec

ring = RingSpec(n=8, moduli=(17, 97))


# Not allowed; uses randomness
@ren.jit
def add_noise(x: Poly) -> Poly:
    return x + Poly.ternary(ring)


x = Poly([1, 2, 3, 4, 0, 0, 0, 0], ring)
try:
    add_noise(x).realize()
except RuntimeError as e:
    print(repr(e))
RuntimeError('Random number generation during jit capture is not supported')

Plan reuse

If a jitted function is called twice with arguments from two separate rings, it will create two different plans. Less intuitively, jit also creates separate plans for constant and non-constant polynomials. Moreover, for constant polynomials, it creates a new plan every time the constant changes.

import ren
from ren.poly import Poly
from ren.ring import RingSpec


ring = RingSpec(n=8, moduli=(17, 97))
x = Poly([1, 2, 3, 4, 0, 0, 0, 0], ring)
y = Poly([5, 6, 7, 8, 0, 0, 0, 0], ring)
z = Poly([9, 0, 1, 2, 0, 0, 0, 0], ring)


@ren.jit
def add_poly(x: Poly, c: Poly) -> Poly:
    return x + c


old_num_plans = 0


def plan_added() -> bool:
    global old_num_plans
    added = len(add_poly._plans) > old_num_plans
    old_num_plans = len(add_poly._plans)
    return added


def print_plan_added(name):
    if plan_added():
        print(f"added plan for {name}")
    else:
        print(f"reused plan for {name}")


add_poly(x, y).realize()
print_plan_added("x + y")
add_poly(x, z).realize()
print_plan_added("x + z")
add_poly(x, Poly.const(7, ring))
print_plan_added("x + 7")
add_poly(x, Poly.const(8, ring))
print_plan_added("x + 8")

ring = RingSpec(n=4, moduli=(17, 97))
x = Poly([1, 2, 3, 4], ring)
y = Poly([5, 6, 7, 8], ring)
add_poly(x, y).realize()
print_plan_added("new ring")
added plan for x + y
reused plan for x + z
added plan for x + 7
added plan for x + 8
added plan for new ring

Flowchart

On the first matching call, Ren runs the Python function, realizes the output, and records the scheduled backend work. Ren pays that capture cost on the first call, so a one-off call is usually not worth jitting.

Later calls with the same polynomial input specs and top-level scalar arguments replay the recorded exec units with new input buffers. During replay, Ren reuses the captured schedule instead of rebuilding and rescheduling the graph, so subsequent matching calls run faster.

flowchart TB A["Call jitted function"] B["Cache lookup"] C["Capture on miss"] D["Replay on hit"] E["Return output structure"] A --> B B -- "miss" --> C B -- "hit" --> D C --> E D --> E

Cache key

JIT collects contained Poly inputs through the nested-value traversal, realizes them, then builds a cache key from their specs. It also records top-level non-Poly scalar arguments because replay does not re-enter the Python function.

Realized inputs are keyed by:

  • ring
  • size
  • dtype
  • device
  • domain
  • input buffer sharing (for example, passing the same Poly twice)

Constant polynomial inputs are keyed by:

  • ring
  • constant value
  • device
  • domain

Changing the ring, device, realized domain, buffer shape, dtype, or constant value can create a new captured plan. If the polynomial specs match an existing plan but a top-level scalar argument changes, Ren raises instead of recapturing, because that scalar may have selected a Python branch during capture.

ren.jit.scope(key, owner=...) supplies a hashable cache key and an optional resource owner to all JIT calls within its scope. Equal keys reuse a plan when the input specs match; different keys create separate plans. The plan retains the owner supplied during capture to keep its resources alive. Exiting the scope restores the previous context, including when an exception occurs.

CKKS contexts enter this scope automatically. JIT treats the key as opaque: the context provider decides which values distinguish its computations.

Each jitted function or bound method can hold at most 16 plans, including context specializations. A seventeenth specialization raises. Use clear_jit() to release those plans before capturing new ones.

Example

import ren
from ren.poly import Poly
from ren.ring import RingSpec


ring = RingSpec(n=8, moduli=(17, 97))
captures = 0


@ren.jit
def step(x: Poly, y: Poly, offset: Poly) -> Poly:
    global captures
    captures += 1
    return (x + y + offset).contiguous()


out1 = step(
    Poly([1, 2, 3, 4, 0, 0, 0, 0], ring),
    Poly([4, 3, 2, 1, 0, 0, 0, 0], ring),
    Poly([1, 1, 1, 1, 0, 0, 0, 0], ring),
)
print("captures after first call:", captures)
print("first output:", out1.to_centered_list())

out2 = step(
    Poly([2, 2, 2, 2, 0, 0, 0, 0], ring),
    Poly([1, 1, 1, 1, 0, 0, 0, 0], ring),
    Poly([0, 1, 0, 1, 0, 0, 0, 0], ring),
)
print("captures after second call:", captures)
print("second output:", out2.to_centered_list())
captures after first call: 1
first output: [6, 6, 6, 6, 0, 0, 0, 0]
captures after second call: 1
second output: [3, 4, 3, 4, 0, 0, 0, 0]

The first call builds and captures the schedule, so captures becomes 1. The second call has new polynomial values but the same realized input specs, so Ren replays the captured plan without entering the Python function again and captures stays 1.

Capture boundary

On a cache miss, JIT:

realize input Polys
enter capture mode and call the user function
collect output Polys
realize outputs while recording scheduled CALLs
normalize buffer bindings
prune input-independent work if enabled
replan captured intermediate memory
rewrite input, output, and intermediate bindings together
lower the replay CALLs into executable units
try to create a backend graph runner
store the captured plan

On a cache hit, JIT builds a temporary binding list from current inputs and, when needed, fresh outputs. The backend graph runner or captured units resolve their buffer parameters from that list and execute the plan. The captured plan does not retain replay inputs.

JIT realizes any remaining lazy outputs before finishing capture. Host reads and random polynomial generation inside the body raise so replay cannot reuse capture-time data or randomness.

Dos

  • Use ren.jit around a stable polynomial computation that you call repeatedly.
  • Keep argument specs stable if you want replay instead of recapture.
  • Pass Poly values directly, inside supported Python containers, or inside PolyContainer objects such as CKKS ciphertexts.
  • Realize or inspect outputs after each call when you need concrete values.
  • Use clear_jit() when you want to drop captured plans and recapture.
  • Consider @ren.jit(prune=True) when the function has expensive input-independent setup work.
  • Use @ren.jit(static_output=True) when each result is consumed before the next call and you want to skip output reconstruction.
  • Keep one JIT boundary around a stable computation when you do not need separate inner and outer caches.

Don'ts

  • Do not use JIT for a function whose arguments contain no Poly inputs.
  • Do not return only non-polynomial data.
  • Do not expect changed polynomial constant inputs to reuse the same plan; constant values are part of the cache key.
  • Do not expect top-level scalar arguments to vary across replays. Use a Poly value, a CKKS Plaintext.const(...), or call clear_jit() before capturing a different branch.
  • Do not expect one JIT object to hold unbounded shapes/specs; it stores a fixed number of captured plans.
  • Do not keep a static_output=True result across calls. Later calls reuse the same output object and buffers.
  • Do not call a jitted function from inside another jitted function. Keep helper functions undecorated and put one @ren.jit boundary around the stable computation.