CoreNeuron Inputs

Premise

This document provides a best-effort overview of the inputs used by CoreNeuron. I do not claim complete knowledge of all internal workings; sections marked with TODO indicate areas where further clarification is needed.

Input Categories

CoreNeuron inputs can be divided into two main categories:

  1. Additional configuration values/files:

    • sim.conf: A general configuration file. All values defined here can also be passed as command-line parameters.

    • report.conf: A configuration file specifying the reports that CoreNeuron needs to emit. This file is used only if Direct Mode is not enabled. The output routines rely on libsonatareport and comply with the Sonata standard: Sonata Documentation.

  2. Data passed from NEURON to CoreNeuron:

    NEURON passes input data to CoreNeuron via files located in the datpath specified in sim.conf (or passed as a CLI argument). These files include:

    • gid_1.dat, gid_2.dat, gid_3.dat: Data for each GID passed in three phases.

    • bbcore_mech.dat: Information about mechanisms.

    • files.dat: TODO — description needed.

    • globals.dat: TODO — description needed.

sim.conf

The sim.conf file is a general configuration file used by CoreNeuron. It can be provided either via the CLI option --read-config or by setting the sim_config attribute in Python:

from neuron import coreneuron
coreneuron.sim_config = "<path to sim.conf>"

Example sim.conf:

outpath='<path where simulation outputs (i.e., reports) are written>'
datpath='<path where NEURON writes input data files for CoreNeuron (usually build/coreneuron_input)>'
tstop=100.0
dt=0.025
prcellgid=-1
celsius=34.0
voltage=-65.0
cell-permute=0
mpi=1
seed=767740
report-conf='<path to report.conf file>'

Parameters explained:

  • outpath: Path where simulation outputs (i.e., reports) are written.

  • datpath: Path where NEURON writes input data files for CoreNeuron.

  • tstop: Total simulation time in milliseconds.

  • dt: Integration time step in milliseconds.

  • prcellgid: If >=0, print state of this GID during simulation.

  • celsius: Temperature of the simulation in °C.

  • voltage: Initial membrane voltage in mV.

  • cell-permute: Index controlling the permutation of cells:

    • 0 — No permutation

    • 1 — Optimize node adjacency (CPU, GPU)

    • 2 — Optimize parent adjacency (GPU)

  • mpi: Number of MPI ranks (if using parallel execution).

  • seed: Random seed for reproducibility.

  • report-conf: Path to report.conf file for simulation reports.

report.conf

The report.conf file specifies the reports that CoreNeuron will emit. It is partially binary and typically generated by Neurodamus.

Format overview:

  1. The file starts with a single number indicating the total number of reports.

  2. Each report has a metadata line with a few key values (see below).

  3. Following the metadata line, there is a binary line with a list of gids.

  4. (Optional) If the report is of type compartment_set, there are 2 additional binary lines:

    • Section IDs (integers)

    • Compartment IDs (integers)

All these binary lines (list of integers) have the same length. It is specified by num_gids in the metadata line (see below).

Example entries (simplified):

2
compartment_set_pas.h5 Mini5 compartment_set pas mV SONATA invalid invalid 1.0 0.0 40.0 8 8 none
<binary data for GIDs>
<binary data for section IDs>
<binary data for compartment IDs>

summation_v.h5 Mosaic summation v mV SONATA soma center 1.0 0.0 40.0 5 8 none
<binary data for GIDs>

Metadata line fields

Each report in report.conf starts with a metadata line describing its properties.

report_name target_name report_type report_variable unit report_format sections compartments dt start_time end_time buffer_size scaling num_gids

The various variables are described in detail in the SONATA report documentation.

Field descriptions:

  1. report_name — Name of the output

  2. target_name — Name of node set (group of gids)

  3. report_type — Type of report

    • compartment

    • compartment_set

    • summation

    • synapse

    • lfp

  4. report_variable — The variable to be reported (e.g., v, i_membrane, pas.i, pas). Any point-process or mechanism variable is allowed. The variable should be specified as <mechanism>.<variable>. If the variable is i, it can be omitted; in that case, the code assumes i by default.

  5. unit — Physical unit of the reported variable (e.g., mV, nS)

  6. report_format — Format of the report (currently only SONATA remains)

  7. sections — Target sections of the cells:

    • Cell, Soma, Axon, Dend (Dendrite), Apic (Apical), Ais, Node, Myelin, All, Invalid (used for compartment_set reports)

  8. compartments — Specific compartments:

    • All, Center, Invalid (used for compartment_set reports)

  9. dt — Sampling interval for the report in milliseconds

  10. start_time — Start time of the report in milliseconds

  11. end_time — End time of the report in milliseconds

  12. num_gids — Number of GIDs included in the report (used to read the following binary lines)

  13. buffer_size — Size of the buffer used to store report values

  14. scaling — Scaling applied to reported values:

    • None, Area

Notes:

  • Following the metadata line, binary lines store the actual data:

    • GIDs (all reports)

    • Section IDs and compartment IDs (for compartment_set reports only)

  • All binary lines have length num_gids.

  • The order of the fields in the metadata line corresponds exactly to the order above.