Setting up a Sonata simulation¶

Neurodamus now supports the SONATA open-source format for its input and output files.

The full specification, including BBP extensions, is available at the BBP Circuit Documentation pages https://sonata-extension.readthedocs.io/en/latest/sonata_overview.html.

The Sonata specification prescribes the file format for all Simulation inputs and outputs, as depicted in the following image:

The Sonata simulation input files¶

Neurodamus CLI expects a simulation configuration file which can provide all the settings, namely the definition of the circuit and the parameters of the simulation.

This file is the successor of the BlueConfig, but with some important changes.

Contrary to BlueConfig the Sonata simulation config only deals with the simulation parameters, leaving out the details of the circuit, in particular the location of the composing files.

For the complete reference please refer to sonata_simulation documentation

As an example let’s consider an Hippocampus sample simulation ( Hippocampus-mini-simultion-config)

Fundamental simulation parameters¶

Sonata Config

BlueConfig

"run": {
"tstop": 100.0,
  "dt": 0.025,
  "random_seed": 264118,
},

"target_simulator": "NEURON",
"network": "circuit_config.json",
"node_sets_file": "node_sets.json",
"node_set": "most_central_100_SP_PC",

"output": {
  "output_dir": "output_sonata",
  "spikes_file": "out.h5",
  "spikes_sort_order": "by_time"
},

Run Default
{
  Duration 100
  Dt 0.025
  BaseSeed 264118

  Simulator NEURON
  # BlueConfig had circuit defs inline
  TargetFile mooc-circuit/user.target
  CircuitTarget hippocampus_neurons:central

  OutputRoot output

  RNGMode Random123  # deprecated
  RunMode RR         # deprecated. use CLI
}

The top of the file specifies the fundamental simulation parameters. In particular the run block must exist and set tstop and dt. Moreover, the target_simulator block is a top-level entity now, which defaults to NEURON.

The second block selects which circuit is to be simulated. This is the main difference wrt BlueConfig. network should point to the circuit config file which, as showing in the diagram, contains information about the location of the files building it up. Therefore this entry replaces all entries specifying circuit files, namely CircuitPath, MorphologyPath, MorphologyType, METypePath, MEComboInfoFile, CellLibraryFile, nrnPath.

There will likely be such files available per circuit, but the user may define himself a custom one. Please refer to the Additional Examples section.

node_sets_file should point to a file defining Sonata nodesets. More on ths in the next section.

The nodeset is basically the selection of nodes (defined in the node_sets_file) which will be simulated. If not set Neurodamus will choose all non-virtual nodes of all populations.

The Sonata Nodeset file¶

Nodesets are selectors, in the form of filter expressions or cell IDs, that can be referenced in several points of the configuration, namely to select the simulation or reporting targets.

Please find the full documentation at https://sonata-extension.readthedocs.io/en/latest/sonata_nodeset.html

In the current example most_central_100_SP_PC must be defined in node_sets.json, in this case:

"most_central_100_SP_PC": {
  "population": "hippocampus_neurons",
  "node_id": [
    11616,
    6392,
    6788,
  ]
}

Notice that, by default the filtering rules or node IDs try to match against all available populations, and therefore specifying which population the rules should apply is generally required.

Additional Examples¶

You can find a number of examples of curated Sonata simulations in the blueconfigs repository

Here’s a quick list of them which can be used as inspiration:

Example Sonata¶
Circuit kind	Simulation Config	Circuit config	Node Sets
Hippocampus	simulation_config.json	circuit_config.json	node_sets.json
SSCX	simulation_config.json	circuit_config.json	node_sets.json
Thalamus	simulation_config.json	circuit_sonata.json	node_sets.json

Supported features¶

Here is a summary of main features supported by the Sonata simulation config file. Details on the parameters can be found in sonata_simulation documentation.

Component	Support	Comments
Nodes and Edges	Full
NodeSets (multiple populations)	Full
Multi-population reports	Full
Simulation configuration	Full
Sonata specific stimuli	Partial	Pending features: PulseTI stimuli, Extracellular stimuli.
NGV support	Partial	Results being validated.
Point Neuron simulation	Partial	No report. No replay.
Neuromodulation	Partial	No replay.
Deprecation of BlueConfig sections	Partial	Modifications, Electrode, Projection [1].
Non-Sonata Configuration as CLI	Full	New args: –save=<PATH>, –save-time=<TIME>, –restore=<PATH>, –lb-mode=[RoundRobin, WholeCell, MultiSplit], –dump-cell-state=<GID>.

SONATA FAQ¶

This is a list of Frequently Asked Questions about the NEURODAMUS support of SONATA format.

How do I convert my old BlueConfig to SONATA configuration?¶

Right now it is a manual process, however we are studying the viability of an automatic converter in this ticket

For more info regarding the corresponding keys between BlueConfig and SONATA you could check this spreadsheet.

There are also some examples where given a BlueConfig, we show the corresponding SONATA config file. The examples can be found here

How do I know if my new SONATA configuration is valid?¶

You can load your simulation_config.json file with libsonata and it will tell you if there are any issues with the file.

$  module load unstable py-libsonata/0.1.14
$  python
$  >>> import libsonata
$  >>> libsonata.SimulationConfig.from_file('simulation_config.json')
File "read_simconfig.py", line 3, in <module>
libsonata.SimulationConfig.from_file('simulation_config.json')
libsonata._libsonata.SonataError: Invalid value: '"compartment"' for key 'type'

More info about the sections and valid values in the simulation config can be found here

And how do I convert my spikes (out.dat) and binary reports (.bbp) to SONATA format?¶

There are 2 options:

If you want to convert also the BlueConfig to SONATA, then rerun the simulation with the new simulation config file that you converted.
If you only need the reports, then we have a proof of concept converter. More info can be found in this ticket

How do I run a SONATA simulation?¶

Basically the same way than before.

First, neurodamus modules need to be loaded

py-neurodamus: should be at least 2.12.0 for base SONATA support
neurodamus-xxx: load the neurodamus model needed for your simulation

$ module load unstable py-neurodamus/2.12.0 neurodamus-neocortex

Finally special is called with the –configFile CLI option pointing to the sonata configuration file

$  srun special -mpi -python $NEURODAMUS_PYTHON/init.py --configFile=simulation_config.json

Source

sonata-simulation.rst