sacc_io: SACC read/write layer for the standard data-product layout

[cailmdaley]

Closes #244. Row 2 of the PRD (#241 §7): the sacc_io module — every data product written to and read from SACC, with round-trip tests. This is the layout contract PRs 3 (converter), 4 (migration), and 6 (blinding) build on. Draft, for review against the PRD.

What's in the file

Product	SACC data type	Tracers	Point tags
ξ± (coarse + fine grids)	galaxy_shear_xi_plus/minus (standard)	(source_i, source_j)	theta (arcmin, TreeCorr meanr), theta_nom, npairs, weight, grid
pseudo-Cℓ EE/BB/EB	galaxy_shear_cl_ee/bb/eb (standard)	(source_i, source_j)	ell + shared BandpowerWindow
COSEBIs	galaxy_shear_cosebi_ee/bb (standard)	(source_i, source_j)	n, theta_min, theta_max
pure E/B	galaxy_shear_xiPure{E,B,Amb}_{plus,minus} (custom)	(source_i, source_j)	theta
ρ₀…ρ₅	psf_rho{k}_xi_{plus,minus} (custom)	(psf_stars, psf_stars)	theta
τ₀,τ₂,τ₅	galaxyPsf_tau{k}_xi_{plus,minus} (custom)	(source_i, psf_stars)	theta
n(z)	NZ tracers source_0, source_1, …

Tomography-native throughout: every writer/reader takes a bin pair (i, j); the current single-bin analysis is the (0, 0) case.

One file per catalogue version — the PRD §1 letter

{version}.sacc carries everything: the analysis vector (coarse ξ±, pseudo-Cℓ, COSEBIs, pure-E/B, ρ/τ, n(z)) and the fine-grid ξ± integration input for COSEBIs / pure-E/B, tagged grid='fine'. The covariance is assembled block-diagonally (zero cross-blocks — the same independence assumption today's cosmosis_fitting.py assembly makes): the per-statistic analysis blocks first, then a dense per-pair fine-ξ block.

The design point that makes this work: the production fine grid is 1000 θ bins (0.5–300′, the B-modes paper's integration binning), where a dense fine block is 2000×2000 ≈ 32 MB per pair — and a real covariance exists at exactly that binning: the Gaussian analytic covariance computed on the integration grid (OneCovariance in this pipeline; Paper II used CosmoCov), which is load-bearing downstream (it is the input to the pure-E/B MC error propagation and the COSEBIs covariance transform). When no analytic covariance exists, the fine block degrades to the TreeCorr varxip/varxim diagonal. Extreme convergence-check grids (a one-off 10 000-bin run) likewise take the diagonal fallback — they degrade the covariance, not the file layout. (This supersedes an earlier two-file amendment on this PR, which was premised on 10k bins being an operating point; it isn't.)

Beyond the PRD's row-2 list, pure-E/B writers are included: §3 derives pure-E/B from blinded ξ± and PR 6's acceptance test measures them, so they need a home in the layout.

Design notes

• Insertion order is the covariance order (sacc preserves it bitwise through FITS save/load — verified), and alignment holds by construction: writers enforce strictly ascending θ/ℓ grids (loud ValueError otherwise) and readers return insertion order, so reader output, covariance sub-blocks, and bandpower-window columns can never silently diverge. Bin pairs normalize to i≤j. Insertion is pair-major ([pair₀ ξ+; pair₀ ξ−; pair₁ ξ+; …]); type-major consumers (DES 2pt-FITS) permute explicitly via Sacc.indices. Analysis points insert before fine points so covariance blocks tile the mean contiguously.
• An independent adversarial review ran against the layout contract before this PR opened; its findings (reader-side sorting vs insertion-order divergence, unnormalized bin pairs) are fixed with regression tests for each.
• assemble_covariance(s, blocks) places per-statistic covariance blocks with zero cross-blocks and fails loud on any gap, overlap, or size mismatch.
• extract() (copy + keep_selection) pulls a subset with its correctly-aligned covariance sub-block — the building block for PR 3's converter and PR 6's blinding passes (blinding the fine block is its own extract→blind→merge pass inside the same file).
• The pseudo-Cℓ writer takes the bandpower window matrix as explicit input: NaMaster computes it today but nothing saves it; PR 4 wires get_bandpower_windows() through.

Testing

27 tests, all synthetic and fast: per-writer round-trips (values, tags, windows, n(z) bitwise), covariance block alignment incl. zero cross-blocks, assemble_covariance failure modes, DiagonalCovariance round-trip, extract sub-covariance alignment, a 2-bin/3-pair tomographic case, reader/writer mirroring on a mixed file, the end-to-end one-file layout (analysis + dense fine block, extract of the fine selection, zero analysis↔fine cross-blocks), and the varxi-diagonal fine fallback. Fast suite: no regressions.

Not in scope here: cosmo_val mixin migration (PR 4), SACC→2pt-FITS converter and OneCovariance glue (PR 3).

— Claude (Fable) on behalf of Cail.