bluecellulab 2.6.61__py3-none-any.whl → 2.6.63__py3-none-any.whl

bluecellulab/analysis/analysis.py

@@ -4,9 +4,11 @@ try:
 except ImportError:
     efel = None
 from itertools import islice
+from itertools import repeat
 import logging
 from matplotlib.collections import LineCollection
 import matplotlib.pyplot as plt
+from multiprocessing import Pool
 import neuron
 import numpy as np
 import pathlib
@@ -40,7 +42,8 @@ def compute_plot_iv_curve(cell,
                           show_figure=True,
                           save_figure=False,
                           output_dir="./",
-                          output_fname="iv_curve.pdf"):
+                          output_fname="iv_curve.pdf",
+                          n_processes=None):
     """Compute and plot the Current-Voltage (I-V) curve for a given cell by
     injecting a range of currents.
 
@@ -72,6 +75,9 @@ def compute_plot_iv_curve(cell,
         save_figure (bool): Whether to save the figure. Default is False.
         output_dir (str): The directory to save the figure if save_figure is True. Default is "./".
         output_fname (str): The filename to save the figure as if save_figure is True. Default is "iv_curve.png".
+        n_processes (int, optional): The number of processes to use for parallel execution.
+            If None or if it is higher than the number of steps,
+            it will use the number of steps as the number of processes.
 
     Returns:
         tuple: A tuple containing:
@@ -95,15 +101,22 @@ def compute_plot_iv_curve(cell,
         for amp in list_amp
     ]
 
-    recordings = []
-    for step in steps:
-        recording = run_stimulus(cell.template_params,
-                                 step,
-                                 section=injecting_section,
-                                 segment=injecting_segment,
-                                 recording_section=recording_section,
-                                 recording_segment=recording_segment)
-        recordings.append(recording)
+    if n_processes is None or n_processes > len(steps):
+        n_processes = len(steps)
+    with Pool(n_processes) as p:
+        recordings = p.starmap(
+            run_stimulus,
+            zip(
+                repeat(cell.template_params),
+                steps,
+                repeat(injecting_section),
+                repeat(injecting_segment),
+                repeat(True),  # cvode
+                repeat(True),  # add_hypamp
+                repeat(recording_section),
+                repeat(recording_segment),
+            )
+        )
 
     steady_states = []
     # compute steady state response
@@ -148,7 +161,8 @@ def compute_plot_fi_curve(cell,
                           show_figure=True,
                           save_figure=False,
                           output_dir="./",
-                          output_fname="fi_curve.pdf"):
+                          output_fname="fi_curve.pdf",
+                          n_processes=None):
     """Compute and plot the Frequency-Current (F-I) curve for a given cell by
     injecting a range of currents.
 
