perf(operator): ⚡ release the init_op_map buckets once its terms bind

[diagonal-hamiltonian]

🤖 AI text below 🤖

Summary

get_operator() now erases bound init_op_map entries in place during its single store->find()
pass via erase_if, then releases the drained buckets with rehash(0) — 1,148,190,448 B → 896 B
of retained buckets at the one point where the map has ever been measured large.

1. The release is the point. erase/clear keep bucket_count() on unordered_flat_map, and
   init_operator_bytes reports exactly that — so a fully drained map keeps holding, and reporting,
   its whole bucket array. rehash(0) on an emptied map releases to bucket_count() == 0. It is
   called only when the pass actually erased something.
2. Erasing in place drops a lookup and a temporary. main collects bound keys into a
   std::vector<Monomial> and then re-hashes each one through init_op_map.erase(mono); erase_if
   removes both the vector and that second hash per bound entry.
3. init_operator_entries / d_init_operator_entries exposes the live entries behind
   init_operator_bytes, outside total_bytes() like every other d_ diagnostic. Without it,
   bytes and entries are indistinguishable and dead buckets read as live storage.
4. The map is per-rank, and only for rank-owned terms
   (cpp/monoprop/detail/monomial_propagator/MonomialPropagator.inl:155-157), so its size is
   obs_terms / ranks. A 1-rank layout concentrates the whole map in one rank; wide layouts divide
   it.

Adversarial review. An independent review traced the form into pinned Boost 1.88 — erase_if is
an ADL-only hidden friend; foa snapshots each group's occupied mask before walking it and erase
never reallocates; rehash(0) reaches 0 buckets because the if (n) guard skips capacity_for's
~29-slot minimum — and did not break it.

Changes

• get_operator(): erase_if binds and erases in one pass, then rehash(0) on a map whose size
  changed. The deferred-erase key vector is gone.
• MPOperatorMemoryBreakdown::init_operator_entries, summed in operator+=, excluded from
  total_bytes(), filled from init_op_map.size() in estimate_memory_usage.
• d_init_operator_entries added to the Python memory-breakdown dict in binder.h.
• Four mp_operator_tests.cpp cases: fully bound, partially bound, nothing bound, and one pinning
  init_operator_entries out of total_bytes().

Measurement

The measurement is a single standalone operator-memory ledger reading on the random-Heisenberg
workload at a 7M-term observable, recorded in the round-3 memory results. init_op_map held
1,148,190,448 bytes with d_init_operator_entries = 0 — a fully drained map still holding its
entire bucket array, because erase never shrinks bucket_count() — and 896 bytes after the
release. The same drain also removed a transient std::vector<Monomial> of keys worth 448 MB of
peak across 16 partitions.

	main	this branch
init_operator_bytes, held for the propagator's lifetime	1,148,190,448	896

d_init_operator_entries cannot prove the map grew, and should not be read that way.
initialize_operator_caches_() runs at construction
(MonomialPropagator.inl:187, calling get_operator() at :500), when every entry binds — so the
counter reads 0 on both arms at every recording point. It proves the drain, not the growth. What
differs between arms is init_operator_bytes: ~1.15 GB held for the propagator's whole lifetime on
main, ~896 B here.

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-268.monoprop-docs.pages.dev

[Copilot]

Pull request overview

This PR optimizes detail::MPOperator::get_operator() by erasing bound init_op_map entries in-place via erase_if and then explicitly releasing the underlying bucket allocation with rehash(0) when the map was drained/changed, ensuring init_operator_bytes reflects freed capacity rather than lingering buckets.

Changes:

• Replace the prior “collect keys then erase” approach in get_operator() with a single-pass erase_if and conditional rehash(0) to release drained buckets.
• Add new memory diagnostic init_operator_entries (exposed to Python as d_init_operator_entries) to report live entries separately from bucket-backed byte estimates.
• Add targeted C++ unit tests covering fully-bound, partially-bound, and nothing-bound cases, plus aggregation semantics for the new diagnostic.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
cpp/monoprop/detail/operator/MPOperator.h	Implements in-place erasure + conditional rehash(0) in get_operator(), and adds/records init_operator_entries in the memory breakdown.
cpp/tests/mp_operator_tests.cpp	Adds white-box tests validating bucket release/shrink behavior and that init_operator_entries stays out of total_bytes().
src/monoprop/bindings/binder.h	Exposes init_operator_entries as a diagnostic entry in operator_memory_breakdown for Python consumers.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.70%. Comparing base (1b30be3) to head (942a5bc).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #268   +/-   ##
=======================================
  Coverage   97.70%   97.70%           
=======================================
  Files          14       14           
  Lines         742      742           
  Branches       98       98           
=======================================
  Hits          725      725           
  Misses         12       12           
  Partials        5        5           

Flag	Coverage Δ
cpp	97.70% <ø> (ø)

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
69.6% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud