iwls_runner: pipeline driving mig_egg on IWLS 2026 contest benchmarks

iwls_runner/.gitignore

@@ -0,0 +1,4 @@
+results/
+abc.history
+*.pyc
+__pycache__/

iwls_runner/README.md

@@ -0,0 +1,131 @@
+# iwls_runner
+
+A pipeline that drives **mig_egg** on the **IWLS 2026 logic-synthesis
+contest** benchmarks.
+
+Input: 100 multi-output truth tables (`benchmarks/ex2NN.truth`).
+Output: a contest-shaped zip of binary AIGER files plus per-bench Pareto
+points of (delay, area).
+
+This folder is part of branch **`iwls-runner`** in this repository. The
+sibling commit on the same branch updates `mig_egg/src/lib.rs` to switch
+`rules()` to AIG-only and add an `iwls_run` test entry that this pipeline
+drives. Checking out the branch gives you both pieces; you do not need to
+apply any external patch.
+
+## What this folder contains
+
+```
+iwls_runner/
+├── README.md                  this file
+├── abc.rc                     ABC startup config (provides resyn2,
+│                              compress2rs, &dc2 aliases) — must sit in cwd
+│                              for ABC alias commands to work
+├── benchmarks/                100 IWLS truth tables (ex200..ex299)
+├── scripts/
+│   ├── aig_to_prefix.py       binary AIGER -> Lisp prefix expressions
+│   ├── prefix_to_aig.py       Lisp prefix -> EQN -> ABC strash -> AIGER
+│   ├── run_one_bench.py       one bench end-to-end (truth->AIG->prefix->
+│   │                           mig_egg->prefix->AIG->cec)
+│   ├── run_all.py             parallel runner over many benches
+│   └── finalize.py            cec-verify + per-bench Pareto + contest zip
+├── examples/
+│   ├── smoke_one.sh           single bench (ex212), ~30s, sanity check
+│   └── full_run.sh            all 100 benches + finalize, ~30 min on 16 cores
+└── results/                   per-run outputs land here (gitignored)
+```
+
+## Quick start
+
+```bash
+# 1. build the mig_egg test binary (this branch already has the lib.rs
+#    changes the pipeline depends on)
+cd ../mig_egg                 # i.e. <repo>/mig_egg
+cargo build --release --tests --no-default-features
+
+# 2. point at your repo root and abc binary, then run smoke
+export ELOGIC_REPO_DIR="$(cd ../.. && pwd)"   # parent of iwls_runner
+export ABC=/abs/path/to/abc                    # default: 'abc' on PATH
+
+cd -                           # back to iwls_runner/
+bash examples/smoke_one.sh     # ex212, ~30s
+
+# 3. full run
+bash examples/full_run.sh
+```
+
+## What the lib.rs sibling commit changes
+
+Single file: `mig_egg/src/lib.rs` (133-line diff, fully revertible with
+`git checkout main -- mig_egg/src/lib.rs`).
+
+1. **`rules()` switched to AIG-only.** Majority-language rules (`maj_*`,
+   `distri`, `com_associ`, ...) are commented out; the 5 AND-language rules
+   already defined in the file (`comm_and`, `comp_and`, `dup_and`,
+   `and_true`, `and_false`) are uncommented. `associ_and` stays off
+   because its O(N²) match cost blows up `node_limit` on bigger benches.
+   Reason: IWLS truth tables strash into pure AIG — running maj rules on
+   `(& a b)` form fires zero rewrites.
+
+2. **`iter_limit(1000)` → `iter_limit(10)`** at three sites
+   (`simplify_depth`, two `simplify_best` runners). egg's `time_limit`
+   is best-effort; tightening `iter_limit` is what actually keeps
+   wall-clock bounded on dense ASTs.
+
+3. **New `iwls_run` test entry** at the bottom of the test module. It
+   reads `IWLS_PREFIX_FILE` (a path to a prefix file with one PO per line,
+   `<idx>\t<expr>`) and, for each line, calls `simplify_best` and prints
+   `iwls case <idx> best_expr[0] = <expr>` to stdout. The Python wrapper
+   greps for that line. `IWLS_FIRST_DEPTH=true|false` chooses delay-first
+   vs area-first cost.
+
+## How a bench gets through
+
+```
+benchmarks/ex212.truth
+     │  abc:  read_truth -xf ... ; strash ; print_stats ; write_aiger
+     ▼
+init.aig  (binary AIGER)
+     │  scripts/aig_to_prefix.py
+     ▼
+init.prefix     (one PO per line, e.g.  "0\t(& (~ a) (& b c))")
+     │  $ELOGIC_REPO_DIR/target/release/deps/mig_egg-<hash> iwls_run
+     │  (env IWLS_PREFIX_FILE=init.prefix)
+     ▼
+optimized.prefix  (best_expr per PO from simplify_best)
+     │  scripts/prefix_to_aig.py  (writes EQN, ABC strash + resyn2)
+     ▼
+final.aig
+     │  abc:  read_truth -xf ... ; cec -n final.aig
+     ▼
+results/<run>/aigs/ex212_<lev>.aig    (only if cec equivalent)
+```
+
+`finalize.py` then walks `results/<run>/aigs/`, dedupes by (lev, and),
+applies per-bench Pareto, optionally cec-verifies again, and emits a flat
+zip ready for the IWLS contest submission form.
+
+## Useful knobs
+
+| flag / env | default | what it does |
+| --- | --- | --- |
+| `--workers N` (run_all) | 16 | concurrent benches; e-graph is RAM-heavy on big inputs (~1-15 GB / worker peak), drop to 4 if you OOM |
+| `--simplify-timeout S` (run_one / run_all) | 900 | wall cap on the cargo test invocation per bench |
+| `--cec-timeout S` | 1800 | wall cap on `cec -n` |
+| `--first-depth true\|false` | true | forwarded to `IWLS_FIRST_DEPTH` (delay-first vs area-first cost) |
+| `--resume` (run_all) | off | skip benches whose `results/<bench>.json` is `ok=true` |
+| `ABC` env | `abc` | path to abc binary |
+| `ELOGIC_REPO_DIR` env | (required) | abs path to the repo root that contains `mig_egg/`; the parent of this folder if you keep `iwls_runner/` inside the repo |
+
+## Notes
+
+- All ABC commands run with `cwd=<this folder>` so abc.rc aliases
+  (`resyn2`, `compress2rs`, `&dc2`) work. If you replace abc.rc, keep
+  those aliases.
+- Truth tables are read with `-xf` (binary, file). Each line is one output;
+  line length is 2^k where k = #inputs.
+- The contest scorer wants `exNNN_LLL.aig` (3-digit padded level) at the
+  zip root. `finalize.py` produces exactly that.
+- Big benches (ex299, ex230, etc.) hit egg's `node_limit(5000)` ceiling and
+  fail simplify. That's a real ceiling of the AIG ruleset on densely shared
+  graphs, not a timeout — bumping simplify-timeout doesn't help.

