neurodamus package

neurodamus

The neurodamus package implements the instantiation of simulations in Neuron based on a configuration file, a.k.a. simulation_config.json It is deeply based on the HOC implementation, therefore providing python modules like node, cell_distributor, etc; and still depends on several low-level HOC files at runtime.

Package-Level Classes

node.Neurodamus(config_path_or_obj[, ...])	A high level interface to Neurodamus
node.Node(config_path_or_obj[, options])	The Node class is the main entity for a distributed Neurodamus execution.

Sub-Modules

cell_distributor	Mechanisms to load and balance cells across the computing resources.
connection_manager	Main module for handling and instantiating synaptical connections and gap-junctions
connection	Implementation of the core Connection classes
gap_junction	Main module for handling and instantiating synaptical connections
metype	Module which defines and handles METypes config (v5/v6 cells)
modification_manager	Implements applying modifications that mimic experimental manipulations
ngv	Module which defines and handles Glia Cells and connectivity
replay	Stimulus implementation where incoming synaptic events are replayed for a single gid
stimulus_manager	Implements coupling artificial stimulus into simulation
target_manager

Module API

neurodamus

class neurodamus.node.Neurodamus(config_path_or_obj: str | SimulationConfig, logging_level=None, **user_opts)

A high level interface to Neurodamus

__init__(config_path_or_obj: str | SimulationConfig, logging_level=None, **user_opts)

Creates and initializes a neurodamus run node

As part of Initiazation it calls:

• load_targets

• compute_load_balance

• Build the circuit (cells, synapses, GJs)

• Add stimulus & replays

• Activate reports if requested

Parameters:

• config_path_or_obj – Path to a SONATA simulation config JSON file, or a libsonata.SimulationConfig instance.

• logging_level – (int) Redefine the global logging level. 0 - Only warnings / errors 1 - Info messages (default) 2 - Verbose 3 - Debug messages

• user_opts – Options to Neurodamus overriding the simulation config file

compute_n_cycles()

Determine the number of model-building cycles

It is based on configuration and system constraints.

init()

Explicitly initialize, allowing users to make last changes before simulation

run(cleanup=True)

Prepares and launches the simulation according to the loaded config. If ‘–only-build-model’ option is set, simulation is skipped.

Parameters:

cleanup (bool) – Free up the model and intermediate files [default: true] Rationale is: the high-level run() method it’s typically for a one shot simulation so we should cleanup. If not it can be set to False

class neurodamus.node.Node(config_path_or_obj: str | SimulationConfig, options: dict | None = None)

The Node class is the main entity for a distributed Neurodamus execution.

Note that this concept of a “Node” differs from both an MPI node, which refers to a process in a parallel computing environment, and a node in the circuit graph, which represents an individual element or component within the simulation’s neural network.

It serves as the orchestrator for the entire simulation, managing the parallel execution of the model and distributing the cells across different computational ranks. As the primary control structure, Node is responsible for coordinating various components involved in the simulation.

Internally, the Node class instantiates and manages parallel structures, dividing the simulation workload among multiple ranks. With the introduction of the concept of multiple populations (also known as multi-circuit), the Node class takes partial responsibility for handling this logic, aided by the neurodamus.node.CircuitManager class (accessible via the circuits property), which manages the different node and edge managers.

While many lower-level details of the Node’s functionality are encapsulated within dedicated helper classes, the Node class still exposes an API that allows advanced users to control and inspect almost every major step of the simulation. For a standard run, users are encouraged to use the higher-level Neurodamus class instead, which simplifies some of the complexities handled by Node.

The Node class exposes the following public properties:

• circuits: is a neurodamus.node.CircuitManager object, responsible for managing multiple node and edge managers within the simulation.

• target_manager: is a neurodamus.target_manager.TargetManager object, responsible for managing the targets in the simulation.

• stimulus_manager: is a neurodamus.stimulus_manager.StimulusManager object, responsible for interpreting and instantiating stimulus events.

• elec_manager: The electrode manager, which controls the interaction with simulation electrodes.

• reports: A list of Neurodamus Report hoc objects, used to generate simulation reports.

Note that, while the Node object owns and manages most of the top-level objects in the simulation, the management of cell and synapse objects has been delegated to the Circuits class, as these are now handled at a lower level.

Technical note:

• The properties exposed by Node are read-only, with most internal attributes being prefixed with an underscore (_). Notable internal attributes include:

  self._sonata_circuits: The SONATA circuits used by the Node each represents a node population.

These details make the Node class versatile and powerful for advanced users who need more granular control over the simulation process.

all_circuits()

property circuits

cleanup()

Have the compute nodes wrap up tasks before exiting.

clear_model(avoid_creating_objs=False, avoid_clearing_queues=True)

Clears appropriate lists and other stored references. For use with intrinsic load balancing. After creating and evaluating the network using round robin distribution, we want to clear the cells and synapses in order to have a clean slate on which to instantiate the balanced cells.

compute_load_balance()

In case the user requested load-balance this function instantiates a CellDistributor to split cells and balance those pieces across the available CPUs.

static coreneuron_cleanup()

Clean coreneuron save files after running

create_cells(load_balance=None)

Instantiate and distributes the cells of the network. Any targets will be updated to know which cells are local to the cpu.

create_synapses()

Create synapses among the cells, handling connections that appear in the config file

dump_cell_states()

Dump the _pr_cell_gid cell state if not already done

We assume that the parallel context is ready. Thus, This function should not be called if coreNeuron is employed and we are not at t=0.0.

enable_modifications()

Iterate over any Modification blocks read from the config file and apply them to the network. The steps needed are more complex than NeuronConfigures, so the user should not be expected to write the hoc directly, but rather access a library of already available mods.

enable_replay()

Activate replay according to config file. Call before connManager.finalize

enable_reports()

Iterate over reports defined in the config file and instantiate them.

enable_stimulus()

Iterate over any stimulus defined in the config file given to the simulation and instantiate them. This passes the raw text in field/value pairs to a StimulusManager object to interpret the text and instantiate an actual stimulus object.

load_targets()

Initialize targets. Nodesets are loaded on demand.

static move_dumpcellstates_to_output_root()

Check for .corenrn or .nrn files in the current directory and move them to CoreConfig.output_root_path(create=True).

property reports

run_all()

Run the whole simulation according to the simulation config file

sim_init(corenrn_gen=None, **sim_opts)

Finalize the model and prepare to run simulation.

After finalizing the model, will eventually write coreneuron config and initialize the neuron simulation if applicable.

Parameters:

• corenrn_gen – Whether to generate coreneuron config. Default: None (if required)

• spike_compress (sim_opts - override _finalize_model options. E.g.)

solve(tstop=None)

Call solver with a given stop time (default: whole interval). Be sure to have sim_init()’d the simulation beforehand

sonata_spikes()

Write the spike events that occured on each node into a single output SONATA file.

property stim_manager

property stims

property target_manager

write_and_get_population_offsets() → tuple[dict, dict, dict]

Retrieve population offsets from the circuit or restore them, write the offsets, and return them.

Returns:

• pop_offsets: Mapping of population names to GID offsets.

• alias_pop: Mapping of population aliases to population names.

• virtual_pop_offsets: Mapping of virtual population names to offsets.

Return type:

tuple[dict, dict, dict]

Source

api/neurodamus.rst