{"id":51399991,"url":"https://github.com/gaperez64/dlx4sop","last_synced_at":"2026-07-04T05:36:36.811Z","repository":{"id":360922362,"uuid":"1252298949","full_name":"gaperez64/dlx4sop","owner":"gaperez64","description":"One of Knuth's dancing techniques for strong quantum-circuit simulation by evaluating sums of powers","archived":false,"fork":false,"pushed_at":"2026-07-02T06:29:22.000Z","size":2367,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-04T05:36:33.865Z","etag":null,"topics":["circuits","openqasm","quantum","simulation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gaperez64.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"gaperez64","thanks_dev":null,"custom":null}},"created_at":"2026-05-28T11:37:06.000Z","updated_at":"2026-07-02T06:29:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gaperez64/dlx4sop","commit_stats":null,"previous_names":["gaperez64/dlx4sop"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/gaperez64/dlx4sop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaperez64%2Fdlx4sop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaperez64%2Fdlx4sop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaperez64%2Fdlx4sop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaperez64%2Fdlx4sop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gaperez64","download_url":"https://codeload.github.com/gaperez64/dlx4sop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaperez64%2Fdlx4sop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35111429,"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-04T02:00:05.987Z","response_time":113,"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":["circuits","openqasm","quantum","simulation"],"created_at":"2026-07-04T05:36:35.897Z","updated_at":"2026-07-04T05:36:36.802Z","avatar_url":"https://github.com/gaperez64.png","language":"Python","funding_links":["https://buymeacoffee.com/gaperez64"],"categories":[],"sub_categories":[],"readme":"# dlx4sop\n\n`dlx4sop` is a C/Meson toolkit for exact finite-modulus quadratic sums of\npowers (QSOPs). The project goal is a competitive exact strong simulator using\nQSOPs with fixed-boundary circuit amplitudes.\n\nCurrent benchmark corpus coverage, solver timings, and native simulator comparisons live\nin [scoreboard.md](scoreboard.md).\n\n## Build\n\n```sh\nmeson setup build\nmeson compile -C build\nmeson test -C build --print-errorlogs\n```\n\nThe default `build` directory is a debug build (`-O0`, assertions on) — correct for\ndevelopment and the test suite. **For benchmarking, use an optimized build** (roughly\n3x faster on solver hot paths):\n\n```sh\nmeson setup build-bench --buildtype=release -Db_lto=true -Dc_args=-march=x86-64-v2\nmeson compile -C build-bench\n```\n\n`-march=x86-64-v2` enables the hardware `popcnt` instruction (portable across x86 CPUs\nsince ~2009) — without it `__builtin_popcount` falls back to a slow libgcc routine that\ndominates ordering-heavy solves. On Apple Silicon (arm64) popcount is hardware by\ndefault, so the `-Dc_args` is unnecessary there.\n\nPoint the benchmark tooling at the optimized binaries (e.g.\n`--sop-solve build-bench/sop-solve`); see the [Benchmarks](#benchmarks) section.\n\nCI enforces at least 75% line coverage over production `src` files:\n\n```sh\ntools/check-coverage.sh build-coverage\n```\n\nRelease binaries are built by `.github/workflows/release-binaries.yml` when a\n`v*` tag is pushed, or manually through GitHub Actions. The workflow compiles\nand packages `qasm2sop`, `sop-check`, `sop-solve`, `sop-stats`, and `sop2wmc`\nas `linux-x86_64` and `macos-arm64` tarballs with SHA-256 sidecar files.\n\n## Tools\n\n- `sop-check`: parse, validate, pin-reduce, and canonicalize QSOP files.\n- `sop-stats`: print structural statistics, with opt-in exact small-width\n  support-graph diagnostics.\n- `sop-solve`: solve exact residue-count histograms; stats mode can include\n  the count vector used by benchmark tooling to reconstruct amplitudes and a\n  convenience probability estimate via `--include-probability`.\n- `qasm2sop`: import the supported static OpenQASM 2.0 subset into QSOP,\n  including common Clifford/T gates, supported phase rotations, `u/u2/u3`,\n  controlled phase/H/SX gates, `dcx`, `rxx/ryy/rzz`, `ccz/ccx/rccx/cswap`,\n  and `iswap`.\n- `sop2wmc`: export a QSOP to DIMACS CNF / WPCNF for external model counting.\n  Five encodings are available via `--encoding \u003cname\u003e`:\n  - `residue-accumulator` (alias `residue`, default): one DIMACS CNF per\n    residue 0..r−1; plain #SAT each. Works with any integer counter (Ganak\n    `--mode 0`, d4, sharpSAT). Requires r calls per instance.\n  - `amp-and` (alias `amplitude`): single WPCNF with Tseitin AND auxiliaries\n    carrying hard complex weights ω^b. All auxiliaries are circuit-determined;\n    use `ganak --mode 6 --verb 0`. Multiply the raw WMC result by\n    ω^constant (from the `c amplitude_factor` metadata line) to get the full\n    amplitude.\n  - `amp-soft`: single WPCNF with implication-only auxiliaries and soft weights\n    ω^b − 1. Produces fewer clauses per edge than amp-and; Ganak integrates\n    over underdetermined variables.\n  - `residue-fourier`: r WPCNF blocks (one per Fourier exponent t) followed by\n    an outer iDFT. Inner encoding selectable via\n    `--wmc-fourier-inner (amp-and|amp-soft)`.\n  - `amp-block`: single WPCNF; detects a uniform complete bipartite subgraph\n    A×B in the edge set and encodes it with a mod-r adder counter per side plus\n    Tseitin selector variables with hard weights ω^(c·a·b mod r). Non-block\n    edges use amp-and. Block triggers when savings ≥ `--wmc-block-min-savings`\n    and both sides ≥ `--wmc-block-min-side` (defaults 0 and 4); falls back to\n    amp-soft output when no profitable block is found.\n- `tools/*.py`: benchmark runners, corpus scanners, and boundary translators.\n  `tools/bench.py` is the unified benchmark entry point (see **Benchmarks**\n  below). `tools/bench_wmc_ganak.py` drives `sop2wmc` + Ganak and cross-checks\n  results against `sop-solve`; all five current encodings are supported.\n\nThe C core has no runtime dependency on Qiskit, PyZX, MQT, or FeynmanDD.\nExternal frameworks stay at the benchmark/import boundary.\n\n## Solver Guide\n\n- `components`: default robust exact solver.\n- `treewidth --treewidth-order min-fill-max-degree`: direct DP baseline for\n  widened corpus tiers.\n- `branch --branch-heuristic split`: current hybrid backend; it splits\n  components and dispatches eligible residuals to treewidth or rankwidth.\n- `rankwidth`: exact decomposition-DP backend with cut-rank diagnostics and\n  count-table/Fourier modes; useful for comparison and targeted\n  low-rank cases, but not the default corpus winner.\n- `brute-force`: small-instance oracle.\n\n## QSOP Format\n\n```text\np qsop-sign \u003cr\u003e \u003cvariables\u003e \u003csign_edges\u003e\nn \u003cnormalization_h\u003e\ncst \u003cconstant_mod_r\u003e\nu \u003cvertex\u003e \u003cunary_coefficient_mod_r\u003e\ne \u003cu\u003e \u003cv\u003e\nf \u003cvertex\u003e \u003c0 | 1\u003e\n```\n\nQuadratic terms are sign edges with implicit coefficient `r/2`;\nduplicate sign edges cancel by parity. Pins (`f`) are applied during parsing,\nand canonical output uses dense variable IDs. Solver\n`counts` are ordinary assignment counts bucketed by phase residue modulo `r`.\n\n## Examples\n\n```sh\nbuild/sop-check tests/golden/sign_raw.qsop\nbuild/sop-stats --format json tests/golden/sign_expected.qsop\nbuild/sop-stats --exact-widths --exact-width-max-vars 12 tests/golden/solve_sign_path.qsop\nbuild/sop-solve --backend treewidth --treewidth-order min-fill-max-degree tests/golden/solve_disconnected.qsop\nbuild/sop-solve --format stats --include-result tests/golden/solve_single.qsop\nbuild/sop-solve --format stats --backend treewidth --solve-mode fourier tests/golden/solve_disconnected.qsop\nbuild/qasm2sop --input 1 --output 1 tests/golden/qasm_h_boundary.qasm\nbuild/qasm2sop --input 1 --output 1 tests/golden/qasm_h_boundary.qasm | build/sop-solve --format stats --include-probability -\nbuild/sop2wmc --residue all tests/golden/solve_disconnected.qsop\nbuild/sop2wmc --residue 2 -o residue2.cnf tests/golden/solve_disconnected.qsop \u0026\u0026 ganak residue2.cnf\nbuild/sop2wmc --encoding amplitude tests/golden/solve_disconnected.qsop | ganak --mode 6 --verb 0 -\n```\n\nThe WMC export reconstructs `amplitude = sum_k counts[k] * exp(2*pi*i*k/r)` and\n`probability = |amplitude|^2 * 2^(-norm_h)` (the same convention as\n`sop-solve --include-probability`) outside the counter; the metadata header in\neach CNF block documents the variable map and the final accumulator bits.\n\n## Benchmarks\n\nThe public performance summary is the QSOP\n[scoreboard.md](scoreboard.md).\n\n`tools/bench.py` is the unified benchmark entry point. It requires only the\nbuilt binaries and the committed QSOP corpus for local runs; external tools\n(Ganak, native simulators, QASM manifests) are only needed for full refreshes.\n\n### Local backend tuning (no external tools)\n\n```sh\nmeson compile -C build\npython3 tools/bench.py local \\\n    --tier tier-17-32 \\\n    --backend treewidth \\\n    --backend rankwidth:from-treewidth \\\n    --backend branch:auto \\\n    --timeout 5 \\\n    --out artifacts/local/tier-17-32.jsonl\npython3 tools/bench.py render \\\n    --artifact-dir artifacts/local \\\n    --view local \\\n    --output /tmp/local-scoreboard.md\n```\n\nAvailable backend variants for `--backend`:\n\n```text\ntreewidth\nrankwidth:from-treewidth\nrankwidth:best        (best decomposition strategy)\nrankwidth:validate    (cross-check two solve paths for consistency)\nbranch:auto\nbranch:from-treewidth\nbranch:native\nbranch:no-rankwidth   (control: branch without rankwidth delegation)\n```\n\n### Full scoreboard refresh (requires Ganak + native simulators)\n\n```sh\npython3 tools/run_corpus_benchmarks.py \\\n    --artifact-dir artifacts/full \\\n    --ganak /path/to/ganak\n```\n\n`run_corpus_benchmarks.py` is the single orchestrator. It runs solver, WMC (Ganak),\nand native-simulator jobs for all tiers (including the MQT Bench large tiers) and the\nWMC-vs-solver scaling study, then renders `scoreboard.md`, `scoreboard.json`, and\nflat `scoreboard-assets/` SVGs for the QSOP benchmark set.\n\n`bench.py full` is a thin alias for the same pipeline. Pass `--skip-wmc`,\n`--skip-native`, `--skip-solver`, `--skip-scaling`, or `--skip-scoreboard` to run a\nsubset, `--timeout N` to override the default 30 s per-instance timeout, and\n`--scaling-timeout N` / `--clifford-max-qubits N` to tune the scaling study and the\nstabilizer-engine qubit cap.\n\nThe native baseline uses dense statevector engines under a qubit cap plus\n`qiskit-clifford` (stabilizer, O(n²) memory) for the large Clifford circuits the\nstatevector engines cannot reach. QSOPs are compared against native runs on\nthe same boundaries (native amplitudes are the shared ground truth).\n\n#### Scaling study (synthetic family)\n\nThe WMC-vs-solver crossover study runs on a committed synthetic phase-polynomial\nfamily under `benchmarks/corpus/sop/synthetic/scaling/`, regenerable with:\n\n```sh\npython3 tools/gen_scaling_family.py --qubits 8,12,16,20,24,28 --seeds 1,2,3 \\\n    --materialize-dir benchmarks/corpus/sop/synthetic/scaling --qasm2sop build/qasm2sop\n```\n\nReal scalable circuit families do not work here: the importable QSOP gate set is\nfinite-modulus (Clifford+T and dyadic phases), so the MQT families that scale\ntreewidth (qaoa/qft/vqe) are rejected for their continuous angles, while the\nimportable ones (ghz/bv/graphstate) are Clifford with trivial treewidth. The\nsynthetic family has treewidth growing with qubit count and lets the scoreboard\ncompare how the branch and treewidth backends and ganak (WMC) degrade as treewidth\ngrows; the [scoreboard](scoreboard.md) reports the measured trend (which depends\non the build optimization level — the branch backend collapses first in all cases).\n\n### Render from existing artifacts\n\n```sh\npython3 tools/bench.py render \\\n    --artifact-dir /tmp/dlx4sop-artifacts \\\n    --view full\n```\n\nThis regenerates `scoreboard.md`, `scoreboard.json`, and SVG plots from existing\nJSONL artifacts without re-running any experiments.\n\n### Other benchmark tools\n\n- `tools/bench_qasm_corpus.py`: run the QSOP importer and solver across a manifest.\n- `tools/bench_wmc_ganak.py`: drive `sop2wmc` + Ganak and cross-check against `sop-solve`.\n- `tools/bench_qasm_native_simulator.py`: compare against supported native simulators.\n- `tools/gen_scaling_family.py`: generate / materialize the synthetic scaling family.\n- `tools/render_scoreboard.py`: render ad hoc reports (local backend summaries, MQT tuning).\n- `tools/run_corpus_benchmarks.py`: the single full-pipeline orchestrator (`bench.py full` is an alias).\n\n## Current Status\n\n[scoreboard.md](scoreboard.md) tracks QSOP benchmark corpus coverage, solver timings,\nWMC backend behavior, native simulator comparisons, and the recommended solver\nconfiguration per tier.\n\nSummary of findings: on QSOPs, treewidth and hybrid branch remain the useful\nnative baselines; WMC/Ganak is complementary and reaches some hard rows, but it\ndoes not yet beat native treewidth on the current scaling study.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaperez64%2Fdlx4sop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgaperez64%2Fdlx4sop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaperez64%2Fdlx4sop/lists"}