NAME¶
CNrun -- 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.
SEE ALSO¶
spike2sdf(1), varfold(1).
AUTHOR¶
CNRun and the underlying library libcn is written by Andrei Zavada
<johnhommer@gmail.com>, building on the original code by Thomas Nowotny,
while at Sussex University in 2008-10.