{"id":51462598,"url":"https://github.com/codenlighten/crown","last_synced_at":"2026-07-06T07:01:19.472Z","repository":{"id":363638960,"uuid":"1264056628","full_name":"codenlighten/crown","owner":"codenlighten","description":"Certified QUBO/Ising optimization with trustless Proof-of-Collapse optimality certificates","archived":false,"fork":false,"pushed_at":"2026-06-09T18:34:37.000Z","size":86,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T19:24:03.460Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codenlighten.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-09T14:15:57.000Z","updated_at":"2026-06-09T18:34:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/codenlighten/crown","commit_stats":null,"previous_names":["codenlighten/crown"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/codenlighten/crown","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenlighten%2Fcrown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenlighten%2Fcrown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenlighten%2Fcrown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenlighten%2Fcrown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codenlighten","download_url":"https://codeload.github.com/codenlighten/crown/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenlighten%2Fcrown/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35180933,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-06T07:01:16.709Z","updated_at":"2026-07-06T07:01:19.404Z","avatar_url":"https://github.com/codenlighten.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CROWN — Certified QUBO/Ising Optimization with Proof-of-Collapse\n\n[![CI](https://github.com/codenlighten/crown/actions/workflows/ci.yml/badge.svg)](https://github.com/codenlighten/crown/actions/workflows/ci.yml)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n\nCROWN is a classical optimizer for **QUBO / Ising** problems that returns not\njust a solution but a **machine-checkable proof of optimality** — one a third\nparty (or a smart contract) can verify by *pure bounded arithmetic*, without\nrerunning the solver and, for many frustrated instances, without trusting any\nheuristic.\n\n\u003e **Thesis.** We don't claim NP-hard problems are easy. We claim many real\n\u003e instances are a large *reducible shell* wrapping a small *irreducible core*,\n\u003e that the shell collapses with a **certified lower bound**, and that the whole\n\u003e result is independently verifiable — *Proof-of-Collapse*.\n\n```bash\npip install -e .          # or: pip install git+https://github.com/codenlighten/crown\n\ncrown solve  problem.qubo --cert c.json --problem p.json   # solve + emit certificate\ncrown verify p.json c.json                                 # trustless verification\ncrown demo                                                 # six worked regimes\ncrown bench --quick                                        # benchmark smoke run\npython tests/test_crown.py                                 # 36 tests\n```\n\nA problem file is either **canonical JSON** (`.json`) or **sparse triplets**\n(`.txt`/`.qubo`, one `i j value` term per line — `i==j` is linear). Or use the\nlibrary directly:\n\n```python\nfrom crown import QUBO, crown_solve, build_certificate, verify\nres  = crown_solve(QUBO.from_matrix(my_matrix))\ncert = build_certificate(qubo, res)        # a Proof-of-Collapse certificate\nassert verify(qubo, cert).certified_optimal\n```\n\n## What it does\n\n```\nQUBO ──roof_dual──▶ certified global bound + persistencies (the shell)\n     ──reduce────▶ fixed shell + irreducible core + lift map\n     ──solve_core▶ bucket elimination (thin) · AOBB / AND-decomposition (wide)\n     ──lift──────▶ full assignment, exact energy on the ORIGINAL problem\n     ──certify───▶ a Proof-of-Collapse certificate (see below)\n```\n\nEvery run emits a certificate carrying the problem/core hashes, the assignment,\ntwo **trustless rigorous lower-bound certificates** (a roof-dual dual vector and\na full-problem **JGLP pairwise-cluster** decomposition), and the claimed kind.\n`crown/verify.py` re-checks all of it independently:\n\n| certificate kind | meaning | rigour |\n|---|---|---|\n| `bound-tight` | energy == best rigorous bound (roof-dual **or** full-problem JGLP) | fully rigorous, persistency-independent, **trustless arithmetic** |\n| `exact-core` | the core was solved exactly (elimination / AOBB) | optimal given roof-dual strong persistency (a theorem) |\n| `bound-tight-core` | energy == tightened core bound | optimal given persistency |\n| `bracket` | no bound met the energy | not certified — reports `[lower bound, energy]` + gap |\n\nThe verifier **rejects** a tampered solution, a swapped problem, a fabricated\nbound, or an optimality *over*-claim it cannot independently confirm.\n\n## What's established vs. what's new\n\nThe individual algorithms are well-established and were implemented from scratch\nand validated against brute force: **roof duality** (Hammer–Hansen–Simeone,\nBoros–Hammer), **bucket / mini-bucket elimination** (Dechter), **weighted\nmini-bucket / JGLP cost-shifting** (Ihler, Marinescu–Dechter), **AND/OR\nbranch-and-bound**.\n\nThe novel synthesis is the **trustless optimization certificate** —\n*Proof-of-Collapse*: a hash-chained, arithmetic-checkable proof of a claimed\noptimum (or an honest bracket), suitable for on-chain anchoring. The key\nidentity is that JGLP reparameterizes the energy into pairwise clusters with\n`const + Σ_c table_c(x) ≡ E(x)`, so shipping the clusters lets anyone verify the\nlower bound `const + Σ_c min table_c` by summing the clusters back to the problem\nand recomputing per-cluster minima — sound regardless of how they were produced.\n\nSee **[DESIGN.md](DESIGN.md)** for the grounded technical spec (including the\nhonest findings: why gauge can't concentrate frustration, why single-variable\ncost-shifting equals roof duality, the decomposability↔JGLP-strength tension),\nand **[VISION.md](VISION.md)** for the original north-star vision.\n\n## Layout\n\n```\ncrown/\n  ising.py        QUBO model, exact energy, Ising view, canonical hashing\n  roofdual.py     roof-dual LP: certified bound + dual certificate + persistency\n  reduce.py       shell substitution + lift map\n  elimination.py  bucket elimination + (weighted) mini-bucket + JGLP\n  search.py       JGLP-guided AOBB, AND/OR-with-caching, component decomposition\n  andor.py        static mini-bucket heuristic + bucket-tree cost-shifting\n  rigorous.py     full-problem JGLP -\u003e trustless pairwise-cluster bound certificate\n  circuit.py      certificate-as-arithmetic-circuit cost + validity-preserving minimiser\n  solve.py        the distill -\u003e reduce -\u003e solve -\u003e certify pipeline\n  certificate.py  Proof-of-Collapse certificate construction\n  verify.py       trustless verifier\n  qubo_io.py      load/save QUBOs (canonical JSON + sparse triplets)\n  cli.py          the `crown` command-line interface\n  generators.py   structured test/demo instances\nexamples/demo.py  six end-to-end regimes\nbenchmarks/       self-benchmark (RESULTS.md) + SOTA comparison (compare.py,\n                  external_solvers.py, instances.py, EXTERNAL_RESULTS.md)\ntests/            36 soundness + correctness tests (validated vs brute force)\n```\n\n## Benchmarks\n\n`python benchmarks/run_benchmark.py` runs CROWN across four instance families and\nvalidates it end-to-end. From the latest full run (80 instances, n up to 44 —\nfull table in **[benchmarks/RESULTS.md](benchmarks/RESULTS.md)**):\n\n- **Correctness:** **40/40** — CROWN's energy matched brute force on every\n  instance small enough to enumerate. It never returned a wrong optimum.\n- **Trustless verification:** **80/80** certificates independently re-verified,\n  with **0** optimality over-claims.\n- **Certified optimality:** 100% on the structured families; **90%** on\n  dense-random (n ≤ 44), of which **70%** carry the strongest fully-rigorous\n  `bound-tight` proof.\n- **Rigorous bound tightening:** full-problem JGLP cut the mean gap-to-optimum\n  from **6.04** (roof duality) to **0.25**.\n- **Scale:** on 40 instances beyond brute-force reach (up to 2⁴⁴), CROWN\n  returned a **certified** optimum **95%** of the time — proofs, not guesses.\n\n### Validated against state-of-the-art\n\n`python benchmarks/compare.py` runs CROWN head-to-head against **toulbar2** (the\n*same* AND/OR-branch-and-bound + mini-bucket algorithm family, in tuned C++) and\n**SCIP**, on standard Sherrington–Kirkpatrick spin-glass and max-cut instances —\nsee **[benchmarks/EXTERNAL_RESULTS.md](benchmarks/EXTERNAL_RESULTS.md)**. Two\nhonest findings:\n\n- **Correctness is corroborated by an independent SOTA solver.** CROWN's optima\n  matched toulbar2 on **20/20** instances and brute force on **8/8**; on the\n  **19** it reported as *certified* it matched toulbar2's proven optimum every\n  time; it never undercut a proven optimum and never certified a wrong one.\n- **CROWN is *not* performance-competitive.** toulbar2 was **~110× faster**\n  (median) — it proves in well under a second the spin-glasses that take CROWN\n  tens of seconds, and certifies n=28 instances that CROWN's pure-Python search\n  cannot certify at all. CROWN's value is the *verifiable certificate* and the\n  clean reference implementation — not raw solve speed.\n\n## Status \u0026 honest scope\n\nResearch-quality, fully tested (36/36), benchmarked, and cross-validated against\ntoulbar2/SCIP. To be clear about what CROWN is and isn't (see\n**[RELATED_WORK.md](RELATED_WORK.md)**):\n\n- The algorithms (roof duality, bucket/mini-bucket elimination, JGLP, AND/OR\n  search) are **established prior art**, implemented from scratch and validated.\n- Certified optimization is an **active field** (VeriPB / pseudo-Boolean proof\n  logging, MAP-MRF dual certificates); CROWN's certificate is classical LP/\n  Lagrangian duality + reparameterization. The most CROWN claims is a *compact,\n  arithmetic-checkable, hash-anchorable bound certificate for QUBO* — an\n  engineering/packaging contribution, not a new theorem.\n- It is **not** competitive with toulbar2/Gurobi on speed or scale.\n\nWe probed the one possibly-open niche — a compact, transparent, on-chain\noptimality certificate for QUBO — and **closed it with evidence**\n(`benchmarks/CIRCUIT_RESULTS.md`): for hard frustrated instances the compact\ncertificate usually doesn't exist (the integrality gap), and where it does the\nverification circuit grows exponentially with cluster scope. The honest verdict\nand landscape are in **[RELATED_WORK.md](RELATED_WORK.md)**.\n\n## License\n\nApache-2.0. Copyright 2026 the CROWN contributors.\n\n🤖 Built with [Claude Code](https://claude.com/claude-code).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodenlighten%2Fcrown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodenlighten%2Fcrown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodenlighten%2Fcrown/lists"}