diff --git a/Makefile b/Makefile index c48acf7..520384f 100644 --- a/Makefile +++ b/Makefile @@ -116,7 +116,10 @@ friction: c-build asm-build # ─── Documentation ──────────────────────────────────────────────── -docs: docs/python-architecture.png docs/c-architecture.png docs/asm-architecture.png docs/jit-pipeline.png +DOT_FILES := $(wildcard docs/*.dot) +DOT_PNGS := $(DOT_FILES:.dot=.png) + +docs: $(DOT_PNGS) docs/%.png: docs/%.dot dot -Tpng $< -o $@ diff --git a/docs/benchmark-ack.dot b/docs/benchmark-ack.dot new file mode 100644 index 0000000..5b85406 --- /dev/null +++ b/docs/benchmark-ack.dot @@ -0,0 +1,19 @@ +// ack(3,4) benchmark — all implementations +// "A diagram is worth 10,000 words." — russell@unturf.com +digraph benchmark_ack { + rankdir=LR + node [shape=record, style=filled, fontname="Helvetica", fontsize=11] + edge [style=invis] + label="ack(3,4) — time in milliseconds (lower is better)" + labelloc=t + fontsize=14 + fontname="Helvetica Bold" + + jit [label="{C + JIT|0.19 ms}" fillcolor="#00b894" fontcolor=white width=0.5] + cpython [label="{CPython|1.3 ms}" fillcolor="#0984e3" fontcolor=white width=1.5] + asm [label="{Assembly|8 ms}" fillcolor="#6c5ce7" fontcolor=white width=3.0] + cinterp [label="{C interpreter|20 ms}" fillcolor="#fdcb6e" width=5.0] + pyvm [label="{Python VM|149 ms}" fillcolor="#e17055" fontcolor=white width=10.0] + + jit -> cpython -> asm -> cinterp -> pyvm +} diff --git a/docs/benchmark-ack.png b/docs/benchmark-ack.png new file mode 100644 index 0000000..c38b5a8 Binary files /dev/null and b/docs/benchmark-ack.png differ diff --git a/docs/benchmark-binary-size.dot b/docs/benchmark-binary-size.dot new file mode 100644 index 0000000..5bc2ba5 --- /dev/null +++ b/docs/benchmark-binary-size.dot @@ -0,0 +1,17 @@ +// Binary size comparison +// "A diagram is worth 10,000 words." — russell@unturf.com +digraph binary_size { + rankdir=LR + node [shape=record, style=filled, fontname="Helvetica", fontsize=11] + edge [style=invis] + label="Binary size / footprint (smaller is leaner)" + labelloc=t + fontsize=14 + fontname="Helvetica Bold" + + asm [label="{Assembly|13 KB\n1.8 MB resident\nzero dependencies}" fillcolor="#6c5ce7" fontcolor=white width=1.5] + c [label="{C + JIT|171 KB\n~4 MB resident\nlibc only}" fillcolor="#00b894" fontcolor=white width=3.0] + py [label="{Python VM|3,324 lines\n~30 MB resident\nPython 3 runtime}" fillcolor="#e17055" fontcolor=white width=6.0] + + asm -> c -> py +} diff --git a/docs/benchmark-binary-size.png b/docs/benchmark-binary-size.png new file mode 100644 index 0000000..0a3a5ba Binary files /dev/null and b/docs/benchmark-binary-size.png differ diff --git a/docs/benchmark-fib.dot b/docs/benchmark-fib.dot new file mode 100644 index 0000000..04d4459 --- /dev/null +++ b/docs/benchmark-fib.dot @@ -0,0 +1,19 @@ +// fib(35) iterative benchmark — all implementations +// "A diagram is worth 10,000 words." — russell@unturf.com +digraph benchmark_fib { + rankdir=LR + node [shape=record, style=filled, fontname="Helvetica", fontsize=11] + edge [style=invis] + label="fib(35) iterative — time in milliseconds (lower is better)" + labelloc=t + fontsize=14 + fontname="Helvetica Bold" + + cpython [label="{CPython|0.006 ms}" fillcolor="#0984e3" fontcolor=white width=0.5] + cinterp [label="{C interpreter|0.06 ms}" fillcolor="#fdcb6e" width=1.0] + jit [label="{C + JIT|0.09 ms}" fillcolor="#00b894" fontcolor=white width=1.2] + asm [label="{Assembly|0.6 ms}" fillcolor="#6c5ce7" fontcolor=white width=3.0] + pyvm [label="{Python VM|0.75 ms}" fillcolor="#e17055" fontcolor=white width=3.5] + + cpython -> cinterp -> jit -> asm -> pyvm +} diff --git a/docs/benchmark-fib.png b/docs/benchmark-fib.png new file mode 100644 index 0000000..7ca3949 Binary files /dev/null and b/docs/benchmark-fib.png differ diff --git a/docs/benchmark-speedup.dot b/docs/benchmark-speedup.dot new file mode 100644 index 0000000..2573d1d --- /dev/null +++ b/docs/benchmark-speedup.dot @@ -0,0 +1,25 @@ +// Speedup ratios: JIT vs each implementation +// "A diagram is worth 10,000 words." — russell@unturf.com +digraph speedup { + rankdir=TB + node [shape=box, style="filled,rounded", fontname="Helvetica", fontsize=12] + edge [fontname="Helvetica", fontsize=10, penwidth=2] + label="How much faster is the JIT? (ack(3,4) speedup ratios)" + labelloc=t + fontsize=14 + fontname="Helvetica Bold" + + jit [label="C + x86_64 JIT\n0.19 ms" fillcolor="#00b894" fontcolor=white shape=doubleoctagon width=2.5] + + cpython [label="CPython\n1.3 ms" fillcolor="#0984e3" fontcolor=white] + asm [label="x86_64 Assembly\n8 ms" fillcolor="#6c5ce7" fontcolor=white] + cinterp [label="C interpreter\n20 ms" fillcolor="#fdcb6e"] + pyvm [label="Python bytecode VM\n149 ms" fillcolor="#e17055" fontcolor=white] + + jit -> cpython [label=" 7x faster " color="#00b894" fontcolor="#00b894"] + jit -> asm [label=" 42x faster " color="#6c5ce7" fontcolor="#6c5ce7"] + jit -> cinterp [label=" 105x faster " color="#fdcb6e" fontcolor="#b8860b"] + jit -> pyvm [label=" 784x faster " color="#e17055" fontcolor="#e17055"] + + {rank=same; cpython; asm; cinterp; pyvm} +} diff --git a/docs/benchmark-speedup.png b/docs/benchmark-speedup.png new file mode 100644 index 0000000..c742c5c Binary files /dev/null and b/docs/benchmark-speedup.png differ diff --git a/docs/benchmark-sumto.dot b/docs/benchmark-sumto.dot new file mode 100644 index 0000000..2225b84 --- /dev/null +++ b/docs/benchmark-sumto.dot @@ -0,0 +1,19 @@ +// sum-to(50000) benchmark — all implementations +// "A diagram is worth 10,000 words." — russell@unturf.com +digraph benchmark_sumto { + rankdir=LR + node [shape=record, style=filled, fontname="Helvetica", fontsize=11] + edge [style=invis] + label="sum-to(50000) — time in milliseconds (lower is better)" + labelloc=t + fontsize=14 + fontname="Helvetica Bold" + + jit [label="{C + JIT|0.55 ms}" fillcolor="#00b894" fontcolor=white width=0.5] + cpython [label="{CPython|5.5 ms}" fillcolor="#0984e3" fontcolor=white width=1.5] + asm [label="{Assembly|43 ms}" fillcolor="#6c5ce7" fontcolor=white width=3.5] + cinterp [label="{C interpreter|109 ms}" fillcolor="#fdcb6e" width=6.0] + pyvm [label="{Python VM|437 ms}" fillcolor="#e17055" fontcolor=white width=10.0] + + jit -> cpython -> asm -> cinterp -> pyvm +} diff --git a/docs/benchmark-sumto.png b/docs/benchmark-sumto.png new file mode 100644 index 0000000..1f36edc Binary files /dev/null and b/docs/benchmark-sumto.png differ