Implement SONATA condition modifications by darshanmandge · Pull Request #63 · openbraininstitute/BlueCelluLab

darshanmandge · 2026-02-16T07:45:20Z

Summary

Implement SONATA condition modifications in BlueCelluLab, supporting all five modification types defined in the SONATA-extension specification.

Changes

New: SONATA Modifications (bluecellulab/simulation/modifications.py)

Type	Description
`ttx`	Block Na channels via `TTXDynamicsSwitch`
`configure_all_sections`	Apply a statement to all sections of target cells
`section_list`	Apply to a named section list (somatic, basal, apical, axonal)
`section`	Apply to specific named sections (e.g. `dend[0]`)
`compartment_set`	Apply to segments defined by a compartment set file

Modifications are:

Defined in conditions.modifications of the SONATA simulation config
Parsed into typed dataclasses via SonataSimulationConfig.get_modifications()
Automatically applied during CircuitSimulation.instantiate_gids(), after cell
creation, but before synapses/stimuli (matching neurodamus ordering)

Graceful Skipping & Logging

Modifications skip sections/cells that don't match rather than failing:

Sections missing a referenced attribute are silently skipped
Zero-match cases log a WARNING
Invalid section_configure syntax raises ValueError

New: Generic Mechanism Handling

Replaced the hardcoded MechanismConditions fields (minis_single_vesicle, init_depleted) with a generic mechanisms: dict in the Conditions dataclass.
set_global_condition_parameters() now iterates the dict and sets NEURON globals dynamically, supporting any mechanism parameter without code changes.

This matches neurodamus behavior and is essential for heterogeneous node sets.

Files Changed

bluecellulab/simulation/modifications.py — New module: modification application logic
bluecellulab/circuit/config/sections.py — Modification dataclasses, generic mechanisms dict
bluecellulab/circuit/config/sonata_simulation_config.py — get_modifications(), empty reports fix
bluecellulab/circuit/config/definition.py — get_modifications() in SimulationConfig protocol
bluecellulab/simulation/neuron_globals.py — Generic mechanism globals application
bluecellulab/circuit_simulation.py — Wire _apply_modifications() into instantiate_gids()
pyproject.toml — Require libsonata>=0.1.34

Example

New notebook examples/2-sonata-network/sonata-modifications.ipynb demonstrates all modification types.

Bug Fix: Empty Reports Dict

get_report_entries() now handles None (returned by libsonata/bluepysnap for "reports": {}) gracefully instead of raising ValueError.

Dependencies

Requires libsonata>=0.1.34 (adds snake_case modification type enums)

- Add support for all 5 SONATA modification types: ttx, configure_all_sections, section_list, section, and compartment_set - Replace hardcoded MechanismConditions with generic mechanisms dict in Conditions - Parse modifications from libsonata via SonataSimulationConfig.get_modifications() - Apply modifications automatically during CircuitSimulation.instantiate_gids() - Handle empty reports dict gracefully (libsonata returns None for reports: {}) - Add 40 unit tests for modifications with 100% coverage on modifications.py - Require libsonata>=0.1.34 for snake_case modification type enums - Add example notebook demonstrating all 5 modification types

codecov · 2026-02-16T07:51:54Z

Codecov Report

❌ Patch coverage is 97.78052% with 18 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
bluecellulab/circuit_simulation.py	73.77%	16 Missing ⚠️
bluecellulab/circuit/config/sections.py	97.77%	1 Missing ⚠️
...ellulab/circuit/config/sonata_simulation_config.py	94.44%	1 Missing ⚠️

Files with missing lines	Coverage Δ
bluecellulab/circuit/config/definition.py	`100.00% <100.00%> (ø)`
bluecellulab/simulation/modifications.py	`100.00% <100.00%> (ø)`
bluecellulab/simulation/neuron_globals.py	`96.29% <100.00%> (+0.46%)`	⬆️
tests/test_circuit/test_simulation_config.py	`100.00% <100.00%> (ø)`
tests/test_simulation/test_modifications.py	`100.00% <100.00%> (ø)`
tests/test_simulation/test_neuron_globals.py	`100.00% <100.00%> (ø)`
bluecellulab/circuit/config/sections.py	`93.07% <97.77%> (+3.42%)`	⬆️
...ellulab/circuit/config/sonata_simulation_config.py	`97.40% <94.44%> (-0.46%)`	⬇️
bluecellulab/circuit_simulation.py	`85.20% <73.77%> (-0.19%)`	⬇️

🚀 New features to boost your workflow:

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

jplanasc · 2026-02-17T13:39:24Z

bluecellulab/circuit_simulation.py

            raise BluecellulabError(
                "instantiate_gids() is called twice on the "
-                "same CircuitSimumation, this is not supported")
+                "same CircuitSimumation, this is not supported"


typo: CircuitSimulation

Thanks! Fixed in the latest commit.

ilkilic · 2026-02-19T16:34:31Z

bluecellulab/circuit/config/sections.py

+    """Base class for all modification types."""
+
+    name: str
+    type: str


Small thought: since the subclass already implies the modification kind, having a free type: str here means the instance can technically end up inconsistent with its class (e.g. a ModificationTTX whose type is "section"). Maybe we could make type fixed per subclass (or not part of the constructor) so it can’t drift?

Good idea. I removed the free type: str from ModificationBase and explicitly defined it as a fixed Literal in each subclass (e.g., type: Literal["ttx"] = "ttx").

