feat(build)!: ✨ ship x86-64 wheels as a fat binary over five ISA tiers

[robertodr]

Summary

Enabling autovectorization has been done with the -march=native flag (monoprop_ENABLE_ARCH_FLAGS=ON) in local builds, but to make portable wheels, we have been compiling to the baseline of the manylinux container. For the various uses of popcount in this codebase that means effectively not using any CPU primitives (neither POPCNT nor VPOPCNTDQ).

The approach here creates a so-called fat binary where a single wheel ships multiple DSO, each compiled for a specific microarchitecture, and then there's a dispatcher wrapping and routing the calls to the best match for the machine once runs on.

Fixes #13.

🤖 Details 🤖

Summary

Published x86-64 wheels carry the propagation engine five times over, compiled for four ISA levels with the top level shipped twice at two vector widths, and monoprop picks one when it is imported. Off by default in source builds, where -march=native beats every tier.

Stacked on #304, which turns _monoprop_query_machine_flags into the general ARCH_FLAGS <flags...> form — exactly the generalization the tiers need, since a tier is a whole flag list and not a single -march token, so this branch adopts that vocabulary rather than carrying its own.

This is the fat-binary half of #276, extracted onto main. #276 is based on refactor-drop-nttp, so it carries the whole NTTP stack (#302–#309) underneath it; the four whole-module fat-binary commits do not depend on any of that and are what this PR is. The narrow-seam commits that follow them (e646bbc, 68ad0a5, and two thirds of 34218ac) are not extractable: their design is "tier exactly the one translation unit holding build_layer's instantiation tree", and on main there is no such TU — MonomialPropagator is header-resident and instantiated per mode width in the generated binder TUs, so the module boundary is the narrowest seam that exists here. That narrowing is a payoff of #308 and should land on top of it.

1. Four ISA levels, from a compile-time study of what each buys this codebase. x86-64, -v2, -v3, and -v4 + avx512vpopcntdq. Plain v4 is not shipped: ablating the eight AVX-512 extensions one at a time, -mavx512vpopcntdq accounts for the entire v4 → v4x gain and the other seven for exactly zero, which is what a codebase of std::popcount word loops and no intrinsics looks like. v1 ships despite being slowest because it is the floor.
2. The top level ships twice, at -mprefer-vector-width=256 and 512. Identical -march, identical __builtin_cpu_supports requirements — the pair exists because left unset GCC takes the AVX-512 width from the -mtune tables, so it was being decided by monoprop_FAT_MTUNE, a core chosen for its schedule. No feature bit answers the question, so the discriminator is a core-name table read through __builtin_cpu_is. znver4 is on it because it is measured: 1.1% to the narrow tier on the 127-qubit kicked-Ising model, three-sample ranges disjoint, against GCC's own znver4 tuning.
3. Two predicates per tier, and the distinction is load-bearing. runnable is features only and gates a monoprop_VARIANT pin; preferred adds the core table and is what the automatic selection reads. They differ for exactly one tier. Conflating them makes the 512-bit tier unpinnable on precisely the machines worth comparing it on.
4. -ffp-contract=off is a contract, not a tuning knob. Without it -march=x86-64-v3 and up contract a*b+c into an FMA and the energy moves 1–2 ULP — the same wheel answering differently per host CPU. It is set project-wide so a source build, a wheel and every tier stay bit-comparable.
5. Why not glibc-hwcaps, which would need no code at all. Its directory names are the four psABI levels, and the top tier is v4 plus avx512vpopcntdq. Installing it as x86-64-v4 hands it to Skylake-X and Cascade Lake, which are v4 with no vector popcount, and they take SIGILL. The predicate has to be ours.
6. Why not target_clones. GCC will not inline across an arch mismatch, so a target-attributed wrapper around the engine is a jmp, flatten notwithstanding; and #pragma GCC target does not capture templates defined outside its region. flatten + target_clones is unaffordable regardless — measured on the runtime-width engine, four flattened clones took one TU from 16.7 s to killed at 21 minutes and ~100 GB of compiler memory.

Deviations from #276

• _isa uses nanobind split mode rather than NB_STATIC: wheel.py-api = "cp311" sets SKBUILD_SABI_VERSION, and nanobind 3 refuses any linked module below cp312. It still links no engine object library, so it inherits no tier's arch flags.
• just diff-baseline-variants is not included: it calls tools/capture-baseline.py, which arrives with feat(tools): ✨ capture and diff a golden baseline #302, and its undefined baseline_dir made the justfile unparseable for every recipe. The byte-wise cross-tier gate is therefore currently only test_variants.py's single probe. Worth restoring once feat(tools): ✨ capture and diff a golden baseline #302 lands — -vw256 and -vw512 are otherwise indistinguishable except by disassembly.
• The flatten / target_clones numbers are attributed to the runtime-width engine they were taken on, and the note about narrowing the seam says what it needs.

