Unify report writing across single-rank and MPI runs using recording sites

[ilkilic]

Refactors report writing to operate on cell recordings instead of voltage trace dictionaries. Reports are now generated from configured recording sites, unifying single-rank and MPI workflows and making compartment reports consistent with the NEURON recording model.

What changed

• Breaking: ReportManager.write_all(cells_or_traces=...) removed → now write_all(cells=...).
• Compartment writers now read traces via cell.get_recording(rec_name) and iterate
  cell.report_sites[report_name].
• Report writing is now variable-agnostic (no longer hardcoded to voltage).
• Adds explicit MPI gather helpers so consumers can gather recordings/spikes to rank 0
  and write reports there.

The cells argument must be a mapping {CellId: cell-like} where entries expose:

• report_sites
• get_recording(rec_name)

Why

The previous pipeline supported multiple input shapes (live cells vs gathered trace
dictionaries). This made behavior harder to reason about and fragile, especially for
non-voltage variables and MPI execution.

The new pipeline separates responsibilities:
1. recording configuration
2. simulation
3. gathering
4. writing

MPI usage (Recommended)

Consumers running under MPI should gather locally recorded data and write only on rank 0:

# after sim.run(...)
local_sites_index = getattr(sim, "sites_index", {})
gathered_sites = pc.py_gather(local_sites_index, 0)

local_payload = collect_local_payload(sim.cells, cell_ids_for_this_rank, sim.recording_index)
local_spikes = collect_local_spikes(sim, cell_ids_for_this_rank)

all_payload, all_spikes = gather_payload_to_rank0(pc, local_payload, local_spikes)

if rank == 0:
    all_sites_index = gather_recording_sites(gathered_sites)
    cells_for_writer = payload_to_cells(all_payload, all_sites_index)

    report_mgr = ReportManager(sim.circuit_access.config, sim.dt)
    report_mgr.write_all(cells=cells_for_writer, spikes_by_pop=all_spikes)

This replaces the previous approach where users gathered trace dicts and passed cells_or_traces=traces.

Non-MPI usage

Single-rank usage remains simple:

report_mgr = ReportManager(sim.circuit_access.config, sim.dt)
report_mgr.write_all(cells=sim.cells)

Any consumer code passing cells_or_traces or trace dictionaries must migrate to:
• cells=sim.cells (single rank), or
• cells=payload_to_cells(...) on rank 0 after MPI gather.

[codecov]

Codecov Report

❌ Patch coverage is 95.89372% with 17 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
bluecellulab/reports/utils.py	95.13%	7 Missing ⚠️
bluecellulab/reports/writers/compartment.py	72.00%	7 Missing ⚠️
tests/test_reports/test_reports_utils.py	98.59%	2 Missing ⚠️
tests/test_reports/test_compartment_writer.py	98.41%	1 Missing ⚠️

Files with missing lines	Coverage Δ
bluecellulab/cell/core.py	78.92% <100.00%> (+0.32%)	⬆️
...ab/circuit/circuit_access/sonata_circuit_access.py	98.20% <100.00%> (ø)
bluecellulab/circuit_simulation.py	85.20% <100.00%> (ø)
bluecellulab/reports/manager.py	95.34% <100.00%> (+0.11%)	⬆️
bluecellulab/type_aliases.py	100.00% <100.00%> (ø)
tests/test_cell/test_core.py	99.40% <100.00%> (+<0.01%)	⬆️
tests/test_reports/test_compartment_writer.py	99.17% <98.41%> (-0.83%)	⬇️
tests/test_reports/test_reports_utils.py	98.80% <98.59%> (-1.20%)	⬇️
bluecellulab/reports/utils.py	94.18% <95.13%> (+10.85%)	⬆️
bluecellulab/reports/writers/compartment.py	83.33% <72.00%> (-2.69%)	⬇️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[darshanmandge]

Thanks! I have made some comments.

[AurelienJaquier]

looks good, thanks a lot!