CNrun(1) a neuronal network simulator

SYNOPSIS

       cnrun -h | -U | -e script [OPTION ...]

DESCRIPTION

CNrun is a neuronal network simulator, similar to NEURON or GENESIS, but without provision for unit compartments. It reads the network topology in NeuroML format as exported, f.i., by neuroConstruct. Unit types are determined by the 'cell_type' attribute in the .nml definitions.

Available neuron types, by the corresponding 'cell_type' string, include:

  • HH and HHRate, conductance- and rate-based Hodgkin-Huxley neurons (Traub & Miles, 1991);
  • A simplified but fast, fixed-dt Map neurons mimicking the HH model;
  • Poisson, Van der Pol (VdP) and simple Pulse oscillators;
  • synapses as described in Rall et al, 1967 (Rall) and Destexhe et al, 1994 (AB).

Unit parameters can be set via a set_parm_* command (see SCRIPTING below); values can be set once before the simulation, or continuously or periodically per user-defined schedule.

A 6-5-order Runge-Kutta integration method is used to compute state variables. These (membrane potential E or instantaneous firing rate R for neurons, neurotransmitter release S for synapses) as well as spike times can be logged.

Scripting support in CNrun includes commands for creating and populating a model, setting parameters for single units or groups selected based on regex matching. Variables ('a = 1; b = a + 2') and arithmetic expressions ('-', '+', '*', '/', '()' ) are supported.

OPTIONS

