Module: Kumi::Core::IR::ExecutionEngine

Defined in:
lib/kumi/core/ir/execution_engine.rb,
lib/kumi/core/ir/execution_engine/values.rb,
lib/kumi/core/ir/execution_engine/profiler.rb,
lib/kumi/core/ir/execution_engine/combinators.rb,
lib/kumi/core/ir/execution_engine/interpreter.rb

Overview

ExecutionEngine interpreter for IR execution

ARCHITECTURE:

  • Values:

    • Scalar(v) → { k: :scalar, v: v }
    • Vec(scope, rows, has_idx) → { k: :vec, scope: [:axis, ...], rows: [{ v:, idx:[...] }, ...], has_idx: true/false }
      • Rank = idx length; scope length is the logical axes carried by the vector

  • Combinators (pure, stateless, delegate to Executor):

    • broadcast_scalar(scalar, vec) → replicate scalar across vec rows (preserves idx/scope)
    • zip_same_scope(vec1, vec2, ...) → positional zip for equal scope & equal row count
    • align_to(tgt_vec, src_vec, to_scope) → expand src by prefix indices to match a higher-rank scope
    • group_rows(rows, depth) → stable grouping by idx prefix to nested Ruby arrays

  • Executor:

    • Executes IR ops in order; delegates to combinators; maintains a slot stack
    • No structural inference; trusts IR attributes (scope, has_idx, is_scalar)

OP SEMANTICS (subset):

  • const(value) → push Scalar(value)
  • ref(name) → push previous slot by stored name (twins allowed: :name__vec)
  • load_input(plan_id, attrs) → call accessor; return Scalar or Vec according to attrs/mode
  • map(fn, argc, *args) → elementwise or scalar call; auto alignment already handled by IR
  • reduce(fn, axis, ...) → reduce one vector arg; returns Scalar
  • align_to(to_scope, a, b) → align b to a’s to_scope (prefix-compat only)
  • array(count, *args) → collect args into a Scalar(Array)
  • lift(to_scope, slot) → require Vec(has_idx), group rows with group_rows to nested Scalar
  • store(name, slot) → bind slot to name in env (used for :name and :name__vec twins)

PRINCIPLES:

  • Mechanical execution only; “smarts” live in LowerToIR.
  • Never sniff Ruby types to guess shapes.
  • Errors early and clearly if invariants are violated (e.g., align_to expects vecs with indices).

DEBUGGING:

  • DEBUG_VM_ARGS=1 prints per-op execution and arguments.
  • DEBUG_GROUP_ROWS=1 prints grouping decisions during Lift.

Defined Under Namespace

Modules: Combinators, Interpreter, Profiler, Values

Class Method Summary collapse

Class Method Details

.run(schedule, input:, accessors:, registry:, runtime: {}) ⇒ Object 



44
45
46
47
48
49
50
 
# File 'lib/kumi/core/ir/execution_engine.rb', line 44

def self.run(schedule, input:, accessors:, registry:, runtime: {})
  runtime[:accessor_cache] ||= {}

  Dev::Profiler.phase("engine.interpreter") do
    Interpreter.run(schedule, input: input, runtime: runtime, accessors: accessors, registry: registry)
  end
end