Skip to main content

ClikaRT::graph::TraceOptions

struct

Header: ClikaRT/graph/trace.h

ClikaRT::trace: record an eager model function into an executable ModelGraph.

Any callable written against the public ops/nn surface (positional tensors in, positional tensors out) can be traced: the function runs ONCE on symbolic stand-in tensors, every op it calls records into a graph instead of computing, and the result is the same ModelGraph that io::OnnxModel::compile produces. From there the model runs, and future graph-level tooling (optimization, quantization; calibration inputs are consumed at that stage) operates on it like on any other ModelGraph.

​

The authoring convention (what makes a function traceable)​

  • Public ops/nn only. Every tensor-producing step goes through ClikaRT::ops::* / ClikaRT::nn::*; that is what records. Module weights (real bound tensors) become the graph's weights automatically.
  • No data-dependent control flow. The trace records ONE execution path, so a branch on host data picks its arm at trace time and that arm is what the graph replays forever. Reading a tensor's VALUE during tracing (item, item_as_vec, host data access) fails the trace loudly; the stand-ins carry no data by design, precisely so a value dependence cannot bake in silently. Branching on plain C++ values (configuration, flags) is fine: the taken arm is the model.
  • Dynamic dims are declared, not defaulted. A dimension that should stay flexible at run time must be dynamic in the tracing signature (spec::TensorSpec::kDynamicDim, optionally named via dim_names; the same name on two inputs declares the same size, exactly as in io::OnnxModel). A concrete signature dim traces a graph specialized to it.
  • State is IO, explicit or surfaced. Anything that persists across calls (a KV cache, a state buffer) either enters as an input and leaves as a returned output, or is a captured live tensor the function writes through an in-place op; the trace then SURFACES each written buffer as an additional named graph output automatically. An attention layer's in-place present planes surface as present.<layer>.key / present.<layer>.value (layer-ordered; enumerated by ModelGraph::kv_cache_info), other written buffers as state_out_<k>. A plain run returns those outputs in fresh storage; to advance the live buffers in place (the serving-loop cache semantics), bind each surfaced output to its own live tensor through run's bound-output form. Either way the graph is a pure function of its inputs and the bound buffers' current contents.

Every fallible operation returns its value directly and raises ClikaRT::Error on failure; wrap in CLIKART_TRY(...) to inspect a Result instead.

How a trace FINISHES the captured graph. The defaults reproduce the plain trace(...) behavior exactly, so existing calls are unaffected; each knob exists for a caller that drives the finishing itself (a compile step, a graph-tooling flow that wants the raw capture).

Whatever the knobs say, the capture itself is unchanged: inputs, declared outputs, and the automatically surfaced in-place state outputs (the present.<layer>.{key,value} planes, kv_cache_info) are part of tracing, not of the finishing; a raw capture still carries them.

Data members​

run_transforms​

bool run_transforms = true

Run the standard graph-optimization pipeline over the captured graph. Off: the graph replays exactly the operations the function recorded.

Declared in ClikaRT/graph/trace.h, line 83

bake​

bool bake = true

Finalize for serving: one-time weight packing and constant absorption. Off: the graph still runs (resolved per run) and stays open to graph-level tooling that must precede finalization.

Declared in ClikaRT/graph/trace.h, line 87

shape_fixation​

bool shape_fixation = true

Let the pipeline specialize shape arithmetic that is fully determined by the signature's static dims. Off keeps every recorded shape computation dynamic. Meaningful only while run_transforms is on.

Declared in ClikaRT/graph/trace.h, line 91

place​

StreamOrDevice place = {}

Home the finished graph on this device/stream (weights pack on it, the graph runs on it). Unspecified: the graph stays where tracing built it, the CPU.

Declared in ClikaRT/graph/trace.h, line 95