-C dir chdir to dir before running.
-D
Dump all unit types in the model and exit.
-e [script]
Execute script. If this option is given without a file name (or not given at all), start an interactive interpreter.
-s
Sort units (mostly useful with verbose output).
-L[1dbxL]
For all listeners:
d
Defer writing to disk until done rather than write continuously (speeds up the simulation but you can't watch the progress live with gnuplot)
1
Only log the first variable (appropriate for the HH model, which units have in excess the three uninteresting gating parameters).
b
Write in native binary form rather than in ASCII. This will speed up viewing the (now label.varx files) with gnuplot. Do your plotting with "binary format="%lf%lf"" to achieve this.

These options can also be set using command listen_mode (which see, below).

L
log integrator dt.
-E double
Listen at this interval (default 1 msec; set to 0 to listen every cycle, which can slow cnrun down considerably). Also available as command listen_dt.
-k[l|0]
Write a model-wide log of spiking neurons, using labels ('l') or unit ids ('0').
-e uint
Set precision for all output (default 8).
-iTdouble
dt_max (default 0.5).
-itdouble
dt_min (default 1e-05).
-ixdouble
Cap dt increase by current dt value x this (default 5).
-nc
Disable synapse coalescing (for benchmarking).
-v int
Set verbosity level (default 1; values up to 7 are meaningful). Use a negative value to show the progress percentage only, indented on the line at -8 x this value.
-U
List all available units.
-h
Print the overview of command-line options.

Space is optional between the option letter and argument for single-letter options. In all two-letter options taking an argument though, make sure there is no space in between.

SCRIPTING

Commands are delimited by a colon or new-line. Comments are lines starting with #. The following commands are available:
new_model NAME
Create a new model called NAME. Existing model is deleted.
use_nml NML_FILE
Load network topology from NML_FILE, creating a model if necessary, or replacing an existing model" topology.
merge_nml NML_FILE
Merge in the topology from NML_FILE.
add_neuron TYPE LABEL
Add a new newron of type TYPE with label LABEL.
add_synapse TYPE SOURCE TARGET G
Connect the neuron labelled SOURCE to one labelled TARGET with a synapse of type TYPE, with gsyn G.
cull_deaf_synapses
Remove synapses with zero weight.
set_parm_neuron LABEL PARM VALUE
Set parameter PARM for a specified group of neurons labelled matching LABEL.
set_parm_synapse SRC TGT PARM VALUE
Set parameter PARM for synapses between neurons labelled matching SRC and TGT. The synaptic weight, itself not being a synapse parameter, can also be set with this command: to do this, use 'gsyn' as PARM.
reset
Reset the model. Model time is rewound to 0 and all units have their state variables reset to stock defaults. Any previously assigned unit parameters and attached data sources are preserved.
reset_revert_params
Reset the model. Model time is rewound to 0, all units have their state variables and parameters reset to stock defaults.
reset_state_units REGEX
Reset the units' as above, keeping current model time.
advance_until TIME
Advance until TIME msec.
advance TIME
Advance TIME msec.
putout REGEX
Delete units matching REGEX by label.
decimate REGEX FRAC
Randomly delete FRAC units of a population of units selected by REGEX.
start_listen REGEX
Make matching units listen.
stop_listen
Make matching units stop listening.
listen_dt [VALUE]
Set listening interval to VALUE, or show current value if VALUE not given.
listen_mode [SPEC]
Print (if argument is omitted) the current listening mode (one var only, deferred write, and/or binary); otherwise, enable the corresponding mode if '1', 'd' or 'b' occurs in SPEC, or disable it if it does and is immediately followed by a '-'. Note that those units already listening will be unaffected; to change the mode for them, issue start_listen for them after the new mode has been set.
start_log_spikes REGEX
Make neurons matching REGEX log spikes.
stop_log_spikes REGEX
Make neurons matching REGEX stop log spikes.
sxf_params DELAY:PERIOD:SIGMA
Set spike density function initial delay, sampling period and sigma as specified.
describe_model
Print a summary of model topology and unit types.
show_units REGEX
Print parameters and state of units matching REGEX.
new_source TYPE ID ARG ...
Create a new source of type and with an id as indicated. Sources can be connected to unit parameters as a means to set up a dynamically changing behaviour. See DYNAMIC SOURCES below.
connect_source SOURCE_ID LABEL PARM
Connect this source to matching units' parameter.
show_sources
Show the currently active sources (both connected and idle).
exec [SCRIPT]
Execute a script. If SCRIPT not specified, start an interactive interpreter.
verbosity [LEVEL]
Set/show verbosity level.
show_vars [REGEX]
Print variables matching REGEX, or all variables if REGEX omitted.
clear_vars [REGEX]
Clear variables matching REGEX, or all if REGEX omitted.
pause [DELAY]
Pause for DELAY sec if specified, or until user presses Enter otherwise.
quit
Exit current interpreter if called by exec; exit the program otherwise.

When you use the interpreter interactively, TAB will list completions approproiately, depending on the context.

DYNAMIC SOURCES

In addition to static unit parameter/variable assignment with set_parm_{neuron,synapse}, units can have a data source attached to any of their parameters or variable (even though variables will get overwritten in the next cycle).

Data sources are of three types (a fourth one is available for developers, an arbitrary user function of time, but not exposed as an interpreter command). Where data for a source are read from a file, values are read using a '>>' operator (from <ifstream>) into a double variable. The corresponding new_source arguments are:

Tape FILE
Read "time value" pairs from FILE and set the parameter's value accordingly.
Periodic FILE
FILE is expected to contain, as the first number value read by scanf("%lg"), a time period at which the following values are sequentially assigned to the parameter. Values are assigned at the beginning of each integration cycle.
Noise MIN:MAX
Generate (irrespective of time) a uniformly distributed random number within MIN:MAX.

Similarly to the parameters, state variables can also be set in this manner; in this case, the values read, will override whatever the inner workings of the unit assign to it. Where a Tape has a gap between assignment times larger than current dt, assignments are still made; this, however, does not apply to Periodic sources (chiefly for performance reasons).

SYNAPSE COALESCING

Coalesced synapses are those having identical parameters and having the same source. Coalescing reduces, per divergence rate, the number of times the S variable is recomputed with identical parameters per cycle; additionally for hosted synapses, the integration vector is shrunk to fit towards further performance gain.

Coalescing happens automatically between two synapses from same source when, after all parameter assignments, they are found to be identical (disregarding synaptic weights). Conversely, when the user changes a parameter to one coalesced synapses that is different from that parameter's value in the others, that synapse becomes independent.

Note that a synapse units's label is dynamically formed of the label of the source with a semicolon and the current number of targets. Another consequence of coalescing is that there can be more than one synapse units labelled identically (hence, uniquely to identify a synapse, you need to specify its source and target).

The command-line option -nc can be used to disable coalescing.

FILES

.cnrun-history, a per-directory history of entered commands.

EXAMPLE

In /usr/share/doc/cnrun/ratiocoding, there is a working example of cnrun setup which reproduces some of the results presented in Zavada et al (2011) PLoS paper.

BUGS

The oscillator units other than Poisson, have not been tested.

AUTHOR

CNRun and the underlying library libcn is written by Andrei Zavada <[email protected]>, building on the original code by Thomas Nowotny, while at Sussex University in 2008-10.