iwls_runner/abc.rc

@@ -0,0 +1,150 @@
+# global parameters
+set check         # checks intermediate networks
+#set checkfio      # prints warnings when fanins/fanouts are duplicated
+#unset checkread   # does not check new networks after reading from file
+#set backup        # saves backup networks retrived by "undo" and "recall"
+#set savesteps 1   # sets the maximum number of backup networks to save 
+#set progressbar   # display the progress bar
+
+# program names for internal calls
+set dotwin dot.exe
+set dotunix dot
+set gsviewwin gsview32.exe
+set gsviewunix gv
+set siswin sis.exe
+set sisunix sis
+set mvsiswin mvsis.exe
+set mvsisunix mvsis
+set capowin MetaPl-Capo10.1-Win32.exe
+set capounix MetaPl-Capo10.1
+set gnuplotwin wgnuplot.exe
+set gnuplotunix gnuplot
+
+# Niklas Een's commands
+#load_plugin C:\_projects\abc\lib\bip_win.exe "BIP"
+
+# standard aliases
+alias hi history
+alias b balance
+alias cg clockgate
+alias cl cleanup
+alias clp collapse
+alias cs care_set
+alias el eliminate
+alias esd ext_seq_dcs
+alias f fraig
+alias fs fraig_sweep
+alias fsto fraig_store
+alias fres fraig_restore
+alias fr fretime
+alias ft fraig_trust
+alias ic indcut
+alias lp lutpack
+alias pcon print_cone
+alias pd print_dsd
+alias pex print_exdc -d
+alias pf print_factor
+alias pfan print_fanio
+alias pg print_gates
+alias pl print_level
+alias plat print_latch
+alias pio print_io
+alias pk print_kmap
+alias pm print_miter
+alias ps print_stats 
+alias psb print_stats -b
+alias psu print_supp
+alias psy print_symm
+alias pun print_unate
+alias q quit
+alias r read
+alias ra read_aiger
+alias r3 retime -M 3
+alias r3f retime -M 3 -f
+alias r3b retime -M 3 -b
+alias ren renode
+alias rh read_hie
+alias ri read_init
+alias rl read_blif
+alias rb read_bench
+alias ret retime
+alias dret dretime
+alias rp read_pla
+alias rt read_truth
+alias rv read_verilog
+alias rvl read_verlib
+alias rsup read_super mcnc5_old.super
+alias rlib read_library
+alias rlibc read_library cadence.genlib
+alias rty read_liberty
+alias rlut read_lut
+alias rw rewrite
+alias rwz rewrite -z
+alias rf refactor
+alias rfz refactor -z
+alias re restructure
+alias rez restructure -z
+alias rs resub
+alias rsz resub -z
+alias sa set autoexec ps
+alias scl scleanup
+alias sif if -s
+alias so source -x
+alias st strash
+alias sw sweep
+alias ssw ssweep
+alias tr0 trace_start
+alias tr1 trace_check
+alias trt "r c.blif; st; tr0; b; tr1"
+alias u undo
+alias w write
+alias wa write_aiger
+alias wb write_bench
+alias wc write_cnf
+alias wh write_hie
+alias wl write_blif
+alias wp write_pla
+alias wv write_verilog
+
+# standard scripts
+alias resyn       "b; rw; rwz; b; rwz; b"
+alias resyn2      "b; rw; rf; b; rw; rwz; b; rfz; rwz; b"
+alias resyn2a     "b; rw; b; rw; rwz; b; rwz; b"
+alias resyn3      "b; rs; rs -K 6; b; rsz; rsz -K 6; b; rsz -K 5; b"
+alias compress    "b -l; rw -l; rwz -l; b -l; rwz -l; b -l"
+alias compress2   "b -l; rw -l; rf -l; b -l; rw -l; rwz -l; b -l; rfz -l; rwz -l; b -l"
+alias choice      "fraig_store; resyn; fraig_store; resyn2; fraig_store; fraig_restore"
+alias choice2     "fraig_store; balance; fraig_store; resyn; fraig_store; resyn2; fraig_store; resyn2; fraig_store; fraig_restore"
+alias rwsat       "st; rw -l; b -l; rw -l; rf -l"
+alias drwsat2     "st; drw; b -l; drw; drf; ifraig -C 20; drw; b -l; drw; drf"
+alias share       "st; multi -m; sop; fx; resyn2"
+alias addinit     "read_init; undc; strash; zero"
+alias blif2aig    "undc; strash; zero"
+alias v2p         "&vta_gla; &ps; &gla_derive; &put; w 1.aig; pdr -v"
+alias g2p         "&ps; &gla_derive; &put; w 2.aig; pdr -v"
+alias &sw_        "&put; sweep; st; &get"
+alias &fx_        "&put; sweep; sop; fx; st; &get"
+alias &dc3        "&b; &jf -K 6; &b; &jf -K 4; &b"
+alias &dc4        "&b; &jf -K 7; &fx; &b; &jf -K 5; &fx; &b"
+
+# resubstitution scripts for the IWLS paper
+alias src_rw      "st; rw -l; rwz -l; rwz -l" 
+alias src_rs      "st; rs -K 6 -N 2 -l; rs -K 9 -N 2 -l; rs -K 12 -N 2 -l" 
+alias src_rws     "st; rw -l; rs -K 6 -N 2 -l; rwz -l; rs -K 9 -N 2 -l; rwz -l; rs -K 12 -N 2 -l" 
+alias resyn2rs    "b; rs -K 6; rw; rs -K 6 -N 2; rf; rs -K 8; b; rs -K 8 -N 2; rw; rs -K 10; rwz; rs -K 10 -N 2; b; rs -K 12; rfz; rs -K 12 -N 2; rwz; b"
+alias r2rs        "b; rs -K 6; rw; rs -K 6 -N 2; rf; rs -K 8; b; rs -K 8 -N 2; rw; rs -K 10; rwz; rs -K 10 -N 2; b; rs -K 12; rfz; rs -K 12 -N 2; rwz; b"
+alias compress2rs "b -l; rs -K 6 -l; rw -l; rs -K 6 -N 2 -l; rf -l; rs -K 8 -l; b -l; rs -K 8 -N 2 -l; rw -l; rs -K 10 -l; rwz -l; rs -K 10 -N 2 -l; b -l; rs -K 12 -l; rfz -l; rs -K 12 -N 2 -l; rwz -l; b -l"
+alias c2rs        "b -l; rs -K 6 -l; rw -l; rs -K 6 -N 2 -l; rf -l; rs -K 8 -l; b -l; rs -K 8 -N 2 -l; rw -l; rs -K 10 -l; rwz -l; rs -K 10 -N 2 -l; b -l; rs -K 12 -l; rfz -l; rs -K 12 -N 2 -l; rwz -l; b -l"
+alias &resyn2rs    "&put; resyn2rs; &get"
+alias &compress2rs "&put; compress2rs; &get"
+
+# use this script to convert 1-valued and DC-valued flops for an AIG
+alias fix_aig     "logic; undc; strash; zero"
+
+# use this script to convert 1-valued and DC-valued flops for a logic network coming from BLIF
+alias fix_blif    "undc; strash; zero"
+
+# lazy man's synthesis
+alias recadd3     "st; rec_add3; b; rec_add3; dc2; rec_add3; if -K 8; bidec; st; rec_add3; dc2; rec_add3; if -g -K 6; st; rec_add3"
+
+