x86-64

The fat binary includes the following microarchitectures:[^1]

• x86-64-v1 which is the baseline
• x86-64-v2 which adds POPCNT
• `x86-64-v3
• x86-64-v4-vpopcntdq-vw256 AVX512 + VPOPCNTDQ with 256 bit vector width
• x86-64-v4-vpopcntdq-vw512 AVX512 + VPOPCNTDQ with 512 bit vector width

aarch64

WIP

Changes

• Retire entirely the use of -march=native
• Fat-binary build is default on Linux x86-64
• Fat-binary build is default on Linux aarch64

🤖 Details 🤖

Changes

• Add cmake/compiler_flags/FatBinary.cmake: the only place a tier or a narrow-vector core is declared. It generates the loader's predicate table into FatVariants.h, so a tier cannot be built without being selectable or selectable without being built.
• Compile the engine once per tier behind monoprop_engine_sources(...) and configure every tier through one _monoprop_configure_engine_objs, so the tiers cannot drift apart in anything but arch flags. A new .cpp registered with target_sources(monoprop-objs ...) reaches only the baseline tier.
• Apply the baseline ISA as a global floor in CMAKE_CXX_FLAGS, not per target: nanobind's glue is compiled with whatever -march the toolchain defaults to, which is not the psABI baseline (Ubuntu's GCC is --with-arch-64=x86-64-v3), and without the floor _isa itself would fault on the machines it exists to detect.
• Add src/monoprop/bindings/isa.cpp, a ~100 KB baseline-ISA probe answering supported_variants() / runnable_variants() / known_variants() off the generated table, and src/monoprop/_bootstrap.py, which binds one variant as monoprop._core before anything else imports it.
• Configure Variants.h per tier rather than once, so monoprop.__variant__ and __compiler_flags__ report what actually loaded. They previously reported a -march=native query whenever monoprop_ENABLE_ARCH_FLAGS was ON, regardless of what was compiled.
• Add monoprop_ARCH_MARCH as the variant id a single-ISA build reports as __variant__, so what is compiled and what is reported cannot disagree. The flags themselves are ARCH_FLAG, fed to refactor(cmake): ♻️ query machine flags from ARCH_FLAG itself #304's ARCH_FLAGS query.
• Enable the fat binary for *-manylinux_x86_64 wheels only, via a cibuildwheel override: it is x86-64 only, and the other legs are aarch64.
• Add tests/test_variants.py (15 cases) and just build-fat / just test-variants.
• Add docs/content/docs/fat-binary.mdx; update AGENTS.md, README.md and docs/content/docs/building.mdx.

Checklist

• Tests added or updated to cover the changes
• Documentation updated (docstrings, docs/, CONTRIBUTING.md) if needed
• CHANGELOG / release notes updated if applicable

AI/LLM disclosure

• I did not use LLM tooling, or used it only privately for ideation
• I used the following tool to help write this PR description: Claude Code
• I used the following tool to generate or modify code: Claude Code

Important

By opening this PR I confirm that I have read CONTRIBUTING.md and I agree to the terms of the Contributor License Agreement.

Warning

If you're contributing on behalf of your employer, contact cla@algorithmiq.fi to arrange a Corporate CLA.

[github-actions]

Docs preview: https://pr-311.monoprop-docs.pages.dev

[robertodr]

I thinks we're fine with the compiler generating FMAs for us.

[codecov]

Codecov Report

❌ Patch coverage is 43.85965% with 32 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.86%. Comparing base (aa38399) to head (960d6d5).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/monoprop/_bootstrap.py	42.85%	29 Missing and 3 partials ⚠️

Additional details and impacted files

@@                   Coverage Diff                   @@
##           split/03-arch-flags     #311      +/-   ##
=======================================================
- Coverage                97.70%   93.86%   -3.85%     
=======================================================
  Files                       14       15       +1     
  Lines                      742      799      +57     
  Branches                    98      105       +7     
=======================================================
+ Hits                       725      750      +25     
- Misses                      12       41      +29     
- Partials                     5        8       +3     

Flag	Coverage Δ
cpp	93.86% <43.85%> (-3.85%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
46.5% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud