LFP: electrode_offsets refactor for multi-report support (#3779)

Refactor the LFP electrode metadata representation from a scalar `num_electrodes` to a CSR-style `electrode_offsets` vector, enabling per-report electrode file support for multiple LFP reports with different electrode configurations.

Fix: #3784

## Motivation

The SONATA spec is moving `electrodes_file` from the global `run` section to individual LFP report blocks ([sonata-extension#34](BlueBrain/sonata-extension#34), [libsonata katta/per-report-electrodes-file](https://github.com/BlueBrain/libsonata/tree/katta/per-report-electrodes-file)). This enables different LFP reports to use different electrode weight files (e.g. deep probes vs surface EEG).

CoreNEURON currently stores a single set of electrode factors per cell with a scalar `num_electrodes`. To support multiple electrode files, we replace this with a CSR-style offsets array and add per-report slicing at report setup time.

## What this PR does

1. Replace `SecMapping::num_electrodes` (int) with `SecMapping::electrode_offsets` (vector<int>)
2. Update `nrnbbcore_register_mapping` to accept a Vector (offsets) instead of scalar int
3. Update the transfer callback to pass `vector<int>` instead of `int`
4. CoreNEURON `CellMapping` stores offsets, `num_electrodes()` derives from `offsets.back()`
5. File format: header line extended with offset count + values
6. `get_lfp_vars_to_report` uses report-specific offset/count slicing for its output buffer
7. neurodamus: passes `Nd.Vector([0, N])` instead of scalar `N` (or `[0, N, N+M]` for multi-report)

## What does NOT change

- `lfp_calc()` computation — iterates all electrodes as before (factors are concatenated)
- LFP output — bit-for-bit identical for single-report case
- Performance — no hot-path allocations added; offsets resolved at setup time only

## Design

For a single report with N electrodes: `electrode_offsets = [0, N]`
For two reports with 2 and 3 electrodes: `electrode_offsets = [0, 2, 5]`

Each LFP report (by order in report.conf) knows its slice: report i uses electrodes `[offsets[i], offsets[i+1])`. The factor vector per segment is the concatenation of all reports' factors.

`lfp_calc()` always computes over the full electrode set (all factors). The slicing only matters at report output time in `get_lfp_vars_to_report`.

## Related PRs (separate repos)

- **neurodamus:** Will adapt to read `electrodes_file` from per-report blocks (new libsonata API), load multiple electrode files, and pass concatenated offsets.
- **libsonata:** [katta/per-report-electrodes-file](https://github.com/BlueBrain/libsonata/tree/katta/per-report-electrodes-file)
- **sonata-extension:** [katta/strict-lfp-variable-name](https://github.com/BlueBrain/sonata-extension/tree/katta/strict-lfp-variable-name)

## Testing

- All existing ctest LFP tests pass unchanged (behavioral equivalence for single-report)
- All neurodamus `test_lfp.py` tests pass unchanged
- Multi-report correctness validated against sequential single-report runs

Author: cattabiani

src/coreneuron/apps/main1.cpp

@@ -561,7 +561,11 @@ extern "C" int run_solve_core(int argc, char** argv) {
 
         // register all reports with libsonata
         double min_report_dt = INT_MAX;
+        size_t lfp_report_counter = 0;
         for (size_t i = 0; i < configs.size(); i++) {
+            if (configs[i].type == ReportType::LFP) {
+                configs[i].lfp_report_index = lfp_report_counter++;
+            }
             std::unique_ptr<ReportHandler> report_handler = create_report_handler(configs[i],
                                                                                   spikes_info);
             if (report_handler) {

src/coreneuron/io/nrn2core_direct.h

@@ -106,7 +106,7 @@ extern void (*nrn2core_get_dat3_secmapping_)(int i_c,
                                              int& nsec,
                                              int& nseg,
                                              size_t& total_lfp_factors,
-                                             int& n_electrodes,
+                                             std::vector<size_t>& electrode_offsets,
                                              std::vector<int>& data_sec,
                                              std::vector<int>& data_seg,
                                              std::vector<double>& data_lfp);

src/coreneuron/io/nrn_filehandler.hpp

@@ -10,6 +10,7 @@
 
 #include <iostream>
 #include <fstream>
+#include <sstream>
 #include <vector>
 #include <cmath>
 #include <sys/stat.h>
@@ -118,18 +119,27 @@ class FileHandler {
                           NrnThreadMappingInfo* ntmapping,
                           std::shared_ptr<CellMapping> cmap,
                           const NrnThread& nt) {
-        int nsec, nseg, n_scan;
-        size_t total_lfp_factors;
-        int num_electrodes;
-        char line_buf[max_line_length], name[max_line_length];
-
-        F.getline(line_buf, sizeof(line_buf));
-        n_scan = sscanf(
-            line_buf, "%s %d %d %zd %d", name, &nsec, &nseg, &total_lfp_factors, &num_electrodes);
-
-        nrn_assert(n_scan == 5);
+        std::string line;
+        std::getline(F, line);
+
+        std::istringstream iss(line);
+        std::string name_str;
+        int nsec = 0;
+        int nseg = 0;
+        size_t total_lfp_factors = 0;
+        int offset_count = 0;
+        iss >> name_str >> nsec >> nseg >> total_lfp_factors >> offset_count;
+        nrn_assert(!iss.fail());
+
+        if (offset_count > 0) {
+            cmap->electrode_offsets.resize(offset_count);
+            for (int k = 0; k < offset_count; k++) {
+                iss >> cmap->electrode_offsets[k];
+            }
+            nrn_assert(!iss.fail());
+        }
 
-        mapinfo->type = section_type_from_string(name);
+        mapinfo->type = section_type_from_string(name_str);
 
         if (nseg) {
             auto sec = read_vector<int>(nseg);
@@ -148,7 +158,7 @@ class FileHandler {
                 mapinfo->add_segment(sec[i], seg[i]);
                 ntmapping->add_segment_id(seg[i]);
                 if (total_lfp_factors > 0) {
-                    // Abort if the factors contains a NaN
+                    const auto num_electrodes = cmap->num_electrodes();
                     nrn_assert(count_if(lfp_factors.begin(), lfp_factors.end(), [](double d) {
                                    return std::isnan(d);
                                }) == 0);

src/coreneuron/io/nrnsection_mapping.hpp

@@ -80,6 +80,10 @@ struct CellMapping {
     /** flat array of lfp factors: stride = num_electrodes, indexed as [i * stride + e] */
     std::vector<double> lfp_factors_flat;
 
+    /** Electrode offsets per LFP report (CSR-style, size = num_reports + 1).
+     *  offsets[i]..offsets[i+1] gives the electrode range for report i. */
+    std::vector<size_t> electrode_offsets;
+
     CellMapping(int g)
         : gid(g) {}
 
@@ -103,9 +107,9 @@ struct CellMapping {
                                });
     }
 
-    /** @brief return the number of electrodes per segment **/
+    /** @brief return the total number of electrodes **/
     size_t num_electrodes() const {
-        return lfp_segment_ids.empty() ? 0 : lfp_factors_flat.size() / lfp_segment_ids.size();
+        return electrode_offsets.empty() ? 0 : electrode_offsets.back();
     }
 
     /** @brief number of section lists */

src/coreneuron/io/phase3.cpp

@@ -20,7 +20,7 @@ void (*nrn2core_get_dat3_secmapping_)(int i_c,
                                       int& nsec,
                                       int& nseg,
                                       size_t& total_lfp_factors,
-                                      int& n_electrodes,
+                                      std::vector<size_t>& electrode_offsets,
                                       std::vector<int>& data_sec,
                                       std::vector<int>& data_seg,
                                       std::vector<double>& data_lfp);
@@ -60,7 +60,6 @@ void Phase3::read_direct(NrnThreadMappingInfo* ntmapping, const NrnThread& nt) {
             std::string sclname;
             int n_sec;
             int n_seg;
-            int n_electrodes;
             size_t total_lfp_factors;
             std::vector<int> data_sec;
             std::vector<int> data_seg;
@@ -71,10 +70,11 @@ void Phase3::read_direct(NrnThreadMappingInfo* ntmapping, const NrnThread& nt) {
                                           n_sec,
                                           n_seg,
                                           total_lfp_factors,
-                                          n_electrodes,
+                                          cmap->electrode_offsets,
                                           data_sec,
                                           data_seg,
                                           data_lfp);
+            const auto n_electrodes = cmap->num_electrodes();
             if (nt._permute) {
                 node_permute(data_seg.data(), data_seg.size(), nt._permute);
             }

src/coreneuron/io/reports/nrnreport.hpp

@@ -258,6 +258,7 @@ struct ReportConfiguration {
     std::vector<int> point_compartment_ids;  // list of compartment_ids for this compartment set
                                              // report (empty otherwise)
     Scaling scaling;
+    size_t lfp_report_index = 0;  // position of this LFP report in electrode_offsets
 };
 
 void setup_report_engine(double dt_report, double mindelay);

src/coreneuron/io/reports/report_event.cpp

@@ -116,8 +116,8 @@ void ReportEvent::lfp_calc(NrnThread* nt) {
         }
 
         // write LFP values to report output buffers
-        for (size_t e = 0; e < electrode_outputs.size(); e++) {
-            *(electrode_outputs[e].var_value) = lfp_values[e];
+        for (const auto& output: electrode_outputs) {
+            *(output.var_value) = lfp_values[output.id];
         }
     }
 }

src/coreneuron/io/reports/report_event.hpp

@@ -22,8 +22,8 @@ namespace coreneuron {
 struct VarWithMapping {
     uint32_t id;
     double* var_value;
-    VarWithMapping(int id_, double* v_)
-        : id(id_)
+    VarWithMapping(size_t id_, double* v_)
+        : id(static_cast<uint32_t>(id_))
         , var_value(v_) {}
 };
 

src/coreneuron/io/reports/report_handler.cpp

@@ -584,7 +584,7 @@ static VarsToReport get_synapse_vars_to_report(const NrnThread& nt,
                         for (auto i = 0; i < var_ptrs.size(); ++i) {
                             if (selected_vars.empty() || static_cast<bool>(selected_vars[i])) {
                                 vars_to_report[gid].push_back(
-                                    {static_cast<int>(*synapseIDs[i]), var_ptrs[i]});
+                                    {static_cast<size_t>(*synapseIDs[i]), var_ptrs[i]});
                             }
                         }
                     }
@@ -598,7 +598,8 @@ static VarsToReport get_synapse_vars_to_report(const NrnThread& nt,
 static VarsToReport get_lfp_vars_to_report(const NrnThread& nt,
                                            const std::vector<int>& intersection_ids,
                                            ReportConfiguration& report,
-                                           double* report_variable) {
+                                           double* report_variable,
+                                           size_t lfp_report_index) {
     const auto* mapinfo = static_cast<NrnThreadMappingInfo*>(nt.mapping);
     if (!mapinfo) {
         std::cerr << "[ERROR] : LFP report mapping information is missing for a Cell group "
@@ -617,8 +618,15 @@ static VarsToReport get_lfp_vars_to_report(const NrnThread& nt,
             nrn_abort(1);
         }
         std::vector<VarWithMapping> to_report;
-        int num_electrodes = cell_mapping->num_electrodes();
-        for (int electrode_id = 0; electrode_id < num_electrodes; electrode_id++) {
+        const auto& offsets = cell_mapping->electrode_offsets;
+        size_t start = 0;
+        size_t end = 0;
+        if (!offsets.empty()) {
+            nrn_assert(offsets.size() > lfp_report_index + 1);
+            start = offsets[lfp_report_index];
+            end = offsets[lfp_report_index + 1];
+        }
+        for (auto electrode_id = start; electrode_id < end; electrode_id++) {
             to_report.emplace_back(VarWithMapping(electrode_id, report_variable + offset_lfp));
             offset_lfp++;
         }
@@ -681,8 +689,11 @@ void ReportHandler::create_report(ReportConfiguration& report_config,
         }
         case ReportType::LFP: {
             mapinfo->prepare_lfp();
-            vars_to_report =
-                get_lfp_vars_to_report(nt, intersection_ids, report_config, mapinfo->_lfp.data());
+            vars_to_report = get_lfp_vars_to_report(nt,
+                                                    intersection_ids,
+                                                    report_config,
+                                                    mapinfo->_lfp.data(),
+                                                    report_config.lfp_report_index);
             register_section_report(nt, report_config, vars_to_report, is_soma_target);
             break;
         }

src/nrniv/nrncore_write/callbacks/nrncore_callbacks.cpp

@@ -249,7 +249,7 @@ void nrnthread_dat3_secmapping(int i_c,
                                int& nsec,
                                int& nseg,
                                size_t& total_lfp_factors,
-                               int& n_electrodes,
+                               std::vector<size_t>& electrode_offsets,
                                std::vector<int>& data_sec,
                                std::vector<int>& data_seg,
                                std::vector<double>& data_lfp) {
@@ -259,7 +259,9 @@ void nrnthread_dat3_secmapping(int i_c,
     nsec = s->nsec;
     nseg = s->size();
     total_lfp_factors = s->seglfp_factors.size();
-    n_electrodes = s->num_electrodes;
+    if (!s->electrode_offsets.empty()) {
+        electrode_offsets = s->electrode_offsets;
+    }
     data_sec = s->sections;
     data_seg = s->segments;
     data_lfp = s->seglfp_factors;