bluecellulab 2.5.0__py3-none-any.whl → 2.6.38__py3-none-any.whl

bluecellulab/circuit/synapse_properties.py

@@ -1,4 +1,4 @@
-# Copyright 2012-2024 Blue Brain Project / EPFL
+# Copyright 2023-2024 Blue Brain Project / EPFL
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -40,6 +40,7 @@ class SynapseProperty(Enum):
     NRRP = "NRRP"
     U_HILL_COEFFICIENT = "u_hill_coefficient"
     CONDUCTANCE_RATIO = "conductance_scale_factor"
+    AFFERENT_SECTION_POS = "afferent_section_pos"
 
     @classmethod
     def from_bluepy(cls, prop: BLPSynapse) -> SynapseProperty:
@@ -76,6 +77,7 @@ class SynapseProperties:
         SynapseProperty.NRRP,
         SynapseProperty.U_HILL_COEFFICIENT,
         SynapseProperty.CONDUCTANCE_RATIO,
+        SynapseProperty.AFFERENT_SECTION_POS,
     )
     plasticity = (
         "volume_CR", "rho0_GB", "Use_d_TM", "Use_p_TM", "gmax_d_AMPA",
@@ -98,6 +100,7 @@ snap_to_synproperty = MappingProxyType({
     "n_rrp_vesicles": SynapseProperty.NRRP,
     "u_hill_coefficient": SynapseProperty.U_HILL_COEFFICIENT,
     "conductance_scale_factor": SynapseProperty.CONDUCTANCE_RATIO,
+    "afferent_section_pos": SynapseProperty.AFFERENT_SECTION_POS,
 })
 
 
@@ -137,23 +140,36 @@ def properties_from_bluepy(
     'str's."""
     if not BLUEPY_AVAILABLE:
         raise ExtraDependencyMissingError("bluepy")
-    return [
-        SynapseProperty.from_bluepy(prop)
-        if isinstance(prop, BLPSynapse)
-        else prop
-        for prop in props
-    ]
+    res: list[SynapseProperty | str] = []
+    for prop in props:
+        if isinstance(prop, BLPSynapse):
+            res.append(SynapseProperty.from_bluepy(prop))
+        elif prop == "afferent_section_pos":  # jira_url/project/issues/browse/NSETM-2313
+            res.append(SynapseProperty.AFFERENT_SECTION_POS)
+        else:
+            res.append(prop)
+    return res
 
 
 def properties_to_bluepy(props: list[SynapseProperty | str]) -> list[BLPSynapse | str]:
     """Convert a list of SynapseProperty to bluepy Synapse properties, spare
     'str's."""
-    return [
+    # bluepy does not have AFFERENT_SECTION_POS atm.
+    # jira_url/project/issues/browse/NSETM-2313
+    bluepy_recognised_props = props.copy()
+    removed_afferent_section_pos = False
+    if SynapseProperty.AFFERENT_SECTION_POS in bluepy_recognised_props:
+        removed_afferent_section_pos = True
+        bluepy_recognised_props.remove(SynapseProperty.AFFERENT_SECTION_POS)
+    res = [
         prop.to_bluepy()
         if isinstance(prop, SynapseProperty)
         else prop
-        for prop in props
+        for prop in bluepy_recognised_props
     ]
+    if removed_afferent_section_pos:
+        res.append("afferent_section_pos")
+    return res
 
 
 def synapse_property_encoder(dct: dict[SynapseProperty | str, Any]) -> dict[str, Any]:

bluecellulab/circuit/validate.py

@@ -1,4 +1,4 @@
-# Copyright 2012-2024 Blue Brain Project / EPFL
+# Copyright 2023-2024 Blue Brain Project / EPFL
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

bluecellulab/{ssim.py → circuit_simulation.py}

@@ -1,4 +1,4 @@
-# Copyright 2012-2024 Blue Brain Project / EPFL
+# Copyright 2023-2024 Blue Brain Project / EPFL
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -25,6 +25,9 @@ import neuron
 import numpy as np
 import pandas as pd
 from pydantic.types import NonNegativeInt
+from typing_extensions import deprecated
+from typing import Optional
+
 import bluecellulab
 from bluecellulab.cell import CellDict
 from bluecellulab.cell.sonata_proxy import SonataProxy
@@ -53,9 +56,14 @@ from bluecellulab.synapse.synapse_types import SynapseID
 logger = logging.getLogger(__name__)
 
 
+@deprecated("SSim will be removed, use CircuitSimulation instead.")
 class SSim:
     """Class that loads a circuit simulation to do cell simulations."""
 
+
+class CircuitSimulation:
+    """Class that loads a circuit simulation to do cell simulations."""
+
     @load_mod_files
     def __init__(
         self,
@@ -109,6 +117,8 @@ class SSim:
         self.spike_threshold = self.circuit_access.config.spike_threshold
         self.spike_location = self.circuit_access.config.spike_location
 
+        self.projections: list[str] = []
+
         condition_parameters = self.circuit_access.config.condition_parameters()
         set_global_condition_parameters(condition_parameters)
 
@@ -219,34 +229,34 @@ class SSim:
                 }
 
         if self.gids_instantiated:
-            raise Exception("SSim: instantiate_gids() called twice on the \
-                    same SSim, this is not supported yet")
+            raise BluecellulabError(
+                "instantiate_gids() is called twice on the "
+                "same CircuitSimumation, this is not supported")
         else:
             self.gids_instantiated = True
 
         if pre_spike_trains or add_replay:
             if add_synapses is False:
-                raise Exception("SSim: you need to set add_synapses to True "
-                                "if you want to specify use add_replay or "
-                                "pre_spike_trains")
+                raise BluecellulabError("You need to set add_synapses to True "
+                                        "if you want to specify use add_replay or "
+                                        "pre_spike_trains")
 
         if add_projections is True:
-            projections = self.circuit_access.config.get_all_projection_names()
+            self.projections = self.circuit_access.config.get_all_projection_names()
         elif add_projections is False:
-            projections = []
+            self.projections = []
         else:
-            projections = add_projections
+            self.projections = add_projections
 
         self._add_cells(cell_ids)
         if add_synapses:
             self._add_synapses(
                 pre_gids=pre_gids,
-                add_minis=add_minis,
-                projections=projections)
+                add_minis=add_minis)
         if add_replay or interconnect_cells or pre_spike_trains:
             if add_replay and not add_synapses:
-                raise Exception("SSim: add_replay option can not be used if "
-                                "add_synapses is False")
+                raise BluecellulabError("add_replay option can not be used if "
+                                        "add_synapses is False")
             self._add_connections(add_replay=add_replay,
                                   interconnect_cells=interconnect_cells,
                                   user_pre_spike_trains=pre_spike_trains)  # type: ignore
@@ -349,18 +359,17 @@ class SSim:
                 ornstein_uhlenbeck_stim_count += 1
 
     def _add_synapses(
-            self, pre_gids=None, add_minis=False, projections=None):
+            self, pre_gids=None, add_minis=False):
         """Instantiate all the synapses."""
         for cell_id in self.cells:
             self._add_cell_synapses(
                 cell_id, pre_gids=pre_gids,
-                add_minis=add_minis,
-                projections=projections)
+                add_minis=add_minis)
 
     def _add_cell_synapses(
-        self, cell_id: CellId, pre_gids=None, add_minis=False, projections=None
+        self, cell_id: CellId, pre_gids=None, add_minis=False
     ) -> None:
-        syn_descriptions = self.get_syn_descriptions(cell_id, projections=projections)
+        syn_descriptions = self.get_syn_descriptions(cell_id)
 
         if pre_gids is not None:
             if self.circuit_format == CircuitFormat.SONATA:
@@ -415,12 +424,10 @@ class SSim:
         )
         return syn_descriptions[filtered_rows]
 
-    def get_syn_descriptions(
-        self, cell_id: int | tuple[str, int], projections=None
-    ) -> pd.DataFrame:
+    def get_syn_descriptions(self, cell_id: int | tuple[str, int]) -> pd.DataFrame:
         """Get synapse descriptions dataframe."""
         cell_id = create_cell_id(cell_id)
-        return self.circuit_access.extract_synapses(cell_id, projections=projections)
+        return self.circuit_access.extract_synapses(cell_id, projections=self.projections)
 
     @staticmethod
     def merge_pre_spike_trains(*train_dicts) -> dict[CellId, np.ndarray]:
@@ -549,7 +556,7 @@ class SSim:
         cvode: bool = False,
         show_progress: bool = False,
     ):
-        """Simulate the SSim.
+        """Simulate the Circuit.
 
         Parameters
         ----------
@@ -591,10 +598,10 @@ class SSim:
             forward_skip_value = self.circuit_access.config.forward_skip
         if celsius is None:
             celsius = self.circuit_access.config.celsius
-            NeuronGlobals.get_instance().temperature = celsius
+        NeuronGlobals.get_instance().temperature = celsius
         if v_init is None:
             v_init = self.circuit_access.config.v_init
-            NeuronGlobals.get_instance().v_init = v_init
+        NeuronGlobals.get_instance().v_init = v_init
 
         sim = bluecellulab.Simulation(self.pc)
         for cell_id in self.cells:
@@ -705,7 +712,7 @@ class SSim:
         return voltage
 
     def delete(self):
-        """Delete ssim and all of its attributes.
+        """Delete CircuitSimulation and all of its attributes.
 
         NEURON objects are explicitly needed to be deleted.
         """

bluecellulab/connection.py

@@ -1,4 +1,4 @@
-# Copyright 2012-2024 Blue Brain Project / EPFL
+# Copyright 2023-2024 Blue Brain Project / EPFL
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

bluecellulab/dendrogram.py

@@ -1,4 +1,4 @@
-# Copyright 2012-2024 Blue Brain Project / EPFL
+# Copyright 2023-2024 Blue Brain Project / EPFL
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

bluecellulab/exceptions.py

@@ -1,4 +1,4 @@
-# Copyright 2012-2024 Blue Brain Project / EPFL
+# Copyright 2023-2024 Blue Brain Project / EPFL
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

bluecellulab/graph.py

@@ -82,4 +82,4 @@ def plot_graph(G: nx.Graph, node_size: float = 400, edge_width: float = 0.4, nod
     # Add text at the bottom of the figure
     plt.figtext(0.5, 0.01, "Network of simulated cells", ha="center", fontsize=10, va="bottom")
 
-    plt.show()
+    return plt

bluecellulab/importer.py

@@ -1,4 +1,4 @@
-# Copyright 2012-2024 Blue Brain Project / EPFL
+# Copyright 2023-2024 Blue Brain Project / EPFL
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

bluecellulab/neuron_interpreter.py

@@ -1,4 +1,4 @@
-# Copyright 2012-2024 Blue Brain Project / EPFL
+# Copyright 2023-2024 Blue Brain Project / EPFL
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

bluecellulab/plotwindow.py

@@ -1,4 +1,4 @@
-# Copyright 2012-2024 Blue Brain Project / EPFL
+# Copyright 2023-2024 Blue Brain Project / EPFL
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

bluecellulab/psection.py

@@ -1,4 +1,4 @@
-# Copyright 2012-2024 Blue Brain Project / EPFL
+# Copyright 2023-2024 Blue Brain Project / EPFL
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -13,6 +13,7 @@
 # limitations under the License.
 """Represents a python version of NEURON Section (for drawing)."""
 from __future__ import annotations
+import re
 import neuron
 
 import bluecellulab
@@ -75,21 +76,6 @@ class PSection:
         self.pchildren: list[PSection] = []
         self.isec = isec
 
-        if 'apic' in self.name:
-            self.section_type = 'apical'
-        elif 'dend' in self.name:
-            self.section_type = 'basal'
-        elif 'soma' in self.name:
-            self.section_type = 'somatic'
-        elif 'axon' in self.name:
-            self.section_type = 'axonal'
-        elif 'myelin' in self.name:
-            self.section_type = 'myelin'
-        else:
-            raise Exception(
-                "PSection: Section of unknown type: %s" %
-                self.name)
-
         self.psegments: list[PSegment] = []
         self.maxsegdiam = 0.0
         for hsegment in hsection:
@@ -101,6 +87,15 @@ class PSection:
         self.xSpacing = 1.0
         self.ySpacing = 5.0
 
+    @property
+    def section_type(self) -> str:
+        """Return the type of the section."""
+        # From Cell[0].soma[0] -> soma
+        matches = re.findall(r'\.([^.\[\]]+)\[', self.name)
+        if matches:
+            return matches[-1]  # Return the last match
+        return 'unknown'  # Return 'unknown' if no matches are found
+
     @property
     def is_leaf(self) -> bool:
         """Return true if section is a leaf in the morphological structure."""

bluecellulab/psegment.py

@@ -1,4 +1,4 @@
-# Copyright 2012-2024 Blue Brain Project / EPFL
+# Copyright 2023-2024 Blue Brain Project / EPFL
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -17,7 +17,7 @@ import neuron
 
 from bluecellulab.neuron_interpreter import eval_neuron
 
-type_colormap = {'apical': 'm', 'basal': 'r', 'somatic': 'k', 'axonal': 'b', 'myelin': 'g'}
+type_colormap = {'apic': 'm', 'dend': 'r', 'soma': 'k', 'axon': 'b', 'myelin': 'g', 'unknown': 'c'}
 
 
 class PSegment:
@@ -25,7 +25,7 @@ class PSegment:
 
     def __init__(self, hsegment, parentsection):
         # import matplotlib as plt
-        from matplotlib import cm
+        from matplotlib import colormaps
 
         self.hsegment = hsegment
         self.parentsection = parentsection
@@ -35,7 +35,7 @@ class PSegment:
         self.figure = None
         self.figX = None
         self.figY = None
-        self.color_map = cm.get_cmap("hot")
+        self.color_map = colormaps["hot"]
         self.ax = None
         self.patch = None
         self.plotvariable = None

bluecellulab/rngsettings.py

@@ -1,4 +1,4 @@
-# Copyright 2012-2024 Blue Brain Project / EPFL
+# Copyright 2023-2024 Blue Brain Project / EPFL
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -105,7 +105,7 @@ class RNGSettings:
         options = {"Compatibility": 0, "Random123": 1, "UpdatedMCell": 2}
         if new_val not in options:
             raise UndefinedRNGException(
-                "SSim: RNG mode %s not in accepted list: %s"
+                "RNG mode's value %s is not in the accepted list: %s"
                 % (self.mode, list(options.keys()))
             )
         else:

bluecellulab/simulation/neuron_globals.py

@@ -1,4 +1,4 @@
-# Copyright 2012-2024 Blue Brain Project / EPFL
+# Copyright 2023-2024 Blue Brain Project / EPFL
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -13,6 +13,7 @@
 # limitations under the License.
 """Module that handles the global NEURON parameters."""
 
+from typing import NamedTuple
 import neuron
 from bluecellulab.circuit.config.sections import Conditions, MechanismConditions
 from bluecellulab.exceptions import error_context
@@ -62,6 +63,11 @@ def set_minis_single_vesicle_values(mech_conditions: MechanismConditions) -> Non
             )
 
 
+class NeuronGlobalParams(NamedTuple):
+    temperature: float
+    v_init: float
+
+
 class NeuronGlobals:
     _instance = None
 
@@ -96,3 +102,10 @@ class NeuronGlobals:
     def v_init(self, value):
         self._v_init = value
         neuron.h.v_init = value
+
+    def export_params(self) -> NeuronGlobalParams:
+        return NeuronGlobalParams(self.temperature, self.v_init)
+
+    def load_params(self, params: NeuronGlobalParams) -> None:
+        self.temperature = params.temperature
+        self.v_init = params.v_init

bluecellulab/simulation/parallel.py

@@ -0,0 +1,40 @@
+"""Controlled simulations in parallel."""
+
+from __future__ import annotations
+import multiprocessing
+from multiprocessing.pool import Pool
+from bluecellulab.simulation.neuron_globals import NeuronGlobals
+
+
+class IsolatedProcess(Pool):
+    """Multiprocessing Pool that restricts a worker to run max 1 process.
+
+    Use this when running isolated NEURON simulations. Running 2 NEURON
+    simulations on a single process is to be avoided. Required global
+    NEURON simulation parameters will automatically be passed to each
+    worker. `fork` mode of multiprocessing is used to pass any other
+    global NEURON parameters to each worker.
+    """
+
+    def __init__(self, processes: int | None = 1):
+        """Initialize the IsolatedProcess pool.
+
+        Args:
+            processes: The number of processes to use for running the simulations.
+                       If set to None, then the number returned by os.cpu_count() is used.
+        """
+        ctx = multiprocessing.get_context("fork")
+        neuron_global_params = NeuronGlobals.get_instance().export_params()
+        super().__init__(
+            processes=processes,
+            initializer=self.init_worker,
+            initargs=(neuron_global_params,),
+            maxtasksperchild=1,
+            context=ctx,
+        )
+
+    @staticmethod
+    def init_worker(neuron_global_params):
+        """Load global parameters for the NEURON environment in each worker
+        process."""
+        NeuronGlobals.get_instance().load_params(neuron_global_params)

bluecellulab/simulation/simulation.py

@@ -1,4 +1,4 @@
-# Copyright 2012-2024 Blue Brain Project / EPFL
+# Copyright 2023-2024 Blue Brain Project / EPFL
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -28,13 +28,14 @@ logger = logging.getLogger(__name__)
 class Simulation:
     """Class that represents a neuron simulation."""
 
-    def __init__(self, parallel_context=None) -> None:
+    def __init__(self, parallel_context=None, custom_progress_function=None) -> None:
         self.cells: list[bluecellulab.Cell] = []
         self.fih_progress = None
         self.progress = None
         self.progress_closed = None
         self.progress_dt: Optional[float] = None
         self.pc = parallel_context
+        self.custom_progress_function = custom_progress_function
 
     def add_cell(self, new_cell: bluecellulab.Cell) -> None:
         """Add a cell to a simulation."""
@@ -50,26 +51,29 @@ class Simulation:
 
     def progress_callback(self):
         """Callback function for the progress bar."""
-        if self.progress > 0:
-            sys.stdout.write("\x1b[3F")
-
-        self.progress += 1
-        self.progress_closed = not self.progress_closed
-        if self.progress_closed:
-            sys.stdout.write(" %s%s%s \n" % (" " * (
-                self.progress - 1), " ", " " * (100 - self.progress)))
-            sys.stdout.write("[%s%s%s]\n" % ("#" * (
-                self.progress - 1), "-", "." * (100 - self.progress)))
-            sys.stdout.write(" %s%s%s \n" % (" " * (
-                self.progress - 1), " ", " " * (100 - self.progress)))
+        if self.custom_progress_function is None:
+            if self.progress > 0:
+                sys.stdout.write("\x1b[3F")
+
+            self.progress += 1
+            self.progress_closed = not self.progress_closed
+            if self.progress_closed:
+                sys.stdout.write(" %s%s%s \n" % (" " * (
+                    self.progress - 1), " ", " " * (100 - self.progress)))
+                sys.stdout.write("[%s%s%s]\n" % ("#" * (
+                    self.progress - 1), "-", "." * (100 - self.progress)))
+                sys.stdout.write(" %s%s%s \n" % (" " * (
+                    self.progress - 1), " ", " " * (100 - self.progress)))
+            else:
+                sys.stdout.write(" %s%s%s \n" % (" " * (
+                    self.progress - 1), "/", " " * (100 - self.progress)))
+                sys.stdout.write("[%s%s%s]\n" % ("#" * (
+                    self.progress - 1), ">", "." * (100 - self.progress)))
+                sys.stdout.write(" %s%s%s \n" % (" " * (
+                    self.progress - 1), "\\", " " * (100 - self.progress)))
+            sys.stdout.flush()
         else:
-            sys.stdout.write(" %s%s%s \n" % (" " * (
-                self.progress - 1), "/", " " * (100 - self.progress)))
-            sys.stdout.write("[%s%s%s]\n" % ("#" * (
-                self.progress - 1), ">", "." * (100 - self.progress)))
-            sys.stdout.write(" %s%s%s \n" % (" " * (
-                self.progress - 1), "\\", " " * (100 - self.progress)))
-        sys.stdout.flush()
+            self.custom_progress_function()
 
         neuron.h.cvode.event(
             neuron.h.t + self.progress_dt, self.progress_callback)

bluecellulab/stimulus/circuit_stimulus_definitions.py

@@ -1,4 +1,4 @@
-# Copyright 2012-2024 Blue Brain Project / EPFL
+# Copyright 2023-2024 Blue Brain Project / EPFL
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -170,7 +170,7 @@ class Stimulus:
                 decay_time=stimulus_entry["DecayTime"],
                 mean_percent=stimulus_entry["MeanPercent"],
                 sd_percent=stimulus_entry["SDPercent"],
-                amp_cv=stimulus_entry["AmpCV"],
+                relative_skew=stimulus_entry.get("RelativeSkew", 0.5),
                 seed=stimulus_entry.get("Seed", None),
                 mode=mode,
                 reversal=stimulus_entry.get("Reversal", 0.0)
@@ -243,7 +243,6 @@ class Stimulus:
                 delay=stimulus_entry["delay"],
                 duration=stimulus_entry["duration"],
                 spike_file=stimulus_entry["spike_file"],
-                source=stimulus_entry["source"],
             )
         elif pattern == Pattern.SHOT_NOISE:
             return ShotNoise(
@@ -270,7 +269,7 @@ class Stimulus:
                 decay_time=stimulus_entry["decay_time"],
                 mean_percent=stimulus_entry["mean_percent"],
                 sd_percent=stimulus_entry["sd_percent"],
-                amp_cv=stimulus_entry["amp_cv"],
+                relative_skew=stimulus_entry.get("RelativeSkew", 0.5),
                 seed=stimulus_entry.get("random_seed", None),
                 mode=ClampMode(stimulus_entry.get("input_type", "current_clamp").lower()),
                 reversal=stimulus_entry.get("reversal", 0.0)
@@ -331,7 +330,6 @@ class RelativeLinear(Stimulus):
 @dataclass(frozen=True, config=dict(extra="forbid"))
 class SynapseReplay(Stimulus):
     spike_file: str
-    source: str
 
     @field_validator("spike_file")
     @classmethod
@@ -367,7 +365,7 @@ class RelativeShotNoise(Stimulus):
     decay_time: float
     mean_percent: float
     sd_percent: float
-    amp_cv: float
+    relative_skew: float = 0.5
     dt: float = 0.25
     seed: Optional[int] = None
     mode: ClampMode = ClampMode.CURRENT
@@ -380,6 +378,13 @@ class RelativeShotNoise(Stimulus):
             raise ValueError("decay_time must be greater than rise_time")
         return v
 
+    @field_validator("relative_skew")
+    @classmethod
+    def relative_skew_in_range(cls, v):
+        if v < 0.0 or v > 1.0:
+            raise ValueError("relative skewness must be in [0,1]")
+        return v
+
 
 @dataclass(frozen=True, config=dict(extra="forbid"))
 class OrnsteinUhlenbeck(Stimulus):