runmat-vm 0.4.4

RunMat virtual machine and bytecode interpreter
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

# Idioms in the RunMat Compiler

This directory contains the compiler side of VM idioms.

An idiom is a rooted source pattern that the compiler can recognize and lower to a dedicated VM opcode instead of lowering it as a more generic sequence of statements and expressions.

The split is:

- compile-time idiom detection and lowering live under `src/compiler/idioms/`
- runtime idiom execution helpers live under `src/accel/idioms/`

That split is intentional. Detection is a compiler concern. Execution is a VM/runtime concern.

# How it works

The compiler idiom pipeline is:

1. Statement lowering starts from a rooted `HirStmt`.
2. `try_lower_stmt_idiom(...)` asks whether that statement matches any supported idiom.
3. Each idiom detector proves its own rooted pattern.
4. If a match succeeds, the compiler lowers directly to a dedicated VM opcode.
5. Normal statement lowering is skipped for that statement.

The public compiler entrypoint is `try_lower_stmt_idiom(...)` in `src/compiler/idioms/mod.rs`.

This is intentionally generic at the statement boundary. The idiom framework does not encode separate public APIs for loop idioms, assignment idioms, or expression idioms. Each idiom decides internally what kind of rooted statement it can start from.

That keeps the architecture simple:

- the framework is statement-rooted
- the individual idiom owns the pattern details

# Adding a new idiom

For a new idiom, the usual steps are:

1. Add a new detector/lowerer in `src/compiler/idioms/`.
2. Match from `&HirStmt`, not from a special-case public hook for one statement kind.
3. Prove the pattern conservatively.
4. Lower to a dedicated opcode.
5. Add the runtime execution helper under `src/accel/idioms/`.
6. Add tests for:
   - positive detection
   - rejection of near-miss patterns
   - correct lowering shape
   - end-to-end runtime behavior

Good compiler idioms tend to have these properties:

- the rooted source pattern is stable and unambiguous
- lowering to a dedicated opcode preserves existing semantics
- there is a meaningful benefit from specializing execution
- the opcode contract is small and deterministic

If a transformation is hard to prove from HIR, or does not need a dedicated opcode, it probably belongs in a different optimization layer instead of the idiom system.

# Current idioms implemented

## `stochastic_evolution`

Current status:

- compiler detection/lowering lives in `src/compiler/idioms/stochastic_evolution.rs`
- runtime execution lives in `src/accel/idioms/stochastic_evolution.rs`
- lowering targets `Instr::StochasticEvolution`

This idiom is rooted at a `HirStmt::For`, which is the statement boundary for the idiom pattern scan. The detector proves a specific computation graph pattern and then lowers the whole statement directly to one opcode.