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.

ilkilic · 2026-02-24T10:59:51Z

bluecellulab/simulation/modifications.py

+
+    # Extract list name from section_configure: e.g. "apical.gbar = 0" -> "apical"
+    # The format is "<list_name>.attr = value [; <list_name>.attr = value ...]"
+    match = re.match(r"^(\w+)\.", mod.section_configure)


From the SONATA spec it looks like a section_list entry should reference a single list. Since this only inspects the first prefix, could a snippet that accidentally mixes lists (e.g. apical, basal) pass here and only fail later during exec? Would it be worth checking all statements use the same prefix and raising a clearer config error?

could a snippet that accidentally mixes lists (e.g. apical, basal)

Just to understand what you meant: you meant checking for entries such as apical.basal.gbar_NaTg =2 or apicalbasal.gbar_NaTg =2 or something else?

I meant semicolon separated statements using different lists, e.g. apical.gbar_NaTg = 0.0; basal.cm = 1. Right now we only rewrite the first prefix so the basal. part would remain and likely fail during exec. Maybe we should either support mixed prefixes or detect them and raise a clearer error?

Thanks for pointing that out. The SONATA documentation notes that the section_lists modification has the same section_list per modification entry in section_configure. So, this "apical.gbar_NaTg = 0.0; apical.cm = 1" is acceptable. The code will now raise an error for mixed prefixes for your example, apical.gbar_NaTg = 0.0; basal.cm = 1 as intended.

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!

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

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

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov bot commented Feb 16, 2026 •

edited

Loading