@@ -182,6 +196,9 @@ def compute_plot_fi_curve(cell,
         save_figure (bool): Whether to save the figure. Default is False.
         output_dir (str): The directory to save the figure if save_figure is True. Default is "./".
         output_fname (str): The filename to save the figure as if save_figure is True. Default is "iv_curve.png".
+        n_processes (int, optional): The number of processes to use for parallel execution.
+            If None or if it is higher than the number of steps,
+            it will use the number of steps as the number of processes.
 
     Returns:
         tuple: A tuple containing:
@@ -201,19 +218,26 @@ def compute_plot_fi_curve(cell,
         for amp in list_amp
     ]
 
-    spikes = []
-    for step in steps:
-        recording = run_stimulus(cell.template_params,
-                                 step,
-                                 section=injecting_section,
-                                 segment=injecting_segment,
-                                 recording_section=recording_section,
-                                 recording_segment=recording_segment,
-                                 enable_spike_detection=True,
-                                 threshold_spike_detection=threshold_voltage)
-        spikes.append(recording.spike)
-
-    spike_count = [len(spike) for spike in spikes]
+    if n_processes is None or n_processes > len(steps):
+        n_processes = len(steps)
+    with Pool(n_processes) as p:
+        recordings = p.starmap(
+            run_stimulus,
+            zip(
+                repeat(cell.template_params),
+                steps,
+                repeat(injecting_section),
+                repeat(injecting_segment),
+                repeat(True),  # cvode
+                repeat(True),  # add_hypamp
+                repeat(recording_section),
+                repeat(recording_segment),
+                repeat(True),  # enable_spike_detection
+                repeat(threshold_voltage),  # threshold_spike_detection
+            )
+        )
+
+    spike_count = [len(recording.spike) for recording in recordings]
 
     plot_fi_curve(list_amp,
                   spike_count,

bluecellulab/circuit/config/definition.py

@@ -68,6 +68,14 @@ class SimulationConfig(Protocol):
     def spike_location(self) -> str:
         raise NotImplementedError
 
+    @property
+    def tstart(self) -> Optional[float]:
+        raise NotImplementedError
+
+    @property
+    def tstop(self) -> Optional[float]:
+        raise NotImplementedError
+
     @property
     def duration(self) -> Optional[float]:
         raise NotImplementedError

bluecellulab/circuit/config/sonata_simulation_config.py

@@ -17,6 +17,7 @@ import json
 import logging
 from pathlib import Path
 from typing import Optional
+import warnings
 
 from bluecellulab.circuit.config.sections import Conditions, ConnectionOverrides
 from bluecellulab.stimulus.circuit_stimulus_definitions import Stimulus
@@ -160,9 +161,21 @@ class SonataSimulationConfig:
         return self.impl.conditions.spike_location.name
 
     @property
-    def duration(self) -> Optional[float]:
+    def tstart(self) -> Optional[float]:
+        return self.impl.config.get("run", {}).get("tstart", 0.0)
+
+    @property
+    def tstop(self) -> float:
         return self.impl.run.tstop
 
+    @property
+    def duration(self) -> Optional[float]:
+        warnings.warn(
+            "`duration` is deprecated. Use `tstop` instead.",
+            DeprecationWarning
+        )
+        return self.tstop
+
     @property
     def dt(self) -> float:
         return self.impl.run.dt

bluecellulab/circuit/simulation_access.py

@@ -172,16 +172,38 @@ class SonataSimulationAccess:
 
 
 def get_synapse_replay_spikes(f_name: str) -> dict:
-    """Read the .h5 file containing the spike replays."""
+    """Read the .h5 file containing the spike replays.
+
+    Args:
+        f_name: Path to SONATA .h5 spike file.
+
+    Returns:
+        Dictionary mapping node_id to np.array of spike times.
+    """
+    all_spikes = []
     with h5py.File(f_name, 'r') as f:
-        # Access the timestamps and node_ids datasets
-        timestamps = f['/spikes/All/timestamps'][:]
-        node_ids = f['/spikes/All/node_ids'][:]
+        if "spikes" not in f:
+            raise ValueError("spike file is missing required 'spikes' group.")
 
-        spikes = pd.DataFrame(data={'t': timestamps, 'node_id': node_ids})
-        spikes = spikes.astype({"node_id": int})
+        for population in f["spikes"]:
+            pop_group = f["spikes"][population]
+            timestamps = pop_group["timestamps"][:]
+            node_ids = pop_group["node_ids"][:]
+
+            pop_spikes = pd.DataFrame({"t": timestamps, "node_id": node_ids})
+            pop_spikes = pop_spikes.astype({"node_id": int})
+            all_spikes.append(pop_spikes)
+
+    if not all_spikes:
+        return {}
+
+    spikes = pd.concat(all_spikes, ignore_index=True)
 
     if (spikes["t"] < 0).any():
         logger.warning("Found negative spike times... Clipping them to 0")
         spikes["t"].clip(lower=0., inplace=True)
-    return spikes.groupby("node_id")["t"].apply(np.array).to_dict()
+
+    # Group spikes by node_id and ensure spike times are sorted in ascending order.
+    # This is critical because NEURON's VecStim requires monotonically increasing times per train.
+    grouped = spikes.groupby("node_id")["t"]
+    return {k: np.sort(np.asarray(v.values)) for k, v in grouped}

bluecellulab/circuit_simulation.py

@@ -17,12 +17,11 @@ simulations."""
 
 from __future__ import annotations
 from collections.abc import Iterable
-import os
 from pathlib import Path
 from typing import Optional
 import logging
 
-from collections import defaultdict
+from bluecellulab.reports.utils import configure_all_reports
 import neuron
 import numpy as np
 import pandas as pd
@@ -47,7 +46,6 @@ from bluecellulab.circuit.simulation_access import BluepySimulationAccess, Simul
 from bluecellulab.importer import load_mod_files
 from bluecellulab.rngsettings import RNGSettings
 from bluecellulab.simulation.neuron_globals import NeuronGlobals
-from bluecellulab.simulation.report import configure_all_reports, write_compartment_report, write_sonata_spikes
 from bluecellulab.stimulus.circuit_stimulus_definitions import Noise, OrnsteinUhlenbeck, RelativeOrnsteinUhlenbeck, RelativeShotNoise, ShotNoise
 import bluecellulab.stimulus.circuit_stimulus_definitions as circuit_stimulus_definitions
 from bluecellulab.exceptions import BluecellulabError
@@ -638,15 +636,32 @@ class CircuitSimulation:
                        will not be exactly reproduced.
         """
         if t_stop is None:
-            duration = self.circuit_access.config.duration
-            if duration is None:  # type narrowing
+            t_stop = self.circuit_access.config.tstop
+            if t_stop is None:  # type narrowing
                 t_stop = 0.0
-            else:
-                t_stop = duration
         if dt is None:
             dt = self.circuit_access.config.dt
-        if forward_skip_value is None:
-            forward_skip_value = self.circuit_access.config.forward_skip
+
+        config_forward_skip_value = self.circuit_access.config.forward_skip  # legacy
+        config_tstart = self.circuit_access.config.tstart or 0.0             # SONATA
+        # Determine effective skip value and flag
+        if forward_skip_value is not None:
+            # User explicitly provided value → use it
+            effective_skip_value = forward_skip_value
+            effective_skip = forward_skip
+        elif config_forward_skip_value is not None:
+            # Use legacy config if available
+            effective_skip_value = config_forward_skip_value
+            effective_skip = forward_skip
+        elif config_tstart > 0.0:
+            # Use SONATA tstart *only* if no other skip value was provided
+            effective_skip_value = config_tstart
+            effective_skip = True
+        else:
+            # No skip
+            effective_skip_value = None
+            effective_skip = False
+
         if celsius is None:
             celsius = self.circuit_access.config.celsius
         NeuronGlobals.get_instance().temperature = celsius
@@ -664,15 +679,13 @@ class CircuitSimulation:
                            "simulations")
 
         sim.run(
-            t_stop,
+            tstop=t_stop,
             cvode=cvode,
             dt=dt,
-            forward_skip=forward_skip,
-            forward_skip_value=forward_skip_value,
+            forward_skip=effective_skip,
+            forward_skip_value=effective_skip_value,
             show_progress=show_progress)
 
-        self.write_reports()
-
     def get_mainsim_voltage_trace(
             self, cell_id: int | tuple[str, int], t_start=None, t_stop=None, t_step=None
     ) -> np.ndarray:
@@ -713,23 +726,31 @@ class CircuitSimulation:
         first_key = next(iter(self.cells))
         return self.cells[first_key].get_time()
 
-    def get_time_trace(self, t_step=None) -> np.ndarray:
+    def get_time_trace(self, t_start=None, t_stop=None, t_step=None) -> np.ndarray:
         """Get the time vector for the recordings, negative times removed.
 
         Parameters
         -----------
-        t_step: time step (should be a multiple of report time step T;
-        equals T by default)
+        t_start, t_stop: time range of interest.
+        t_step: time step (multiple of report dt; equals dt by default)
 
         Returns:
-            One dimentional np.ndarray to represent the times.
+            1D np.ndarray representing time points.
         """
         time = self.get_time()
-        time = time[np.where(time >= 0.0)]
+        time = time[time >= 0.0]
+
+        if t_start is None or t_start < 0:
+            t_start = 0
+        if t_stop is None:
+            t_stop = np.inf
+
+        time = time[(time >= t_start) & (time <= t_stop)]
 
         if t_step is not None:
             ratio = t_step / self.dt
             time = _sample_array(time, ratio)
+
         return time
 
     def get_voltage_trace(
@@ -806,78 +827,3 @@ class CircuitSimulation:
                                  record_dt=cell_kwargs['record_dt'],
                                  template_format=cell_kwargs['template_format'],
                                  emodel_properties=cell_kwargs['emodel_properties'])
-
-    def write_reports(self):
-        """Write all reports defined in the simulation config."""
-        report_entries = self.circuit_access.config.get_report_entries()
-
-        for report_name, report_cfg in report_entries.items():
-            report_type = report_cfg.get("type", "compartment")
-            section = report_cfg.get("sections")
-
-            if report_type != "compartment":
-                raise NotImplementedError(f"Report type '{report_type}' is not supported.")
-
-            output_path = self.circuit_access.config.report_file_path(report_cfg, report_name)
-            if section == "compartment_set":
-                if report_cfg.get("cells") is not None:
-                    raise ValueError(
-                        "Report config error: 'cells' must not be set when using 'compartment_set' sections."
-                    )
-                compartment_sets = self.circuit_access.config.get_compartment_sets()
-                write_compartment_report(
-                    report_name=report_name,
-                    output_path=output_path,
-                    cells=self.cells,
-                    report_cfg=report_cfg,
-                    source_sets=compartment_sets,
-                    source_type="compartment_set",
-                    sim_dt=self.dt,
-                )
-
-            else:
-                node_sets = self.circuit_access.config.get_node_sets()
-                if report_cfg.get("compartments") not in ("center", "all"):
-                    raise ValueError(
-                        f"Unsupported 'compartments' value '{report_cfg.get('compartments')}' "
-                        "for node-based section recording (must be 'center' or 'all')."
-                    )
-                write_compartment_report(
-                    report_name=report_name,
-                    output_path=output_path,
-                    cells=self.cells,
-                    report_cfg=report_cfg,
-                    source_sets=node_sets,
-                    source_type="node_set",
-                    sim_dt=self.dt,
-                )
-
-        self.write_spike_report()
-
-    def write_spike_report(self):
-        """Collect and write in-memory recorded spike times to a SONATA HDF5
-        file, grouped by population as required by the SONATA specification."""
-        output_path = self.circuit_access.config.spikes_file_path
-
-        if os.path.exists(output_path):
-            os.remove(output_path)
-
-        # Group spikes per population
-        spikes_by_population = defaultdict(dict)
-        for gid, cell in self.cells.items():
-            pop = getattr(gid, 'population_name', None)
-            if pop is None:
-                continue
-            try:
-                cell_spikes = cell.get_recorded_spikes(location=self.spike_location, threshold=self.spike_threshold)
-                if cell_spikes is not None:
-                    spikes_by_population[pop][gid.id] = list(cell_spikes)
-            except AttributeError:
-                continue
-
-        # Ensure we at least create empty groups for all known populations
-        all_populations = set(getattr(gid, 'population_name', None) for gid in self.cells.keys())
-
-        for pop in all_populations:
-            spikes = spikes_by_population.get(pop, {})  # May be empty
-            write_sonata_spikes(output_path, spikes, pop)

bluecellulab/reports/manager.py

@@ -0,0 +1,78 @@
+# Copyright 2025 Open Brain Institute
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Optional, Dict
+from bluecellulab.reports.writers import get_writer
+from bluecellulab.reports.utils import extract_spikes_from_cells  # helper you already have / write
+
+
+class ReportManager:
+    """Orchestrates writing all requested SONATA reports."""
+
+    def __init__(self, config, sim_dt: float):
+        self.cfg = config
+        self.dt = sim_dt
+
+    def write_all(
+        self,
+        cells_or_traces: Dict,
+        spikes_by_pop: Optional[Dict[str, Dict[int, list]]] = None,
+    ):
+        """Write all configured reports (compartment and spike) in SONATA
+        format.
+
+        Parameters
+        ----------
+        cells_or_traces : dict
+            A dictionary mapping (population, gid) to either:
+            - Cell objects with recorded data (used in single-process simulations), or
+            - Precomputed trace dictionaries, e.g., {"voltage": ndarray}, typically gathered across ranks in parallel runs.
+
+        spikes_by_pop : dict, optional
+            A precomputed dictionary of spike times by population.
+            If not provided, spike times are extracted from `cells_or_traces`.
+
+        Notes
+        -----
+        In parallel simulations, you must gather all traces and spikes to rank 0 and pass them here.
+        """
+        self._write_voltage_reports(cells_or_traces)
+        self._write_spike_report(spikes_by_pop or extract_spikes_from_cells(cells_or_traces, location=self.cfg.spike_location, threshold=self.cfg.spike_threshold))
+
+    def _write_voltage_reports(self, cells_or_traces):
+        for name, rcfg in self.cfg.get_report_entries().items():
+            if rcfg.get("type") != "compartment":
+                continue
+
+            section = rcfg.get("sections")
+            if section == "compartment_set":
+                if rcfg.get("cells") is not None:
+                    raise ValueError("'cells' may not be set with 'compartment_set'")
+                src_sets, src_type = self.cfg.get_compartment_sets(), "compartment_set"
+            else:
+                if rcfg.get("compartments") not in ("center", "all"):
+                    raise ValueError("invalid 'compartments' value")
+                src_sets, src_type = self.cfg.get_node_sets(), "node_set"
+
+            rcfg["_source_sets"] = src_sets
+            rcfg["_source_type"] = src_type
+
+            out_path = self.cfg.report_file_path(rcfg, name)
+            writer = get_writer("compartment")(rcfg, out_path, self.dt)
+            writer.write(cells_or_traces, self.cfg.tstart)
+
+    def _write_spike_report(self, spikes_by_pop):
+        out_path = self.cfg.spikes_file_path
+        writer = get_writer("spikes")({}, out_path, self.dt)
+        writer.write(spikes_by_pop)

bluecellulab/reports/utils.py

@@ -0,0 +1,156 @@
+# Copyright 2025 Open Brain Institute
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Report class of bluecellulab."""
+
+from collections import defaultdict
+import logging
+from typing import Dict, Any, List
+
+from bluecellulab.tools import resolve_segments, resolve_source_nodes
+
+logger = logging.getLogger(__name__)
+
+
+def _configure_recording(cell, report_cfg, source, source_type, report_name):
+    """Configure recording of a variable on a single cell.
+
+    This function sets up the recording of the specified variable (e.g., membrane voltage)
+    in the target cell, for each resolved segment.
+
+    Parameters
+    ----------
+    cell : Any
+        The cell object on which to configure recordings.
+
+    report_cfg : dict
+        The configuration dictionary for this report.
+
+    source : dict
+        The source definition specifying nodes or compartments.
+
+    source_type : str
+        Either "node_set" or "compartment_set".
+
+    report_name : str
+        The name of the report (used in logging).
+    """
+    variable = report_cfg.get("variable_name", "v")
+
+    node_id = cell.cell_id
+    compartment_nodes = source.get("compartment_set") if source_type == "compartment_set" else None
+
+    targets = resolve_segments(cell, report_cfg, node_id, compartment_nodes, source_type)
+    for sec, sec_name, seg in targets:
+        try:
+            cell.add_variable_recording(variable=variable, section=sec, segx=seg)
+        except AttributeError:
+            logger.warning(f"Recording for variable '{variable}' is not implemented in Cell.")
+            return
+        except Exception as e:
+            logger.warning(
+                f"Failed to record '{variable}' at {sec_name}({seg}) on GID {node_id} for report '{report_name}': {e}"
+            )
+
+
+def configure_all_reports(cells, simulation_config):
+    """Configure recordings for all reports defined in the simulation
+    configuration.
+
+    This iterates through all report entries, resolves source nodes or compartments,
+    and configures the corresponding recordings on each cell.
+
+    Parameters
+    ----------
+    cells : dict
+        Mapping from (population, gid) → Cell object.
+
+    simulation_config : Any
+        Simulation configuration object providing report entries,
+        node sets, and compartment sets.
+    """
+    report_entries = simulation_config.get_report_entries()
+
+    for report_name, report_cfg in report_entries.items():
+        report_type = report_cfg.get("type", "compartment")
+        section = report_cfg.get("sections", "soma")
+
+        if report_type != "compartment":
+            raise NotImplementedError(f"Report type '{report_type}' is not supported.")
+
+        if section == "compartment_set":
+            source_type = "compartment_set"
+            source_sets = simulation_config.get_compartment_sets()
+            source_name = report_cfg.get("compartments")
+            if not source_name:
+                logger.warning(f"Report '{report_name}' does not specify a node set in 'compartments' for {source_type}.")
+                continue
+        else:
+            source_type = "node_set"
+            source_sets = simulation_config.get_node_sets()
+            source_name = report_cfg.get("cells")
+            if not source_name:
+                logger.warning(f"Report '{report_name}' does not specify a node set in 'cells' for {source_type}.")
+                continue
+
+        source = source_sets.get(source_name)
+        if not source:
+            logger.warning(f"{source_type.title()} '{source_name}' not found for report '{report_name}', skipping recording.")
+            continue
+
+        population = source["population"]
+        node_ids, _ = resolve_source_nodes(source, source_type, cells, population)
+
+        for node_id in node_ids:
+            cell = cells.get((population, node_id))
+            if not cell:
+                continue
+            _configure_recording(cell, report_cfg, source, source_type, report_name)
+
+
+def extract_spikes_from_cells(
+    cells: Dict[Any, Any],
+    location: str = "soma",
+    threshold: float = -20.0,
+) -> Dict[str, Dict[int, list]]:
+    """Extract spike times from recorded cells, grouped by population.
+
+    Parameters
+    ----------
+    cells : dict
+        Mapping from (population, gid) → Cell object, or similar.
+
+    location : str
+        Recording location passed to Cell.get_recorded_spikes().
+
+    threshold : float
+        Voltage threshold (mV) used for spike detection.
+
+    Returns
+    -------
+    spikes_by_population : dict
+        {population → {gid_int → [spike_times_ms]}}
+    """
+    spikes_by_pop: defaultdict[str, Dict[int, List[float]]] = defaultdict(dict)
+
+    for key, cell in cells.items():
+        if isinstance(key, tuple):
+            pop, gid = key
+        else:
+            raise ValueError(f"Cell key {key} is not a (population, gid) tuple.")
+
+        times = cell.get_recorded_spikes(location=location, threshold=threshold)
+        if times is not None and len(times) > 0:
+            spikes_by_pop[pop][gid] = list(times)
+
+    return dict(spikes_by_pop)

bluecellulab/reports/writers/__init__.py

@@ -0,0 +1,25 @@
+# Copyright 2025 Open Brain Institute
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .compartment import CompartmentReportWriter
+from .spikes import SpikeReportWriter
+
+REGISTRY = {
+    "compartment": CompartmentReportWriter,
+    "spikes": SpikeReportWriter,
+}
+
+
+def get_writer(report_type):
+    return REGISTRY[report_type]