ilkilic · 2026-02-19T16:39:33Z

bluecellulab/circuit/config/sections.py

+
+def modification_from_libsonata(mod) -> ModificationBase:
+    """Convert a libsonata modification object to a BlueCelluLab dataclass."""
+    type_name = mod.type.name  # e.g. "ttx", "configure_all_sections", etc.


Maybe worth normalizing to lowercase before matching?

Yes, thanks. I updated to use mod.type.name.lower().

…hing

ilkilic · 2026-02-24T10:13:54Z

bluecellulab/simulation/modifications.py

+    n_sections = 0
+    for cell_id in target_cell_ids:
+        cell = cells[cell_id]
+        cell_applied = 0


cell_applied reads a bit like a boolean but it actually counts how many sections in the cell were affected. Maybe something like sections_applied / sections_modified would make the later > 0 check clearer?

Renamed cell_applied to sections_applied in all functions.

bluecellulab/simulation/modifications.py

ilkilic · 2026-02-24T12:14:09Z

bluecellulab/simulation/modifications.py

+    section_configs: dict[str, tuple[str, set[str]]] = {}
+    for sec_name in section_names:
+        escaped = re.escape(sec_name)
+        config_str = re.sub(escaped + r"\.", "sec.", mod.section_configure)


I might be misunderstanding, but it looks like we replace
. with sec. in the full string rather than isolating the statements for that section. If we references multiple sections (e.g. apic[10], dend[3]), would we still execute the other statements when applying to one section?

I updated the code to only support one section per modification, as per the SONATA spec. Can you please check again?

ilkilic · 2026-02-24T12:24:21Z

bluecellulab/simulation/modifications.py

+
+    # Parse section_configure — bare format: "attr = value"
+    # Prefix with "seg." to make it executable
+    config_str = re.sub(r"(\b\w+)\s*=", r"seg.\1 =", mod.section_configure)


Small question: we build config_str with the regex rewrite but then overwrite it below by prefixing each full statement. Is the first transformation intentionally unused?

Removed the confusing section_configs dict loop and the unused regex. Since the SONATA spec requires section modifications to reference only one section, the multi-section was not needed.

ilkilic · 2026-02-24T12:29:30Z

bluecellulab/circuit_simulation.py

            pre_gids = None

-        # if pre_spike_trains take int as key then convert to CellId
+        normalized_pre_spike_trains: dict[CellId, Iterable] | None = None


much clearer, thanks!

ilkilic · 2026-03-06T14:07:52Z

examples/2-sonata-network/sonata-modifications.ipynb

+      "======================================================================\n",
+      "\n",
+      "Cell CellId(population_name='NodeA', id=0):\n",
+      "soma[0] cm = {soma.cm}\n",


small bug: the variable here and below were not resolved, did you run the cell with f-string?

It was from an old run. I ran again, and I can see the values now.

ilkilic · 2026-03-06T14:08:31Z

examples/2-sonata-network/sonata-modifications.ipynb

+    "# Simulation WITHOUT modifications (baseline)\n",
+    "baseline_config = Path(\"sim_quick_scx_sonata_multicircuit\") / \"simulation_config_noinput.json\"\n",
+    "sim_baseline = CircuitSimulation(baseline_config)\n",
+    "sim_baseline.instantiate_gids(all_cell_ids, add_stimuli=False, add_synapses=False)\n",


why setting add_stimuli to false?

To check changes in baseline potentials.

ilkilic

Thank you!

darshanmandge added 2 commits February 13, 2026 19:12

intial implementation

7e33f3a

darshanmandge self-assigned this Feb 16, 2026

darshanmandge requested a review from ilkilic February 16, 2026 07:45

jplanasc reviewed Feb 17, 2026

View reviewed changes

fix typos, lint and type-checking issues

75772be

ilkilic reviewed Feb 19, 2026

View reviewed changes

darshanmandge added 2 commits February 20, 2026 10:46

Fix PR comments: fixed type attribute per subclass and lowercase matc…

433ec7f

…hing

fix test

e9a9ada

ilkilic reviewed Feb 24, 2026

View reviewed changes

bluecellulab/simulation/modifications.py Show resolved Hide resolved

ilkilic reviewed Feb 24, 2026

View reviewed changes

darshanmandge added 4 commits February 27, 2026 17:38

improve variable naming, validation, and code clarity

fb23e54

Merge main branch: add SEClamp stimulus support

e3a2696

Fix f-string formatting in sonata-modifications notebook

b5f62b0

Fix section_list prefix validation regex and add

128f3e5

ilkilic reviewed Mar 6, 2026

View reviewed changes

darshanmandge mentioned this pull request Mar 6, 2026

Fix handling of empty reports section in SONATA config #66

Closed

minor fix in example sonata-modifications.ipynb

2ccbe96

ilkilic approved these changes Mar 9, 2026

View reviewed changes

darshanmandge merged commit 614b1d5 into main Mar 9, 2026
8 checks passed

darshanmandge deleted the condtions_modifications branch March 19, 2026 21:20

Conversation

darshanmandge commented Feb 16, 2026

Summary

Changes

New: SONATA Modifications (bluecellulab/simulation/modifications.py)

Graceful Skipping & Logging

New: Generic Mechanism Handling

Files Changed

Example

Bug Fix: Empty Reports Dict

Dependencies

Uh oh!

codecov bot commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ilkilic left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov bot commented Feb 16, 2026 •

edited

Loading