Bytecode execution tracer that visualizes FLUX program execution step-by-step with register and control flow tracking.
flux-timeline is a Python module that traces FLUX bytecode execution and produces human-readable timelines showing PC movement, register changes, jump decisions, and stack operations for every cycle.
Understanding what a program does at the cycle level is essential for debugging and optimization:
flux-debuggerprovides interactive stepping; timeline provides batch tracingflux-profilermeasures performance; timeline shows what happenedflux-decompilershows what the code is; timeline shows what it doesflux-signaturesidentifies patterns statically; timeline confirms them dynamicallyflux-coveragetracks which instructions executed; timeline shows the order
| Feature | Description |
|---|---|
| Cycle-by-Cycle Tracing | Every instruction produces a TimelineEvent with full state |
| Register Snapshots | Each event captures all R0–R15 values |
| Jump Tracking | Records branch taken/not-taken decisions with target PCs |
| Stack Events | Tracks PUSH/POP operations |
| Text Output | to_text() produces formatted execution log |
| CSV Export | to_csv() for spreadsheet analysis |
| Opcodes Supported | HALT, MOVI, INC, DEC, ADD, MUL, CMP_EQ, JZ, JNZ, PUSH, POP |
from flux_timeline import TimelineTracer
tracer = TimelineTracer()
# Trace a factorial program
bytecode = [0x18, 0, 3, 0x18, 1, 1, 0x22, 1, 1, 0, 0x09, 0, 0x3D, 0, -6, 0, 0x00]
timeline = tracer.trace(bytecode)
print(f"Total cycles: {timeline.total_cycles}")
print(f"Jumps taken: {timeline.jumps_taken}")
print(f"Max PC: {timeline.max_pc}")
# Human-readable output
print(timeline.to_text())
# Machine-readable output
print(timeline.to_csv())python -m pytest tests/ -v
# or
python timeline.pyflux-debugger— Interactive step debuggerflux-profiler— Performance profilingflux-decompiler— Bytecode to assemblyflux-signatures— Pattern detectionflux-coverage— Code coverage analysis
Part of the SuperInstance FLUX fleet.