# Engine overview

Ren's engine is the path from user-facing polynomial or CKKS code to backend work. Use this page as the map before reading the more detailed engine pages.

flowchart LR subgraph Frontend\["User-facing layer"\] A\["CKKS objects"\] B\["Poly values"\] end subgraph IR\["Lazy IR"\] C\["Node DAG\<br/\>ops, sources, ring/domain metadata"\] end subgraph Planning\["Planning"\] E\["Scheduler"\] F\["Memory planner"\] end subgraph Runtime\["Runtime"\] G\["ExecUnits"\] H\["Python backend"\] I\["CUDA backend"\] end A --\> B --\> C C --\> E --\> F --\> G G --\> H G --\> I E -. "scheduled CALLs" .-\> J\["ren.jit"\] J -. "builds a replay plan" .-\> G

## Frontend values

User code starts with `Poly` values or higher-level CKKS objects. CKKS `Plaintext` and `Ciphertext` values contain `Poly` fields, so CKKS arithmetic eventually enters the same polynomial graph path.

`Poly` wraps a lazy `Node` graph. Arithmetic, domain conversions, ring changes, copies, and constants add nodes. They do not launch backend work until a concrete result is needed.

## Realization boundary

Realization is the boundary between symbolic graph construction and execution. Calls such as `realize()`, `tolist()`, `tobytes()`, serialization, decryption, and JIT capture force Ren to schedule the requested outputs.

Ren gathers requested outputs under one `SINK` so shared intermediates can be scheduled together. That is why realizing multiple outputs in one call can produce a better schedule than realizing them one at a time.

## Scheduler and memory planner

The scheduler rewrites the `Node` DAG into scheduled work. It lowers high-level ring operations, inserts required domain conversions, chooses materialization boundaries, turns stores into kernel roots, and records how lazy outputs become realized buffers.

The memory planner then packs temporary buffers whose identity does not matter. Final outputs, allocated buffers, external parameter bindings, copy buffers, and explicitly protected storage stay fixed. Intermediate views can share arena storage with their bases.

## Backends and replay

Backend lowering turns scheduled work into executable units. Compute units run through the selected backend; copies use lightweight execution units. Buffer views remain storage expressions and need no execution unit.

`ren.jit` records scheduled `CALL`s during the first realization, replans their intermediate memory, and lowers the replay plan into executable units. Later calls with matching input specs, scope key, and top-level scalar arguments pass new input and output bindings to that plan.

## Read next

| Need | Page |
| --- | --- |
| Ring, RNS, domain, node, constant, and view semantics | [Polynomial engine](<https://ren-docs.pages.dev/engine/polynomial/index.md>) |
| Full realization path from lazy graph to execution | [Execution pipeline](<https://ren-docs.pages.dev/engine/execution/index.md>) |
| Scheduler pass order and rewrite tracing | [Scheduling](<https://ren-docs.pages.dev/engine/scheduling/index.md>) |
| Memory planning, executable units, copies, views, and backends | [Runtime](<https://ren-docs.pages.dev/engine/runtime/index.md>) |
| Capture, cache keys, replay, and failure modes | [`ren.jit` replay](<https://ren-docs.pages.dev/engine/jit/index.md>) |

## Source map

- [`ren/poly.py`](<https://github.com/fieldextension/ren-onboarding/blob/main/ren/poly.py>): `Poly`, realization, and user-facing graph entry points.
- [`ren/ir/node.py`](<https://github.com/fieldextension/ren-onboarding/blob/main/ren/ir/node.py>): graph nodes, metadata, constants, and formatting.
- [`ren/engine/schedule.py`](<https://github.com/fieldextension/ren-onboarding/blob/main/ren/engine/schedule.py>): scheduler entry point and pass order.
- [`ren/engine/memory.py`](<https://github.com/fieldextension/ren-onboarding/blob/main/ren/engine/memory.py>): arena planning and buffer remapping.
- [`ren/engine/realize.py`](<https://github.com/fieldextension/ren-onboarding/blob/main/ren/engine/realize.py>): lowering scheduled work into executable units.
- [`ren/engine/jit.py`](<https://github.com/fieldextension/ren-onboarding/blob/main/ren/engine/jit.py>): capture, replay, buffer binding, and alias handling.
- [`ren/backends/python/`](<https://github.com/fieldextension/ren-onboarding/tree/main/ren/backends/python>) and [`ren/backends/cuda/`](<https://github.com/fieldextension/ren-onboarding/tree/main/ren/backends/cuda>): backend execution paths.
