# Runtime

After scheduling, Ren plans memory, lowers calls into executable units, and runs backend programs. Read [Scheduling](<https://ren-docs.pages.dev/engine/scheduling/index.md>) for the pass sequence that produces calls, or [Engine overview](<https://ren-docs.pages.dev/engine/overview/index.md>) for the shorter path from user API to backend execution.

## Realization path

The realization path is:

```text
ren.realize(*values)
  -> tree.collect(..., leaf=Poly)
  -> _schedule_and_lower(...)
       -> schedule(SINK(...))
       -> plan_memory(...)
       -> make_exec_units(...)
  -> run_exec_units(...)
```

`ren.realize(a, b, ...)` realizes Polys in nested values together and returns `None`. That lets the scheduler see shared intermediate work instead of compiling each output in isolation. `Poly.realize()` and `PolyContainer.realize()` delegate to it and return `self`.

## Memory planning

`plan_memory(...)` computes first and last use for scheduled buffers. The planner packs intermediate buffers that do not need stable identity into one arena per device using a TLSF-style allocator simulation.

The practical effect is that temporaries whose live ranges do not overlap can reuse the same backing storage. Ren still leaves some buffers alone when callers or later executable units rely on a stable object/base relationship.

Ren keeps buffers out of the arena when identity matters:

- final outputs;
- already allocated buffers;
- external parameter bindings;
- bases of preserved output views;
- explicit no-opt buffers.

Copy buffers also stay out of the arena to preserve transfer parallelism. Other intermediate views can share arena storage with their bases.

The planner returns a mapping from intermediate buffers to views into shared backing storage. Executable-unit lowering applies that mapping to the scheduled calls.

## Backends

The Python backend interprets the lowered kernel AST with NumPy and Montgomery helpers. Use it for correctness checks, debugging, and CPU-only development.

The CUDA backend renders kernels, compiles them with NVRTC, builds launch specs, and runs them on CUDA queues. It also has backend graph support for JIT replay when a captured program is eligible.

## Copies and views

Copies lower to either device transfer or host-mediated copy depending on allocator support and device type.

`BUFFER_VIEW` describes a range of its source buffer. Views remain expressions in call arguments and returned Polys, so they need no executable unit. Memory planning tracks their base storage; replay resolves them against the current input buffers.

## JIT capture and replay

`ren.jit` works at the realized-buffer boundary:

```text
realize input Polys
enter capture mode and call function
collect output Poly values
realize while recording scheduled CALLs
normalize bindings and prune input-independent work if enabled
replan captured intermediates
rewrite input, output, and intermediate bindings together
lower the replay CALLs into ExecUnits
create backend graph runner if possible
```

On replay, JIT passes current input and output bindings to the backend graph runner or captured units. The CUDA graph runner resolves each distinct dynamic binding once and updates the affected kernel and copy nodes. Without a graph runner, each unit resolves its own bindings. The captured plan does not retain replay inputs.

The main constraints are:

- the jitted function must receive and return at least one structure containing a `Poly`;
- polynomial host reads and random polynomial generation inside the jitted body are rejected; explicit `realize()` calls are allowed;
- top-level scalar arguments are frozen with the captured plan and must not change across replays;
- replay protects still-live outputs by default, while `static_output=True` reuses the captured output and snapshots aliased inputs before writing.

See [`ren.jit` replay](<https://ren-docs.pages.dev/engine/jit/index.md>) for examples, cache-key rules, and failure modes.

## Files to read

- [`ren/poly.py`](<https://github.com/fieldextension/ren-onboarding/blob/main/ren/poly.py>): `realize()` and `_schedule_and_lower()`.
- [`ren/engine/realize.py`](<https://github.com/fieldextension/ren-onboarding/blob/main/ren/engine/realize.py>): `make_exec_units()` and `run_exec_units()`.
- [`ren/engine/memory.py`](<https://github.com/fieldextension/ren-onboarding/blob/main/ren/engine/memory.py>): arena planning and buffer remapping.
- [`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.
