Add causality and K-best example

causality-and-k-best/README.md

@@ -0,0 +1,42 @@
+# Causality and K-best
+
+This directory is a self-contained example based on the current Butadiene code.
+Nothing in `ILP/butadien` or `mod/butadien` is changed.
+
+## 1. Enumerate K best supports with Gurobi
+
+Set `K` near the top of `butadiensynthesis_k_best.py` and run:
+
+```bash
+python3 butadiensynthesis_k_best.py
+```
+
+The script is the existing Butadiene ILP with one small generalisation: instead of
+computing only the best and second-best support, it repeatedly excludes every
+previously found support. It writes all solutions to `gurobi_flows.json`.
+
+Thus "K best" here means K best distinct reaction supports, matching the meaning
+of the existing second-best code.
+
+## 2. Check the Gurobi solutions for causality
+
+Activate the MØD environment and run this directory with MØD:
+
+```bash
+mod -f check_causality.py
+```
+
+The checker reads `gurobi_flows.json`, maps each reaction to the current MØD
+derivation graph by educt/product SMILES, fixes exactly that hyperflow, and runs
+`causality.RealisabilityQuery`.
+
+Typical output is:
+
+```text
+solution 1: causally realisable: YES
+solution 2: causally realisable: NO
+...
+```
+
+`butadienNetwork.py` and `graph.py` are local helper copies for constructing
+the same Butadiene MØD network.