RunMat Ignition (Interpreter)

Ignition is RunMat's reference interpreter. It compiles the high-level IR (HIR) emitted by runmat-hir into a compact bytecode and executes it on a fast, non-allocating stack virtual machine. The design goal is full MATLAB grammar/semantic compatibility with clear, testable semantics and a codebase that is easy to extend.

Sibling docs for deep dives:

• INSTR_SET.md - opcode semantics, stack effects, failure modes
• COMPILER_PIPELINE.md - HIR → bytecode lowering strategy
• INDEXING_AND_SLICING.md - column-major rules, end arithmetic, N-D gather/scatter, expansion
• ERROR_MODEL.md - MException and mex identifier normalization
• OOP_SEMANTICS.md - objects, properties/methods, subsref/subsasgn, operator overloading

Module structure

• instr.rs: Instruction set enum Instr (bytecode opcodes)
• functions.rs: UserFunction, frames, and ExecutionContext
• compiler.rs: exhaustive lowering for HirStmt/HirExprKind
• bytecode.rs: compile, compile_with_functions
• vm.rs: Interpreter loop and semantics (execute)
• gc_roots.rs: RAII GC roots for stack/locals/globals

Public API

• compile(&HirProgram) -> Bytecode
• compile_with_functions(&HirProgram, &HashMap<String, UserFunction>) -> Bytecode
• interpret(&Bytecode) -> Result<Vec<Value>, String>
• interpret_with_vars(&Bytecode, &mut [Value]) -> Result<Vec<Value>, String>
• execute(&HirProgram) -> Result<Vec<Value>, String>

Execution model

• Each function compiles to bytecode + constants. Calls create frames holding PC, locals, return arity, and a base stack pointer.
• The VM uses a single operand stack of Value. Locals are a separate array per frame. Both are GC roots.
• Column-major semantics are global invariants. All indexing, reshape, broadcast and assignment follow MATLAB order.

Compatibility surface

• Expressions: numbers/strings/identifiers/constants; unary (+, -, transpose, non-conjugate transpose .'), logical not (~); arithmetic (+, -, , /, ^), elementwise (., ./, .^); comparisons; ranges (start[:step]:end).
• Tensors/Cells: 2-D literals, transpose, indexing, stores.
• Indexing: scalar/vector/range/logical/colon/end; N-D gather via IndexSlice; 1-D/2-D fast-paths preserved.
• Slice assignment: N-D scatter via StoreSlice with broadcast/shape checks.
• Control flow: if/elseif/else, while, for (±/0 step), break/continue, switch/case/otherwise.
• Try/catch: nested via EnterTry/PopTry; catch variable bound to Value::MException.
• Functions/Recursion: fixed arity + varargs; nargin/nargout accounted; multi-assign via CallFunctionMulti.
• Handles/Closures: captures and feval supported.
• OOP: properties/methods (instance/static), access checks, class refs/metaclass, overloaded indexing routed to subsref/subsasgn.

Compiler principles

• Evaluation order is preserved (left-to-right) to match MATLAB side-effects.
• Control flow uses structured blocks with patched jumps.
• Multi-assign lowers to CallFunctionMulti with explicit arity then sequential stores.
• Indexing lowers to 2-D fast paths where safe, otherwise IndexSlice. Stores mirror via StoreSlice.

Indexing and slicing (summary)

• Column-major gather: cartesian enumeration in column-major with shape normalization (2-D (I,scalar) → [|I|,1], (scalar,J) → [1,|J|]).
• end arithmetic per dimension; logical masks are validated and expanded to indices.
• Slice assignment enforces exact shape/broadcast rules; scalar broadcasts along selected extents.
• Cells and function returns expand in argument lists and (when applicable) into slice targets.

Error model (mex)

• All interpreter errors are normalized: mex(id, message) returns "<ID>: <message>".
• Identifiers include: MATLAB:UndefinedFunction, MATLAB:UndefinedVariable, MATLAB:NotEnoughInputs, MATLAB:TooManyInputs, MATLAB:TooManyOutputs, MATLAB:VarargoutMismatch, MATLAB:SliceNonTensor, MATLAB:IndexOutOfBounds, MATLAB:CellIndexType, MATLAB:CellSubscriptOutOfBounds, MATLAB:ExpandError, MATLAB:MissingSubsref, MATLAB:MissingSubsasgn.

OOP semantics (summary)

• Instance: LoadMember/StoreMember, LoadMethod/CallMethod with access checks.
• Static: LoadStaticProperty/CallStaticMethod when base is a class reference.
• Overloaded indexing: the VM constructs selector cells and routes to subsref/subsasgn. Missing hooks surface mex identifiers above.
• Operator overloading: delegated through runtime dispatch (e.g., plus, mtimes), with numeric fallbacks normalized.

Testing strategy

• Unit/property tests cover:
  • Gather/scatter round-trip invariants, column-major mapping, broadcast laws.
  • Negative paths: invalid indices, arity/output errors, expansion/type mismatches, OOP dispatch failures.
  • Parser+compiler+VM end-to-end for command-form, metaclass postfix, imports.
• Tests assert mex identifiers to prevent semantic drift.

Performance

• Correctness-first generic paths, plus 2-D fast paths for A(:, j) and A(i, :) with strict shape checks and column-major writes.
• Unhandled opcodes in JIT (Turbine) explicitly fall back to the interpreter.

Remaining edges

• Error model sweep: confirm all remaining failure paths surface normalized mex identifiers (indexing, arity, OOP dispatch). Most paths covered; add a couple more targeted tests.
• OOP negative strictness: once the runtime registry guarantees absence of subsref/subsasgn, tighten tests to expect MATLAB:MissingSubsref/MATLAB:MissingSubsasgn only.
• Expansion into slice targets: core implemented; add a few degenerate/empty seeds when encountered.

Contributing

• Add builtins in runmat-runtime; wire special handling in the VM only if semantics require.
• Prefer centralizing MATLAB rules in IndexSlice/StoreSlice rather than scattering logic.
• When adding opcodes, document in INSTR_SET.md and ensure mex errors are uniform.