iwls_runner/benchmarks/ex255.truth

@@ -0,0 +1,8 @@
+1010101010101010000000000000000010101010101010100000000000000000101010101010101000000000000000001010101010101010000000000000000010101010101010100000000000000000101010101010101000000000000000001010101010101010000000000000000010101010101010100000000000000000
+0110011001100110101010101010101011001100110011000000000000000000011001100110011010101010101010101100110011001100000000000000000001100110011001101010101010101010110011001100110000000000000000000110011001100110101010101010101011001100110011000000000000000000
+0001111000011110011001100110011001011010010110101010101010101010101101001011010011001100110011001111000011110000000000000000000000011110000111100110011001100110010110100101101010101010101010101011010010110100110011001100110011110000111100000000000000000000
+0000000111111110000111100001111000111001110001100110011001100110011011011001001001011010010110100101010110101010101010101010101010101011010101001011010010110100100100110110110011001100110011001100011100111000111100001111000011111111000000000000000000000000
+0101010101010100101010110101010001010010100101001011010010110100010010010010010010010011011011000110011011001100110011001100110000110011100110001100011100111000000111000111000011110000111100000000011111000000111111110000000000000000000000000000000000000000
+1001100110011000001100111001100001100011000110001100011100111000100011100011100000011100011100000111100011110000111100001111000011000011111000000000011111000000000111111000000011111111000000001111100000000000000000000000000000000000000000000000000000000000
+1110000111100000110000111110000010000011111000000000011111000000000011111100000000011111100000000111111100000000111111110000000011111100000000001111100000000000111000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+1111111000000000111111000000000011111100000000001111100000000000111100000000000011100000000000001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000