From 994d4f54160136499196e20ea45e6cf5a729370d Mon Sep 17 00:00:00 2001 From: steffen Date: Wed, 25 May 2016 07:52:40 +0200 Subject: [PATCH 01/20] renaming files --- .../documentation/an-introduction-to-sli.md | 86 +++ .../analog-recording-with-multimeter.md | 97 +++ .../md/documentation/connection-management.md | 603 ++++++++++++++++++ .../documentation/continuous-integration.md | 129 ++++ .../userdoc/md/documentation/documentation.md | 14 +- extras/userdoc/md/documentation/download.md | 2 +- extras/userdoc/md/documentation/features.md | 6 +- .../userdoc/md/documentation/first-steps.md | 169 +++++ .../frequently-asked-questions.md | 78 +++ .../md/documentation/getting-started.md | 53 ++ extras/userdoc/md/documentation/index.md | 2 +- .../userdoc/md/documentation/installation.md | 4 +- .../md/documentation/neural-simulations.md | 466 ++++++++++++++ .../documentation/objects-and-data-types.md | 211 ++++++ .../md/documentation/parallel-computing.md | 222 +++++++ ...rt-1-neurons-and-simple-neural-networks.md | 6 +- .../part-2-populations-of-neurons.md | 2 +- ...art-3-connecting-networks-with-synapses.md | 4 +- ...art-4-topologically-structured-networks.md | 2 +- .../md/documentation/programming-in-sli.md | 313 +++++++++ .../md/documentation/random-numbers.md | 454 +++++++++++++ .../scheduling-and-simulation-flow.md | 6 +- .../simulations-with-precise-spike-times.md | 4 +- .../using-files-and-keyboard-input.md | 159 +++++ .../md/documentation/using-nest-with-music.md | 307 +++++++++ 25 files changed, 3373 insertions(+), 26 deletions(-) create mode 100644 extras/userdoc/md/documentation/an-introduction-to-sli.md create mode 100644 extras/userdoc/md/documentation/analog-recording-with-multimeter.md create mode 100644 extras/userdoc/md/documentation/connection-management.md create mode 100644 extras/userdoc/md/documentation/continuous-integration.md create mode 100644 extras/userdoc/md/documentation/first-steps.md create mode 100644 extras/userdoc/md/documentation/frequently-asked-questions.md create mode 100644 extras/userdoc/md/documentation/getting-started.md create mode 100644 extras/userdoc/md/documentation/neural-simulations.md create mode 100644 extras/userdoc/md/documentation/objects-and-data-types.md create mode 100644 extras/userdoc/md/documentation/parallel-computing.md create mode 100644 extras/userdoc/md/documentation/programming-in-sli.md create mode 100644 extras/userdoc/md/documentation/random-numbers.md create mode 100644 extras/userdoc/md/documentation/using-files-and-keyboard-input.md create mode 100644 extras/userdoc/md/documentation/using-nest-with-music.md diff --git a/extras/userdoc/md/documentation/an-introduction-to-sli.md b/extras/userdoc/md/documentation/an-introduction-to-sli.md new file mode 100644 index 0000000000..55122dce5a --- /dev/null +++ b/extras/userdoc/md/documentation/an-introduction-to-sli.md @@ -0,0 +1,86 @@ +An Introduction to SLI +====================== + +Introduction +------------ + +NEST can be started by typing + + /bin/nest + +at the command prompt. You should then see something like this: + gewaltig@jasmin-vm:~$ nest + -- N E S T 2 beta -- + + Copyright 1995-2009 The NEST Initiative + Version 1.9-svn Feb 6 2010 00:33:50 + + This program is provided AS IS and comes with + NO WARRANTY. See the file LICENSE for details. + + Problems or suggestions? + Website  : http://www.nest-initiative.org + Mailing list: nest_user@nest-initiative.org + + Type 'help' to get more information. + Type 'quit' or CTRL-D to quit NEST. + +Command line switches +--------------------- + +Type + + nest --help + +to find out about NEST's command-line parameters. + + gewaltig@jasmin-vm:~$ nest --help + usage: nest [options] [file ..] + -h --help print usage and exit + -v --version print version information and exit. + + - --batch read input from a stdin/pipe + --userargs=arg1:... put user defined arguments in statusdict::userargs + -d --debug start in debug mode (implies --verbosity=ALL) + --verbosity=ALL turn on all messages. + --verbosity=DEBUG|STATUS|INFO|WARNING|ERROR|FATAL + show messages of this priority and above. + --verbosity=QUIET turn off all messages. + +### Supplying SLI scripts with parameters + +Using the `--userargs=arg1:...` command line switch, it is possible to supply a +SLI script with parameters from the outside of NEST. A common use case for this +are parameter sweeps, where the parameters are defined in a bash script and +multiple instances of NEST are used to test one parameter each. +A bash script for this could look like this: + + for lambda in `seq 1 20`; do + for gamma in `seq 1 5`; do + nest --userargs=lambda=$lambda:$gamma=$gamma simulation.sli + done + done + +The corresponding SLI script `simulation.sli` could use the supplied parameters +like this: + + /args mark statusdict/userargs :: {(=) breakup} Map { arrayload pop int exch cvlit exch } forall >> def + args /lambda get == + +The first line first gets the array of user supplied arguments (`userargs`) from +the `statusdict` and breaks each element at the "="-symbol. It then converts the +first element (lambda, gamma) to a literal and the second argument (the number) +to an integer. Using `mark` and `>>`, the content of the userargs array is added +to a dictionary, which is stored under the name `args`. The second line just +prints the content of the lamda variable. + +SLI user manual +--------------- + +This manual gives a brief overview of the SLI programming language. + +1. [First Steps](first-steps.md "First Steps") +2. [Objects and data types](objects-and-data-types.md "Objects and data types") +3. [Programming in SLI](programming-in-sli.md "Programming in SLI") +4. [Using files and keyboard input](using-files-and-keyboard-input.md "Using files and keyboard input") +5. [Neural simulations](neural-simulations.md "Neural simulations") diff --git a/extras/userdoc/md/documentation/analog-recording-with-multimeter.md b/extras/userdoc/md/documentation/analog-recording-with-multimeter.md new file mode 100644 index 0000000000..f01480b3a3 --- /dev/null +++ b/extras/userdoc/md/documentation/analog-recording-with-multimeter.md @@ -0,0 +1,97 @@ +Analog recording with multimeter +================================ + +As of r89xx, NEST replaces a range of analog recording devices, such as +voltmeter, conductancemeter and aeif\_w\_meter with a universal *multimeter*, +which can record all analog quantities a model neuron makes available for +recording. +Multimeter works essentially as the old-style voltmeter, but with a few changes: + +- The `/recordables` list of a neuron model will tell you which quantities + can be recorded: + + In [3]: nest.GetDefaults('iaf_cond_alpha')['recordables'] + Out[3]: ['V_m', 'g_ex', 'g_in', 't_ref_remaining'] + + +- You have to configure multimeter to record from a set of quantities: + + nest.Create('multimeter', params={'record_from': ['V_m', 'g_ex']}) + + +- By default, the recording interval is 1ms, but you can change this + + nest.Create('multimeter', params={'record_from': ['V_m', 'g_ex'], 'interval' :0.1}) + +- The set of variables to record and the recording interval must be set + **before** the multimeter is connected to any node, and cannot be changed + afterwards. + +- After one has simulated a little, the `events` entry of the multimeter + status dictionary will contain one numpy array of data for each recordable. + +- Any node can only be recorded from by one multimeter. + +Adapting scripts using voltmeter +-------------------------------- + +Many NEST users have scripts that use voltmeter to record membrane potential. +To ease the transition to the new-style analog recording, NEST still provides a +device called `voltmeter`. It is simply a multimeter pre-configured to record +the membrane potential `V_m`. It can be used exactly as the old voltmeter. +The only change you need to make to your scripts is that you collect data from +events/V\_m instead of from events/potentials, e.g. + + In [24]: nest.GetStatus(m, 'events')[0]['V_m'] + + Out[24]: + array([-70. , -70. , -70. , -70. , + -70. , -70. , -70. , -70. , + +An example +---------- + +As an example, here is the multimeter.py example from the PyNEST examples set: + + import nest + import numpy as np + import pylab as pl + + # display recordables for illustration + print 'iaf_cond_alpha recordables: ', nest.GetDefaults('iaf_cond_alpha')['recordables'] + + # create neuron and multimeter + n = nest.Create('iaf_cond_alpha', params = {'tau_syn_ex': 1.0, 'V_reset': -70.0}) + + m = nest.Create('multimeter', params = {'withtime': True, 'interval': 0.1, 'record_from': ['V_m', 'g_ex', 'g_in']}) + + # Create spike generators and connect + gex = nest.Create('spike_generator', params = {'spike_times': np.array([10.0, 20.0, 50.0])}) + gin = nest.Create('spike_generator', params = {'spike_times': np.array([15.0, 25.0, 55.0])}) + + nest.Connect(gex, n, params={'weight': 40.0}) # excitatory + nest.Connect(gin, n, params={'weight': -20.0}) # inhibitory + nest.Connect(m, n) + + # simulate + nest.Simulate(100) + + # obtain and display data + events = nest.GetStatus(m)[0]['events'] + t = events['times']; + + pl.subplot(211) + pl.plot(t, events['V_m']) + pl.axis([0, 100, -75, -53]) + pl.ylabel('Membrane potential [mV]') + + pl.subplot(212) + pl.plot(t, events['g_ex'], t, events['g_in']) + pl.axis([0, 100, 0, 45]) + pl.xlabel('Time [ms]') + pl.ylabel('Synaptic conductance [nS]') + pl.legend(('g_exc', 'g_inh')) + +Here is the result: + +![MultimeterExample](../../img/MultimeterExample.png) diff --git a/extras/userdoc/md/documentation/connection-management.md b/extras/userdoc/md/documentation/connection-management.md new file mode 100644 index 0000000000..e0af02a6b3 --- /dev/null +++ b/extras/userdoc/md/documentation/connection-management.md @@ -0,0 +1,603 @@ +Connection Management +===================== + +From NEST 2.4 onwards the old connection routines (i.e. +`(Random)ConvergentConnect`, `(Random)DivergentConnect` and plain `Connect`) are +replaced by one unified `Connect` function. In +[SLI](an-introduction-to-sli.md "An Introduction to SLI") +,the old syntax of the function still works, while in +[PyNEST](introduction-to-pynest.md "PyNEST"), the `Connect()` +function has been renamed to `OneToOneConnect()`. However, simple cases, which +are just creating one-to-one connections between two lists of nodes are still +working with the new command without the need to change the code. Note that the +topology-module is not effected by theses changes. The translation between the +old and the new connect routines is described in [Old Connection Routines](connection-management.md#Old-Connection-Routines). + +The connectivity pattern is defined inside the `Connect()` function under the +key 'rule'. The patterns available are described in +[Connection Rules](connection-management.md#Connection-Rules). In +addition the synapse model can be specified within the connect function and all +synaptic parameters can be randomly distributed. + +The `Connect()` function can be called in either of the following manners: + + Connect(pre, post) + Connect(pre, post, conn_spec) + Connect(pre, post, conn_spec, syn_spec) + +`pre` and `post` are lists of Global Ids defining the nodes of origin and +termination. + +`conn_spec` can either be a string containing the name of the connectivity rule +(default: 'all\_to\_all') or a dictionary specifying the rule and the +rule-specific parameters (e.g. 'indegree'), which must be given. + +In addition switches allowing self-connections ('autapses', default: True) and +multiple connections between pairs of neurons ('multapses', default: True) can +be contained in the dictionary. The validity of the switches is confined by the +Connect-call. Thus connecting the same set of neurons multiple times with the +switch 'multapses' set to False, one particular connection might be established +multiple times. The same applies to nodes being specified multiple times in the +source or target vector. Here 'multapses' set to False will result in one +potential connection between each occurring node pair. + +`syn_spec` defines the synapse type and its properties. It can be given as a +string defining the synapse model (default: 'static\_synapse') or as a +dictionary. By using the key-word variant (`Connect(pre, post, +syn_spec=syn_spec_dict)`), the conn\_spec can be omitted in the call to +connect and 'all\_to\_all' is assumed as the default. +The exact usage of the synapse dictionary is described in [Synapse Specification](connection-management.md#Synapse-Specification). + +Connection Rules +---------------- + +Connection rules are specified using the `conn_spec` parameter, which can be a +string naming a connection rule or a dictionary containing a rule specification. +Only connection rules requiring no parameters can be given as strings, for all +other rules, a dictionary specifying the rule and its parameters, such as in- +or out-degrees, is required. + +one-to-one +---------- + +The ith node in `pre` is connected to the ith node in +`post`. The node lists pre and post have to be of the same length. + +Example: + +![One\_to\_one](../../img/One_to_one.png) +one-to-one connections + + n = 10 + A = Create("iaf_neuron", n) + B = Create("spike_detector", n) + Connect(A, B, 'one_to_one') + +This rule can also take two Global IDs A and B instead of integer lists. A +shortcut is provided if only two nodes are connected with the parameters weight +and delay such that weight and delay can be given as third and fourth argument +to the Connect() function. + +Example: + + weight = 1.5 + delay = 0.5 + Connect(A[0], B[0], weight, delay) + +all-to-all +---------- + +![all-to-all connections](../../img/All_to_all.png) +all-to-all connections + +Each node in `pre` is connected to every node in `post`. Since 'all\_to\_all' is +the default, 'rule' doesn't need to specified. + +Example: + + n, m = 10, 12 + A = Create("iaf_neuron", n) + B = Create("iaf_neuron", m) + Connect(A, B) + +### fixed-indegree + +![fixed-indegree connections](../../img/Fixed_indegree.png) +fixed-indegree connections + +The nodes in `pre` are randomly connected with the nodes in `post` such that +each node in `post` has a fixed `indegree`. + +Example: + + n, m, N = 10, 12, 2 + A = Create("iaf_neuron", n) + B = Create("iaf_neuron", m) + conn_dict = {'rule': 'fixed_indegree', 'indegree': N} + Connect(A, B, conn_dict) + +#### fixed-outdegree + +![Fixed\_outdegree](../../img/Fixed_outdegree.png) +fixed-outdegree connections + +The nodes in `pre` are randomly connected with the nodes in `post` such that +each node in `pre` has a fixed `outdegree`. + +Example: + + n, m, N = 10, 12, 2 + A = Create("iaf_neuron", n) + B = Create("iaf_neuron", m) + conn_dict = {'rule': 'fixed_outdegree', 'outdegree': N} + Connect(A, B, conn_dict) + +#### fixed-total-number + +The nodes in `pre` are randomly connected with the nodes in `post` such that the +total number of connections equals `N`. + +Example: + + n, m, N = 10, 12, 30 + A = Create("iaf_neuron", n) + B = Create("iaf_neuron", m) + conn_dict = {'rule': 'fixed_total_number', 'N': N} + Connect(A, B, conn_dict) + +#### pairwise-bernoulli + +For each possible pair of nodes from `pre` and `post`, a connection is created +with probability `p`. + +Example: + + n, m, p = 10, 12, 0.2 + A = Create("iaf_neuron", n) + B = Create("iaf_neuron", m) + conn_dict = {'rule': 'pairwise_bernoulli', 'p': p} + Connect(A, B, conn_dict) + +### Synapse Specification + +The synapse properties can be given as a string or a dictionary. The string can +be the name of a pre-defined synapse which can be found in the synapsedict (see +[Synapse Types](connection-management.md#Synapse-Types)) or a +manually defined synapse via `CopyModel()`. + +Example: + + n = 10 + A = Create("iaf_neuron", n) + B = Create("iaf_neuron", n) + CopyModel("static_synapse","excitatory",{"weight":2.5, "delay":0.5}) + Connect(A, B, syn_spec="excitatory") + +Specifying the synapse properties in a dictionary allows for distributed +synaptic parameter. +In addition to the key 'model' the dictionary can contain specifications for +'weight', 'delay', 'receptor\_type' and parameters specific to the chosen +synapse model. The specification of all parameters is optional. Unspecified +parameters will use the default values determined by the current synapse model. +All parameters can be scalars, arrays or distributions (specified as +dictionaries). One synapse dictionary can contain an arbitrary combination of +parameter types, as long as they agree with the connection routine ('rule'). + +**Scalar** parameters must be given as floats except for the 'receptor\_type' +which has to be initialized as an integer. For more information on the receptor +type see [Receptor Types](connection-management.md#Synapse-Types) . + +Example: + + n = 10 + neuron_dict = {'tau_syn': [0.3, 1.5]} + A = Create("iaf_psc_exp_multisynapse", n, neuron_dict) + B = Create("iaf_psc_exp_multisynapse", n, neuron_dict) + syn_dict ={"model": "static_synapse", "weight":2.5, "delay":0.5, 'receptor_type': 1} + Connect(A, B, syn_spec=syn_dict) + +**Array** parameters can be used in conjunction with the rules 'one\_to\_one' +and 'all\_to\_all'. The arrays can be specified as numpy arrays or lists. As +for the scalar parameters, all parameters but the receptor types must be +specified as arrays of floats. For 'one\_to\_one' the array must have the same +length as the population vector. + +Example: + + A = Create("iaf_neuron", 2) + B = Create("spike_detector", 2) + conn_dict = {'rule': 'one_to_one'} + syn_dict = {'weight': [1.2, -3.5]} + Connect(A, B, conn_dict, syn_dict) + +When connecting using 'all\_to\_all', the array must be of dimension len(post) +x len(pre). + +Example: + + A = Create("iaf_neuron", 3) + B = Create("iaf_neuron", 2) + syn_dict = {'weight': [[1.2, -3.5, 2.5],[0.4, -0.2, 0.7]]} + Connect(A, B, syn_spec=syn_dict) + +**Distributed** parameters are initialized with yet another dictionary +specifying the 'distribution' and the distribution-specific parameters, whose +specification is optional. + +Available distributions are given in the rdevdict, the most common ones are: + +Distributions +Keys +'normal' +'mu', 'sigma' +'normal\_clipped' +'mu', 'sigma', 'low ', 'high' +'normal\_clipped\_to\_boundary' +'mu', 'sigma', 'low ', 'high' +'lognormal' +'mu', 'sigma' +'lognormal\_clipped' +'mu', 'sigma', 'low', 'high' +'lognormal\_clipped\_to\_boundary' +'mu', 'sigma', 'low', 'high' +'uniform' +'low', 'high' +'uniform\_int' +'low', 'high' +'binomial' +'n', 'p' +'binomial\_clipped' +'n', 'p', 'low', 'high' +'binomial\_clipped\_to\_boundary' +'n', 'p', 'low', 'high' +'gsl\_binomial' +'n', 'p' +'exponential' +'lambda' +'exponential\_clipped' +'lambda', 'low', 'high' +'exponential\_clipped\_to\_boundary' +'lambda', 'low', 'high' +'gamma' +'order', 'scale' +'gamma\_clipped' +'order', 'scale', 'low', 'high' +'gamma\_clipped\_to\_boundary' +'order', 'scale', 'low', 'high' +'poisson' +'lambda' +'poisson\_clipped' +'lambda', 'low', 'high' +'poisson\_clipped\_to\_boundary' +'lambda', 'low', 'high' +Example: + + n = 10 + A = Create("iaf_neuron", n) + B = Create("iaf_neuron", n) + syn_dict = {'model': 'stdp_synapse', + 'weight': 2.5, + 'delay': {'distribution': 'uniform', 'low': 0.8, 'high': 2.5}, + 'alpha': {'distribution': 'normal_clipped', 'low': 0.5, 'mu': 5.0, 'sigma': 1.0} + } + Connect(A, B, syn_spec=syn_dict) + +In this example, the 'all\_to\_all' connection rule is applied by default, using +the 'stdp\_synapse' model. All synapses are created with weight 2.5, a delay +uniformly distributed in [0.8, 2.5), while the alpha parameters is drawn from a +normal distribution with mean 5.0 and std.dev 1.0; values below 0.5 are excluded +by re-drawing any values below 0.5. Thus, the actual distribution is a slightly +distorted Gaussian. + +If the synapse is supposed to have a unique name and distributed parameters it +needs to be defined in two steps: + + n = 10 + A = Create("iaf_neuron", n) + B = Create("iaf_neuron", n) + CopyModel('static_synapse','excitatory',{'weight':2.5}) + syn_dict = {'model': 'excitatory', + 'weight': 2.5, + 'delay': {'distribution': 'uniform', 'low': 0.8, 'high': 2.5}, + 'alpha': {'distribution': 'normal_clipped', 'low': 0.5, 'mu': 5.0, 'sigma': 1.0} + } + Connect(A, B, syn_spec=syn_dict) + +For further information on the distributions see +[Random numbers in NEST](random-numbers.md "Random numbers in NEST"). + +Old Connection Routines +----------------------- + +The old connection routines are still available in NEST 2.4, apart from the old +`Connect()` which has been renamed to `OneToOneConnect()` and whose the support +will end with the next release. + +This section contains the documentation for the old connection routines and +provides a manual on how to convert the old connection routines to the new +`Connect()` function. +The new connection routine doesn't yet support arrays or lists as input +parameter other than `pre` and `post`. As a workaround we suggest to loop over +the arrays. + +### One-to-one connections + +![](../../img/One_to_one.png) +one-to-one connections + +`Connect(pre, post, params=None, delay=None, model='static_synapse')`: Make +one-to-one connections of type *model* between the nodes in *pre* and the nodes +in *post*. *pre* and *post* have to be lists of the same length. If *params* is +given (as dictionary or list of dictionaries), they are used as parameters for +the connections. If *params* is given as a single float or as list of floats, +it is used as weight(s), in which case *delay* also has to be given as float or +as list of floats. + +Example old connection routine: + + A = Create("iaf_neuron", 2) + B = Create("spike_detector", 2) + weight = [1.2, -3.5] + delay = [0.3, 0.5] + Connect(A, B, weight, delay) + +**Note:** Using `Connect()` with any of the variables `params`, `delay` and +`model` will break the code. As a temporary fix the function `OnToOneConnect()` +is provided which works in the same manner as the previous `Connect()`. However, +`OneToOneConnect()` won't be supported in the next release. + +Example temporary fix for old connection routine: + + A = Create("iaf_neuron", 2) + B = Create("spike_detector", 2) + weight = [1.2, -3.5] + delay = [0.3, 0.5] + OneToOneConnect(A, B, weight, delay) + +Example new connection routine: + + A = Create("iaf_neuron", 2) + B = Create("spike_detector", 2) + conn_dict = {'rule': 'one_to_one'} + syn_dict = {'weight': weight, 'delay', delay} + Connect(A, B, conn_dict, syn_dict) + +### Convergent connections + +![convergent connections](../../img/Convergent_connect.png) +convergent connections + +`ConvergentConnect(pre, post, weight=None, delay=None, model='static_synapse')`: +Connect all neurons in *pre* to each neuron in *post*. *pre* and *post* have to +be lists. If *weight* is given (as a single float or as list of floats), *delay* +also has to be given as float or as list of floats. + +Example old connection routine: + + A = Create("iaf_neuron", 2) + B = Create("spike_detector") + ConvergentConnect(A, B) + +Example new connection routine: + + A = Create("iaf_neuron", 2) + B = Create("spike_detector") + Connect(A, B) + +`RandomConvergentConnect(pre, post, n, weight=None, delay=None, +model='static_synapse')`: Connect *n* randomly selected neurons from *pre* to +each neuron in *post*. *pre* and *post* have to be lists. If *weight* is given +(as a single float or as list of floats), *delay* also has to be given as float +or as list of floats. + +Example old connection routine: + + option_dict = {'allow_autapses': True, 'allow_multapses': True} + model = 'my_synapse' + nest.RandomConvergentConnect(A, B, N, w0, d0, model, option_dict) + +Example new connection routine: + + conn_dict = {'rule': 'fixed_indegree', 'indegree': N, 'autapses': True, 'multapses': True} + syn_dict = {'model': 'my_synapse', 'weight': w0, 'delay': d0} + nest.Connect(A, B, conn_dict, syn_dict) + +### Divergent connections + +![Divergent\_connect](../../img/Divergent_connect.png) +divergent connections + +`DivergentConnect(pre, post, weight=None, delay=None, model='static_synapse')`: +Connect each neuron in *pre* to all neurons in *post*. *pre* and *post* have to +be lists. If *weight* is given (as a single float or as list of floats), *delay* +also has to be given as float or as list of floats. + +Example old connection routine: + + A = Create("iaf_neuron") + B = Create("spike_detector", 2) + DivergentConnect(A, B) + +Example new connection routine: + + A = Create("iaf_neuron") + B = Create("spike_detector", 2) + Connect(A, B) + +`RandomDivergentConnect(pre, post, n, weight=None, delay=None, +model='static_synapse')`: Connect each neuron in *pre* to *n* randomly selected +neurons from *post*. *pre* and *post* have to be lists. If *weight* is given (as +a single float or as list of floats), *delay* also has to be given as float or +as list of floats. + +Example old connection routine: + + option_dict = {'allow_autapses': True, 'allow_multapses': True} + model = 'my_synapse' + nest.RandomDivergentConnect(A, B, N, w0, d0, model, option_dict) + +Example new connection routine: + + conn_dict = {'rule': 'fixed_outdegree', 'outdegree': N, 'autapses': True, 'multapses': True} + syn_dict = {'model': 'my_synapse', 'weight': w0, 'delay': w0} + nest.Connect(A, B, conn_dict, syn_dict) + +Topological Connections +----------------------- + +If the connect functions above are not sufficient, the topology provides more +sophisticated functions. For example, it is possible to create receptive field +structures and much more! See +[Topological Connections](Topology_UserManual.pdf) +for more information. + +Receptor Types +-------------- + +Each connection in NEST targets a specific receptor type on the post-synaptic +node. Receptor types are identified by integer numbers, the default receptor +type is 0. The meaning of the receptor type depends on the model and is +documented in the model documentation. To connect to a non-standard receptor +type, the parameter *receptor\_type* of the additional argument *params* is used +in the call to the `Connect` command. To illustrate the concept of receptor +types, we give an example using standard integrate-and-fire neurons as +presynaptic nodes and a multi-compartment integrate-and-fire neuron +(`iaf_cond_alpha_mc`) as post-synaptic node. + +![Receptor types](../../img/Receptor_types.png) +Receptor types + + A1, A2, A3, A4 = Create("iaf_neuron", 4) + B = Create("iaf_cond_alpha_mc") + receptors = GetDefaults("iaf_cond_alpha_mc")["receptor_types"] + print receptors + + {'soma_exc': 1, + 'soma_inh': 2, + 'soma_curr': 7, + 'proximal_exc': 3 + 'proximal_inh': 4, + 'proximal_curr': 8, + 'distal_exc': 5, + 'distal_inh': 6, + 'distal_curr': 9,} + + Connect([A1], B, syn_spec={"receptor_type": receptors["distal_inh"]}) + Connect([A2], B, syn_spec={"receptor_type": receptors["proximal_inh"]}) + Connect([A3], B, syn_spec={"receptor_type": receptors["proximal_exc"]}) + Connect([A4], B, syn_spec={"receptor_type": receptors["soma_inh"]}) + +The code block above connects a standard integrate-and-fire neuron to a somatic +excitatory receptor of a multi-compartment integrate-and-fire neuron model. The +result is illustrated in the figure. + +Synapse Types +------------- + +NEST supports multiple synapse types that are specified during connection setup. +The default synapse type in NEST is `static_synapse`. Its weight does not change +over time. To allow learning and plasticity, it is possible to use other synapse +types that implement long-term or short-term plasticity. A list of available +types is accessible via the command *Models("synapses")*. The output of this +command (as of revision 11199) is shown below: + + ['cont_delay_synapse', + 'ht_synapse', + 'quantal_stp_synapse', + 'static_synapse', + 'static_synapse_hom_wd', + 'stdp_dopamine_synapse', + 'stdp_facetshw_synapse_hom', + 'stdp_pl_synapse_hom', + 'stdp_synapse', + 'stdp_synapse_hom', + 'tsodyks2_synapse', + 'tsodyks_synapse'] + +All synapses store their parameters on a per-connection basis. An exception to +this scheme are the homogeneous synapse types (identified by the suffix +*\_hom*), which only store weight and delay once for all synapses of a type. +This means that these are the same for all connections. They can be used to +save memory. + +The default values of a synapse type can be inspected using the command +`GetDefaults()`, which takes the name of the synapse as an argument, and +modified with `SetDefaults()`, which takes the name of the synapse type and a +parameter dictionary as arguments. + + print GetDefaults("static_synapse") + + {'delay': 1.0, + 'max_delay': -inf, + 'min_delay': inf, + 'num_connections': 0, + 'num_connectors': 0, + 'receptor_type': 0, + 'synapsemodel': 'static_synapse', + 'weight': 1.0} + + SetDefaults("static_synapse", {"weight": 2.5}) + +For the creation of custom synapse types from already existing synapse types, +the command `CopyModel` is used. It has an optional argument `params` to +directly customize it during the copy operation. Otherwise the defaults of the +copied model are taken. + + CopyModel("static_synapse", "inhibitory", {"weight": -2.5}) + Connect(A, B, syn_spec="inhibitory") + +**Note**: Not all nodes can be connected via all available synapse types. The +events a synapse type is able to transmit is documented in the *Transmits* +section of the model documentation. + +Inspecting Connections +---------------------- + +`GetConnections(source=None, target=None, synapse_model=None)`: Return an array +of identifiers for connections that match the given parameters. source and +target need to be lists of global ids, model is a string representing a synapse +model. If GetConnections is called without parameters, all connections in the +network are returned. If a list of source neurons is given, only connections +from these pre-synaptic neurons are returned. If a list of target neurons is +given, only connections to these post-synaptic neurons are returned. If a +synapse model is given, only connections with this synapse type are returned. +Any combination of source, target and model parameters is permitted. Each +connection id is a 5-tuple or, if available, a NumPy array with the following +five entries: source-gid, target-gid, target-thread, synapse-id, port. + +The result of `GetConnections` can be given as an argument to the `GetStatus` +function, which will then return a list with the parameters of the connections: + + n1 = Create("iaf_neuron") + n2 = Create("iaf_neuron") + Connect(n1, n2) + conn = GetConnections(n1) + print GetStatus(conn) + + [{'synapse_type': 'static_synapse', + 'target': 2, + 'weight': 1.0, + 'delay': 1.0, + 'source': 1, + 'receptor': 0}] + +Modifying existing Connections +------------------------------ + +To modify the connections of an existing connection, one also has to obtain +handles to the connections with `GetConnections()` first. These can then be +given as arguments to the `SetStatus()` functions: + + n1 = Create("iaf_neuron") + n2 = Create("iaf_neuron") + Connect(n1, n2) + conn = GetConnections(n1) + SetStatus(conn, {"weight": 2.0}) + print GetStatus(conn) + + [{'synapse_type': 'static_synapse', + 'target': 2, + 'weight': 2.0, + 'delay': 1.0, + 'source': 1, + 'receptor': 0}] diff --git a/extras/userdoc/md/documentation/continuous-integration.md b/extras/userdoc/md/documentation/continuous-integration.md new file mode 100644 index 0000000000..36c0353902 --- /dev/null +++ b/extras/userdoc/md/documentation/continuous-integration.md @@ -0,0 +1,129 @@ +Continuous Integration +====================== + +Introduction +------------ + +[**Continuous Integration**](http://en.wikipedia.org/wiki/Continuous_integration) (CI) +is a software development practice where quality control is continuously +applied to the product as opposed to the traditional procedure of +applying quality control *after* completing all development (during the +so called *integration phase*). In essence, it is a way of decreasing +the risks associated with the integration by spreading required efforts +over time, which helps to improve on the quality of software, and to +reduce the time taken to deliver it. + +Stringent quality control is particularly important in the context of +NEST, a neuronal network simulator with the emphasis on correctness, +reproducibility and performance. However, given the limited amount of +the available resources, it is wasteful to transfer the responsibility +to re-run the test suite for all target platforms on every single code +base change to the shoulders of the developers. + +In order to address this problem, a +[Jenkins](http://jenkins-ci.org/)-based CI infrastructure was created +during the [NEST Google Summer of Code +2011](http://www.google-melange.com/gsoc/project/google/gsoc2011/zaytsev/17001) +project, which would allow for regular testing of changes that are +getting into the tree and timely reporting of identified problems. This +way, issues will be discovered earlier and the amount of efforts to fix +them will be significantly decreased (hopefully). + +Continuous Integration at NEST Initiative +-------------------------------------------------------------------------------------------------------------------------- + +The current CI implementation is now available at the following URL: + + +The site is secured with a Class 1 SSL certificate issued by StartCom +Ltd. + +### Build jobs + +The CI system is set up to regularly poll the version control repository +hosting the main official NEST source tree. Whenever changes are +detected, the latest source code is downloaded to a build executor +machine and the following actions are performed: + +- Bootstrap the build system +- Build and install NEST +- Run the test suite +- Bootstrap MyModule +- Build and install MyModule + +If any of these steps fails (returns a non-zero exit code), the build is +marked as failed and a notification is sent to the developers mailing +list. + +Additionally, a number of metrics are collected from the build log to +obtain a cumulative project "health" indicators: + +- Build status: + + - *Success* (all steps completed successfully) + + - *Unstable* (some publishers reported non-fatal errors, e.g. + there were failed tests) + + - *Failed* (a fatal error happened during the build, e.g. non-zero + exit code was returned) + +- Weather report (how many failures there were out of 5 latest builds) + +- Test suite report (all JUnit-compatible reports are aggregated) + +- Compiler warnings report (all GCC4 / LD warnings are aggregated) + +The values of these indicators are archived along with the build logs +and trends can be graphed for arbitrary periods of time. + +### User registration + +NEST developers, using the system as registered users enjoy a number of +benefits as compared to the anonymous users. Most notably they may: + +- Access projects workspace on the build executors +- Schedule / remove / edit builds manually +- Be granted personal build jobs for their branches +- Be allowed to create jobs (to be discussed) + +Project workspace access allows one to view the source code and build +directories / logs as they are on the build executor machines, which can +be helpful in diagnosing build problems. + +If you'd like to register with the system, please contact the +administrators! + +### Technical details + +The infrastructure resides on a Dell PowerEdge R710 server hosted in a +private BCF rack at Uni Freiburg running KVM hypervisor which controls +virtual machines that host Jenkins and build executors. + +The repositories hosting the up to date versions of the configuration +([*anubis-puppet*](http://git.zaytsev.net/?p=anubis-puppet.git;a=summary)) +and documentation +([*anubis-docs*](http://git.zaytsev.net/?p=anubis-docs.git;a=summary)) +are available online. Please refer to these repositories for more +detailed documentation regarding the setup, which is out of the scope of +this brief user manual. + +### Administrators + +At the moment, the following NEST developers have administrative access +to the build system: + +- Yury V. Zaytsev + +Further reading +--------------- + +- [Martin Fowler's paper on Continuous + Integration](http://martinfowler.com/articles/continuousIntegration.html) + +- [Continuous Integration vs Continuous Delivery vs Continuous + Deployment: what is the + difference?](http://www.itwriting.com/blog/4797-continuous-integration-vs-continuous-delivery-vs-continuous-deployment-what-is-the-difference.html) + +- [8 Principles of Continuous + Delivery](http://java.dzone.com/articles/8-principles-continuous) diff --git a/extras/userdoc/md/documentation/documentation.md b/extras/userdoc/md/documentation/documentation.md index a75ac13a09..eb21f17e10 100644 --- a/extras/userdoc/md/documentation/documentation.md +++ b/extras/userdoc/md/documentation/documentation.md @@ -10,16 +10,16 @@ Documentation NEST User Manual --------------------------------------------------------------------------- -- [Frequently Asked Questions](frequently_asked_questions.md "Frequently Asked Questions") -- [Analog recording with multimeter](analog_recording_with_multimeter.md "Analog recording with multimeter") -- [Connection Management](connection_management.md "Connection Management") +- [Frequently Asked Questions](frequently-asked-questions.md "Frequently Asked Questions") +- [Analog recording with multimeter](analog-recording-with-multimeter.md "Analog recording with multimeter") +- [Connection Management](connection-management.md "Connection Management") - [Topological Connections](wp-content/uploads/2015/04/Topology_UserManual.pdf "Topological Connections") -- [Random numbers in NEST](random_numbers.md "Random numbers in NEST") -- [Parallel Computing](parallel_computing.md "Parallel Computing") +- [Random numbers in NEST](random-numbers.md "Random numbers in NEST") +- [Parallel Computing](parallel-computing.md "Parallel Computing") - [Scheduling and simulation flow](scheduling-and-simulation-flow.md) - [Simulations with precise spike times](simulations-with-precise-spike-times.md) -- [Using NEST with MUSIC](using_nest_with_music.md "Using NEST with MUSIC") -- [Using NEST with the SLI interpreter](an_introduction_to_sli.md "An Introduction to SLI") +- [Using NEST with MUSIC](using-nest-with-music.md "Using NEST with MUSIC") +- [Using NEST with the SLI interpreter](an-introduction-to-sli.md "An Introduction to SLI") - [NEST/SLI Quick Reference](quickref.md) - [NEST Command Index](helpindex.md) diff --git a/extras/userdoc/md/documentation/download.md b/extras/userdoc/md/documentation/download.md index b02a64d17b..f0ff1673bc 100644 --- a/extras/userdoc/md/documentation/download.md +++ b/extras/userdoc/md/documentation/download.md @@ -1,7 +1,7 @@ Download & Releases =================== -NEST is available under the [GNU General Public License 2 or later](license/index.html "License"). +NEST is available under the [GNU General Public License 2 or later](license.md "License"). This means that you can - use NEST for your research, diff --git a/extras/userdoc/md/documentation/features.md b/extras/userdoc/md/documentation/features.md index 33338ad557..0242237873 100644 --- a/extras/userdoc/md/documentation/features.md +++ b/extras/userdoc/md/documentation/features.md @@ -5,7 +5,7 @@ General ------------------------------------------------------ - Python based user interface ([PyNEST](introduction-to-pynest.md )) -- Built-in simulation language interpreter ([SLI](an_introduction_to_sli.md "An Introduction to SLI")) +- Built-in simulation language interpreter ([SLI](an-introduction-to-sli.md "An Introduction to SLI")) - Multi-threading to use multi-processor machines efficiently - MPI-parallelism to use computer clusters and super computers @@ -43,7 +43,7 @@ Network models Interoperability ---------------- -- Interface to the Multi Simulator Coordinator [MUSIC](using_nest_with_music.md "Using NEST with MUSIC") +- Interface to the Multi Simulator Coordinator [MUSIC](using-nest-with-music.md "Using NEST with MUSIC") - Backend for the simulator-independent modeling tool [PyNN](http://neuralensemble.org/trac/PyNN/) Accuracy @@ -66,7 +66,7 @@ Verification - After installation NEST can be verified by an automatic testsuite - The testsuite is automatically run after each modification of the NEST - sources. You can watch the current status on our [Continuous Integration](continuous_integration.md "Continuous Integration") system. + sources. You can watch the current status on our [Continuous Integration](continuous-integration.md "Continuous Integration") system. Supported platforms ------------------- diff --git a/extras/userdoc/md/documentation/first-steps.md b/extras/userdoc/md/documentation/first-steps.md new file mode 100644 index 0000000000..5e8266c586 --- /dev/null +++ b/extras/userdoc/md/documentation/first-steps.md @@ -0,0 +1,169 @@ +First Steps +=========== + +Overview +-------- + +SLI is the simulation language interface of NEST. It is a stack language where +each command expects to find its arguments on the stack. + +A stack is a place where data can be stored. The stack is + organized into levels and the data can be thought of being on top + of each other. As new data is entered, it is placed on the +*top* of the stack. If a piece of data is removed or + manipulated, this is usually done to the top level of the stack. + The levels of the stack are numbered from zero onwards. Level zero + corresponds to the top of the stack. + +Initially the stack is empty. In general, you enter data onto the + stack and then execute commands to manipulate the data. + +Each command expects to find its arguments on the stack. When a + SLI command is executed, it usually removes all arguments from + the stack and pushes one or more results back on the stack. + The basic concepts of stack operation are: + +- Commands that require *arguments* take their arguments from the stack. Thus, + this data must be present before you execute the command. + +- The arguments are then removed by the command as it is executed. + +- Any results which are produced by the command are returned to the stack, so + you can use them in other operations. + +Commands with one argument +-------------------------- + +Commands which need one argument take their argument from the top + of the stack. If the command produces a result, it is placed on + top of the stack, after the argument has been removed. Thus, the + argument is replaced by the result: + +### Example + + SLI ] 10 log = + 1 + +Here, the command `log` is used to compute the decadic logarithm of 10. Then, +the command `=` is used to display the result of this computation. + +Commands with more arguments +---------------------------- + +Commands which need more than one argument, take their arguments from level 0, +1, 2, and so forth and return their result to level 0, the top of the stack. +Examples are the arithmetic functions `add`, `sub`, `mul`, and `div`, which +take two arguments and return one result. + + SLI ] 1 2 add = + 3 + SLI ] 1 2. div = + 0.5 + +So far, we have used the command `=` to display the top object on the stack. In +addition, this command removes the object. You can also list the contents of the +stack without changing it. + + SLI ] 1 2 + SLI [2] stack + 2 + 1 + SLI [2] add + SLI [1] stack + 3 + SLI [1] + +Using previous results +---------------------- + +Chain calculations are calculations which involve more than one operation. A +stack is particularly useful for chaining operations,because it retains +intermediate results. + +This example shows, how the stack can be used for chain calculations. Calculate +(10+13) \\(cdot\\) (8-12) + + SLI [1] 10 13 add 8 12 sub + SLI [2] stack + -4 + 23 + SLI [2] mul = + -92 + +Notice that the results of the fist two operations remain on the stack, until +they are used in the multiplication. + +Exchanging the first two stack levels +------------------------------------- + +The command `exch` exchanges the contents of the levels 0 and 1. This is useful, +if the order of objects on the stack does not match the order required by the +desired command. + +### Example 1 + +Calculate 1/ln(2). + + SLI ] 2 ln + SLI [1] 1 + SLI [2] exch div + SLI [1] = + 1.4427 + +Removing stack elements +----------------------- + +The command `pop` removes the top object (level 0) of the stack. The remaining +items move up on the stack, so that the object which was at level 1 is now at +level 0. + +The command `clear` clears the entire stack. + +Duplicating the top element +--------------------------- + +The command `dup` duplicates the contents of the object at +level 0 and pushes the other element down one level. +This command is useful if the result of an operation is needed +more than once in a chain calculation. + +### Example 2 + +Calculate (1+4/2) + exp(1+4/2) + + SLI ] 1 4 2.0 div add + SLI [1] dup + SLI [2] exp + SLI [2] add + SLI [1] = + 23.0855 + +Important stack commands +------------------------ + +Command +Description +`=` +Print the object at level 0. +`==` +Print the object at level 0 in syntax form. +`count` +Count the number of objects on the stack. +`patsck` +Display the stack in syntax form. +`stack` +Display the stack. +`pop`, `;` +Pop object from stack. +`npop` +Pop `n` objects from stack. +`dup` +Duplicate top object of stack. +`copy` +Copy the first n objects of the stack. +`index` +Copy the `n`'th object of the stack. +`roll` +Roll a portion of `n` stack levels `k` times. +`exec` +Execute the top element on the stack. diff --git a/extras/userdoc/md/documentation/frequently-asked-questions.md b/extras/userdoc/md/documentation/frequently-asked-questions.md new file mode 100644 index 0000000000..5a2da4f051 --- /dev/null +++ b/extras/userdoc/md/documentation/frequently-asked-questions.md @@ -0,0 +1,78 @@ +Frequently Asked Questions +========================== + +Installation +------------ + +1. **If I compile NEST with MPI support, I get errors about `SEEK_SET`, + `SEEK_CUR` and `SEEK_END` being defined** This is a known issue in some MPI + implementations. A solution is to add + --with-debug="-DMPICH\_IGNORE\_CXX\_SEEK" + to the configure command line. + More details about this problem can be found [here](http://www-unix.mcs.anl.gov/mpi/mpich/faq.htm#cxxseek) + +2. **Configure warns that Makefile.in seems to ignore the --datarootdir setting + and the installation fails because of permission errors** + This problem is due to a change in autoconf 2.60, where the prefix + directory for the NEST documentation can end up being empty during the + installation. This leads to wrong installation paths for some components of + NEST. If you have the GNU autotools installed, you can run `./bootstrap.sh` + in the source directory followed by `./configure`. If you don't have the + autotools, appending `--datadir=PREFIX/share/nest` with the same PREFIX as + in the `--prefix` option should help. + +3. **I get 'Error: /ArgumentType in validate' when compiling an extension** + This is a known bug that has been fixed. Ask your local NEST dealer for a + new pre-release. You need at least nest-1.9-7320. + +4. **I get 'collect2: ld returned 1 exit status, ld: -rpath can only be used + when targeting Mac OS X 10.5 or later** + Please try to set the environment variable MACOSX\_DEPLOYMENT\_TARGET to + 10.5 (export MACOSX\_DEPLOYMENT\_TARGET=10.5) + +5. **Ipython crashes with a strange error message as soon as I import `nest`** + If ipython crashes on `import nest` complaining about a + `Non-aligned pointer being freed`, you probably compiled NEST with a + different version of g++ than python. Take a look at the information + ipython prints when it starts up. That should tell you which compiler was + used. Then re-build NEST with the same compiler version. + +6. **I get a segmentation fault wher I use SciPy in the same script together + with PyNEST**. We recently observed that if PyNEST is used with some + versions of SciPy, a segmentation fault is caused. A workaround for the + problem is to import SciPy before PyNEST. See + for the official bug report in NumPy. + +Neuron models +------------- + +1. **I cannot see any of the conductance based models. Where are they?** + Some neuron model need the GNU Scientific Library (GSL) to work. The + conductance based models are among those. If your NEST installation does + not have these models, you probably have no GSL or GSL development packages + installed. To solve this problem, install the GSL and its development + headers. Then reconfigure and recompile NEST. + +Connections +----------- + +1. **How can I create connections to multicompartment neurons?** + You need to create a synapse type with the proper receptor\_type as in this + example, which connects all 100 neurons in n to the first neuron in n: + + syns = nest.GetDefaults('iaf_cond_alpha_mc')['receptor_types'] + nest.CopyModel('static_synapse', 'exc_dist_syn', {'receptor_type': syns['distal_exc']}) + n = nest.Create('iaf_cond_alpha_mc', 100) + nest.Connect(n, n[:1], sync_spec={'model'='exc_dist_syn'}) + nest.Simulate(10) + +Physical units in nest +---------------------- + +- time - ms +- voltage - mV +- capacitance - pF +- current - pA +- conductance - nS +- Spike rates in (eg poisson\_generator) - spikes/s +- modulation frequencies (eg ac\_generator) - Hz diff --git a/extras/userdoc/md/documentation/getting-started.md b/extras/userdoc/md/documentation/getting-started.md new file mode 100644 index 0000000000..908225c6e9 --- /dev/null +++ b/extras/userdoc/md/documentation/getting-started.md @@ -0,0 +1,53 @@ +Getting started +=============== + +[Documentation](documentation.md "Documentation") +This page contains the steps that you should follow right after you +[installed NEST](installation.md "Installation"). Another good +starting point is the help page, which is available as command `help` in SLI and +`nest.help()` in PyNEST + +Set up the integrated helpdesk +------------------------------ + +The command `helpdesk` needs to know which browser to launch in order to display +the help pages. The browser is set as an option of `helpdesk`. Please see the +file `~/.nestrc` for an example setting `firefox` as browser. Please note that +the command `helpdesk` does not work if you have compiled NEST with MPI support, +but you have to enter the address of the helpdesk +(`file://$PREFIX/share/doc/nest(`) manually into the browser. Please +replace `$PREFIX` with the prefix you chose during the configuration of NEST. +If you did not explicitly specify one, it is most likely set to `/usr` or +`/usr/local` depending on what system you are. + +Tell NEST about your MPI setup +------------------------------ + +If you compiled NEST with support for distributed computing via MPI, you have to + tell it how your `mpirun`/`mpiexec` command works by defining the function + mpirun in your `~/.nestrc` file. This file already contains an example + implementation that should work with [OpenMPI](http://www.openmpi.org) library. + +Creating Models with NEST +------------------------- + +After NEST is installed and configured properly, you can start to build your +model. + +### Examples + +A good starting point to learn more about modeling in NEST are the +[example networks](more-example-networks.md "Example networks") +that come together with NEST. + +### Where does data get stored + +By default, the data files produced by NEST are stored in the directory from +where NEST is called. The location can be changed by changing the property +`data_path` of the root node using +`nest.SetKernelStatus("data_path", "/path/to/data")`. This property can also be +set using the environment variable `NEST_DATA_PATH`. Please note that the +directory `/path/to/data` has to exist. A common prefix for all data files can +be set using the property `data_prefix` of the root node by calling +`nest.SetKernelStatus("data_prefix", "prefix")` or setting the environment +variable `NEST_DATA_PREFIX`. diff --git a/extras/userdoc/md/documentation/index.md b/extras/userdoc/md/documentation/index.md index 3a2a24b459..8625525bd1 100644 --- a/extras/userdoc/md/documentation/index.md +++ b/extras/userdoc/md/documentation/index.md @@ -117,7 +117,7 @@ To learn more about the capabilities of NEST, see the [Feature summary](features 8. NEST has minimal dependencies. All it really needs is a C++ compiler. Everything else is optional. -9. NEST developers are using agile [continuous integration](continuous_integration.md "Continuous Integration")-based +9. NEST developers are using agile [continuous integration](continuous-integration.md "Continuous Integration")-based workflows in order to maintain high code quality standards for correct and reproducible simulations. diff --git a/extras/userdoc/md/documentation/installation.md b/extras/userdoc/md/documentation/installation.md index fc6e043cda..61f8f29b2a 100644 --- a/extras/userdoc/md/documentation/installation.md +++ b/extras/userdoc/md/documentation/installation.md @@ -27,7 +27,7 @@ Following are the basic steps to compile and install NEST from source code: 7. Install by running `make install` -8. See the [Getting started](getting_started.md "Getting started") pages to +8. See the [Getting started](getting-started.md "Getting started") pages to find out how to get going with NEST Please see the sections on [minimal](installation.md#Minimal_configuration) and @@ -192,7 +192,7 @@ the help pages. The browser is set as an option of `helpdesk`. Please see the file `~/.nestrc` for an example setting `firefox` as browser. Please note that the command `helpdesk` does not work if you have compiled NEST with MPI support, but you have to enter the address of the helpdesk -(`file://$PREFIX/share/doc/nest/index.html`) manually into the browser. +(`file://$PREFIX/share/doc/nest.md`) manually into the browser. Please replace `$PREFIX` with the prefix you chose during the configuration of NEST. If you did not explicitly specify one, it is most likely set to `/usr` or `/usr/local` depending on what system you are. diff --git a/extras/userdoc/md/documentation/neural-simulations.md b/extras/userdoc/md/documentation/neural-simulations.md new file mode 100644 index 0000000000..30f5af7f5a --- /dev/null +++ b/extras/userdoc/md/documentation/neural-simulations.md @@ -0,0 +1,466 @@ +Neural simulations +================== + +Overview +--------- + +A simulation of a network is like an experiment with the difference that it +takes place inside the computer's memory rather than in the physical world. + +Like in a real experiment, you need a system which you want to investigate. +Moreover, you need a clear idea of *what* you want to learn from the experiment. +In the context of a network simulation this means that you have to know +*which input* you want to give to your network and *which output* you expect. + +The next section will illustrate the main concepts of NEST simulations, using a +simple simulation. The following sections will then give a step-by-step +introduction to the main concepts of NEST simulations. Finally, we will discuss +a complex example. + +A simple simulation +-------------------- + +The simplest simulation in NEST is that of a network which contains just one +neuron: + + SLI ] /iaf_neuron Create /neuron Set + +We are going to simulate a standard integrate and fire model with resting +potential at -70 mV and spike threshold at -55 mV. In this line, we use the +model `iaf_neuron` to create a neuron. The command `Create` returns a handle to +the created neuron, which we store in the variable `neuron`. + +Next, we would like to add a stimulation and a recording device to the neuron, +so that we will see something during the simulation. + +In our little example, we want to inject a current into the neuron and record +its membrane potential. Thus, we need to create the corresponding devices and +connect them to the neuron: + + SLI ] /voltmeter Create /vm Set + +This command creates a voltmeter node. The handle to the new voltmeter is stored +in the variable `vm`. + +By default, the voltmeter will only record membrane potential values, so we +configure it to show us the time stamp of each value as well. We also set it to +print the time and potential to the screen and we set the recording interval to +0.1 ms. The default is 1.0 ms. + + SLI ] vm << /withtime true /to_screen true /interval 0.1 >> SetStatus + +The double angled brackets ` << ` and ` >> `delimit a dictionary definition +which consists of successive `/key value ` pairs. + +After setting the parameters of the voltmeter, we connect it to the neuron, +using the handles we have created above: + + SLI ] vm neuron Connect + +Now we create a DC generator which will supply a constant current to our neuron: + + SLI ] /dc_generator Create /stim Set + +Next, we want to set the amplitude of the DC generator such that it delivers +enough current to elicit a spike in the neuron: + + SLI ] stim << /amplitude 600.0 >> SetStatus + +Here, we only adjust the strength of the input, we set its new value to `600.0`, +which is the amplitude in pA. + +We have to connect the DC generator to the neuron: + + SLI ] stim neuron Connect + +We can now run the simulation and expect to see some results: + + SLI ] 15.0 Simulate + +The command `Simulate` runs the simulation for the specified number of +milliseconds. Below, you see a transcript of the simulation: + + Nov 10 08:57:51 Simulate [Info]: + Simulating 15 ms. + Nov 10 08:57:51 Scheduler::prepare_nodes [Info]: + Please wait. Preparing elements. + Nov 10 08:57:51 Scheduler::prepare_nodes [Info]: + Simulating 3 local nodes. + Nov 10 08:57:51 Scheduler::update [Info]: + Simulating using OpenMP. + + 1 0.1 -70 + 1 0.2 -70 + 1 0.3 -70 + 1 0.4 -70 + 1 0.5 -70 + 1 0.6 -70 + 1 0.7 -70 + 1 0.8 -70 + 1 0.9 -70 + 1 1 -70 + 1 1.1 -70 + 1 1.2 -69.7612 + 1 1.3 -69.5248 + 1 1.4 -69.2907 + 1 1.5 -69.0589 + + : + + 1 10.5 -55.3751 + 1 10.6 -55.2818 + 1 10.7 -55.1894 + 1 10.8 -55.098 + 1 10.9 -55.0075 + 1 11 -70 + 1 11.1 -70 + 1 11.2 -70 + 1 11.3 -70 + + : + + 1 12.7 -70 + 1 12.8 -70 + 1 12.9 -70 + 1 13 -70 + 1 13.1 -69.7612 + 1 13.2 -69.5248 + 1 13.3 -69.2907 + 1 13.4 -69.0589 + 1 13.5 -68.8295 + 1 13.6 -68.6023 + 1 13.7 -68.3775 + 1 13.8 -68.1548 + 1 13.9 -67.9343 + 1 14 -67.7161 + + Nov 10 08:57:51 Scheduler::resume [Info]: + Simulation finished. + Nov 10 08:57:51 Scheduler::finalize_nodes() [Info]: + using OpenMP. + +After some initial messages from the simulation scheduler, we see the output +from the voltmeter. The number in the left column represents the global ID (GID) +of the model neuron and the center column the network time in milliseconds. The +right column contains the values of the membrane potential at that time. The +potential is given in mV. + +By default, NEST uses a simulation stepsize of 0.1 ms. With a simulation time +of 15.0 ms, we have 150 simulation steps. + +The neuron that we have simulated was a standard *integrate-and-fire* neuron +\[Tuckwell91\] with a resting potential of -70 mV and a threshold at -55.0 mV. +We see the first effect of the DC input current at 1.2 ms. This time delay is +due to several reasons: The `dc_generator` emits the first current output at the +end of the first time step, i.e., at 0.1 ms. Since the connection between +generator and neuron was created with the default delay of 1 ms, the current +signal arrives at the neuron at 1.1 ms and thus affects the membrane potential +for the first time during the time step from 1.1 ms to 1.2 ms. + +During the time step from 10.9 ms to 11.0 ms, the membrane potential crosses the +threshold value -55.0 mV. Thus, the neuron emits an output spike at 11.0 ms and +the membrane potential is then reset to -70.0 mV and clamped to the resting +value for 2 ms, the refractory period of the neuron. After the refractory +period, the membrane continues to depolarize due to the continuing input +current. + +Nodes and Models +----------------- + +In NEST, the neural system is a collection of nodes and their interactions. +Nodes correspond to things like neurons, synapses, and devices, and are +implemented in C++. The network and its configuration are defined at the level +of the simulation language interpreter. + +Nodes are created from a set of prescribed models which are stored in the +dictionary `modeldict`. The most important neuron models are: + +Model name +Description +`iaf_neuron` +Simple integrate-and-fire neuron with alpha-function PSCs. +`iaf_psc_delta` +Integrate-and-fire neuron with delta-function PSCs. +`iaf_cond_alpha` +Conductance-based integrate-and-fire neuron with alpha-function synapses. +`iaf_cond_exp` +Conductance-based integrate-and-fire neuron with exp-function synapses. +`hh_psc_alpha` +`hh_cond_exp_traub` +In order to make the models visible to the interpreter, the model dictionary +has to be opened. + +### Creating nodes + +Before continuing with the example, we reset NEST, to clear all nodes that we +have created before. + + SLI ] ResetKernel + Sep 21 10:13:39 Network::clear_models [Info]: + Models will be cleared and parameters reset. + +Nodes are created from a model, using the command `Create`. + + SLI ] /iaf_neuron Create == + 1 + +In the fist line, we create one integrate and fire neuron from the model +`iaf_neuron`. + +The return value of `Create` is an integer that identifies the last node that +was created in the network (note that this can be different from 1 if you have +not called `ResetKernel before)`. This integer is called the node's *global id* +(the network as a whole owns the global id `0`, therefore the ids of +user-created nodes start with `1`). Often, it is neccessary to have a large +number of nodes of the same type. The command Create can also be used for this +purpose. The following line of code create 10 integrate and fire neurons: + + SLI ] /iaf_neuron 10 Create == + 11 + +Status information +------------------- + +Nodes have a state which can be extracted and modified. In the follwing example, +we display the status information of one the neurons in the layer we have +created above: + + SLI ] 1 ShowStatus + -------------------------------------------------- + Name Type Value + -------------------------------------------------- + archiver_length integertype 0 + C_m doubletype 250 + E_L doubletype -70 + frozen booltype false + global_id integertype 1 + I_e doubletype 0 + local booltype true + local_id integertype 1 + model literaltype iaf_neuron + node_type literaltype neuron + parent integertype 0 + recordables arraytype + state integertype 0 + tau_m doubletype 10 + tau_minus doubletype 20 + tau_minus_triplet doubletype 110 + tau_syn doubletype 2 + thread integertype 0 + t_ref doubletype 2 + t_spike doubletype -1 + vp integertype 0 + V_m doubletype -70 + V_reset doubletype -70 + V_th doubletype -55 + -------------------------------------------------- + Total number of entries: 24 + +Using the command `SetStatus`, it is possible to change the entries of this so +called *status dictionary*. The following lines of code change the threshold +value `V_th` to -60 mV: + + SLI ] 1 << /V_th -60.0 >> SetStatus + SLI ] 1 GetStatus /V_th get = + -60 + +Please note, that `SetStatus` checks if a property really exists in a node and +will issue an error if it doesn't. This behavior can be changed by the following +command: + + 0 << /dict_miss_is_error false >> SetStatus + +Then, NEST is very tolerant with respect to the property that you are trying to +change: If it does not know the property, or if the property cannot be changed, +there will be no error, but only a warning. In any case, `SetStatus` does +complain if the new value does not match in the expected type: + + SLI ] 1 << /V_th (60) >> SetStatus + + + Dec 01 15:33:54 SetStatus_ad [Error]: TypeMismatch + Expected datatype: doubletype + Provided datatype: stringtype + +In order to find out, which properties of a given model can be changed an which +not, you have to refer to the model's documentation. + +Connections +------------ + +Connections between nodes define possible channels for interactions between +them. A connection between two nodes is established, using the command +`Connect`. + +Each connection has two basic parameters, *weight* and *delay*. The weight +determines the strength of the connection, the delay determines how long an +event needs to travel from the sending to the receiving node. The delay must be +a positive number greater or equal to the simulation stepsize and is given in +ms. + +### Example 1 + + SLI ] /iaf_neuron Create /n1 Set + SLI ] /iaf_neuron Create /n2 Set + SLI ] /iaf_neuron Create /n3 Set + SLI ] + SLI ] n1 n2 Connect + SLI ] n1 n3 Connect + +To inspect the parameters of a connection, one first needs to obtain a handle +to the connection. This is done using the command `FindConnections`. It takes a +dictionary that at least contains the id of the source node and will return a +list of handles for all outgoing connections. The search can be restricted by +using the optional parameters *target* and *synapse\_type*. + +### Example 2 + + SLI ] << /source n1 >> FindConnections /c1 Set + SLI ] c1 length == + 2 + SLI ] << /source n1 /target n2 >> FindConnections /c2 Set + SLI ] c2 length == + 1 + +To actually see the parameters of the connection, `GetStatus` is used, just like +it is for nodes. + +### Example 3 + + SLI ] c1 0 get GetStatus info + -------------------------------------------------- + Name Type Value + -------------------------------------------------- + delay doubletype 1 + receptor integertype 0 + sizeof integertype 32 + source integertype 1 + synapse_model literaltype static_synapse + target integertype 2 + weight doubletype 1 + -------------------------------------------------- + Total number of entries: 7 + +To change the paramters of a connection, `SetStatus` is used, just like it is +for nodes. + +### Example 4 + + SLI ] c1 0 get << /weight 2.0 >> SetStatus + SLI ] c1 0 get GetStatus /weight get == + 2.000000e+00 + +Devices +-------- + +Devices are network nodes which provide input to the network or record its +output. They encapsulate the stimulation and measurement process. If you want +to extract certain information from a simulation, you need a device which is +able to deliver this information. Likewise, if you want to send specific input +to the network, you need a device which delivers this input. + +Devices have a built-in timer which controls the period they are active. Outside +this interval, a device will remain siltent. The timer can be configured using +the command `SetStatus`. + +By definition a device is active in the interval \\((t\_1,t\_2)\\) +, if we can observe events \\(E\\) +with time stamps \\(t\_E\\) +which obey \\(t\_1 <= t\_E < t\_2\\) +for all \\(E\\) +. +In other words, the interval during which the device is active corresponds to +the range of time-stamps of the device's events. + +Note that it is not possible to generate/observe an event with time stamp 0. + +### Device parameters + +The following entries of the status dictionary are the same for all stimulation +and recording devices: + +Property +Type +Description +`/start` +double +First time of activity, relative to the value of `origin` in ms. +`/stop` +double +First time of inactivity, relative to the value of `origin` in ms. +`/origin` +double +Origin of the device clock, relative to the network time in ms. +In general, the following must hold: + +1. *stop* \>= *start* +2. If *stop =* start*, the device is inactive.* + +### Stimulating Devices + +A range of devices is available for the stimulation of neurons. The most +important ones are listed in the following table. For details, refer to the +documentation of the respective decive. + +Model name +Description +`spike_generator` +Device to generate spikes at specific times. +`poisson_generator` +Device to generate poisson shotnoise. +`dc_generator` +Device to generate a constant current. +`ac_generator` +Device to generate an alternating (sine) current. +`step_current_generator` +Device to generate a step current with different amplitudes at different times. + +#### Example 5 + + SLI ] /iaf_neuron Create /n Set + SLI ] /poisson_generator Create /pg Set + SLI ] pg << /rate 220.0 Hz >> SetStatus + SLI ] pg n Connect + +### Recording devices + +All devices which are used to observe the state of other network nodes are +called recording devices. Examples are `voltmeter` and `spike_detector`. + +Recording devices have properties which control the amount, the format, and the +destination of their output. All recorders can either dump the recorded data to +a file (property `to_file`), print it to the screen (property `to_screen`) or +hold the data in memory (property `to_memory`). Data stored in memory can be +retrieved after the simulation using `GetStatus`. + +Device models are also stored in the dictionary `modeldict`. The most important +devices are: + +Model name +Description +`voltmeter` +Device to observe membrane potentials. +`multimeter` +Device to observe arbitrary analog quantities. +`spike_detector` +Device to observe spike times. +Please note that the connection direction for analog recorders (all except +`spike_detector` in above list) is inverted with respect to other recorders. + +#### Example 6 + + SLI ] /iaf_neuron Create /n Set + SLI ] /voltmeter Create /vm Set + SLI ] /spike_detector Create /sd Set + SLI ] vm n Connect + SLI ] n sd Connect + +Simulation +----------- + +NEST simulations are time driven. The simulation time proceeds in discrete steps +of size `dt`, set using the property `resolution` of the root node. In each time +slice, all nodes in the system are updated and pending events are delivered. + +The simulation is run by calling the command `t Simulate`, where `t` is the +simulation time in milliseconds diff --git a/extras/userdoc/md/documentation/objects-and-data-types.md b/extras/userdoc/md/documentation/objects-and-data-types.md new file mode 100644 index 0000000000..70bdeb5abd --- /dev/null +++ b/extras/userdoc/md/documentation/objects-and-data-types.md @@ -0,0 +1,211 @@ +Objects and data types +====================== + +Overview +-------- + +Anything that can be put on the stack is called object. There are several +different types of objects, which can store different types of data. For a +number of object types there exist two different states: *executable* and +*literal*. Some object types can change between these two states. Literal +objects are the majority and are simply pushed on the stack when they are +entered. By contrast, executable objects perform some operation when they are +entered and cannot easily be pushed on the stack. + +Numbers +------- + +SLI distinguishes between real and integer numbers. Real numbers +correspond to the type `double` in C/C++. Integer numbers +correspond to the type `long int` of C/C++. + +### Examples 1 + +Real numers are: `1.4`, `.5`, `1.`, `1e-2` + +Integer numers are `1`, `2`, `3000` + +Arrays +------ + +Arrays are sequential containers which can hold any SLI object. The elements of +an array are indexed, starting with zero (0) as the first index. + +SLI arrays are heterogeneous. Objects of different type may be mixed within one +array. Arrays may also be nested to define matrices or tensors of arbitrary rank. + +Arrays are delimited by square brackets. The different elements of an array are +separated by white-spaces. + +### Examples 2 + + [1 2 3]  % a simple array with integers + [1 a b]  % a mixed array + [[1 2 3] [4 5 6]] % a 2x3 Matrix defined by nested array + +Calculate the dot product of the vectors \\([1 2 3]cdot[4 5 6]\\) + + SLI ] [1 2 3] + SLI [1] [4 5 6] + SLI [2] Dot = + 32 + +Names +----- + +Names are used to create variables and to identify specific SLI objects. +If a name is entered, it is immediately executed. + +If you want to put a name on the stack without evaluating it, you need to +protect it by prepending a shash character (e.g. `/a`). In this case, the name +is called a *literal name*. + +The command `def` is used to create an associoation between a name an an object. + +### Example 3 + + SLI ] /pi 3.1415 def + SLI ] pi + SLI [1] = + 3.1415 + +The command `who` gives the list of names which have been + defined during the SLI session. + +### Example 4 + +Define the variables *a* and *b* with values 1 and 2 and calculate *a+b* + + SLI ] /a 1 def + SLI ] /b 2 def + SLI ] a b add + SLI ] = + 3 + SLI ] who + -------------------------------------------------- + Name Type Value + -------------------------------------------------- + pi doubletype 3.1415 + a integertype 1 + b integertype 2 + -------------------------------------------------- + Total number of dictionary entries: 3 + +Strings +------- + +Strings are sequences of characters, delimited by parenthesis. In SLI, +characters are represented by interger numbers, e.g. 97 represents the letter +'a', while 32 represents the *space* character. + +The elements of a string are indexed, starting with zero (0) as the first index. + +Matched pairs of parentheses may be used inside strings. + +### Examples 5 + + SLI ] (Hello World!) = + Hello World! + +Procedures +---------- + +Procedures are a sequence of SLI commands, enclosed by the delimiters +`{` and `}`. The delimiters prevent the objects from being executed as you enter + them. Rather, they will be executed, when you evaluate the procedure. + +Bound to a name, procedures can be used like any builtin SLI + command. + +### Example: Hello World + +Print the string *Hello World!*. + + /HelloWorld + { + (Hello World !) = + } def + +Dictionaries +------------ + +A dictionary is an associative array. It stores pairs of names and objects, +where the name acts as a key to access the object inside the dictionary. + +The pairs are delimited by the characters `<<` and `>>`. Note that the pairs are +evaluated during the construction of the dictionary. Thus, literal names have to +be used here. The individual name/value pairs have no defined sequential order +(unlike a real dictionary where the keys are ordered alphabetically). + +### Example 6 + +Create a dictionary which stores named parameters. + + SLI ] /parameters << /alpha 1.0 /beta 3.5 /tau 10.0 >> def + SLI ] parameters /tau get = + 10 + +### Example: Showing dictionaries + +The command `info` can be used to examine the contents of a dictionary. + + SLI ] parameters info + -------------------------------------------------- + Name Type Value + -------------------------------------------------- + alpha doubletype 1 + beta doubletype 3.5 + tau doubletype 10 + -------------------------------------------------- + Total number of dictionary entries: 3 + +Object types +------------ + +There are a number of different object types in SLI. Each type is represented by +a literal name (i.e. a name with a prepended slash). Here is a list of the most +important types: + +|-----------------|-------------------| +| `/integertype` | `/doubletype` | +| `/booltype` | `/stringtype` | +| `/nametype` | `/literaltype` | +| `/arraytype` | `/proceduretype` | +| `/modeltype` | `/dictionarytype` | +| `/ostreamtype` | `/istreamtype` | +| `/xistreamtype` | `/trietype` | + +### Getting type information + +The command `type` returns the type-name of the top element of the stack. Note +that type removes the element. + +The command `typeinfo` returns the type of an object without popping it off the +stack. + +### Conversion between types + +It is possible to perform conversions between types. However, unlike in C or C++ +this type conversion is never done implicitly. Some of the conversion operators +are inherited from PostScript. Others are special to SLI. + +Here, we list the most important conversion operators. Each conversion operator +gets one argument which can, in general, be of any type. If the operator is +meaningless for a given object, an argument type error is raised. + +Command +Description +`cvd` +Convert a number to a double. +`cvi` +Convert a number to an integer. +`cvs` +Tries to convert the object to a string. +`cst` +Convert a string to an array. +`cvx` +Convert an object to an executable object, e.g. string to a procedure, or a +literal name to a name. +`cvlit` +Convert an object to a literal object, e.g. a procedure to an array or a string +to a literal name. diff --git a/extras/userdoc/md/documentation/parallel-computing.md b/extras/userdoc/md/documentation/parallel-computing.md new file mode 100644 index 0000000000..a225c998a3 --- /dev/null +++ b/extras/userdoc/md/documentation/parallel-computing.md @@ -0,0 +1,222 @@ +Parallel Computing +================== + +Introduction +------------ + +Parallelization is a means to run simulations faster and use the capabilities of +computer clusters and supercomputers to run large-scale simulations. + +Since version 2.0, NEST is capable of running simulations on +multi-core/-processor machines and computer clusters using two ways of +parallelization: *thread-parallel simulation* and *distributed simulations*. +The first is implemented using OpenMP (POSIX threads prior to NEST 2.2), while +the second is implemented on top of the Message Passing Interface (MPI). Both +ways of parallelism can be combined in a hybrid fashion. + +Using threads allows to take advantage of multi-core and multi-processor +computers without the need for additional software libraries. Using distributed +computing allows to draw in more computers and thus enables larger simulations, +than would fit into the memory of a single machine. The following paragraphs +describe the facilities for parallel and distributed computing in detail. + +See [Plesser et al (2007)](http://dx.doi.org/10.1007/978-3-540-74466-5_71) for +more information on NEST parallelization and be sure to check the documentation +on [Random numbers in NEST](../random-numbers.md "Random numbers in NEST"). + +Concepts and definitions +------------------------ + +In order to ease the handling of neuron and synapse distribution with both +thread and process based parallelization, we use the concept of local and remote +threads, called *virtual processes*. A virtual process (VP) is a thread living +in one of NEST's MPI processes. Virtual processes are distributed round-robin +onto the MPI processes and counted continuously over all processes. The concept +is visualized in the following figure: + +![Process\_vp\_thread](../../img/Process_vp_thread.png) +Basic scheme for counting threads (T), virtual processes (VP) and MPI processes +(P) in NEST + +The status dictionary of each node (i.e. neuron or device) contains three +entries that are related to parallel computing: + +- *local* (boolean): indicating if the node exists on the local process or not +- *thread* (integer): id of the local thread the node is assigned to +- *vp* (integer): id of the virtual process the node is assigned to. + +### Node distribution + +The distribution of nodes is based on the type of the node. Neurons are assigned +to one of the virtual processes in a round-robin fashion. On all other virtual +processes, no object is created (the *proxy* object in the figure below is just +a conceptual way of keeping the id of the real node free on remote processes). +The virtual process *idVP* on which a neuron with global id +*idNode* is allocated is given by +*idVP = idNode % NVP*, where +*NVP* is the total number of virtual processes in the simulation. + +Devices for the stimulation and observation of the network are replicated once +on each thread in order to balance the load of the different threads and +minimize their interaction. Devices thus do not have proxies on remote virtual +processes. + +The node distribution for a small network consisting of `spike_generator`, four +`iaf_neuron`s, and a `spike_detector` in a scenario with two processes with two +threads each is shown in the following figure: + +![Node\_distribution](../../img/Node_distribution.png) +Illustration of node distribution. sg=spike\_generator, iaf=iaf\_neuron, +sd=spike\_detector. Numbers to the left and right indicate global ids. + +For recording devices that are configured to record to a file +(property *to\_file* set to *true*), the distribution also results in multiple +data files, each containing the data from one thread. The files names are +composed according to the following scheme + + [model|label]-gid-vp.[dat|gdf] + +The first part is the name of the model (e.g. `voltmeter` or `spike_detector`) +or, if set, the *label* of the recording device. The second part is the global +id (GID) of the recording device. The third part is the id of the virtual +process the recorder is assigned to, counted from 0. The extension is `gdf` for +spike files and `dat` for analog recordings from the `multimeter`. +The `label` and `file_extension` of a recording device can be set like any other +parameter of a node using `SetStatus`. + +Using multiple threads +---------------------- + +Thread-parallelism is compiled into NEST by default and should work on all MacOS +and Linux machines without additional requirements. In order to keep results +comparable and reproducible across different machines, however, the default mode +is that only a single thread is used and multi-threading has to be turned on +explicitly. + +To use multiple threads for the simulation, the desired number of threads has to +be set *before* any nodes or connections are created. The command for this is + + nest.SetKernelStatus({"local_num_threads": T}) + +Usually, a good choice for T is the number of processor cores available on your +machine. In some situations, oversubscribing can yield 20-30% improvement in +simulation speed. Finding the optimal thread number for a specific situation +might require a bit of experimenting. + +Using distributed computing +--------------------------- + +### Build requirements + +To compile NEST for distributed computing, you need a library implementation of +MPI on your system. If you are on a cluster, you most likely have this already. +Note, that in the case of a pre-packaged MPI library you will need both, the +library and the development packages. Please see the [Installation instructions](../installation.md "Installation") +for general information on installing NEST. +Please be advised that NEST should currently only be run in a homogeneous MPI environment. Running in a heterogenenous environment can lead to unexpected results or even crashes. Please contact the [NEST community](http://www.nest-simulator.org/community/) if you require support for exotic setups. + +### Compilation + +If the MPI library and header files are installed to the standard directories +of the system, it is likely that a simple + + $NEST_SOURCE_DIR/configure --with-mpi + +will find them (`$NEST_SOURCE_DIR` is the directory holding the NEST sources). +If MPI is installed to a non-standard location `/path/to/mpi`, the command line +looks like this: + + $NEST_SOURCE_DIR/configure --with-mpi=/path/to/mpi + +In some cases it might be necessary to specify MPI compiler wrappers explicitly: + + $NEST_SOURCE_DIR/configure CC=mpicc CXX=mpicxx --with-mpi + +Additional information concerning MPI on OSX can be found [here](../installation.md "Installation"). + +### Running distributed simulations + +Distributed simulations cannot be run interactively, which means that the +simulation has to be provided as a script. However, the script does not have to +be changed compared to the script for serial simulation: inter-process +communication and node distribution is managed transparently inside of NEST. + +To distribute a simulation onto 128 processes of a computer cluster, the command +line to execute looks like this: + + mpirun -np 128 python simulation.py + +Please refer to the MPI library documentation for details on the usage of +`mpirun`. + +### MPI related commands + +Although we generally advise strongly against writing process-aware code in +simulation scripts (e.g. creating a neuron or device only on one process and +such), in special cases it may be necessary to obtain information about the MPI +application. One example would opening the right stimulus file for a specific +rank. Therefore, some MPI specific commands are available: + +`NumProcesses` +The number of MPI processes in the simulation + +`ProcessorName` +The name of the machine. The result might differ on each process. + +`Rank` +The rank of the MPI process. The result differs on each process. + +`SyncProcesses` +Synchronize all MPI processes. + +Reproducibility +--------------- + +To achieve the same simulation results even when using different parallelization +strategies, the number of virtual processes has to be kept constant. A +simulation with a specific number of virtual processes will always yield the +same results, no matter how they are distributed over threads and processes, +given that the seeds for the random number generators of the different virtual +processes are the same (see [Random numbers in NEST](../random-numbers.md "Random numbers in NEST")). + +In order to achieve a constant number of virtual processes, NEST provides the +property *total\_num\_virtual\_procs* to adapt the number of local threads +(property *local\_num\_threads*, explained above) to the number of available +processes. + +The following listing contains a complete simulation script (*simulation.py*) +with four neurons connected in a chain. The first neuron receives random input +from a `poisson_generator` and the spikes of all four neurons are recorded to +files. + + from nest import * + SetKernelStatus({"total_num_virtual_procs": 4}) + pg = Create("poisson_generator", params={"rate": 50000.0}) + n = Create("iaf_neuron", 4) + sd = Create("spike_detector", params={"to_file": True}) + Connect(pg, [n[0]], 1000.0, 1.0) + Connect([n[0]], [n[1]], 1000.0, 1.0) + Connect([n[1]], [n[2]], 1000.0, 1.0) + Connect([n[2]], [n[3]], 1000.0, 1.0) + ConvergentConnect(n, sd) + Simulate(100.0) + +The script is run three times using different numbers of MPI processes, but 4 +virtual processes in every run: + + mkdir 4vp_1p; cd 4vp_1p + mpirun -np 1 python ../simulation.py + cd ..; mkdir 4vp_2p; cd 4vp_2p + mpirun -np 2 python ../simulation.py + cd ..; mkdir 4vp_4p; cd 4vp_4p + mpirun -np 4 python ../simulation.py + cd .. + diff 4vp_1p 4vp_2p + diff 4vp_1p 4vp_4p + +Each variant of the experiment produces four data files, one for each virtual +process (*spike\_detector-6-0.gdf*, *spike\_detector-6-1.gdf*, +*spike\_detector-6-2.gdf*, and *spike\_detector-6-3.gdf*). Using diff on the +three data directories shows that they all contain the same spikes, which means +that the simulation results are indeed the same independently of the details of +parallelization. diff --git a/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md b/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md index cd36ff695d..4d31a340a6 100644 --- a/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md +++ b/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md @@ -19,7 +19,7 @@ discusses in this primer, please visit [nest-initiative.org/](http://nest-initia or have a look at the source directory of your NEST installation in the subdirectory: `pynest/examples/`. For the internals of the NEST simulator you may refer -to the [publications](../publications/index.html "Publications"). +to the [publications](../publications.md "Publications"). PyNEST - an interface to the NEST simulator ------------------------------------------- @@ -32,7 +32,7 @@ high-level API. These functions generate code in SLI (Simulation Language Interpreter), the native language of the interpreter of NEST. This interpreter, in turn, controls the NEST simulation kernel. -The NEural Simulation Tool (NEST: [www.nest-initiative.org](../part-1-neurons-and-simple-neural-networks/index.html)) +The NEural Simulation Tool (NEST: [www.nest-initiative.org](../part-1-neurons-and-simple-neural-networks.md)) is designed for the simulation of large heterogeneous networks of point neurons. It is open source software released under the GPL licence. The simulator comes with an interface to Python . illustrates the interaction between the user’s @@ -372,7 +372,7 @@ Here we have just used very simple connection schemes. Connectivity patterns requiring the specification of further parameters, such as in-degree or connection probabilities, must be defined in a dictionary containing the key `"rule"` and the key for parameters associated to the rule. Please see -<../connection_management/index.html> for an illustrated guide to the usage of +<../connection-management.md> for an illustrated guide to the usage of `Connect`. Command overview diff --git a/extras/userdoc/md/documentation/part-2-populations-of-neurons.md b/extras/userdoc/md/documentation/part-2-populations-of-neurons.md index 10dd1ec73c..7ac38a73b5 100644 --- a/extras/userdoc/md/documentation/part-2-populations-of-neurons.md +++ b/extras/userdoc/md/documentation/part-2-populations-of-neurons.md @@ -17,7 +17,7 @@ to: - reset simulations For more information on the usage of NEST, please visit: -[Documentation](../documentation/index.html). To carry out the code snippets in +[Documentation](../documentation.md). To carry out the code snippets in this handout, you need to import `nest` and `numpy`. Creating parameterised populations of nodes diff --git a/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md b/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md index 0e3fbfaef8..22ae017c9b 100644 --- a/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md +++ b/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md @@ -14,7 +14,7 @@ have worked through this material, you will know how to: - set synapse values during and after connection For more information on the usage of NEST, please visit: -[Documentation](../documentation/index.html). To carry out the code snippets in +[Documentation](../documentation.md). To carry out the code snippets in this handout, you need to import `nest` and `numpy`. Parameterising synapse models @@ -146,7 +146,7 @@ set (for example `mu`). Here we show an example where the parameters `alpha` and "delay": 1.0 } nest.Connect(epop1, neuron, "all_to_all", syn_dict) -Available distributions and associated parameters are described in [Connection_Management](../connection_management/index.html)), +Available distributions and associated parameters are described in [Connection_Management](../connection-management.md)), the most common ones are: | Distributions | Keys | diff --git a/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md b/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md index 733c1c0c59..aa973bb14d 100644 --- a/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md +++ b/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md @@ -13,7 +13,7 @@ networks. When you have worked through this material you will be able to: - Visualise the connectivity For more information on the usage of NEST, please visit: -[http://www.nest-simulator.org/documentation/](../documentation/index.html))> +[http://www.nest-simulator.org/documentation/](../documentation.md))> Incorporating structure in networks of point neurons ---------------------------------------------------- diff --git a/extras/userdoc/md/documentation/programming-in-sli.md b/extras/userdoc/md/documentation/programming-in-sli.md new file mode 100644 index 0000000000..28eaddd825 --- /dev/null +++ b/extras/userdoc/md/documentation/programming-in-sli.md @@ -0,0 +1,313 @@ +Programming in SLI +================== + +Overview +-------- + +A procedure is a sequence of SLI objects whose execution is delayed until the +procedure is executed. Because procedures are objects, they can be: + +- placed on the stack +- bound to a name +- executed repeatedly +- executed by another procedure + +A program is a sequence of SLI objects and procedures which are + defined in a file. This section introduces the fundamentals of + SLI programming. + +This chapter covers the basic programming concepts of the SLI + language features. + +Entering and executing programs +------------------------------- + +A program is a sequence of SLI objects and procedures which are defined in a +file. Program files are ordinary ASCII text files, which can be created and +modified with an editor of your choice (e.g. GNU Emacs). + +SLI programs usually have the file ending "sli", for example `hello_world.sli`. + +The `run` command is used to execute a program file. + +### Example: "Hello World!" + +Write the program `hello_world.sli` according to the + example, given above. + +1. Create an empty file `hello_world.sli` in the directory from which the + interpreter was started. + +2. Copy the *Hello World* example to the file and save it. + +3. Enter `(hello_world.sli) run` at the command prompt. + + + /HelloWorld + { + (Hello World !) = + } def + + + + SLI ] (hello_world.sli) run + SLI ] HelloWorld + Hello World ! + +Note that the procedure is not immediately executed by `run`. Rather, all +objects which are contained in the file are read and executed. + +Using local variables +--------------------- + +Usually, all names you define are globally accessible. But, if you use a lot of +procedures that define their own variables, there is an increasing danger that +two procedures use the same name for different purposes. This problem can be +solved by keeping variable *local* to the procedure that defines them. + +SLI uses dictionaries to store and resolve variables. + +### Example 2 + +Compute the alpha-function of *t* according to *a(t)=t\*Exp(-t/tau)* + + /alpha + { + << /tau -1.0 >> % create dictionary for local variables + begin  % open local name space + /t exch def  % store argument in local variable t + t tau div exp  % compute formula + t mul + end  % close local name space + } def + +Conditionals +------------ + +Conditional expressions allow a program to ask questions and make decisions: + +- Comparisons and logical functions + +- Conditional structures which test a certain condition and use the result to + make a decision. + +In general, conditional structures take a *boolean* object as well as one or +more procedure objects as argument and evaluate one of the procedures, depending +on the value of the boolean. + +### Example 3 + +The program in this example implements the faculty function according to the +definition: + + fac(1) := 1 + fac(n) := n*fac(n-1), for n>1 + +The program expects the argument on the stack and replaces it by the result. +Here, we use the `if` command to test whether the argument is greater than 1. +The `if` command takes two arguments, a boolean and a procedure object. The +boolean is supplied by the `gt` command which test if the object at stack level +1 is greater than the object at level 0. + + /fac + { + dup  % duplicate the argument, since we still need it. + 1 gt  % If n > 1 we call fac recursively + {  % according to fac(n)=n*fac(n-1) + dup + 1 sub fac % call fac with n-1 as argument + mul  % multiply the result with the argument + } if + } def + +This example also shows how procedures can be called *recursively*. It is, +however, important to supply a *termination condition* for the recursion like in +this example. + +Comparison functions +-------------------- + +Comparison functions are used to compare objects. The result of comparison +functions are of type `/booltype` and can be used for logical functions and +conditional structures. + +Command +Description +`eq` +Test whether two objects are equal. +`ne` +Test whether two objects are not equal. +`gt` +Test whether the object at level 1 is greater than the object at level 0. +`lt` +Test whether the object at level 1 is less than the object at level 0. +`leq` +Test whether the object at level 1 is less than or equal to the object at level +0. +`geq` +Test whether the object at level 1 is greater than or equal to the object at +level 0. + +Logical functions +----------------- + +Command +Description +`not` +Negates a bool. +`and` +Returns true if both arguments are true. +`or` +Returns true if at least one of the arguments is true. +`xor` +Returns true if and only if one of the arguments is true. +  + +The *if-ifelse* structure +------------------------- + +Command +Description +`bool proc if` +Executes `proc` if the boolean is true. +`bool proc_1 proc_2 ifelse` +Executes `proc_1` if the boolean is true and `proc_2` otherwise. + +### Example + + SLI ] 1 2 eq {(Equal!) = } { (Not equal !) =} ifelse + Not equal ! + SLI ] 2 2 eq {(Equal!) = } { (Not equal !) =} ifelse + Equal! + +The *case-switch* structure +--------------------------- + +While the commands `if` and `ifelse` test only one condition, the *case-switch* +structure can be used to test a number of different conditions. + +The *case-switch* structure has the general form: + + mark + bool_1 proc_1 case + bool_2 proc_2 case +  : + bool_n proc_n case + switch + +In this structure, `proc_i` is executed, if the corresponding value of `bool_i` +is true. + +Sometimes it is necessary to provide a default procedure, which is evaluated if +none of the boolean is true. + +The *case-switchdefault* structure has the general form + + mark + bool_1 proc_1 case + bool_2 proc_2 case +  : + bool_n proc_n case + procdefault + switchdefault + +Here, `procdefault` is executed if none of the booleans was true. + +Loops +----- + +Loops and control structures are commands that take procedure objects as + arguments. + +### Infinite loops + +The simplest loop is performed by the command `loop`: + + SLI ] {(Hello World) =} loop + Hello World + Hello World + Hello World + Hello World + Hello World + Hello World + Hello World + Hello World +  : + +`loop` performs the procedure repeatedly and thus in the example, an infinite +succession of the words "Hello World" is printed. The only way to leave a +`loop`-structure is to call the command `exit` somewhere inside the loop: + + SLI ] 0 + SLI [1] { 1 add dup (Hello World) = 10 eq {exit} if } + SLI [2] loop + +it prints ten times 'Hello World'. First the initial value 0 is pushed on the +operand stack. The procedure adds 1 in each cycle and takes care that one copy +of the counter stays on the stack to serve as the initial value for the next +cycle. After the message has been printed, the stop value 10 is pushed and is +compared with the counter. If the counter is equal to 10, the nested procedure +s executed. This procedure then executes the command `exit`, and interrupts the +loop. + +Command +Description +`proc loop` +Repeatedly execute procedure `proc`. + `exit` +Exit the innermost loop structure. + +### Finite loops + +The last example can be implemented much easier, using a `repeat` loop. `repeat` +takes two arguments: An integer, and a procedure object. The integer determines +how often the procedure is executed. Thus, in order to print ten times +"Hello World" we write: + + SLI ] 10 { (Hello World) = } repeat + +Sometimes, one needs to know the counter of the loop and one may also be +interested in influencing the step-size of the iterations. For this purpose SLI +offers the `for`-loop. `for` is + called like this: + + start step stop proc for + +`for` executes the procedure `proc` as long as the + counter is smaller than the stop-value (for positive step values) (please refer + to reference *RedBook* for the exact termination conditions). + +In each cycle, the current value of the counter is pushed automatically. This +value can be consumed by the procedure. Actually, in very long running loops, +the counter must be removed by the procedure in order to avoid stack overflow. +The following example prints the first ten cubic numbers: + + SLI ] 1 1 10 { dup mul = } for + 1 + 4 + 9 + 16 + 25 + 36 + 49 + 64 + 81 + 100 + SLI ] + +Command +Description +`n proc repeat` +Execute procedure proc n times. +`i s e proc for` +Execute procedure proc for all values from i to e with steps. +`array proc forall` +Execute procedure proc for all elements of `array`. +`array proc forallindexed` +Execute procedure proc for all elements of `array`. +`array proc Map` +Apply `proc` to all elements of `array`. +`array proc MapIndexed` +Apply `proc` to all elements of `array`. +`x proc n NestList` +Gives a list of the results of applying `proc` to`x` 0 through `n` times. diff --git a/extras/userdoc/md/documentation/random-numbers.md b/extras/userdoc/md/documentation/random-numbers.md new file mode 100644 index 0000000000..c7020d5538 --- /dev/null +++ b/extras/userdoc/md/documentation/random-numbers.md @@ -0,0 +1,454 @@ +Random numbers +============== + +Introduction +------------- + +Random numbers are used for a variety of purposes in neuronal network +simulations, e.g. + +- to create randomized connections + +- to choose parameter values randomly + +- to inject noise into network simulations, e.g., in the form of Poissonian + spike trains. + +This document discusses how NEST provides random numbers for these purposes, how +you can choose which random number generator (RNG) to choose, and how to set the +seed of RNGs in NEST. We use the term "random number" here for ease of writing, +even though we are always talking about pseudorandom numbers generated by some +algorithm. + +NEST is designed to support parallel simulation and this puts some constraints +on the use and generation of random numbers. We discuss these in the next +section, before going into the details of how to control RNGs in NEST. + +On this page, we mainly discuss the use of random numbers in parallel NEST +simulations, but the comments pertain equally to serial simulations (N\_vp=1). + +### Random Numbers vs Random Deviates + +NEST distinguishes between random number generators, provided by `rngdict` and +random deviate generators provided by `rdevdict`. Random *number* generators +only provide double-valued numbers uniformly distributed on \[0, 1\] and +uniformly distributed integers in {0, 1, ..., N}. Random *deviate* generators, +on the other hand, provide random numbers drawn from a range of distributions, +such as the normal or binomial distributions. In most cases, you will be using +random deviate generators. They are in particular used to initialize properties +during network construction, as described in the sections [Changes in NEST 2.4](../random-numbers.md#Changes-in-random-number-generation-in-NEST-2.4) and [Examples](../random-numbers.md#Examples) below. + +Changes in random number generation in NEST 2.4 +------------------------------------------------- + +Random deviate generation has become significantly more powerful in NEST 2.4, to +fully support randomization of connections parameters offered by the revised +`Connect` function, as described in [Connection Management](../connection-management.md "Connection Management") +and illustrated by the [examples](../random-numbers.md#examples) below. +We have also made minor changes to make to achieve greater similarity between +NEST, PyNN, and NumPy. For most users, these changes only add new features. +Only existing scripts using + +- `uniformint` +- `normal_clipped`, `normal_clipped_left`, `normal_clipped_right` + +generators from NEST 2.2 need to be adapted as detailed below. + +The changes are as follows: + +- Uniform integer generator + + - renamed from `uniformint` to `uniform_int` + - parameters renamed to `low` and `high` + - returns uniformly distributed integers from `{low, low+1, …, high}` + +- Uniform continuous generator + + - new generator `uniform` + - parameters `low` and `high` + - generates numbers uniformly distributed in `[low, high)` + +- Full parameter sets for generators + + - In the past, many random deviate generators returned values for fixed + parameters, e.g., the `normal` generator could only return zero-mean, + unit-variance normal random numbers. + + - Now, all parameters for each generator can be set, in particular: + + - normal: mu, sigma + - lognormal: mu, sigma + - exponential: lambda + - gamma: order, scale + + - Parameter values are checked more systematically for unsuitable values. + +- Clipped normal generators + + - parameter names changed to `mu` and `sigma` + + - clipping limits now called `low` and `high` + + - `_left` and `_right` variants removed: for one-sided clipping, just set + the boundary you want to clip at, the other is positive or negative + infinity + +- Clipped variants for most generators + + - For most random deviate generators, `_clipped` variants exist now. + + - For all clipped variants, one can set a lower limit (`low`, default: + -infinity) and an upper limit (`high`: +infinty). + + - Clipped variants will then return numbers strictly in `(low, high)` for + continuous distributions (e.g. normal, exponential) or + `{low, low+1, …, high}` for discrete distributions (e.g. poisson, + binomial). This is achieved by redrawing numbers until an acceptable + number is drawn. + + - Note that the resulting distribution differs from the original one and + that drawing may become very slow if `(low, high)` contains only very + small probability mass. Clipped generator variants should therefore + mostly be used to clip tails with very small probability mass when + randomizing time constants or delays. + +- Clipped-to-boundary variants for most generators + + - To facilitate reproduction of certain publications, NEST also provides + `_clipped_to_boundary` variants of most generators. + + - Clipped-to-boundary variants return the value `low` if a number smaller + than `low` is drawn, and `high` if a number larger than `high` is drawn. + + - We believe that these variants should *not* be used for new studies. + +Basics of parallel simulation in NEST +-------------------------------------- + +For details of parallelization in NEST, please see [Parallel Computing](../parallel-computing.md "Parallel Computing") +and [Plesser et al (2007)](http://dx.doi.org/10.1007/978-3-540-74466-5_71). +Here, we just summarize a few basics. + +- NEST can parallelize simulations through *multi-threading*, *distribution* + or a combination of the two. + +- A distributed simulation is spread across several processes under the + control of MPI (Message Passing Interface). Each network node is *local* to + exactly one process and complete information about the node is only + available to that process. Information about each connection is stored by + the process in which the connection target is local and is only available + and changeable on that process. + +- Multi-threaded simulations run in a single process in a single computer. As + a consequence, all nodes in a multi-threaded simulation are local. + +- Distribution and multi-threading can be combined by running identical + numbers of threads in each process. + +- A serial simulation has a single process with a single seed. + +- From the NEST user perspective, distributed processes and threads are + visible as **virtual processes**. A simulation distributed across \\(M\\) + MPI processes with \\(T\\) threads each, has \\(N\_{vp} = M times T\\) + virtual processes. It is a basic design principle of NEST that simulations + shall generate *identical* results when run with a fixed \\(N\_{VP}\\), no + matter how the virutal processes are broken down into MPI processes and + threads. + +- Useful information can be obtained like this + + + import nest + nest.NumProcesses() # number of MPI processes + nest.Rank() # rank of MPI process executing command + nest.GetKernelStatus(['num_processes']) # same as nest.NumProcesses() + nest.GetKernelStatus(['local_num_threads']) # number of threads in present process (same for all processes) + nest.GetKernelStatus(['total_num_virtual_procs']) # N_vp = M x T + +- When querying neurons, only very limited information is available for + neurons on other MPI processes. Thus, before checking for specific + information, you need to check if a node is local: + + + n = nest.Create('iaf_neuron') + if nest.GetStatus(n, 'local')[0]: # GetStatus() returns list, pick element + print nest.GetStatus(n, 'vp') # virtual process "owning" node + print nest.GetStatus(n, 'thread') # thread in calling process "owning" node + +Random numbers in parallel simulations +--------------------------------------- + +Ideally, all random numbers in a simulation should come from a single RNG. This +would require shipping truckloads of random numbers from a central RNG process +to all simulations processes and is thus impractical, if not outright +prohibitively costly. Therefore, parallel simulation requires an RNG on each +parallel process. Advances in RNG technology give us today a range of RNGs that +can be used in parallel, with a quite high level of certainty that the resulting +parallel streams of random numbers are non-overlapping and uncorrelated. While +the former can be guaranteed, we are not aware of any generator for which the +latter can be proven. + +### How many generators in a simulation + +In a typical PyNEST simulation running on \\(N\_{vp}\\) virtual processes, we +will encounter \\(2 N\_{vp} + 1\\) random number generators: + +The global NEST RNG +This generator is mainly used when creating connections using +`RandomDivergentConnect`. + +One RNG per VP in NEST +These generators are used when creating connections using +`RandomConvergentConnect` and to provide random numbers to nodes generating +random output, e.g. the `poisson_generator`. + +One RNG per VP in Python +These generators are used to randomized node properties (e.g., the initial +membrane potential) and connection properties (e.g., weights). + +The generators on the Python level are not strictly necessary, as one could in +principle access the per-VP RNGs built into NEST. This would require very +tedious SLI-coding, though. We therefore recommend at present that you use +additional RNGs on the Python side. + +#### Why a Global RNG in NEST + +In some situations, randomized decisions on different virtual processes are not +independent of each other. The most important case are randomized divergent +connections. The problem here is as follows. For the sake of efficiency, NEST +stores all connection information in the virtual process (VP) to which the +target of a connection resides (target process). Thus, all connections are +generated by this target process. Now consider the task of generating 100 +randomized divergent connections emanating from a given source neuron while +using 4 VPs. Then there should be 25 targets on each VP *on average*, but actual +numbers will fluctuate. If independent processes on all VPs tried to choose +target neurons, we could never be sure that exactly 100 targets would be chosen +in total. + +NEST thus creates divergent connections using a global RNG. This random number +generator provides the exact same sequence of random numbers on each virtual +process. Using this global RNG, each VP chooses 100 targets from the entire +network, but actually creates connections only for those targets that reside on +the VP. In practice, the global RNG is implemented using one "clone" on each VP; +NEST checks occasionally that all these clones are synchronized, i.e., indeed +generate identical sequences. + +### Seeding the Random Generators + +Each of the \\(N\_{vp}\\) random generators needs to be seeded with a different +seed to generate a different random number sequences. We recommend that you +choose a *master seed* `msd` and seed the \\(2N\_{vp}+1\\) generators with seeds +`msd`, `msd+1`, ..., `msd+2*N_vp`. Master seeds for for independent experiments +must differ by at least \\(2N\_{vp}+1\\) +. Otherwise, the same sequence(s) would enter in several experiments. + +#### Seeding the Python RNGs + +You can create a properly seeded list of \\(N\_{vp}\\) RNGs on the Python side +using + + import numpy + msd = 123456 + N_vp = nest.GetKernelStatus(['total_num_virtual_procs'])[0] + pyrngs = [numpy.random.RandomState(s) for s in range(msd, msd+N_vp)] + +`msd` is the master seed, choose your own! + +#### Seeding the global RNG + +The global NEST rng is seeded with a single, positive integer number: + + nest.SetKernelStatus({’grng_seed’ : msd+N_vp}) + +#### Seeding the per-process RNGs + +The per-process RNGs are seeded by a list of \\(N\_{vp}\\) +positive integers: + + nest.SetKernelStatus({’rng_seeds’ : range(msd+N_vp+1, msd+2*N_vp+1)}) + +### Choosing the random generator type + +Python and NumPy have the [MersenneTwister MT19937ar](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html) +random number generator built in. There is no simple way of choosing a different +generator in NumPy, but as the MT19937ar appears to be a very robust generator, +this should not cause significant problems. + +NEST uses by default Knuth's lagged Fibonacci random number generator (The Art +of Computer Programming, vol 2, 3rd ed, 9th printing or later, ch 3.6). If you +want to use other generators, you can exchange them as described below. If you +have built NEST without the GNU Science Library (GSL), you will only have the +Mersenne Twister MT19937ar and Knuth's lagged Fibonacci generator available. +Otherwise, you will also have some 60 generators from the GSL at your disposal +(not all of them particularly good). You can see the full list of RNGs using + + nest.sli_run('rngdict info') + +#### Setting a different global RNG + +To set a different global RNG in NEST, you have to pass a NEST random number +generator object to the NEST kernel. This can currently only be done by writing +some SLI code. The following code replaces the current global RNG with MT19937 +seeded with 101: + + nest.sli_run('0 << /grng rngdict/MT19937 :: 101 CreateRNG >> SetStatus') + +The following happens here: + +- `rngdict/MT19937 ::` fetches a "factory" for MT19937 from the `rngdict` + +- `101 CreateRNG` uses the factory to create a single MT19937 generator with + seed 101 + +- This is generator is then passed to the `/grng` status variable of the + kernel. This is a "write only" variable that is invisible in + `GetKernelStatus()`. + +#### Setting different per-processes RNGs + +One always needs to exchange all \\(N\_{vp}\\) per-process RNGs at once. This is +done by (assuming \\(N\_{vp}=2\\) ): + + nest.sli_run('0 << /rngs [102 103] { rngdict/MT19937 :: exch CreateRNG } Map >> SetStatus') + +The following happens here: + +- `[102 103] { rngdict/MT19937 :: exch CreateRNG } Map` creates an array of + two RNG objects seeded with 102 and 103, respectively. + +- This array is then passed to the `/rngs` status variable of the kernel. + This variable is invisible as well. + +Examples +-------- + +**NOTE: These examples are not yet updated for NEST 2.4** + +### No random variables in script + +If no explicit random variables appear in your script, i.e., if randomness only +enters in your simulation through random stimulus generators such as +`poisson_generator` or randomized connection routines such as +`RandomConvergentConnect`, you do not need to worry about anything except +choosing and setting your random seeds, possibly exchanging the random number +generators. + +### Randomizing the membrane potential + +If you want to randomize the membrane potential (or any other property of a +neuron), you need to take care that each node is updated by the process on which +it is local using the per-VP RNG for the VP to which the node belongs. +This is achieved by the following code + + pyrngs = [numpy.random.RandomState(s) for s in range(msd, msd+N_vp)] + nodes = nest.Create('iaf_psc_delta', 10) + node_info = nest.GetStatus(nodes) + local_nodes = [(ni['global_id'], ni['vp']) for ni in node_info if ni['local']] + for gid,vp in local_nodes: + nest.SetStatus([gid], {'V_m': pyrngs[vp].uniform(-70.0, -50.0)}) + +The first line generates \\([N\_{vp}\\) properly seeded NumPy RNGs as discussed +above. The next line creates 10 nodes, while the third line extracts status +information about each node. For local nodes, this will be full information, +for non-local nodes we only get the following fields: +`local`, `model` and `type`. On the fourth line, we create a list of tuples, +containing global ID and virtual process number for all local neurons. The for +loop then sets the membrane potential of each local neuron drawn from a uniform +distribution on \\(\[-70, -50\]\\) using the Python-side RNG for the VP to which +the neuron belongs. + +### Randomizing convergent connections + +We continue the above example by creating random convergent connections, +\\(C\_E\\) connections per target node. In the process, we randomize the +connection weights: + + C_E = 10 + nest.CopyModel("static_synapse", "excitatory") + for tgt_gid, tgt_vp in local_nodes: + weights = pyrngs[tgt_vp].uniform(0.5, 1.5, C_E) + nest.RandomConvergentConnect(nodes, [tgt_gid], C_E, + weight=list(weights), delay=2.0, + model="excitatory") + +Here we loop over all local nodes considered as target nodes. For each target, +we create an array of \\(C\_E\\) randomly chosen weights, uniform on +\\([0.5, 1.5\\. We then call `RandomConvergentConnect()` with this weight list +as argument. Note a few details: + +- We need to put `tgt_gid` into brackets as PyNEST functions always expect + lists of GIDs. + +- We need to convert the NumPy array `weights` to a plain Python list, as most + PyNEST functions currently cannot handle array input. + +- If we specify `weight`, we must also provide `delay`. + +You can check the weights selected by + + print nest.GetStatus(nest.GetConnections(), ['source', 'target', 'weight']) + +which will print a list containing a triple of source GID, target GID and weight +for each connection in the network. If you want to see only a subset of +connections, pass source, target, or synapse model to `GetConnections()`. + +### Randomizing divergent connections + +Randomizing the weights (or delays or any other properties) of divergent +connections is more complicated than for convergent connections, because the +target for each connection is not known upon the call to +`RandomDivergentConnect`. We therefore need to first create all connections +(which we can do with a single call, passing lists of nodes and targets), and +then need to manipulate all connections. This is not only more complicated, +but also significantly slower than the example above. + + nest.CopyModel('static_synapse', 'inhibitory', {'weight': 0.0, 'delay': 3.0}) + nest.RandomDivergentConnect(nodes, nodes, C_E, model='inhibitory') + gid_vp_map = dict(local_nodes) + for src in nodes: + conns = nest.GetConnections(source=[src], synapse_model='inhibitory') + tgts = [conn[1] for conn in conns] + rweights = [{'weight': pyrngs[gid_vp_map[tgt]].uniform(-2.5, -0.5)} + for tgt in tgts] + nest.SetStatus(conns, rweights) + +In this code, we first create all connections with weight 0. We then create +`gid_vp_map`, mapping GIDs to VP number for all local nodes. For each node +considered as source, we then find all outgoing excitatory connections from that +node and then obtain a flat list of the targets of these connections. For each +target we then choose a random weight as above, using the RNG pertaining to the +VP of the target. Finally, we set these weights. Note that the code above is +**slow**. Future versions of NEST will provide better solutions. + +### Testing scripts randomizing node or connection parameters + +To ensure that you are consistently using the correct RNG for each node or +connection, you should run your simulation several times the same \\(N\_{vp}\\), +but using different numbers of MPI processes. To this end, add towards the +beginning of your script + + nest.SetKernelStatus({"total_num_virtual_procs": 4}) + +and ensure that spikes are logged to file in the current working directory. +Then run the simulation with different numbers of MPI processes in separate +directories + + mkdir 41 42 44 + cd 41 + mpirun -np 1 python test.py + cd ../42 + mpirun -np 2 python test.py + cd ../44 + mpirun -np 4 python test.py + cd .. + +These directories should now have identical content, something you can check +with `diff`: + + diff 41 42 + diff 41 44 + +These commands should not generate any output. Obviously, this test checks only +a necessary, by no means a sufficient condition for a correct simulation (Oh +yes, do make sure that these directories contain data! Nothing easier that to +pass a diff-test on empty dirs.) diff --git a/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md b/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md index 4017f19d8b..15b5fff851 100644 --- a/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md +++ b/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md @@ -15,7 +15,7 @@ In contrast to the update of nodes, an event-driven approach is used for the synapses, meaning that they are only updated when an event is transmitted through them ([Morrison et al. 2005](http://dx.doi.org/10.1162/0899766054026648)). To speed up the simulation and allow the efficient use of computer clusters, -NEST uses a [hybrid parallelization strategy](../parallel_computing/index.html). +NEST uses a [hybrid parallelization strategy](../parallel-computing.md). The following figure shows the basic loop that is run upon a call to `Simulate`: ![Simulation Loop](../../img/simulation_loop-241x300.png) @@ -80,6 +80,6 @@ of NEST (large *dmax*). Related topics -------------- -Please see the [FAQ on precise spike time neurons](../qa-precise-spike-times/index.html) -for details about neuron update in continuous time and the [documentation on connection management](../connection_management/index.html) +Please see the [FAQ on precise spike time neurons](../qa-precise-spike-times.md) +for details about neuron update in continuous time and the [documentation on connection management](../connection-management.md) for how to set the delay when creating synapses. diff --git a/extras/userdoc/md/documentation/simulations-with-precise-spike-times.md b/extras/userdoc/md/documentation/simulations-with-precise-spike-times.md index 64ed14deea..4b7fd146eb 100644 --- a/extras/userdoc/md/documentation/simulations-with-precise-spike-times.md +++ b/extras/userdoc/md/documentation/simulations-with-precise-spike-times.md @@ -2,7 +2,7 @@ Simulations with precise spike times ==================================== The simulation resolution *h* and the minimum synaptic transmission delay -*dmin* define the two major time intervals of the [scheduling and simulation flow of NEST](../scheduling-and-simulation-flow/index.html): +*dmin* define the two major time intervals of the [scheduling and simulation flow of NEST](../scheduling-and-simulation-flow.md): neurons update their state variables in steps of *h*, whereas spikes are communicated and delivered to their targets in steps of *dmin*, where *dmin* is a multiple of *h*. @@ -89,4 +89,4 @@ Questions and answers about precise neurons During the review process of the above mentioned papers, we came up with a list of questions and answers pertaining to the implementation and usage of precise -spiking neurons. This list can be found [here](../qa-precise-spike-times/index.html). +spiking neurons. This list can be found [here](../qa-precise-spike-times.md). diff --git a/extras/userdoc/md/documentation/using-files-and-keyboard-input.md b/extras/userdoc/md/documentation/using-files-and-keyboard-input.md new file mode 100644 index 0000000000..ee9a5749ae --- /dev/null +++ b/extras/userdoc/md/documentation/using-files-and-keyboard-input.md @@ -0,0 +1,159 @@ +Using files and keyboard input +============================== + +Overview +--------- + +SLI's input/output fascilities differ from those of PostScript and are close to +the stream concept of C++. However, for compatibility some PostScript output +commands are implemented. + +Like in C++, files are represented as *streams*, which can be put on the stack. +All i/o commands leave their stream argument on the stack, so that operations +can be chained. + +### Example + +Print *Hello World* to the standard output. + + SLI ] cout (Hello World) <- endl + Hello World + SLI [1] ; + SLI ] + +`cout` is the standard output of SLI. The command `<-` takes the role of C++'s +`<<` output operator and prints the ASCII representation of the object at stack +level 0 to the stream at level 1. After this, the object is removed and the +stream remains at level 0. + +The command `endl` corresponds to the C++ manipulator of the same name. It +prints an end of line character to the stream at level 0. Again, it leaves the +stream argument on the stack. + +Now, the abbreviated form of `pop`, i.e. the command `;`, is used to remove the +stream object from the stack. + +Standard streams +----------------- + +The standard streams of a UNIX program are mapped to the following names. Note +that these streams should not be closed by a SLI program, since the result is +undefined. + +Name +Description +`cin` +Standart input stream. +`cout` +Standart output stream. +`cerr` +Standart error output stream. + +Opening and closing a stream +---------------------------- + +Streams are objects which handle the input and output of data to or from some +external target. The target of a stream can be a file, a string, a devide, or +another process. + +Command +Description +`(name) (r) file` +Open file for reading. +`(name) ifstream` +Open file for reading. +`(name) (w) file` +Open file for writing. +`(name) ofstream` +Open file for writing. +`(string) istrstream` +Open string-stream for reading. +`(string) ostrstream` +Open string-stream for writing. +`strstream` +Extract a string from a string-stream. +`stream close` +Close the stream. + +Writing to streams +------------------ + +Command +Description +`stream obj <-` +Print ASCII representation of `obj` to `stream`. +`stream obj <--` +Print detailed ASCII representation of `obj` to `stream`. +`stream obj =` +Print ASCII representation of `obj` to `cout`. +`stream obj ==` +Print detailed ASCII representation of `obj` to `cout`. + +### Example + +Print *Hello World* to a text file. + + SLI ] (test.txt) (w) file + SLI [1] (Hello World!) <- + SLI [1] endl + SLI [1] ; + +Manipulators +------------- + +Manipulators are used to manipulate the state of a stream object. Such changes +can, for instance, affect the precision with which numbers are printed. + +Manipulators take one or more arguments. In general, the manipulator leaves the +stream object at the top of the stack and removes all other arguments. + +Manipulator +Description +`ofstream flush` +Write contents of buffer to file. +`ofstream endl` +Line terminator. +`osstream ends` +char[] string terminator. +`ifstream ws` +Eat white-spaces. +`ofstream boolalpha` +Prints bool as true/false. +`ofstream noboolalpha` +Opposite. +`fstream n setw` +Set width of input/output fields to `n`. +`stream (c) setfill` +Defines a fill symbol `c` for the field. +`ostream left` +Allign to left of the field. +`ostream right` +Allign to right of the field. +`ostream internal` +Sign left and number right. +`ostream showpos` +Print positive sign. +`ostream noshowpos` +Opposite. +`stream uppercase` +`ostream nouppercase` +`ostream oct` +Switch to octal notation. +`ostream dec` +Switch to decimal notation. +`ostream hex` +Switch to hexadecimal notation. +`ostream showbase` +Show base according to use of oct/dec/hex. +`ostream noshowbase` +Don't show base according to use of oct/dec/hex. +`ostream showpoint` +Decimal point is always printed. +`ostream noshowpoint` +Decimal point is never printed. +`ostream n setprecision` +Set number of decimal places to `n`. +`ostream fixed` +Use fixed point notation. +`ostream scientific` +Use scientific notation. diff --git a/extras/userdoc/md/documentation/using-nest-with-music.md b/extras/userdoc/md/documentation/using-nest-with-music.md new file mode 100644 index 0000000000..3b9254ea00 --- /dev/null +++ b/extras/userdoc/md/documentation/using-nest-with-music.md @@ -0,0 +1,307 @@ +Using NEST with MUSIC +===================== + + Introduction +------------- + +NEST supports the [MUSIC interface](http://software.incf.org/software/music), a +standard by the INCF, which allows the transmission of data between applications +at runtime. It can be used to couple NEST with other simulators, with +applications for stimulus generation and data analysis and visualization and +with custom applications that also use the MUSIC interface. + +Basically, all communication with MUSIC is mediated via *proxies* that +receive/send data from/to remote applications using MUSIC. Different proxies are +used for the different types of data. At the moment, NEST supports sending and +receiving spike events and receiving continuous data and string messages. + +### Publication + +The implementation of the MUSIC interface for NEST is published as +*Mikael Djurfeldt, Johannes Hjorth, Jochen Martin Eppler, Niraj Dudani, +Moritz Helias, Tobias C Potjans, Upinder S Bhalla, Markus Diesmann, +Jeanette Hellgren Kotaleski, and Örjan Ekeberg. Run-time interoperability +between neuronal simulators based on the MUSIC framework. +Neuroinformatics, 8, 2010. doi:10.1007/s12021-010-9064-z* and available from [here](http://www.springerlink.com/content/r6j425027lmv1251/). + +Sending and receiving spike events +----------------------------------- + +A minimal example for the exchange of spikes between two independent instances +of NEST is given in the example `examples/nest/music/minimalmusicsetup.music`. +It uses one [SLI script](../an-introduction-to-sli.md "An Introduction +to SLI"), which sends spikes using a `music_event_out_proxy` and one SLI script, +which receives the spikes using a `music_event_in_proxy`. The configuration file +is shown in the following listing: + + [from] + binary=nest + np=1 + args=minimalmusicsetup_sendnest.sli + + [to] + binary=nest + np=1 + args=minimalmusicsetup_receivenest.sli + from.spikes_out -> to.spikes_in [1] + +This configuration file sets up two applications, `from` and `to`, which are +both instances of `NEST`. The first runs a script to send spike events on the +MUSIC port `spikes_out` to the second, which receives the events on the port +`spikes_in`. The width of the port is 1. The content of +`minimalmusicsetup_sendnest.sli` is contained in the following listing: + + /spike_generator Create /sg Set + sg << /spike_times [1.0 1.5 2.0 ]>> SetStatus + /iaf_neuron Create /n Set + sg n << /weight 750.0 >> Connect + /voltmeter Create /vm Set + vm << /to_memory false /to_screen true >> SetStatus + vm n Connect + /music_event_out_proxy Create /meop Set + meop << /port_name (spikes_out) >> SetStatus + sg meop << /music_channel 0 >> Connect + 10 Simulate + +Line 1 creates a `spike_generator`, which sends three spikes. The spike times +are specified in line 2. The script then creates an `iaf_neuron` in line 3 and +connects the `spike_generator` to the `iaf_neuron` in line 4. The membrane +potential of the `iaf_neuron` is measured by a `voltmeter`, which is created in +line 5 and set to print the measured values in line 6. The connection between +the `voltmeter` and the `iaf_neuron` is established in line 7. Line 8 creates a +`music_event_out_proxy`, which forwards the spikes it receives directly to the +MUSIC event output port `spikes_out` (set in line 9). The `spike_generator` is +connected to the MUSIC channel 0 on the `music_event_out_proxy` in line 10. +Finally, the network is simulated for 10 miliseconds. + +The next listing contains the content of `minimalmusicsetup_receivenest.sli`: + +/music_event_in_proxy Create /meip Set +meip << /port_name (spikes_in) /music_channel 0 >> SetStatus +/iaf_neuron Create /n Set +meip n << /weight 750.0 >> Connect +/voltmeter Create /vm Set +vm << /to_memory false /to_screen true >> SetStatus +vm n Connect +10 Simulate + +Running the example using `mpirun -np 2 music minimalmusicsetup.music` yields +the following output, which shows that the neurons in both processes receive the +same input from the `spike_generator` in the first NEST process and show the +same membrane potential trace. + + NEST v1.9.svn (C) 1995-2008 The NEST Initiative + -70 + -70 + -68.1559 + -61.9174 + -70 + -70 + -70 + -65.2054 + -62.1583 + + NEST v1.9.svn (C) 1995-2008 The NEST Initiative + -70 + -70 + -68.1559 + -61.9174 + -70 + -70 + -70 + -65.2054 + -62.1583 + +Receiving string messages +--------------------------- + +Currently, NEST is only able to receive, but not to send string messages. We +thus use MUSIC's `messagesource` program for the generation of messages in the +following example. The configuration file (`msgtest.music`) is shown in the +following listing: + + stoptime=1.0 + np=1 + [from] + binary=messagesource + args=messages + [to] + binary=./msgtest.py + + from.out -> to.msgdata [0] + +This configuration file connects MUSIC's `messagesource` program to the port +`msgdata` of a NEST instance. The `messagesource` program needs a data file, +which contains the messages and the corresponding time stamps. The data file +(`messages0.dat`) is shown in the following listing: + + 0.3 Hello + 0.7  ! + +Please note that MUSIC uses a default unit of seconds for the specification of +times, while NEST uses miliseconds. The example uses the [PyNEST](../introduction-to-pynest.md "PyNEST") +syntax instead of SLI for the NEST part. The script that sets up the receiving +side (`msgtest.py`) of the exampe is shown in the following listing: + + #!/usr/bin/python + + import nest + + mmip = nest.Create ('music_message_in_proxy') + nest.SetStatus (mmip, {'port_name' : 'msgdata'}) + + # Simulate and get message data with a granularity of 10 ms: + time = 0 + while time < 1000: + nest.Simulate (10) + data = nest.GetStatus(mmip, 'data') + print data + time += 10 + + +We first import the `nest` in line 2 and create an instance of the +`music_message_in_proxy` in line 3. In line 4, we set the name of the port it +listens to to `msgdata`. Lines 6 through 11 simulate the network in steps of +10 ms. Running the example using `mpirun -np 2 music msgtest.music` yields the +following output: + + -- N E S T 2 beta -- + Neural Simulation Tool + Copyright 1995-2009 The NEST Initiative + Version 1.9-svn Sep 22 2010 16:50:01 + + This program is provided AS IS and comes with + NO WARRANTY. See the file LICENSE for details. + + Problems or suggestions? + Website  : http://www.nest-initiative.org + Mailing list: nest_user@nest-initiative.org + + Type 'nest.help()' to find out more about NEST. + + Sep 23 16:09:12 Simulate [Info]: + Simulating 10 ms. + + Sep 23 16:09:12 Scheduler::prepare_nodes [Info]: + Please wait. Preparing elements. + + Sep 23 16:09:12 music_message_in_proxy::calibrate() [Info]: + Mapping MUSIC input port 'msgdata' with width=0 and acceptable latency=0 + ms. + + Sep 23 16:09:12 Scheduler::prepare_nodes [Info]: + Simulating 1 nodes. + + Sep 23 16:09:12 Scheduler::resume [Info]: + Entering MUSIC runtime with tick = 0.1 ms + + Sep 23 16:09:12 Scheduler::resume [Info]: + Simulation finished. + [{'messages': [], 'message_times': array([], dtype=float64)}] + + : + + Sep 23 16:13:36 Simulate [Info]: + Simulating 10 ms. + + Sep 23 16:13:36 Scheduler::prepare_nodes [Info]: + Please wait. Preparing elements. + + Sep 23 16:13:36 Scheduler::prepare_nodes [Info]: + Simulating 1 nodes. + + Sep 23 16:13:36 Scheduler::resume [Info]: + Simulation finished. + [{'messages': ['Hello', '!'], 'message_times': array([ 300., 700.])}] + +Receiving continuous data +-------------------------- + +As in the case of string message, NEST currently only supports receiving +continuous data, but not sending. This means that we have to use another of +MUSIC's test programs to generate the data for us. This time, we use +`constsource`, which generates a sequence of numbers form 0 to w, where w is the +width of the port. The MUSIC configuration file (`conttest.music`) is shown in +the following listing: + + stoptime=1.0 + [from] + np=1 + binary=constsource + [to] + np=1 + binary=./conttest.py + + from.contdata -> to.contdata [10] + +The receiving side is again implemented using a [PyNEST](/introduction-to-pynest.md "PyNEST") +script (`conttest.py`): + + #!/usr/bin/python + + import nest + + mcip = nest.Create('music_cont_in_proxy') + nest.SetStatus(mcip, {'port_name' : 'contdata'}) + + # Simulate and get vector data with a granularity of 10 ms: + time = 0 + while time < 1000: + nest.Simulate (10) + data = nest.GetStatus (mcip, 'data') + print data + time += 10 + +We first import the nest in line 2 and create an instance of the +music\_cont\_in\_proxy in line 3. In line 4, we set the name of the port it +listens to to msgdata. Lines 6 through 11 simulate the network in steps of +10 ms. Running the example using `mpirun -np 2 music conttest.music` yields the +following output: + + -- N E S T 2 beta -- + Neural Simulation Tool + Copyright 1995-2009 The NEST Initiative + Version 1.9-svn Sep 22 2010 16:50:01 + + This program is provided AS IS and comes with + NO WARRANTY. See the file LICENSE for details. + + Problems or suggestions? + Website  : http://www.nest-initiative.org + Mailing list: nest_user@nest-initiative.org + + Type 'nest.help()' to find out more about NEST. + + Sep 23 16:49:09 Simulate [Info]: + Simulating 10 ms. + + Sep 23 16:49:09 Scheduler::prepare_nodes [Info]: + Please wait. Preparing elements. + + Sep 23 16:49:09 music_cont_in_proxy::calibrate() [Info]: + Mapping MUSIC input port 'contdata' with width=10. + + Sep 23 16:49:09 Scheduler::prepare_nodes [Info]: + Simulating 1 nodes. + + Sep 23 16:49:09 Scheduler::resume [Info]: + Entering MUSIC runtime with tick = 0.1 ms + + Sep 23 16:49:09 Scheduler::resume [Info]: + Simulation finished. + [array([ 0., 1., 2., 3., 4., 5., 6., 7., 8., 9.])] + + : + + Sep 23 16:47:24 Simulate [Info]: + Simulating 10 ms. + + Sep 23 16:47:24 Scheduler::prepare_nodes [Info]: + Please wait. Preparing elements. + + Sep 23 16:47:24 Scheduler::prepare_nodes [Info]: + Simulating 1 nodes. + + Sep 23 16:47:24 Scheduler::resume [Info]: + Simulation finished. + [array([ 0., 1., 2., 3., 4., 5., 6., 7., 8., 9.])] From ac06d0f425a942c1171a4cbec17c8e0128860827 Mon Sep 17 00:00:00 2001 From: steffen Date: Wed, 25 May 2016 08:19:03 +0200 Subject: [PATCH 02/20] renamed --- .../documentation/an_introduction_to_sli.md | 86 --- .../analog_recording_with_multimeter.md | 97 --- .../md/documentation/connection_management.md | 603 ------------------ .../documentation/continuous_integration.md | 129 ---- .../userdoc/md/documentation/first_steps.md | 169 ----- .../frequently_asked_questions.md | 78 --- .../md/documentation/getting_started.md | 53 -- .../md/documentation/neural_simulations.md | 466 -------------- .../documentation/objects_and_data_types.md | 211 ------ .../md/documentation/parallel_computing.md | 222 ------- .../md/documentation/programming_in_sli.md | 313 --------- .../md/documentation/random_numbers.md | 454 ------------- .../using_files_and_keyboard_input.md | 159 ----- .../md/documentation/using_nest_with_music.md | 307 --------- pynest/examples/sinusoidal_gamma_generator.py | 3 +- 15 files changed, 2 insertions(+), 3348 deletions(-) delete mode 100644 extras/userdoc/md/documentation/an_introduction_to_sli.md delete mode 100644 extras/userdoc/md/documentation/analog_recording_with_multimeter.md delete mode 100644 extras/userdoc/md/documentation/connection_management.md delete mode 100644 extras/userdoc/md/documentation/continuous_integration.md delete mode 100644 extras/userdoc/md/documentation/first_steps.md delete mode 100644 extras/userdoc/md/documentation/frequently_asked_questions.md delete mode 100644 extras/userdoc/md/documentation/getting_started.md delete mode 100644 extras/userdoc/md/documentation/neural_simulations.md delete mode 100644 extras/userdoc/md/documentation/objects_and_data_types.md delete mode 100644 extras/userdoc/md/documentation/parallel_computing.md delete mode 100644 extras/userdoc/md/documentation/programming_in_sli.md delete mode 100644 extras/userdoc/md/documentation/random_numbers.md delete mode 100644 extras/userdoc/md/documentation/using_files_and_keyboard_input.md delete mode 100644 extras/userdoc/md/documentation/using_nest_with_music.md diff --git a/extras/userdoc/md/documentation/an_introduction_to_sli.md b/extras/userdoc/md/documentation/an_introduction_to_sli.md deleted file mode 100644 index e0d19688da..0000000000 --- a/extras/userdoc/md/documentation/an_introduction_to_sli.md +++ /dev/null @@ -1,86 +0,0 @@ -An Introduction to SLI -====================== - -Introduction ------------- - -NEST can be started by typing - - /bin/nest - -at the command prompt. You should then see something like this: - gewaltig@jasmin-vm:~$ nest - -- N E S T 2 beta -- - - Copyright 1995-2009 The NEST Initiative - Version 1.9-svn Feb 6 2010 00:33:50 - - This program is provided AS IS and comes with - NO WARRANTY. See the file LICENSE for details. - - Problems or suggestions? - Website  : http://www.nest-initiative.org - Mailing list: nest_user@nest-initiative.org - - Type 'help' to get more information. - Type 'quit' or CTRL-D to quit NEST. - -Command line switches ---------------------- - -Type - - nest --help - -to find out about NEST's command-line parameters. - - gewaltig@jasmin-vm:~$ nest --help - usage: nest [options] [file ..] - -h --help print usage and exit - -v --version print version information and exit. - - - --batch read input from a stdin/pipe - --userargs=arg1:... put user defined arguments in statusdict::userargs - -d --debug start in debug mode (implies --verbosity=ALL) - --verbosity=ALL turn on all messages. - --verbosity=DEBUG|STATUS|INFO|WARNING|ERROR|FATAL - show messages of this priority and above. - --verbosity=QUIET turn off all messages. - -### Supplying SLI scripts with parameters - -Using the `--userargs=arg1:...` command line switch, it is possible to supply a -SLI script with parameters from the outside of NEST. A common use case for this -are parameter sweeps, where the parameters are defined in a bash script and -multiple instances of NEST are used to test one parameter each. -A bash script for this could look like this: - - for lambda in `seq 1 20`; do - for gamma in `seq 1 5`; do - nest --userargs=lambda=$lambda:$gamma=$gamma simulation.sli - done - done - -The corresponding SLI script `simulation.sli` could use the supplied parameters -like this: - - /args mark statusdict/userargs :: {(=) breakup} Map { arrayload pop int exch cvlit exch } forall >> def - args /lambda get == - -The first line first gets the array of user supplied arguments (`userargs`) from -the `statusdict` and breaks each element at the "="-symbol. It then converts the -first element (lambda, gamma) to a literal and the second argument (the number) -to an integer. Using `mark` and `>>`, the content of the userargs array is added -to a dictionary, which is stored under the name `args`. The second line just -prints the content of the lamda variable. - -SLI user manual ---------------- - -This manual gives a brief overview of the SLI programming language. - -1. [First Steps](first_steps.md "First Steps") -2. [Objects and data types](objects_and_data_types.md "Objects and data types") -3. [Programming in SLI](programming_in_sli.md "Programming in SLI") -4. [Using files and keyboard input](using_files_and_keyboard_input.md "Using files and keyboard input") -5. [Neural simulations](neural_simulations.md "Neural simulations") diff --git a/extras/userdoc/md/documentation/analog_recording_with_multimeter.md b/extras/userdoc/md/documentation/analog_recording_with_multimeter.md deleted file mode 100644 index f01480b3a3..0000000000 --- a/extras/userdoc/md/documentation/analog_recording_with_multimeter.md +++ /dev/null @@ -1,97 +0,0 @@ -Analog recording with multimeter -================================ - -As of r89xx, NEST replaces a range of analog recording devices, such as -voltmeter, conductancemeter and aeif\_w\_meter with a universal *multimeter*, -which can record all analog quantities a model neuron makes available for -recording. -Multimeter works essentially as the old-style voltmeter, but with a few changes: - -- The `/recordables` list of a neuron model will tell you which quantities - can be recorded: - - In [3]: nest.GetDefaults('iaf_cond_alpha')['recordables'] - Out[3]: ['V_m', 'g_ex', 'g_in', 't_ref_remaining'] - - -- You have to configure multimeter to record from a set of quantities: - - nest.Create('multimeter', params={'record_from': ['V_m', 'g_ex']}) - - -- By default, the recording interval is 1ms, but you can change this - - nest.Create('multimeter', params={'record_from': ['V_m', 'g_ex'], 'interval' :0.1}) - -- The set of variables to record and the recording interval must be set - **before** the multimeter is connected to any node, and cannot be changed - afterwards. - -- After one has simulated a little, the `events` entry of the multimeter - status dictionary will contain one numpy array of data for each recordable. - -- Any node can only be recorded from by one multimeter. - -Adapting scripts using voltmeter --------------------------------- - -Many NEST users have scripts that use voltmeter to record membrane potential. -To ease the transition to the new-style analog recording, NEST still provides a -device called `voltmeter`. It is simply a multimeter pre-configured to record -the membrane potential `V_m`. It can be used exactly as the old voltmeter. -The only change you need to make to your scripts is that you collect data from -events/V\_m instead of from events/potentials, e.g. - - In [24]: nest.GetStatus(m, 'events')[0]['V_m'] - - Out[24]: - array([-70. , -70. , -70. , -70. , - -70. , -70. , -70. , -70. , - -An example ----------- - -As an example, here is the multimeter.py example from the PyNEST examples set: - - import nest - import numpy as np - import pylab as pl - - # display recordables for illustration - print 'iaf_cond_alpha recordables: ', nest.GetDefaults('iaf_cond_alpha')['recordables'] - - # create neuron and multimeter - n = nest.Create('iaf_cond_alpha', params = {'tau_syn_ex': 1.0, 'V_reset': -70.0}) - - m = nest.Create('multimeter', params = {'withtime': True, 'interval': 0.1, 'record_from': ['V_m', 'g_ex', 'g_in']}) - - # Create spike generators and connect - gex = nest.Create('spike_generator', params = {'spike_times': np.array([10.0, 20.0, 50.0])}) - gin = nest.Create('spike_generator', params = {'spike_times': np.array([15.0, 25.0, 55.0])}) - - nest.Connect(gex, n, params={'weight': 40.0}) # excitatory - nest.Connect(gin, n, params={'weight': -20.0}) # inhibitory - nest.Connect(m, n) - - # simulate - nest.Simulate(100) - - # obtain and display data - events = nest.GetStatus(m)[0]['events'] - t = events['times']; - - pl.subplot(211) - pl.plot(t, events['V_m']) - pl.axis([0, 100, -75, -53]) - pl.ylabel('Membrane potential [mV]') - - pl.subplot(212) - pl.plot(t, events['g_ex'], t, events['g_in']) - pl.axis([0, 100, 0, 45]) - pl.xlabel('Time [ms]') - pl.ylabel('Synaptic conductance [nS]') - pl.legend(('g_exc', 'g_inh')) - -Here is the result: - -![MultimeterExample](../../img/MultimeterExample.png) diff --git a/extras/userdoc/md/documentation/connection_management.md b/extras/userdoc/md/documentation/connection_management.md deleted file mode 100644 index 75938a6794..0000000000 --- a/extras/userdoc/md/documentation/connection_management.md +++ /dev/null @@ -1,603 +0,0 @@ -Connection Management -===================== - -From NEST 2.4 onwards the old connection routines (i.e. -`(Random)ConvergentConnect`, `(Random)DivergentConnect` and plain `Connect`) are -replaced by one unified `Connect` function. In -[SLI](an_introduction_to_sli.md "An Introduction to SLI") -,the old syntax of the function still works, while in -[PyNEST](introduction-to-pynest.md "PyNEST"), the `Connect()` -function has been renamed to `OneToOneConnect()`. However, simple cases, which -are just creating one-to-one connections between two lists of nodes are still -working with the new command without the need to change the code. Note that the -topology-module is not effected by theses changes. The translation between the -old and the new connect routines is described in [Old Connection Routines](connection_management.md#Old-Connection-Routines). - -The connectivity pattern is defined inside the `Connect()` function under the -key 'rule'. The patterns available are described in -[Connection Rules](connection_management.md#Connection-Rules). In -addition the synapse model can be specified within the connect function and all -synaptic parameters can be randomly distributed. - -The `Connect()` function can be called in either of the following manners: - - Connect(pre, post) - Connect(pre, post, conn_spec) - Connect(pre, post, conn_spec, syn_spec) - -`pre` and `post` are lists of Global Ids defining the nodes of origin and -termination. - -`conn_spec` can either be a string containing the name of the connectivity rule -(default: 'all\_to\_all') or a dictionary specifying the rule and the -rule-specific parameters (e.g. 'indegree'), which must be given. - -In addition switches allowing self-connections ('autapses', default: True) and -multiple connections between pairs of neurons ('multapses', default: True) can -be contained in the dictionary. The validity of the switches is confined by the -Connect-call. Thus connecting the same set of neurons multiple times with the -switch 'multapses' set to False, one particular connection might be established -multiple times. The same applies to nodes being specified multiple times in the -source or target vector. Here 'multapses' set to False will result in one -potential connection between each occurring node pair. - -`syn_spec` defines the synapse type and its properties. It can be given as a -string defining the synapse model (default: 'static\_synapse') or as a -dictionary. By using the key-word variant (`Connect(pre, post, -syn_spec=syn_spec_dict)`), the conn\_spec can be omitted in the call to -connect and 'all\_to\_all' is assumed as the default. -The exact usage of the synapse dictionary is described in [Synapse Specification](connection_management.md#Synapse-Specification). - -Connection Rules ----------------- - -Connection rules are specified using the `conn_spec` parameter, which can be a -string naming a connection rule or a dictionary containing a rule specification. -Only connection rules requiring no parameters can be given as strings, for all -other rules, a dictionary specifying the rule and its parameters, such as in- -or out-degrees, is required. - -one-to-one ----------- - -The ith node in `pre` is connected to the ith node in -`post`. The node lists pre and post have to be of the same length. - -Example: - -![One\_to\_one](../../img/One_to_one.png) -one-to-one connections - - n = 10 - A = Create("iaf_neuron", n) - B = Create("spike_detector", n) - Connect(A, B, 'one_to_one') - -This rule can also take two Global IDs A and B instead of integer lists. A -shortcut is provided if only two nodes are connected with the parameters weight -and delay such that weight and delay can be given as third and fourth argument -to the Connect() function. - -Example: - - weight = 1.5 - delay = 0.5 - Connect(A[0], B[0], weight, delay) - -all-to-all ----------- - -![all-to-all connections](../../img/All_to_all.png) -all-to-all connections - -Each node in `pre` is connected to every node in `post`. Since 'all\_to\_all' is -the default, 'rule' doesn't need to specified. - -Example: - - n, m = 10, 12 - A = Create("iaf_neuron", n) - B = Create("iaf_neuron", m) - Connect(A, B) - -### fixed-indegree - -![fixed-indegree connections](../../img/Fixed_indegree.png) -fixed-indegree connections - -The nodes in `pre` are randomly connected with the nodes in `post` such that -each node in `post` has a fixed `indegree`. - -Example: - - n, m, N = 10, 12, 2 - A = Create("iaf_neuron", n) - B = Create("iaf_neuron", m) - conn_dict = {'rule': 'fixed_indegree', 'indegree': N} - Connect(A, B, conn_dict) - -#### fixed-outdegree - -![Fixed\_outdegree](../../img/Fixed_outdegree.png) -fixed-outdegree connections - -The nodes in `pre` are randomly connected with the nodes in `post` such that -each node in `pre` has a fixed `outdegree`. - -Example: - - n, m, N = 10, 12, 2 - A = Create("iaf_neuron", n) - B = Create("iaf_neuron", m) - conn_dict = {'rule': 'fixed_outdegree', 'outdegree': N} - Connect(A, B, conn_dict) - -#### fixed-total-number - -The nodes in `pre` are randomly connected with the nodes in `post` such that the -total number of connections equals `N`. - -Example: - - n, m, N = 10, 12, 30 - A = Create("iaf_neuron", n) - B = Create("iaf_neuron", m) - conn_dict = {'rule': 'fixed_total_number', 'N': N} - Connect(A, B, conn_dict) - -#### pairwise-bernoulli - -For each possible pair of nodes from `pre` and `post`, a connection is created -with probability `p`. - -Example: - - n, m, p = 10, 12, 0.2 - A = Create("iaf_neuron", n) - B = Create("iaf_neuron", m) - conn_dict = {'rule': 'pairwise_bernoulli', 'p': p} - Connect(A, B, conn_dict) - -### Synapse Specification - -The synapse properties can be given as a string or a dictionary. The string can -be the name of a pre-defined synapse which can be found in the synapsedict (see -[Synapse Types](connection_management.md#Synapse-Types)) or a -manually defined synapse via `CopyModel()`. - -Example: - - n = 10 - A = Create("iaf_neuron", n) - B = Create("iaf_neuron", n) - CopyModel("static_synapse","excitatory",{"weight":2.5, "delay":0.5}) - Connect(A, B, syn_spec="excitatory") - -Specifying the synapse properties in a dictionary allows for distributed -synaptic parameter. -In addition to the key 'model' the dictionary can contain specifications for -'weight', 'delay', 'receptor\_type' and parameters specific to the chosen -synapse model. The specification of all parameters is optional. Unspecified -parameters will use the default values determined by the current synapse model. -All parameters can be scalars, arrays or distributions (specified as -dictionaries). One synapse dictionary can contain an arbitrary combination of -parameter types, as long as they agree with the connection routine ('rule'). - -**Scalar** parameters must be given as floats except for the 'receptor\_type' -which has to be initialized as an integer. For more information on the receptor -type see [Receptor Types](connection_management.md#Synapse-Types) . - -Example: - - n = 10 - neuron_dict = {'tau_syn': [0.3, 1.5]} - A = Create("iaf_psc_exp_multisynapse", n, neuron_dict) - B = Create("iaf_psc_exp_multisynapse", n, neuron_dict) - syn_dict ={"model": "static_synapse", "weight":2.5, "delay":0.5, 'receptor_type': 1} - Connect(A, B, syn_spec=syn_dict) - -**Array** parameters can be used in conjunction with the rules 'one\_to\_one' -and 'all\_to\_all'. The arrays can be specified as numpy arrays or lists. As -for the scalar parameters, all parameters but the receptor types must be -specified as arrays of floats. For 'one\_to\_one' the array must have the same -length as the population vector. - -Example: - - A = Create("iaf_neuron", 2) - B = Create("spike_detector", 2) - conn_dict = {'rule': 'one_to_one'} - syn_dict = {'weight': [1.2, -3.5]} - Connect(A, B, conn_dict, syn_dict) - -When connecting using 'all\_to\_all', the array must be of dimension len(post) -x len(pre). - -Example: - - A = Create("iaf_neuron", 3) - B = Create("iaf_neuron", 2) - syn_dict = {'weight': [[1.2, -3.5, 2.5],[0.4, -0.2, 0.7]]} - Connect(A, B, syn_spec=syn_dict) - -**Distributed** parameters are initialized with yet another dictionary -specifying the 'distribution' and the distribution-specific parameters, whose -specification is optional. - -Available distributions are given in the rdevdict, the most common ones are: - -Distributions -Keys -'normal' -'mu', 'sigma' -'normal\_clipped' -'mu', 'sigma', 'low ', 'high' -'normal\_clipped\_to\_boundary' -'mu', 'sigma', 'low ', 'high' -'lognormal' -'mu', 'sigma' -'lognormal\_clipped' -'mu', 'sigma', 'low', 'high' -'lognormal\_clipped\_to\_boundary' -'mu', 'sigma', 'low', 'high' -'uniform' -'low', 'high' -'uniform\_int' -'low', 'high' -'binomial' -'n', 'p' -'binomial\_clipped' -'n', 'p', 'low', 'high' -'binomial\_clipped\_to\_boundary' -'n', 'p', 'low', 'high' -'gsl\_binomial' -'n', 'p' -'exponential' -'lambda' -'exponential\_clipped' -'lambda', 'low', 'high' -'exponential\_clipped\_to\_boundary' -'lambda', 'low', 'high' -'gamma' -'order', 'scale' -'gamma\_clipped' -'order', 'scale', 'low', 'high' -'gamma\_clipped\_to\_boundary' -'order', 'scale', 'low', 'high' -'poisson' -'lambda' -'poisson\_clipped' -'lambda', 'low', 'high' -'poisson\_clipped\_to\_boundary' -'lambda', 'low', 'high' -Example: - - n = 10 - A = Create("iaf_neuron", n) - B = Create("iaf_neuron", n) - syn_dict = {'model': 'stdp_synapse', - 'weight': 2.5, - 'delay': {'distribution': 'uniform', 'low': 0.8, 'high': 2.5}, - 'alpha': {'distribution': 'normal_clipped', 'low': 0.5, 'mu': 5.0, 'sigma': 1.0} - } - Connect(A, B, syn_spec=syn_dict) - -In this example, the 'all\_to\_all' connection rule is applied by default, using -the 'stdp\_synapse' model. All synapses are created with weight 2.5, a delay -uniformly distributed in [0.8, 2.5), while the alpha parameters is drawn from a -normal distribution with mean 5.0 and std.dev 1.0; values below 0.5 are excluded -by re-drawing any values below 0.5. Thus, the actual distribution is a slightly -distorted Gaussian. - -If the synapse is supposed to have a unique name and distributed parameters it -needs to be defined in two steps: - - n = 10 - A = Create("iaf_neuron", n) - B = Create("iaf_neuron", n) - CopyModel('static_synapse','excitatory',{'weight':2.5}) - syn_dict = {'model': 'excitatory', - 'weight': 2.5, - 'delay': {'distribution': 'uniform', 'low': 0.8, 'high': 2.5}, - 'alpha': {'distribution': 'normal_clipped', 'low': 0.5, 'mu': 5.0, 'sigma': 1.0} - } - Connect(A, B, syn_spec=syn_dict) - -For further information on the distributions see -[Random numbers in NEST](random_numbers.md "Random numbers in NEST"). - -Old Connection Routines ------------------------ - -The old connection routines are still available in NEST 2.4, apart from the old -`Connect()` which has been renamed to `OneToOneConnect()` and whose the support -will end with the next release. - -This section contains the documentation for the old connection routines and -provides a manual on how to convert the old connection routines to the new -`Connect()` function. -The new connection routine doesn't yet support arrays or lists as input -parameter other than `pre` and `post`. As a workaround we suggest to loop over -the arrays. - -### One-to-one connections - -![](../../img/One_to_one.png) -one-to-one connections - -`Connect(pre, post, params=None, delay=None, model='static_synapse')`: Make -one-to-one connections of type *model* between the nodes in *pre* and the nodes -in *post*. *pre* and *post* have to be lists of the same length. If *params* is -given (as dictionary or list of dictionaries), they are used as parameters for -the connections. If *params* is given as a single float or as list of floats, -it is used as weight(s), in which case *delay* also has to be given as float or -as list of floats. - -Example old connection routine: - - A = Create("iaf_neuron", 2) - B = Create("spike_detector", 2) - weight = [1.2, -3.5] - delay = [0.3, 0.5] - Connect(A, B, weight, delay) - -**Note:** Using `Connect()` with any of the variables `params`, `delay` and -`model` will break the code. As a temporary fix the function `OnToOneConnect()` -is provided which works in the same manner as the previous `Connect()`. However, -`OneToOneConnect()` won't be supported in the next release. - -Example temporary fix for old connection routine: - - A = Create("iaf_neuron", 2) - B = Create("spike_detector", 2) - weight = [1.2, -3.5] - delay = [0.3, 0.5] - OneToOneConnect(A, B, weight, delay) - -Example new connection routine: - - A = Create("iaf_neuron", 2) - B = Create("spike_detector", 2) - conn_dict = {'rule': 'one_to_one'} - syn_dict = {'weight': weight, 'delay', delay} - Connect(A, B, conn_dict, syn_dict) - -### Convergent connections - -![convergent connections](../../img/Convergent_connect.png) -convergent connections - -`ConvergentConnect(pre, post, weight=None, delay=None, model='static_synapse')`: -Connect all neurons in *pre* to each neuron in *post*. *pre* and *post* have to -be lists. If *weight* is given (as a single float or as list of floats), *delay* -also has to be given as float or as list of floats. - -Example old connection routine: - - A = Create("iaf_neuron", 2) - B = Create("spike_detector") - ConvergentConnect(A, B) - -Example new connection routine: - - A = Create("iaf_neuron", 2) - B = Create("spike_detector") - Connect(A, B) - -`RandomConvergentConnect(pre, post, n, weight=None, delay=None, -model='static_synapse')`: Connect *n* randomly selected neurons from *pre* to -each neuron in *post*. *pre* and *post* have to be lists. If *weight* is given -(as a single float or as list of floats), *delay* also has to be given as float -or as list of floats. - -Example old connection routine: - - option_dict = {'allow_autapses': True, 'allow_multapses': True} - model = 'my_synapse' - nest.RandomConvergentConnect(A, B, N, w0, d0, model, option_dict) - -Example new connection routine: - - conn_dict = {'rule': 'fixed_indegree', 'indegree': N, 'autapses': True, 'multapses': True} - syn_dict = {'model': 'my_synapse', 'weight': w0, 'delay': d0} - nest.Connect(A, B, conn_dict, syn_dict) - -### Divergent connections - -![Divergent\_connect](../../img/Divergent_connect.png) -divergent connections - -`DivergentConnect(pre, post, weight=None, delay=None, model='static_synapse')`: -Connect each neuron in *pre* to all neurons in *post*. *pre* and *post* have to -be lists. If *weight* is given (as a single float or as list of floats), *delay* -also has to be given as float or as list of floats. - -Example old connection routine: - - A = Create("iaf_neuron") - B = Create("spike_detector", 2) - DivergentConnect(A, B) - -Example new connection routine: - - A = Create("iaf_neuron") - B = Create("spike_detector", 2) - Connect(A, B) - -`RandomDivergentConnect(pre, post, n, weight=None, delay=None, -model='static_synapse')`: Connect each neuron in *pre* to *n* randomly selected -neurons from *post*. *pre* and *post* have to be lists. If *weight* is given (as -a single float or as list of floats), *delay* also has to be given as float or -as list of floats. - -Example old connection routine: - - option_dict = {'allow_autapses': True, 'allow_multapses': True} - model = 'my_synapse' - nest.RandomDivergentConnect(A, B, N, w0, d0, model, option_dict) - -Example new connection routine: - - conn_dict = {'rule': 'fixed_outdegree', 'outdegree': N, 'autapses': True, 'multapses': True} - syn_dict = {'model': 'my_synapse', 'weight': w0, 'delay': w0} - nest.Connect(A, B, conn_dict, syn_dict) - -Topological Connections ------------------------ - -If the connect functions above are not sufficient, the topology provides more -sophisticated functions. For example, it is possible to create receptive field -structures and much more! See -[Topological Connections](Topology_UserManual.pdf) -for more information. - -Receptor Types --------------- - -Each connection in NEST targets a specific receptor type on the post-synaptic -node. Receptor types are identified by integer numbers, the default receptor -type is 0. The meaning of the receptor type depends on the model and is -documented in the model documentation. To connect to a non-standard receptor -type, the parameter *receptor\_type* of the additional argument *params* is used -in the call to the `Connect` command. To illustrate the concept of receptor -types, we give an example using standard integrate-and-fire neurons as -presynaptic nodes and a multi-compartment integrate-and-fire neuron -(`iaf_cond_alpha_mc`) as post-synaptic node. - -![Receptor types](../../img/Receptor_types.png) -Receptor types - - A1, A2, A3, A4 = Create("iaf_neuron", 4) - B = Create("iaf_cond_alpha_mc") - receptors = GetDefaults("iaf_cond_alpha_mc")["receptor_types"] - print receptors - - {'soma_exc': 1, - 'soma_inh': 2, - 'soma_curr': 7, - 'proximal_exc': 3 - 'proximal_inh': 4, - 'proximal_curr': 8, - 'distal_exc': 5, - 'distal_inh': 6, - 'distal_curr': 9,} - - Connect([A1], B, syn_spec={"receptor_type": receptors["distal_inh"]}) - Connect([A2], B, syn_spec={"receptor_type": receptors["proximal_inh"]}) - Connect([A3], B, syn_spec={"receptor_type": receptors["proximal_exc"]}) - Connect([A4], B, syn_spec={"receptor_type": receptors["soma_inh"]}) - -The code block above connects a standard integrate-and-fire neuron to a somatic -excitatory receptor of a multi-compartment integrate-and-fire neuron model. The -result is illustrated in the figure. - -Synapse Types -------------- - -NEST supports multiple synapse types that are specified during connection setup. -The default synapse type in NEST is `static_synapse`. Its weight does not change -over time. To allow learning and plasticity, it is possible to use other synapse -types that implement long-term or short-term plasticity. A list of available -types is accessible via the command *Models("synapses")*. The output of this -command (as of revision 11199) is shown below: - - ['cont_delay_synapse', - 'ht_synapse', - 'quantal_stp_synapse', - 'static_synapse', - 'static_synapse_hom_wd', - 'stdp_dopamine_synapse', - 'stdp_facetshw_synapse_hom', - 'stdp_pl_synapse_hom', - 'stdp_synapse', - 'stdp_synapse_hom', - 'tsodyks2_synapse', - 'tsodyks_synapse'] - -All synapses store their parameters on a per-connection basis. An exception to -this scheme are the homogeneous synapse types (identified by the suffix -*\_hom*), which only store weight and delay once for all synapses of a type. -This means that these are the same for all connections. They can be used to -save memory. - -The default values of a synapse type can be inspected using the command -`GetDefaults()`, which takes the name of the synapse as an argument, and -modified with `SetDefaults()`, which takes the name of the synapse type and a -parameter dictionary as arguments. - - print GetDefaults("static_synapse") - - {'delay': 1.0, - 'max_delay': -inf, - 'min_delay': inf, - 'num_connections': 0, - 'num_connectors': 0, - 'receptor_type': 0, - 'synapsemodel': 'static_synapse', - 'weight': 1.0} - - SetDefaults("static_synapse", {"weight": 2.5}) - -For the creation of custom synapse types from already existing synapse types, -the command `CopyModel` is used. It has an optional argument `params` to -directly customize it during the copy operation. Otherwise the defaults of the -copied model are taken. - - CopyModel("static_synapse", "inhibitory", {"weight": -2.5}) - Connect(A, B, syn_spec="inhibitory") - -**Note**: Not all nodes can be connected via all available synapse types. The -events a synapse type is able to transmit is documented in the *Transmits* -section of the model documentation. - -Inspecting Connections ----------------------- - -`GetConnections(source=None, target=None, synapse_model=None)`: Return an array -of identifiers for connections that match the given parameters. source and -target need to be lists of global ids, model is a string representing a synapse -model. If GetConnections is called without parameters, all connections in the -network are returned. If a list of source neurons is given, only connections -from these pre-synaptic neurons are returned. If a list of target neurons is -given, only connections to these post-synaptic neurons are returned. If a -synapse model is given, only connections with this synapse type are returned. -Any combination of source, target and model parameters is permitted. Each -connection id is a 5-tuple or, if available, a NumPy array with the following -five entries: source-gid, target-gid, target-thread, synapse-id, port. - -The result of `GetConnections` can be given as an argument to the `GetStatus` -function, which will then return a list with the parameters of the connections: - - n1 = Create("iaf_neuron") - n2 = Create("iaf_neuron") - Connect(n1, n2) - conn = GetConnections(n1) - print GetStatus(conn) - - [{'synapse_type': 'static_synapse', - 'target': 2, - 'weight': 1.0, - 'delay': 1.0, - 'source': 1, - 'receptor': 0}] - -Modifying existing Connections ------------------------------- - -To modify the connections of an existing connection, one also has to obtain -handles to the connections with `GetConnections()` first. These can then be -given as arguments to the `SetStatus()` functions: - - n1 = Create("iaf_neuron") - n2 = Create("iaf_neuron") - Connect(n1, n2) - conn = GetConnections(n1) - SetStatus(conn, {"weight": 2.0}) - print GetStatus(conn) - - [{'synapse_type': 'static_synapse', - 'target': 2, - 'weight': 2.0, - 'delay': 1.0, - 'source': 1, - 'receptor': 0}] diff --git a/extras/userdoc/md/documentation/continuous_integration.md b/extras/userdoc/md/documentation/continuous_integration.md deleted file mode 100644 index 36c0353902..0000000000 --- a/extras/userdoc/md/documentation/continuous_integration.md +++ /dev/null @@ -1,129 +0,0 @@ -Continuous Integration -====================== - -Introduction ------------- - -[**Continuous Integration**](http://en.wikipedia.org/wiki/Continuous_integration) (CI) -is a software development practice where quality control is continuously -applied to the product as opposed to the traditional procedure of -applying quality control *after* completing all development (during the -so called *integration phase*). In essence, it is a way of decreasing -the risks associated with the integration by spreading required efforts -over time, which helps to improve on the quality of software, and to -reduce the time taken to deliver it. - -Stringent quality control is particularly important in the context of -NEST, a neuronal network simulator with the emphasis on correctness, -reproducibility and performance. However, given the limited amount of -the available resources, it is wasteful to transfer the responsibility -to re-run the test suite for all target platforms on every single code -base change to the shoulders of the developers. - -In order to address this problem, a -[Jenkins](http://jenkins-ci.org/)-based CI infrastructure was created -during the [NEST Google Summer of Code -2011](http://www.google-melange.com/gsoc/project/google/gsoc2011/zaytsev/17001) -project, which would allow for regular testing of changes that are -getting into the tree and timely reporting of identified problems. This -way, issues will be discovered earlier and the amount of efforts to fix -them will be significantly decreased (hopefully). - -Continuous Integration at NEST Initiative --------------------------------------------------------------------------------------------------------------------------- - -The current CI implementation is now available at the following URL: - - -The site is secured with a Class 1 SSL certificate issued by StartCom -Ltd. - -### Build jobs - -The CI system is set up to regularly poll the version control repository -hosting the main official NEST source tree. Whenever changes are -detected, the latest source code is downloaded to a build executor -machine and the following actions are performed: - -- Bootstrap the build system -- Build and install NEST -- Run the test suite -- Bootstrap MyModule -- Build and install MyModule - -If any of these steps fails (returns a non-zero exit code), the build is -marked as failed and a notification is sent to the developers mailing -list. - -Additionally, a number of metrics are collected from the build log to -obtain a cumulative project "health" indicators: - -- Build status: - - - *Success* (all steps completed successfully) - - - *Unstable* (some publishers reported non-fatal errors, e.g. - there were failed tests) - - - *Failed* (a fatal error happened during the build, e.g. non-zero - exit code was returned) - -- Weather report (how many failures there were out of 5 latest builds) - -- Test suite report (all JUnit-compatible reports are aggregated) - -- Compiler warnings report (all GCC4 / LD warnings are aggregated) - -The values of these indicators are archived along with the build logs -and trends can be graphed for arbitrary periods of time. - -### User registration - -NEST developers, using the system as registered users enjoy a number of -benefits as compared to the anonymous users. Most notably they may: - -- Access projects workspace on the build executors -- Schedule / remove / edit builds manually -- Be granted personal build jobs for their branches -- Be allowed to create jobs (to be discussed) - -Project workspace access allows one to view the source code and build -directories / logs as they are on the build executor machines, which can -be helpful in diagnosing build problems. - -If you'd like to register with the system, please contact the -administrators! - -### Technical details - -The infrastructure resides on a Dell PowerEdge R710 server hosted in a -private BCF rack at Uni Freiburg running KVM hypervisor which controls -virtual machines that host Jenkins and build executors. - -The repositories hosting the up to date versions of the configuration -([*anubis-puppet*](http://git.zaytsev.net/?p=anubis-puppet.git;a=summary)) -and documentation -([*anubis-docs*](http://git.zaytsev.net/?p=anubis-docs.git;a=summary)) -are available online. Please refer to these repositories for more -detailed documentation regarding the setup, which is out of the scope of -this brief user manual. - -### Administrators - -At the moment, the following NEST developers have administrative access -to the build system: - -- Yury V. Zaytsev - -Further reading ---------------- - -- [Martin Fowler's paper on Continuous - Integration](http://martinfowler.com/articles/continuousIntegration.html) - -- [Continuous Integration vs Continuous Delivery vs Continuous - Deployment: what is the - difference?](http://www.itwriting.com/blog/4797-continuous-integration-vs-continuous-delivery-vs-continuous-deployment-what-is-the-difference.html) - -- [8 Principles of Continuous - Delivery](http://java.dzone.com/articles/8-principles-continuous) diff --git a/extras/userdoc/md/documentation/first_steps.md b/extras/userdoc/md/documentation/first_steps.md deleted file mode 100644 index 5e8266c586..0000000000 --- a/extras/userdoc/md/documentation/first_steps.md +++ /dev/null @@ -1,169 +0,0 @@ -First Steps -=========== - -Overview --------- - -SLI is the simulation language interface of NEST. It is a stack language where -each command expects to find its arguments on the stack. - -A stack is a place where data can be stored. The stack is - organized into levels and the data can be thought of being on top - of each other. As new data is entered, it is placed on the -*top* of the stack. If a piece of data is removed or - manipulated, this is usually done to the top level of the stack. - The levels of the stack are numbered from zero onwards. Level zero - corresponds to the top of the stack. - -Initially the stack is empty. In general, you enter data onto the - stack and then execute commands to manipulate the data. - -Each command expects to find its arguments on the stack. When a - SLI command is executed, it usually removes all arguments from - the stack and pushes one or more results back on the stack. - The basic concepts of stack operation are: - -- Commands that require *arguments* take their arguments from the stack. Thus, - this data must be present before you execute the command. - -- The arguments are then removed by the command as it is executed. - -- Any results which are produced by the command are returned to the stack, so - you can use them in other operations. - -Commands with one argument --------------------------- - -Commands which need one argument take their argument from the top - of the stack. If the command produces a result, it is placed on - top of the stack, after the argument has been removed. Thus, the - argument is replaced by the result: - -### Example - - SLI ] 10 log = - 1 - -Here, the command `log` is used to compute the decadic logarithm of 10. Then, -the command `=` is used to display the result of this computation. - -Commands with more arguments ----------------------------- - -Commands which need more than one argument, take their arguments from level 0, -1, 2, and so forth and return their result to level 0, the top of the stack. -Examples are the arithmetic functions `add`, `sub`, `mul`, and `div`, which -take two arguments and return one result. - - SLI ] 1 2 add = - 3 - SLI ] 1 2. div = - 0.5 - -So far, we have used the command `=` to display the top object on the stack. In -addition, this command removes the object. You can also list the contents of the -stack without changing it. - - SLI ] 1 2 - SLI [2] stack - 2 - 1 - SLI [2] add - SLI [1] stack - 3 - SLI [1] - -Using previous results ----------------------- - -Chain calculations are calculations which involve more than one operation. A -stack is particularly useful for chaining operations,because it retains -intermediate results. - -This example shows, how the stack can be used for chain calculations. Calculate -(10+13) \\(cdot\\) (8-12) - - SLI [1] 10 13 add 8 12 sub - SLI [2] stack - -4 - 23 - SLI [2] mul = - -92 - -Notice that the results of the fist two operations remain on the stack, until -they are used in the multiplication. - -Exchanging the first two stack levels -------------------------------------- - -The command `exch` exchanges the contents of the levels 0 and 1. This is useful, -if the order of objects on the stack does not match the order required by the -desired command. - -### Example 1 - -Calculate 1/ln(2). - - SLI ] 2 ln - SLI [1] 1 - SLI [2] exch div - SLI [1] = - 1.4427 - -Removing stack elements ------------------------ - -The command `pop` removes the top object (level 0) of the stack. The remaining -items move up on the stack, so that the object which was at level 1 is now at -level 0. - -The command `clear` clears the entire stack. - -Duplicating the top element ---------------------------- - -The command `dup` duplicates the contents of the object at -level 0 and pushes the other element down one level. -This command is useful if the result of an operation is needed -more than once in a chain calculation. - -### Example 2 - -Calculate (1+4/2) + exp(1+4/2) - - SLI ] 1 4 2.0 div add - SLI [1] dup - SLI [2] exp - SLI [2] add - SLI [1] = - 23.0855 - -Important stack commands ------------------------- - -Command -Description -`=` -Print the object at level 0. -`==` -Print the object at level 0 in syntax form. -`count` -Count the number of objects on the stack. -`patsck` -Display the stack in syntax form. -`stack` -Display the stack. -`pop`, `;` -Pop object from stack. -`npop` -Pop `n` objects from stack. -`dup` -Duplicate top object of stack. -`copy` -Copy the first n objects of the stack. -`index` -Copy the `n`'th object of the stack. -`roll` -Roll a portion of `n` stack levels `k` times. -`exec` -Execute the top element on the stack. diff --git a/extras/userdoc/md/documentation/frequently_asked_questions.md b/extras/userdoc/md/documentation/frequently_asked_questions.md deleted file mode 100644 index 5a2da4f051..0000000000 --- a/extras/userdoc/md/documentation/frequently_asked_questions.md +++ /dev/null @@ -1,78 +0,0 @@ -Frequently Asked Questions -========================== - -Installation ------------- - -1. **If I compile NEST with MPI support, I get errors about `SEEK_SET`, - `SEEK_CUR` and `SEEK_END` being defined** This is a known issue in some MPI - implementations. A solution is to add - --with-debug="-DMPICH\_IGNORE\_CXX\_SEEK" - to the configure command line. - More details about this problem can be found [here](http://www-unix.mcs.anl.gov/mpi/mpich/faq.htm#cxxseek) - -2. **Configure warns that Makefile.in seems to ignore the --datarootdir setting - and the installation fails because of permission errors** - This problem is due to a change in autoconf 2.60, where the prefix - directory for the NEST documentation can end up being empty during the - installation. This leads to wrong installation paths for some components of - NEST. If you have the GNU autotools installed, you can run `./bootstrap.sh` - in the source directory followed by `./configure`. If you don't have the - autotools, appending `--datadir=PREFIX/share/nest` with the same PREFIX as - in the `--prefix` option should help. - -3. **I get 'Error: /ArgumentType in validate' when compiling an extension** - This is a known bug that has been fixed. Ask your local NEST dealer for a - new pre-release. You need at least nest-1.9-7320. - -4. **I get 'collect2: ld returned 1 exit status, ld: -rpath can only be used - when targeting Mac OS X 10.5 or later** - Please try to set the environment variable MACOSX\_DEPLOYMENT\_TARGET to - 10.5 (export MACOSX\_DEPLOYMENT\_TARGET=10.5) - -5. **Ipython crashes with a strange error message as soon as I import `nest`** - If ipython crashes on `import nest` complaining about a - `Non-aligned pointer being freed`, you probably compiled NEST with a - different version of g++ than python. Take a look at the information - ipython prints when it starts up. That should tell you which compiler was - used. Then re-build NEST with the same compiler version. - -6. **I get a segmentation fault wher I use SciPy in the same script together - with PyNEST**. We recently observed that if PyNEST is used with some - versions of SciPy, a segmentation fault is caused. A workaround for the - problem is to import SciPy before PyNEST. See - for the official bug report in NumPy. - -Neuron models -------------- - -1. **I cannot see any of the conductance based models. Where are they?** - Some neuron model need the GNU Scientific Library (GSL) to work. The - conductance based models are among those. If your NEST installation does - not have these models, you probably have no GSL or GSL development packages - installed. To solve this problem, install the GSL and its development - headers. Then reconfigure and recompile NEST. - -Connections ------------ - -1. **How can I create connections to multicompartment neurons?** - You need to create a synapse type with the proper receptor\_type as in this - example, which connects all 100 neurons in n to the first neuron in n: - - syns = nest.GetDefaults('iaf_cond_alpha_mc')['receptor_types'] - nest.CopyModel('static_synapse', 'exc_dist_syn', {'receptor_type': syns['distal_exc']}) - n = nest.Create('iaf_cond_alpha_mc', 100) - nest.Connect(n, n[:1], sync_spec={'model'='exc_dist_syn'}) - nest.Simulate(10) - -Physical units in nest ----------------------- - -- time - ms -- voltage - mV -- capacitance - pF -- current - pA -- conductance - nS -- Spike rates in (eg poisson\_generator) - spikes/s -- modulation frequencies (eg ac\_generator) - Hz diff --git a/extras/userdoc/md/documentation/getting_started.md b/extras/userdoc/md/documentation/getting_started.md deleted file mode 100644 index 908225c6e9..0000000000 --- a/extras/userdoc/md/documentation/getting_started.md +++ /dev/null @@ -1,53 +0,0 @@ -Getting started -=============== - -[Documentation](documentation.md "Documentation") -This page contains the steps that you should follow right after you -[installed NEST](installation.md "Installation"). Another good -starting point is the help page, which is available as command `help` in SLI and -`nest.help()` in PyNEST - -Set up the integrated helpdesk ------------------------------- - -The command `helpdesk` needs to know which browser to launch in order to display -the help pages. The browser is set as an option of `helpdesk`. Please see the -file `~/.nestrc` for an example setting `firefox` as browser. Please note that -the command `helpdesk` does not work if you have compiled NEST with MPI support, -but you have to enter the address of the helpdesk -(`file://$PREFIX/share/doc/nest(`) manually into the browser. Please -replace `$PREFIX` with the prefix you chose during the configuration of NEST. -If you did not explicitly specify one, it is most likely set to `/usr` or -`/usr/local` depending on what system you are. - -Tell NEST about your MPI setup ------------------------------- - -If you compiled NEST with support for distributed computing via MPI, you have to - tell it how your `mpirun`/`mpiexec` command works by defining the function - mpirun in your `~/.nestrc` file. This file already contains an example - implementation that should work with [OpenMPI](http://www.openmpi.org) library. - -Creating Models with NEST -------------------------- - -After NEST is installed and configured properly, you can start to build your -model. - -### Examples - -A good starting point to learn more about modeling in NEST are the -[example networks](more-example-networks.md "Example networks") -that come together with NEST. - -### Where does data get stored - -By default, the data files produced by NEST are stored in the directory from -where NEST is called. The location can be changed by changing the property -`data_path` of the root node using -`nest.SetKernelStatus("data_path", "/path/to/data")`. This property can also be -set using the environment variable `NEST_DATA_PATH`. Please note that the -directory `/path/to/data` has to exist. A common prefix for all data files can -be set using the property `data_prefix` of the root node by calling -`nest.SetKernelStatus("data_prefix", "prefix")` or setting the environment -variable `NEST_DATA_PREFIX`. diff --git a/extras/userdoc/md/documentation/neural_simulations.md b/extras/userdoc/md/documentation/neural_simulations.md deleted file mode 100644 index 30f5af7f5a..0000000000 --- a/extras/userdoc/md/documentation/neural_simulations.md +++ /dev/null @@ -1,466 +0,0 @@ -Neural simulations -================== - -Overview ---------- - -A simulation of a network is like an experiment with the difference that it -takes place inside the computer's memory rather than in the physical world. - -Like in a real experiment, you need a system which you want to investigate. -Moreover, you need a clear idea of *what* you want to learn from the experiment. -In the context of a network simulation this means that you have to know -*which input* you want to give to your network and *which output* you expect. - -The next section will illustrate the main concepts of NEST simulations, using a -simple simulation. The following sections will then give a step-by-step -introduction to the main concepts of NEST simulations. Finally, we will discuss -a complex example. - -A simple simulation --------------------- - -The simplest simulation in NEST is that of a network which contains just one -neuron: - - SLI ] /iaf_neuron Create /neuron Set - -We are going to simulate a standard integrate and fire model with resting -potential at -70 mV and spike threshold at -55 mV. In this line, we use the -model `iaf_neuron` to create a neuron. The command `Create` returns a handle to -the created neuron, which we store in the variable `neuron`. - -Next, we would like to add a stimulation and a recording device to the neuron, -so that we will see something during the simulation. - -In our little example, we want to inject a current into the neuron and record -its membrane potential. Thus, we need to create the corresponding devices and -connect them to the neuron: - - SLI ] /voltmeter Create /vm Set - -This command creates a voltmeter node. The handle to the new voltmeter is stored -in the variable `vm`. - -By default, the voltmeter will only record membrane potential values, so we -configure it to show us the time stamp of each value as well. We also set it to -print the time and potential to the screen and we set the recording interval to -0.1 ms. The default is 1.0 ms. - - SLI ] vm << /withtime true /to_screen true /interval 0.1 >> SetStatus - -The double angled brackets ` << ` and ` >> `delimit a dictionary definition -which consists of successive `/key value ` pairs. - -After setting the parameters of the voltmeter, we connect it to the neuron, -using the handles we have created above: - - SLI ] vm neuron Connect - -Now we create a DC generator which will supply a constant current to our neuron: - - SLI ] /dc_generator Create /stim Set - -Next, we want to set the amplitude of the DC generator such that it delivers -enough current to elicit a spike in the neuron: - - SLI ] stim << /amplitude 600.0 >> SetStatus - -Here, we only adjust the strength of the input, we set its new value to `600.0`, -which is the amplitude in pA. - -We have to connect the DC generator to the neuron: - - SLI ] stim neuron Connect - -We can now run the simulation and expect to see some results: - - SLI ] 15.0 Simulate - -The command `Simulate` runs the simulation for the specified number of -milliseconds. Below, you see a transcript of the simulation: - - Nov 10 08:57:51 Simulate [Info]: - Simulating 15 ms. - Nov 10 08:57:51 Scheduler::prepare_nodes [Info]: - Please wait. Preparing elements. - Nov 10 08:57:51 Scheduler::prepare_nodes [Info]: - Simulating 3 local nodes. - Nov 10 08:57:51 Scheduler::update [Info]: - Simulating using OpenMP. - - 1 0.1 -70 - 1 0.2 -70 - 1 0.3 -70 - 1 0.4 -70 - 1 0.5 -70 - 1 0.6 -70 - 1 0.7 -70 - 1 0.8 -70 - 1 0.9 -70 - 1 1 -70 - 1 1.1 -70 - 1 1.2 -69.7612 - 1 1.3 -69.5248 - 1 1.4 -69.2907 - 1 1.5 -69.0589 - - : - - 1 10.5 -55.3751 - 1 10.6 -55.2818 - 1 10.7 -55.1894 - 1 10.8 -55.098 - 1 10.9 -55.0075 - 1 11 -70 - 1 11.1 -70 - 1 11.2 -70 - 1 11.3 -70 - - : - - 1 12.7 -70 - 1 12.8 -70 - 1 12.9 -70 - 1 13 -70 - 1 13.1 -69.7612 - 1 13.2 -69.5248 - 1 13.3 -69.2907 - 1 13.4 -69.0589 - 1 13.5 -68.8295 - 1 13.6 -68.6023 - 1 13.7 -68.3775 - 1 13.8 -68.1548 - 1 13.9 -67.9343 - 1 14 -67.7161 - - Nov 10 08:57:51 Scheduler::resume [Info]: - Simulation finished. - Nov 10 08:57:51 Scheduler::finalize_nodes() [Info]: - using OpenMP. - -After some initial messages from the simulation scheduler, we see the output -from the voltmeter. The number in the left column represents the global ID (GID) -of the model neuron and the center column the network time in milliseconds. The -right column contains the values of the membrane potential at that time. The -potential is given in mV. - -By default, NEST uses a simulation stepsize of 0.1 ms. With a simulation time -of 15.0 ms, we have 150 simulation steps. - -The neuron that we have simulated was a standard *integrate-and-fire* neuron -\[Tuckwell91\] with a resting potential of -70 mV and a threshold at -55.0 mV. -We see the first effect of the DC input current at 1.2 ms. This time delay is -due to several reasons: The `dc_generator` emits the first current output at the -end of the first time step, i.e., at 0.1 ms. Since the connection between -generator and neuron was created with the default delay of 1 ms, the current -signal arrives at the neuron at 1.1 ms and thus affects the membrane potential -for the first time during the time step from 1.1 ms to 1.2 ms. - -During the time step from 10.9 ms to 11.0 ms, the membrane potential crosses the -threshold value -55.0 mV. Thus, the neuron emits an output spike at 11.0 ms and -the membrane potential is then reset to -70.0 mV and clamped to the resting -value for 2 ms, the refractory period of the neuron. After the refractory -period, the membrane continues to depolarize due to the continuing input -current. - -Nodes and Models ------------------ - -In NEST, the neural system is a collection of nodes and their interactions. -Nodes correspond to things like neurons, synapses, and devices, and are -implemented in C++. The network and its configuration are defined at the level -of the simulation language interpreter. - -Nodes are created from a set of prescribed models which are stored in the -dictionary `modeldict`. The most important neuron models are: - -Model name -Description -`iaf_neuron` -Simple integrate-and-fire neuron with alpha-function PSCs. -`iaf_psc_delta` -Integrate-and-fire neuron with delta-function PSCs. -`iaf_cond_alpha` -Conductance-based integrate-and-fire neuron with alpha-function synapses. -`iaf_cond_exp` -Conductance-based integrate-and-fire neuron with exp-function synapses. -`hh_psc_alpha` -`hh_cond_exp_traub` -In order to make the models visible to the interpreter, the model dictionary -has to be opened. - -### Creating nodes - -Before continuing with the example, we reset NEST, to clear all nodes that we -have created before. - - SLI ] ResetKernel - Sep 21 10:13:39 Network::clear_models [Info]: - Models will be cleared and parameters reset. - -Nodes are created from a model, using the command `Create`. - - SLI ] /iaf_neuron Create == - 1 - -In the fist line, we create one integrate and fire neuron from the model -`iaf_neuron`. - -The return value of `Create` is an integer that identifies the last node that -was created in the network (note that this can be different from 1 if you have -not called `ResetKernel before)`. This integer is called the node's *global id* -(the network as a whole owns the global id `0`, therefore the ids of -user-created nodes start with `1`). Often, it is neccessary to have a large -number of nodes of the same type. The command Create can also be used for this -purpose. The following line of code create 10 integrate and fire neurons: - - SLI ] /iaf_neuron 10 Create == - 11 - -Status information -------------------- - -Nodes have a state which can be extracted and modified. In the follwing example, -we display the status information of one the neurons in the layer we have -created above: - - SLI ] 1 ShowStatus - -------------------------------------------------- - Name Type Value - -------------------------------------------------- - archiver_length integertype 0 - C_m doubletype 250 - E_L doubletype -70 - frozen booltype false - global_id integertype 1 - I_e doubletype 0 - local booltype true - local_id integertype 1 - model literaltype iaf_neuron - node_type literaltype neuron - parent integertype 0 - recordables arraytype - state integertype 0 - tau_m doubletype 10 - tau_minus doubletype 20 - tau_minus_triplet doubletype 110 - tau_syn doubletype 2 - thread integertype 0 - t_ref doubletype 2 - t_spike doubletype -1 - vp integertype 0 - V_m doubletype -70 - V_reset doubletype -70 - V_th doubletype -55 - -------------------------------------------------- - Total number of entries: 24 - -Using the command `SetStatus`, it is possible to change the entries of this so -called *status dictionary*. The following lines of code change the threshold -value `V_th` to -60 mV: - - SLI ] 1 << /V_th -60.0 >> SetStatus - SLI ] 1 GetStatus /V_th get = - -60 - -Please note, that `SetStatus` checks if a property really exists in a node and -will issue an error if it doesn't. This behavior can be changed by the following -command: - - 0 << /dict_miss_is_error false >> SetStatus - -Then, NEST is very tolerant with respect to the property that you are trying to -change: If it does not know the property, or if the property cannot be changed, -there will be no error, but only a warning. In any case, `SetStatus` does -complain if the new value does not match in the expected type: - - SLI ] 1 << /V_th (60) >> SetStatus - - - Dec 01 15:33:54 SetStatus_ad [Error]: TypeMismatch - Expected datatype: doubletype - Provided datatype: stringtype - -In order to find out, which properties of a given model can be changed an which -not, you have to refer to the model's documentation. - -Connections ------------- - -Connections between nodes define possible channels for interactions between -them. A connection between two nodes is established, using the command -`Connect`. - -Each connection has two basic parameters, *weight* and *delay*. The weight -determines the strength of the connection, the delay determines how long an -event needs to travel from the sending to the receiving node. The delay must be -a positive number greater or equal to the simulation stepsize and is given in -ms. - -### Example 1 - - SLI ] /iaf_neuron Create /n1 Set - SLI ] /iaf_neuron Create /n2 Set - SLI ] /iaf_neuron Create /n3 Set - SLI ] - SLI ] n1 n2 Connect - SLI ] n1 n3 Connect - -To inspect the parameters of a connection, one first needs to obtain a handle -to the connection. This is done using the command `FindConnections`. It takes a -dictionary that at least contains the id of the source node and will return a -list of handles for all outgoing connections. The search can be restricted by -using the optional parameters *target* and *synapse\_type*. - -### Example 2 - - SLI ] << /source n1 >> FindConnections /c1 Set - SLI ] c1 length == - 2 - SLI ] << /source n1 /target n2 >> FindConnections /c2 Set - SLI ] c2 length == - 1 - -To actually see the parameters of the connection, `GetStatus` is used, just like -it is for nodes. - -### Example 3 - - SLI ] c1 0 get GetStatus info - -------------------------------------------------- - Name Type Value - -------------------------------------------------- - delay doubletype 1 - receptor integertype 0 - sizeof integertype 32 - source integertype 1 - synapse_model literaltype static_synapse - target integertype 2 - weight doubletype 1 - -------------------------------------------------- - Total number of entries: 7 - -To change the paramters of a connection, `SetStatus` is used, just like it is -for nodes. - -### Example 4 - - SLI ] c1 0 get << /weight 2.0 >> SetStatus - SLI ] c1 0 get GetStatus /weight get == - 2.000000e+00 - -Devices --------- - -Devices are network nodes which provide input to the network or record its -output. They encapsulate the stimulation and measurement process. If you want -to extract certain information from a simulation, you need a device which is -able to deliver this information. Likewise, if you want to send specific input -to the network, you need a device which delivers this input. - -Devices have a built-in timer which controls the period they are active. Outside -this interval, a device will remain siltent. The timer can be configured using -the command `SetStatus`. - -By definition a device is active in the interval \\((t\_1,t\_2)\\) -, if we can observe events \\(E\\) -with time stamps \\(t\_E\\) -which obey \\(t\_1 <= t\_E < t\_2\\) -for all \\(E\\) -. -In other words, the interval during which the device is active corresponds to -the range of time-stamps of the device's events. - -Note that it is not possible to generate/observe an event with time stamp 0. - -### Device parameters - -The following entries of the status dictionary are the same for all stimulation -and recording devices: - -Property -Type -Description -`/start` -double -First time of activity, relative to the value of `origin` in ms. -`/stop` -double -First time of inactivity, relative to the value of `origin` in ms. -`/origin` -double -Origin of the device clock, relative to the network time in ms. -In general, the following must hold: - -1. *stop* \>= *start* -2. If *stop =* start*, the device is inactive.* - -### Stimulating Devices - -A range of devices is available for the stimulation of neurons. The most -important ones are listed in the following table. For details, refer to the -documentation of the respective decive. - -Model name -Description -`spike_generator` -Device to generate spikes at specific times. -`poisson_generator` -Device to generate poisson shotnoise. -`dc_generator` -Device to generate a constant current. -`ac_generator` -Device to generate an alternating (sine) current. -`step_current_generator` -Device to generate a step current with different amplitudes at different times. - -#### Example 5 - - SLI ] /iaf_neuron Create /n Set - SLI ] /poisson_generator Create /pg Set - SLI ] pg << /rate 220.0 Hz >> SetStatus - SLI ] pg n Connect - -### Recording devices - -All devices which are used to observe the state of other network nodes are -called recording devices. Examples are `voltmeter` and `spike_detector`. - -Recording devices have properties which control the amount, the format, and the -destination of their output. All recorders can either dump the recorded data to -a file (property `to_file`), print it to the screen (property `to_screen`) or -hold the data in memory (property `to_memory`). Data stored in memory can be -retrieved after the simulation using `GetStatus`. - -Device models are also stored in the dictionary `modeldict`. The most important -devices are: - -Model name -Description -`voltmeter` -Device to observe membrane potentials. -`multimeter` -Device to observe arbitrary analog quantities. -`spike_detector` -Device to observe spike times. -Please note that the connection direction for analog recorders (all except -`spike_detector` in above list) is inverted with respect to other recorders. - -#### Example 6 - - SLI ] /iaf_neuron Create /n Set - SLI ] /voltmeter Create /vm Set - SLI ] /spike_detector Create /sd Set - SLI ] vm n Connect - SLI ] n sd Connect - -Simulation ------------ - -NEST simulations are time driven. The simulation time proceeds in discrete steps -of size `dt`, set using the property `resolution` of the root node. In each time -slice, all nodes in the system are updated and pending events are delivered. - -The simulation is run by calling the command `t Simulate`, where `t` is the -simulation time in milliseconds diff --git a/extras/userdoc/md/documentation/objects_and_data_types.md b/extras/userdoc/md/documentation/objects_and_data_types.md deleted file mode 100644 index 70bdeb5abd..0000000000 --- a/extras/userdoc/md/documentation/objects_and_data_types.md +++ /dev/null @@ -1,211 +0,0 @@ -Objects and data types -====================== - -Overview --------- - -Anything that can be put on the stack is called object. There are several -different types of objects, which can store different types of data. For a -number of object types there exist two different states: *executable* and -*literal*. Some object types can change between these two states. Literal -objects are the majority and are simply pushed on the stack when they are -entered. By contrast, executable objects perform some operation when they are -entered and cannot easily be pushed on the stack. - -Numbers -------- - -SLI distinguishes between real and integer numbers. Real numbers -correspond to the type `double` in C/C++. Integer numbers -correspond to the type `long int` of C/C++. - -### Examples 1 - -Real numers are: `1.4`, `.5`, `1.`, `1e-2` - -Integer numers are `1`, `2`, `3000` - -Arrays ------- - -Arrays are sequential containers which can hold any SLI object. The elements of -an array are indexed, starting with zero (0) as the first index. - -SLI arrays are heterogeneous. Objects of different type may be mixed within one -array. Arrays may also be nested to define matrices or tensors of arbitrary rank. - -Arrays are delimited by square brackets. The different elements of an array are -separated by white-spaces. - -### Examples 2 - - [1 2 3]  % a simple array with integers - [1 a b]  % a mixed array - [[1 2 3] [4 5 6]] % a 2x3 Matrix defined by nested array - -Calculate the dot product of the vectors \\([1 2 3]cdot[4 5 6]\\) - - SLI ] [1 2 3] - SLI [1] [4 5 6] - SLI [2] Dot = - 32 - -Names ------ - -Names are used to create variables and to identify specific SLI objects. -If a name is entered, it is immediately executed. - -If you want to put a name on the stack without evaluating it, you need to -protect it by prepending a shash character (e.g. `/a`). In this case, the name -is called a *literal name*. - -The command `def` is used to create an associoation between a name an an object. - -### Example 3 - - SLI ] /pi 3.1415 def - SLI ] pi - SLI [1] = - 3.1415 - -The command `who` gives the list of names which have been - defined during the SLI session. - -### Example 4 - -Define the variables *a* and *b* with values 1 and 2 and calculate *a+b* - - SLI ] /a 1 def - SLI ] /b 2 def - SLI ] a b add - SLI ] = - 3 - SLI ] who - -------------------------------------------------- - Name Type Value - -------------------------------------------------- - pi doubletype 3.1415 - a integertype 1 - b integertype 2 - -------------------------------------------------- - Total number of dictionary entries: 3 - -Strings -------- - -Strings are sequences of characters, delimited by parenthesis. In SLI, -characters are represented by interger numbers, e.g. 97 represents the letter -'a', while 32 represents the *space* character. - -The elements of a string are indexed, starting with zero (0) as the first index. - -Matched pairs of parentheses may be used inside strings. - -### Examples 5 - - SLI ] (Hello World!) = - Hello World! - -Procedures ----------- - -Procedures are a sequence of SLI commands, enclosed by the delimiters -`{` and `}`. The delimiters prevent the objects from being executed as you enter - them. Rather, they will be executed, when you evaluate the procedure. - -Bound to a name, procedures can be used like any builtin SLI - command. - -### Example: Hello World - -Print the string *Hello World!*. - - /HelloWorld - { - (Hello World !) = - } def - -Dictionaries ------------- - -A dictionary is an associative array. It stores pairs of names and objects, -where the name acts as a key to access the object inside the dictionary. - -The pairs are delimited by the characters `<<` and `>>`. Note that the pairs are -evaluated during the construction of the dictionary. Thus, literal names have to -be used here. The individual name/value pairs have no defined sequential order -(unlike a real dictionary where the keys are ordered alphabetically). - -### Example 6 - -Create a dictionary which stores named parameters. - - SLI ] /parameters << /alpha 1.0 /beta 3.5 /tau 10.0 >> def - SLI ] parameters /tau get = - 10 - -### Example: Showing dictionaries - -The command `info` can be used to examine the contents of a dictionary. - - SLI ] parameters info - -------------------------------------------------- - Name Type Value - -------------------------------------------------- - alpha doubletype 1 - beta doubletype 3.5 - tau doubletype 10 - -------------------------------------------------- - Total number of dictionary entries: 3 - -Object types ------------- - -There are a number of different object types in SLI. Each type is represented by -a literal name (i.e. a name with a prepended slash). Here is a list of the most -important types: - -|-----------------|-------------------| -| `/integertype` | `/doubletype` | -| `/booltype` | `/stringtype` | -| `/nametype` | `/literaltype` | -| `/arraytype` | `/proceduretype` | -| `/modeltype` | `/dictionarytype` | -| `/ostreamtype` | `/istreamtype` | -| `/xistreamtype` | `/trietype` | - -### Getting type information - -The command `type` returns the type-name of the top element of the stack. Note -that type removes the element. - -The command `typeinfo` returns the type of an object without popping it off the -stack. - -### Conversion between types - -It is possible to perform conversions between types. However, unlike in C or C++ -this type conversion is never done implicitly. Some of the conversion operators -are inherited from PostScript. Others are special to SLI. - -Here, we list the most important conversion operators. Each conversion operator -gets one argument which can, in general, be of any type. If the operator is -meaningless for a given object, an argument type error is raised. - -Command -Description -`cvd` -Convert a number to a double. -`cvi` -Convert a number to an integer. -`cvs` -Tries to convert the object to a string. -`cst` -Convert a string to an array. -`cvx` -Convert an object to an executable object, e.g. string to a procedure, or a -literal name to a name. -`cvlit` -Convert an object to a literal object, e.g. a procedure to an array or a string -to a literal name. diff --git a/extras/userdoc/md/documentation/parallel_computing.md b/extras/userdoc/md/documentation/parallel_computing.md deleted file mode 100644 index d2f7e9dd64..0000000000 --- a/extras/userdoc/md/documentation/parallel_computing.md +++ /dev/null @@ -1,222 +0,0 @@ -Parallel Computing -================== - -Introduction ------------- - -Parallelization is a means to run simulations faster and use the capabilities of -computer clusters and supercomputers to run large-scale simulations. - -Since version 2.0, NEST is capable of running simulations on -multi-core/-processor machines and computer clusters using two ways of -parallelization: *thread-parallel simulation* and *distributed simulations*. -The first is implemented using OpenMP (POSIX threads prior to NEST 2.2), while -the second is implemented on top of the Message Passing Interface (MPI). Both -ways of parallelism can be combined in a hybrid fashion. - -Using threads allows to take advantage of multi-core and multi-processor -computers without the need for additional software libraries. Using distributed -computing allows to draw in more computers and thus enables larger simulations, -than would fit into the memory of a single machine. The following paragraphs -describe the facilities for parallel and distributed computing in detail. - -See [Plesser et al (2007)](http://dx.doi.org/10.1007/978-3-540-74466-5_71) for -more information on NEST parallelization and be sure to check the documentation -on [Random numbers in NEST](../random_numbers/index.html "Random numbers in NEST"). - -Concepts and definitions ------------------------- - -In order to ease the handling of neuron and synapse distribution with both -thread and process based parallelization, we use the concept of local and remote -threads, called *virtual processes*. A virtual process (VP) is a thread living -in one of NEST's MPI processes. Virtual processes are distributed round-robin -onto the MPI processes and counted continuously over all processes. The concept -is visualized in the following figure: - -![Process\_vp\_thread](../../img/Process_vp_thread.png) -Basic scheme for counting threads (T), virtual processes (VP) and MPI processes -(P) in NEST - -The status dictionary of each node (i.e. neuron or device) contains three -entries that are related to parallel computing: - -- *local* (boolean): indicating if the node exists on the local process or not -- *thread* (integer): id of the local thread the node is assigned to -- *vp* (integer): id of the virtual process the node is assigned to. - -### Node distribution - -The distribution of nodes is based on the type of the node. Neurons are assigned -to one of the virtual processes in a round-robin fashion. On all other virtual -processes, no object is created (the *proxy* object in the figure below is just -a conceptual way of keeping the id of the real node free on remote processes). -The virtual process *idVP* on which a neuron with global id -*idNode* is allocated is given by -*idVP = idNode % NVP*, where -*NVP* is the total number of virtual processes in the simulation. - -Devices for the stimulation and observation of the network are replicated once -on each thread in order to balance the load of the different threads and -minimize their interaction. Devices thus do not have proxies on remote virtual -processes. - -The node distribution for a small network consisting of `spike_generator`, four -`iaf_neuron`s, and a `spike_detector` in a scenario with two processes with two -threads each is shown in the following figure: - -![Node\_distribution](../../img/Node_distribution.png) -Illustration of node distribution. sg=spike\_generator, iaf=iaf\_neuron, -sd=spike\_detector. Numbers to the left and right indicate global ids. - -For recording devices that are configured to record to a file -(property *to\_file* set to *true*), the distribution also results in multiple -data files, each containing the data from one thread. The files names are -composed according to the following scheme - - [model|label]-gid-vp.[dat|gdf] - -The first part is the name of the model (e.g. `voltmeter` or `spike_detector`) -or, if set, the *label* of the recording device. The second part is the global -id (GID) of the recording device. The third part is the id of the virtual -process the recorder is assigned to, counted from 0. The extension is `gdf` for -spike files and `dat` for analog recordings from the `multimeter`. -The `label` and `file_extension` of a recording device can be set like any other -parameter of a node using `SetStatus`. - -Using multiple threads ----------------------- - -Thread-parallelism is compiled into NEST by default and should work on all MacOS -and Linux machines without additional requirements. In order to keep results -comparable and reproducible across different machines, however, the default mode -is that only a single thread is used and multi-threading has to be turned on -explicitly. - -To use multiple threads for the simulation, the desired number of threads has to -be set *before* any nodes or connections are created. The command for this is - - nest.SetKernelStatus({"local_num_threads": T}) - -Usually, a good choice for T is the number of processor cores available on your -machine. In some situations, oversubscribing can yield 20-30% improvement in -simulation speed. Finding the optimal thread number for a specific situation -might require a bit of experimenting. - -Using distributed computing ---------------------------- - -### Build requirements - -To compile NEST for distributed computing, you need a library implementation of -MPI on your system. If you are on a cluster, you most likely have this already. -Note, that in the case of a pre-packaged MPI library you will need both, the -library and the development packages. Please see the [Installation instructions](../installation/index.html "Installation") -for general information on installing NEST. -Please be advised that NEST should currently only be run in a homogeneous MPI environment. Running in a heterogenenous environment can lead to unexpected results or even crashes. Please contact the [NEST community](http://www.nest-simulator.org/community/) if you require support for exotic setups. - -### Compilation - -If the MPI library and header files are installed to the standard directories -of the system, it is likely that a simple - - $NEST_SOURCE_DIR/configure --with-mpi - -will find them (`$NEST_SOURCE_DIR` is the directory holding the NEST sources). -If MPI is installed to a non-standard location `/path/to/mpi`, the command line -looks like this: - - $NEST_SOURCE_DIR/configure --with-mpi=/path/to/mpi - -In some cases it might be necessary to specify MPI compiler wrappers explicitly: - - $NEST_SOURCE_DIR/configure CC=mpicc CXX=mpicxx --with-mpi - -Additional information concerning MPI on OSX can be found [here](../installation/index.html "Installation"). - -### Running distributed simulations - -Distributed simulations cannot be run interactively, which means that the -simulation has to be provided as a script. However, the script does not have to -be changed compared to the script for serial simulation: inter-process -communication and node distribution is managed transparently inside of NEST. - -To distribute a simulation onto 128 processes of a computer cluster, the command -line to execute looks like this: - - mpirun -np 128 python simulation.py - -Please refer to the MPI library documentation for details on the usage of -`mpirun`. - -### MPI related commands - -Although we generally advise strongly against writing process-aware code in -simulation scripts (e.g. creating a neuron or device only on one process and -such), in special cases it may be necessary to obtain information about the MPI -application. One example would opening the right stimulus file for a specific -rank. Therefore, some MPI specific commands are available: - -`NumProcesses` -The number of MPI processes in the simulation - -`ProcessorName` -The name of the machine. The result might differ on each process. - -`Rank` -The rank of the MPI process. The result differs on each process. - -`SyncProcesses` -Synchronize all MPI processes. - -Reproducibility ---------------- - -To achieve the same simulation results even when using different parallelization -strategies, the number of virtual processes has to be kept constant. A -simulation with a specific number of virtual processes will always yield the -same results, no matter how they are distributed over threads and processes, -given that the seeds for the random number generators of the different virtual -processes are the same (see [Random numbers in NEST](../random_numbers/index.html "Random numbers in NEST")). - -In order to achieve a constant number of virtual processes, NEST provides the -property *total\_num\_virtual\_procs* to adapt the number of local threads -(property *local\_num\_threads*, explained above) to the number of available -processes. - -The following listing contains a complete simulation script (*simulation.py*) -with four neurons connected in a chain. The first neuron receives random input -from a `poisson_generator` and the spikes of all four neurons are recorded to -files. - - from nest import * - SetKernelStatus({"total_num_virtual_procs": 4}) - pg = Create("poisson_generator", params={"rate": 50000.0}) - n = Create("iaf_neuron", 4) - sd = Create("spike_detector", params={"to_file": True}) - Connect(pg, [n[0]], 1000.0, 1.0) - Connect([n[0]], [n[1]], 1000.0, 1.0) - Connect([n[1]], [n[2]], 1000.0, 1.0) - Connect([n[2]], [n[3]], 1000.0, 1.0) - ConvergentConnect(n, sd) - Simulate(100.0) - -The script is run three times using different numbers of MPI processes, but 4 -virtual processes in every run: - - mkdir 4vp_1p; cd 4vp_1p - mpirun -np 1 python ../simulation.py - cd ..; mkdir 4vp_2p; cd 4vp_2p - mpirun -np 2 python ../simulation.py - cd ..; mkdir 4vp_4p; cd 4vp_4p - mpirun -np 4 python ../simulation.py - cd .. - diff 4vp_1p 4vp_2p - diff 4vp_1p 4vp_4p - -Each variant of the experiment produces four data files, one for each virtual -process (*spike\_detector-6-0.gdf*, *spike\_detector-6-1.gdf*, -*spike\_detector-6-2.gdf*, and *spike\_detector-6-3.gdf*). Using diff on the -three data directories shows that they all contain the same spikes, which means -that the simulation results are indeed the same independently of the details of -parallelization. diff --git a/extras/userdoc/md/documentation/programming_in_sli.md b/extras/userdoc/md/documentation/programming_in_sli.md deleted file mode 100644 index 28eaddd825..0000000000 --- a/extras/userdoc/md/documentation/programming_in_sli.md +++ /dev/null @@ -1,313 +0,0 @@ -Programming in SLI -================== - -Overview --------- - -A procedure is a sequence of SLI objects whose execution is delayed until the -procedure is executed. Because procedures are objects, they can be: - -- placed on the stack -- bound to a name -- executed repeatedly -- executed by another procedure - -A program is a sequence of SLI objects and procedures which are - defined in a file. This section introduces the fundamentals of - SLI programming. - -This chapter covers the basic programming concepts of the SLI - language features. - -Entering and executing programs -------------------------------- - -A program is a sequence of SLI objects and procedures which are defined in a -file. Program files are ordinary ASCII text files, which can be created and -modified with an editor of your choice (e.g. GNU Emacs). - -SLI programs usually have the file ending "sli", for example `hello_world.sli`. - -The `run` command is used to execute a program file. - -### Example: "Hello World!" - -Write the program `hello_world.sli` according to the - example, given above. - -1. Create an empty file `hello_world.sli` in the directory from which the - interpreter was started. - -2. Copy the *Hello World* example to the file and save it. - -3. Enter `(hello_world.sli) run` at the command prompt. - - - /HelloWorld - { - (Hello World !) = - } def - - - - SLI ] (hello_world.sli) run - SLI ] HelloWorld - Hello World ! - -Note that the procedure is not immediately executed by `run`. Rather, all -objects which are contained in the file are read and executed. - -Using local variables ---------------------- - -Usually, all names you define are globally accessible. But, if you use a lot of -procedures that define their own variables, there is an increasing danger that -two procedures use the same name for different purposes. This problem can be -solved by keeping variable *local* to the procedure that defines them. - -SLI uses dictionaries to store and resolve variables. - -### Example 2 - -Compute the alpha-function of *t* according to *a(t)=t\*Exp(-t/tau)* - - /alpha - { - << /tau -1.0 >> % create dictionary for local variables - begin  % open local name space - /t exch def  % store argument in local variable t - t tau div exp  % compute formula - t mul - end  % close local name space - } def - -Conditionals ------------- - -Conditional expressions allow a program to ask questions and make decisions: - -- Comparisons and logical functions - -- Conditional structures which test a certain condition and use the result to - make a decision. - -In general, conditional structures take a *boolean* object as well as one or -more procedure objects as argument and evaluate one of the procedures, depending -on the value of the boolean. - -### Example 3 - -The program in this example implements the faculty function according to the -definition: - - fac(1) := 1 - fac(n) := n*fac(n-1), for n>1 - -The program expects the argument on the stack and replaces it by the result. -Here, we use the `if` command to test whether the argument is greater than 1. -The `if` command takes two arguments, a boolean and a procedure object. The -boolean is supplied by the `gt` command which test if the object at stack level -1 is greater than the object at level 0. - - /fac - { - dup  % duplicate the argument, since we still need it. - 1 gt  % If n > 1 we call fac recursively - {  % according to fac(n)=n*fac(n-1) - dup - 1 sub fac % call fac with n-1 as argument - mul  % multiply the result with the argument - } if - } def - -This example also shows how procedures can be called *recursively*. It is, -however, important to supply a *termination condition* for the recursion like in -this example. - -Comparison functions --------------------- - -Comparison functions are used to compare objects. The result of comparison -functions are of type `/booltype` and can be used for logical functions and -conditional structures. - -Command -Description -`eq` -Test whether two objects are equal. -`ne` -Test whether two objects are not equal. -`gt` -Test whether the object at level 1 is greater than the object at level 0. -`lt` -Test whether the object at level 1 is less than the object at level 0. -`leq` -Test whether the object at level 1 is less than or equal to the object at level -0. -`geq` -Test whether the object at level 1 is greater than or equal to the object at -level 0. - -Logical functions ------------------ - -Command -Description -`not` -Negates a bool. -`and` -Returns true if both arguments are true. -`or` -Returns true if at least one of the arguments is true. -`xor` -Returns true if and only if one of the arguments is true. -  - -The *if-ifelse* structure -------------------------- - -Command -Description -`bool proc if` -Executes `proc` if the boolean is true. -`bool proc_1 proc_2 ifelse` -Executes `proc_1` if the boolean is true and `proc_2` otherwise. - -### Example - - SLI ] 1 2 eq {(Equal!) = } { (Not equal !) =} ifelse - Not equal ! - SLI ] 2 2 eq {(Equal!) = } { (Not equal !) =} ifelse - Equal! - -The *case-switch* structure ---------------------------- - -While the commands `if` and `ifelse` test only one condition, the *case-switch* -structure can be used to test a number of different conditions. - -The *case-switch* structure has the general form: - - mark - bool_1 proc_1 case - bool_2 proc_2 case -  : - bool_n proc_n case - switch - -In this structure, `proc_i` is executed, if the corresponding value of `bool_i` -is true. - -Sometimes it is necessary to provide a default procedure, which is evaluated if -none of the boolean is true. - -The *case-switchdefault* structure has the general form - - mark - bool_1 proc_1 case - bool_2 proc_2 case -  : - bool_n proc_n case - procdefault - switchdefault - -Here, `procdefault` is executed if none of the booleans was true. - -Loops ------ - -Loops and control structures are commands that take procedure objects as - arguments. - -### Infinite loops - -The simplest loop is performed by the command `loop`: - - SLI ] {(Hello World) =} loop - Hello World - Hello World - Hello World - Hello World - Hello World - Hello World - Hello World - Hello World -  : - -`loop` performs the procedure repeatedly and thus in the example, an infinite -succession of the words "Hello World" is printed. The only way to leave a -`loop`-structure is to call the command `exit` somewhere inside the loop: - - SLI ] 0 - SLI [1] { 1 add dup (Hello World) = 10 eq {exit} if } - SLI [2] loop - -it prints ten times 'Hello World'. First the initial value 0 is pushed on the -operand stack. The procedure adds 1 in each cycle and takes care that one copy -of the counter stays on the stack to serve as the initial value for the next -cycle. After the message has been printed, the stop value 10 is pushed and is -compared with the counter. If the counter is equal to 10, the nested procedure -s executed. This procedure then executes the command `exit`, and interrupts the -loop. - -Command -Description -`proc loop` -Repeatedly execute procedure `proc`. - `exit` -Exit the innermost loop structure. - -### Finite loops - -The last example can be implemented much easier, using a `repeat` loop. `repeat` -takes two arguments: An integer, and a procedure object. The integer determines -how often the procedure is executed. Thus, in order to print ten times -"Hello World" we write: - - SLI ] 10 { (Hello World) = } repeat - -Sometimes, one needs to know the counter of the loop and one may also be -interested in influencing the step-size of the iterations. For this purpose SLI -offers the `for`-loop. `for` is - called like this: - - start step stop proc for - -`for` executes the procedure `proc` as long as the - counter is smaller than the stop-value (for positive step values) (please refer - to reference *RedBook* for the exact termination conditions). - -In each cycle, the current value of the counter is pushed automatically. This -value can be consumed by the procedure. Actually, in very long running loops, -the counter must be removed by the procedure in order to avoid stack overflow. -The following example prints the first ten cubic numbers: - - SLI ] 1 1 10 { dup mul = } for - 1 - 4 - 9 - 16 - 25 - 36 - 49 - 64 - 81 - 100 - SLI ] - -Command -Description -`n proc repeat` -Execute procedure proc n times. -`i s e proc for` -Execute procedure proc for all values from i to e with steps. -`array proc forall` -Execute procedure proc for all elements of `array`. -`array proc forallindexed` -Execute procedure proc for all elements of `array`. -`array proc Map` -Apply `proc` to all elements of `array`. -`array proc MapIndexed` -Apply `proc` to all elements of `array`. -`x proc n NestList` -Gives a list of the results of applying `proc` to`x` 0 through `n` times. diff --git a/extras/userdoc/md/documentation/random_numbers.md b/extras/userdoc/md/documentation/random_numbers.md deleted file mode 100644 index 740c5763f1..0000000000 --- a/extras/userdoc/md/documentation/random_numbers.md +++ /dev/null @@ -1,454 +0,0 @@ -Random numbers -============== - -Introduction -------------- - -Random numbers are used for a variety of purposes in neuronal network -simulations, e.g. - -- to create randomized connections - -- to choose parameter values randomly - -- to inject noise into network simulations, e.g., in the form of Poissonian - spike trains. - -This document discusses how NEST provides random numbers for these purposes, how -you can choose which random number generator (RNG) to choose, and how to set the -seed of RNGs in NEST. We use the term "random number" here for ease of writing, -even though we are always talking about pseudorandom numbers generated by some -algorithm. - -NEST is designed to support parallel simulation and this puts some constraints -on the use and generation of random numbers. We discuss these in the next -section, before going into the details of how to control RNGs in NEST. - -On this page, we mainly discuss the use of random numbers in parallel NEST -simulations, but the comments pertain equally to serial simulations (N\_vp=1). - -### Random Numbers vs Random Deviates - -NEST distinguishes between random number generators, provided by `rngdict` and -random deviate generators provided by `rdevdict`. Random *number* generators -only provide double-valued numbers uniformly distributed on \[0, 1\] and -uniformly distributed integers in {0, 1, ..., N}. Random *deviate* generators, -on the other hand, provide random numbers drawn from a range of distributions, -such as the normal or binomial distributions. In most cases, you will be using -random deviate generators. They are in particular used to initialize properties -during network construction, as described in the sections [Changes in NEST 2.4](../random_numbers/index.html#Changes-in-random-number-generation-in-NEST-2.4) and [Examples](../random_numbers/index.html#Examples) below. - -Changes in random number generation in NEST 2.4 -------------------------------------------------- - -Random deviate generation has become significantly more powerful in NEST 2.4, to -fully support randomization of connections parameters offered by the revised -`Connect` function, as described in [Connection Management](../connection_management/index.html "Connection Management") -and illustrated by the [examples](../random_numbers/index.html#examples) below. -We have also made minor changes to make to achieve greater similarity between -NEST, PyNN, and NumPy. For most users, these changes only add new features. -Only existing scripts using - -- `uniformint` -- `normal_clipped`, `normal_clipped_left`, `normal_clipped_right` - -generators from NEST 2.2 need to be adapted as detailed below. - -The changes are as follows: - -- Uniform integer generator - - - renamed from `uniformint` to `uniform_int` - - parameters renamed to `low` and `high` - - returns uniformly distributed integers from `{low, low+1, …, high}` - -- Uniform continuous generator - - - new generator `uniform` - - parameters `low` and `high` - - generates numbers uniformly distributed in `[low, high)` - -- Full parameter sets for generators - - - In the past, many random deviate generators returned values for fixed - parameters, e.g., the `normal` generator could only return zero-mean, - unit-variance normal random numbers. - - - Now, all parameters for each generator can be set, in particular: - - - normal: mu, sigma - - lognormal: mu, sigma - - exponential: lambda - - gamma: order, scale - - - Parameter values are checked more systematically for unsuitable values. - -- Clipped normal generators - - - parameter names changed to `mu` and `sigma` - - - clipping limits now called `low` and `high` - - - `_left` and `_right` variants removed: for one-sided clipping, just set - the boundary you want to clip at, the other is positive or negative - infinity - -- Clipped variants for most generators - - - For most random deviate generators, `_clipped` variants exist now. - - - For all clipped variants, one can set a lower limit (`low`, default: - -infinity) and an upper limit (`high`: +infinty). - - - Clipped variants will then return numbers strictly in `(low, high)` for - continuous distributions (e.g. normal, exponential) or - `{low, low+1, …, high}` for discrete distributions (e.g. poisson, - binomial). This is achieved by redrawing numbers until an acceptable - number is drawn. - - - Note that the resulting distribution differs from the original one and - that drawing may become very slow if `(low, high)` contains only very - small probability mass. Clipped generator variants should therefore - mostly be used to clip tails with very small probability mass when - randomizing time constants or delays. - -- Clipped-to-boundary variants for most generators - - - To facilitate reproduction of certain publications, NEST also provides - `_clipped_to_boundary` variants of most generators. - - - Clipped-to-boundary variants return the value `low` if a number smaller - than `low` is drawn, and `high` if a number larger than `high` is drawn. - - - We believe that these variants should *not* be used for new studies. - -Basics of parallel simulation in NEST --------------------------------------- - -For details of parallelization in NEST, please see [Parallel Computing](../parallel_computing/index.html "Parallel Computing") -and [Plesser et al (2007)](http://dx.doi.org/10.1007/978-3-540-74466-5_71). -Here, we just summarize a few basics. - -- NEST can parallelize simulations through *multi-threading*, *distribution* - or a combination of the two. - -- A distributed simulation is spread across several processes under the - control of MPI (Message Passing Interface). Each network node is *local* to - exactly one process and complete information about the node is only - available to that process. Information about each connection is stored by - the process in which the connection target is local and is only available - and changeable on that process. - -- Multi-threaded simulations run in a single process in a single computer. As - a consequence, all nodes in a multi-threaded simulation are local. - -- Distribution and multi-threading can be combined by running identical - numbers of threads in each process. - -- A serial simulation has a single process with a single seed. - -- From the NEST user perspective, distributed processes and threads are - visible as **virtual processes**. A simulation distributed across \\(M\\) - MPI processes with \\(T\\) threads each, has \\(N\_{vp} = M times T\\) - virtual processes. It is a basic design principle of NEST that simulations - shall generate *identical* results when run with a fixed \\(N\_{VP}\\), no - matter how the virutal processes are broken down into MPI processes and - threads. - -- Useful information can be obtained like this - - - import nest - nest.NumProcesses() # number of MPI processes - nest.Rank() # rank of MPI process executing command - nest.GetKernelStatus(['num_processes']) # same as nest.NumProcesses() - nest.GetKernelStatus(['local_num_threads']) # number of threads in present process (same for all processes) - nest.GetKernelStatus(['total_num_virtual_procs']) # N_vp = M x T - -- When querying neurons, only very limited information is available for - neurons on other MPI processes. Thus, before checking for specific - information, you need to check if a node is local: - - - n = nest.Create('iaf_neuron') - if nest.GetStatus(n, 'local')[0]: # GetStatus() returns list, pick element - print nest.GetStatus(n, 'vp') # virtual process "owning" node - print nest.GetStatus(n, 'thread') # thread in calling process "owning" node - -Random numbers in parallel simulations ---------------------------------------- - -Ideally, all random numbers in a simulation should come from a single RNG. This -would require shipping truckloads of random numbers from a central RNG process -to all simulations processes and is thus impractical, if not outright -prohibitively costly. Therefore, parallel simulation requires an RNG on each -parallel process. Advances in RNG technology give us today a range of RNGs that -can be used in parallel, with a quite high level of certainty that the resulting -parallel streams of random numbers are non-overlapping and uncorrelated. While -the former can be guaranteed, we are not aware of any generator for which the -latter can be proven. - -### How many generators in a simulation - -In a typical PyNEST simulation running on \\(N\_{vp}\\) virtual processes, we -will encounter \\(2 N\_{vp} + 1\\) random number generators: - -The global NEST RNG -This generator is mainly used when creating connections using -`RandomDivergentConnect`. - -One RNG per VP in NEST -These generators are used when creating connections using -`RandomConvergentConnect` and to provide random numbers to nodes generating -random output, e.g. the `poisson_generator`. - -One RNG per VP in Python -These generators are used to randomized node properties (e.g., the initial -membrane potential) and connection properties (e.g., weights). - -The generators on the Python level are not strictly necessary, as one could in -principle access the per-VP RNGs built into NEST. This would require very -tedious SLI-coding, though. We therefore recommend at present that you use -additional RNGs on the Python side. - -#### Why a Global RNG in NEST - -In some situations, randomized decisions on different virtual processes are not -independent of each other. The most important case are randomized divergent -connections. The problem here is as follows. For the sake of efficiency, NEST -stores all connection information in the virtual process (VP) to which the -target of a connection resides (target process). Thus, all connections are -generated by this target process. Now consider the task of generating 100 -randomized divergent connections emanating from a given source neuron while -using 4 VPs. Then there should be 25 targets on each VP *on average*, but actual -numbers will fluctuate. If independent processes on all VPs tried to choose -target neurons, we could never be sure that exactly 100 targets would be chosen -in total. - -NEST thus creates divergent connections using a global RNG. This random number -generator provides the exact same sequence of random numbers on each virtual -process. Using this global RNG, each VP chooses 100 targets from the entire -network, but actually creates connections only for those targets that reside on -the VP. In practice, the global RNG is implemented using one "clone" on each VP; -NEST checks occasionally that all these clones are synchronized, i.e., indeed -generate identical sequences. - -### Seeding the Random Generators - -Each of the \\(N\_{vp}\\) random generators needs to be seeded with a different -seed to generate a different random number sequences. We recommend that you -choose a *master seed* `msd` and seed the \\(2N\_{vp}+1\\) generators with seeds -`msd`, `msd+1`, ..., `msd+2*N_vp`. Master seeds for for independent experiments -must differ by at least \\(2N\_{vp}+1\\) -. Otherwise, the same sequence(s) would enter in several experiments. - -#### Seeding the Python RNGs - -You can create a properly seeded list of \\(N\_{vp}\\) RNGs on the Python side -using - - import numpy - msd = 123456 - N_vp = nest.GetKernelStatus(['total_num_virtual_procs'])[0] - pyrngs = [numpy.random.RandomState(s) for s in range(msd, msd+N_vp)] - -`msd` is the master seed, choose your own! - -#### Seeding the global RNG - -The global NEST rng is seeded with a single, positive integer number: - - nest.SetKernelStatus({’grng_seed’ : msd+N_vp}) - -#### Seeding the per-process RNGs - -The per-process RNGs are seeded by a list of \\(N\_{vp}\\) -positive integers: - - nest.SetKernelStatus({’rng_seeds’ : range(msd+N_vp+1, msd+2*N_vp+1)}) - -### Choosing the random generator type - -Python and NumPy have the [MersenneTwister MT19937ar](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html) -random number generator built in. There is no simple way of choosing a different -generator in NumPy, but as the MT19937ar appears to be a very robust generator, -this should not cause significant problems. - -NEST uses by default Knuth's lagged Fibonacci random number generator (The Art -of Computer Programming, vol 2, 3rd ed, 9th printing or later, ch 3.6). If you -want to use other generators, you can exchange them as described below. If you -have built NEST without the GNU Science Library (GSL), you will only have the -Mersenne Twister MT19937ar and Knuth's lagged Fibonacci generator available. -Otherwise, you will also have some 60 generators from the GSL at your disposal -(not all of them particularly good). You can see the full list of RNGs using - - nest.sli_run('rngdict info') - -#### Setting a different global RNG - -To set a different global RNG in NEST, you have to pass a NEST random number -generator object to the NEST kernel. This can currently only be done by writing -some SLI code. The following code replaces the current global RNG with MT19937 -seeded with 101: - - nest.sli_run('0 << /grng rngdict/MT19937 :: 101 CreateRNG >> SetStatus') - -The following happens here: - -- `rngdict/MT19937 ::` fetches a "factory" for MT19937 from the `rngdict` - -- `101 CreateRNG` uses the factory to create a single MT19937 generator with - seed 101 - -- This is generator is then passed to the `/grng` status variable of the - kernel. This is a "write only" variable that is invisible in - `GetKernelStatus()`. - -#### Setting different per-processes RNGs - -One always needs to exchange all \\(N\_{vp}\\) per-process RNGs at once. This is -done by (assuming \\(N\_{vp}=2\\) ): - - nest.sli_run('0 << /rngs [102 103] { rngdict/MT19937 :: exch CreateRNG } Map >> SetStatus') - -The following happens here: - -- `[102 103] { rngdict/MT19937 :: exch CreateRNG } Map` creates an array of - two RNG objects seeded with 102 and 103, respectively. - -- This array is then passed to the `/rngs` status variable of the kernel. - This variable is invisible as well. - -Examples --------- - -**NOTE: These examples are not yet updated for NEST 2.4** - -### No random variables in script - -If no explicit random variables appear in your script, i.e., if randomness only -enters in your simulation through random stimulus generators such as -`poisson_generator` or randomized connection routines such as -`RandomConvergentConnect`, you do not need to worry about anything except -choosing and setting your random seeds, possibly exchanging the random number -generators. - -### Randomizing the membrane potential - -If you want to randomize the membrane potential (or any other property of a -neuron), you need to take care that each node is updated by the process on which -it is local using the per-VP RNG for the VP to which the node belongs. -This is achieved by the following code - - pyrngs = [numpy.random.RandomState(s) for s in range(msd, msd+N_vp)] - nodes = nest.Create('iaf_psc_delta', 10) - node_info = nest.GetStatus(nodes) - local_nodes = [(ni['global_id'], ni['vp']) for ni in node_info if ni['local']] - for gid,vp in local_nodes: - nest.SetStatus([gid], {'V_m': pyrngs[vp].uniform(-70.0, -50.0)}) - -The first line generates \\([N\_{vp}\\) properly seeded NumPy RNGs as discussed -above. The next line creates 10 nodes, while the third line extracts status -information about each node. For local nodes, this will be full information, -for non-local nodes we only get the following fields: -`local`, `model` and `type`. On the fourth line, we create a list of tuples, -containing global ID and virtual process number for all local neurons. The for -loop then sets the membrane potential of each local neuron drawn from a uniform -distribution on \\(\[-70, -50\]\\) using the Python-side RNG for the VP to which -the neuron belongs. - -### Randomizing convergent connections - -We continue the above example by creating random convergent connections, -\\(C\_E\\) connections per target node. In the process, we randomize the -connection weights: - - C_E = 10 - nest.CopyModel("static_synapse", "excitatory") - for tgt_gid, tgt_vp in local_nodes: - weights = pyrngs[tgt_vp].uniform(0.5, 1.5, C_E) - nest.RandomConvergentConnect(nodes, [tgt_gid], C_E, - weight=list(weights), delay=2.0, - model="excitatory") - -Here we loop over all local nodes considered as target nodes. For each target, -we create an array of \\(C\_E\\) randomly chosen weights, uniform on -\\([0.5, 1.5\\. We then call `RandomConvergentConnect()` with this weight list -as argument. Note a few details: - -- We need to put `tgt_gid` into brackets as PyNEST functions always expect - lists of GIDs. - -- We need to convert the NumPy array `weights` to a plain Python list, as most - PyNEST functions currently cannot handle array input. - -- If we specify `weight`, we must also provide `delay`. - -You can check the weights selected by - - print nest.GetStatus(nest.GetConnections(), ['source', 'target', 'weight']) - -which will print a list containing a triple of source GID, target GID and weight -for each connection in the network. If you want to see only a subset of -connections, pass source, target, or synapse model to `GetConnections()`. - -### Randomizing divergent connections - -Randomizing the weights (or delays or any other properties) of divergent -connections is more complicated than for convergent connections, because the -target for each connection is not known upon the call to -`RandomDivergentConnect`. We therefore need to first create all connections -(which we can do with a single call, passing lists of nodes and targets), and -then need to manipulate all connections. This is not only more complicated, -but also significantly slower than the example above. - - nest.CopyModel('static_synapse', 'inhibitory', {'weight': 0.0, 'delay': 3.0}) - nest.RandomDivergentConnect(nodes, nodes, C_E, model='inhibitory') - gid_vp_map = dict(local_nodes) - for src in nodes: - conns = nest.GetConnections(source=[src], synapse_model='inhibitory') - tgts = [conn[1] for conn in conns] - rweights = [{'weight': pyrngs[gid_vp_map[tgt]].uniform(-2.5, -0.5)} - for tgt in tgts] - nest.SetStatus(conns, rweights) - -In this code, we first create all connections with weight 0. We then create -`gid_vp_map`, mapping GIDs to VP number for all local nodes. For each node -considered as source, we then find all outgoing excitatory connections from that -node and then obtain a flat list of the targets of these connections. For each -target we then choose a random weight as above, using the RNG pertaining to the -VP of the target. Finally, we set these weights. Note that the code above is -**slow**. Future versions of NEST will provide better solutions. - -### Testing scripts randomizing node or connection parameters - -To ensure that you are consistently using the correct RNG for each node or -connection, you should run your simulation several times the same \\(N\_{vp}\\), -but using different numbers of MPI processes. To this end, add towards the -beginning of your script - - nest.SetKernelStatus({"total_num_virtual_procs": 4}) - -and ensure that spikes are logged to file in the current working directory. -Then run the simulation with different numbers of MPI processes in separate -directories - - mkdir 41 42 44 - cd 41 - mpirun -np 1 python test.py - cd ../42 - mpirun -np 2 python test.py - cd ../44 - mpirun -np 4 python test.py - cd .. - -These directories should now have identical content, something you can check -with `diff`: - - diff 41 42 - diff 41 44 - -These commands should not generate any output. Obviously, this test checks only -a necessary, by no means a sufficient condition for a correct simulation (Oh -yes, do make sure that these directories contain data! Nothing easier that to -pass a diff-test on empty dirs.) diff --git a/extras/userdoc/md/documentation/using_files_and_keyboard_input.md b/extras/userdoc/md/documentation/using_files_and_keyboard_input.md deleted file mode 100644 index ee9a5749ae..0000000000 --- a/extras/userdoc/md/documentation/using_files_and_keyboard_input.md +++ /dev/null @@ -1,159 +0,0 @@ -Using files and keyboard input -============================== - -Overview ---------- - -SLI's input/output fascilities differ from those of PostScript and are close to -the stream concept of C++. However, for compatibility some PostScript output -commands are implemented. - -Like in C++, files are represented as *streams*, which can be put on the stack. -All i/o commands leave their stream argument on the stack, so that operations -can be chained. - -### Example - -Print *Hello World* to the standard output. - - SLI ] cout (Hello World) <- endl - Hello World - SLI [1] ; - SLI ] - -`cout` is the standard output of SLI. The command `<-` takes the role of C++'s -`<<` output operator and prints the ASCII representation of the object at stack -level 0 to the stream at level 1. After this, the object is removed and the -stream remains at level 0. - -The command `endl` corresponds to the C++ manipulator of the same name. It -prints an end of line character to the stream at level 0. Again, it leaves the -stream argument on the stack. - -Now, the abbreviated form of `pop`, i.e. the command `;`, is used to remove the -stream object from the stack. - -Standard streams ------------------ - -The standard streams of a UNIX program are mapped to the following names. Note -that these streams should not be closed by a SLI program, since the result is -undefined. - -Name -Description -`cin` -Standart input stream. -`cout` -Standart output stream. -`cerr` -Standart error output stream. - -Opening and closing a stream ----------------------------- - -Streams are objects which handle the input and output of data to or from some -external target. The target of a stream can be a file, a string, a devide, or -another process. - -Command -Description -`(name) (r) file` -Open file for reading. -`(name) ifstream` -Open file for reading. -`(name) (w) file` -Open file for writing. -`(name) ofstream` -Open file for writing. -`(string) istrstream` -Open string-stream for reading. -`(string) ostrstream` -Open string-stream for writing. -`strstream` -Extract a string from a string-stream. -`stream close` -Close the stream. - -Writing to streams ------------------- - -Command -Description -`stream obj <-` -Print ASCII representation of `obj` to `stream`. -`stream obj <--` -Print detailed ASCII representation of `obj` to `stream`. -`stream obj =` -Print ASCII representation of `obj` to `cout`. -`stream obj ==` -Print detailed ASCII representation of `obj` to `cout`. - -### Example - -Print *Hello World* to a text file. - - SLI ] (test.txt) (w) file - SLI [1] (Hello World!) <- - SLI [1] endl - SLI [1] ; - -Manipulators -------------- - -Manipulators are used to manipulate the state of a stream object. Such changes -can, for instance, affect the precision with which numbers are printed. - -Manipulators take one or more arguments. In general, the manipulator leaves the -stream object at the top of the stack and removes all other arguments. - -Manipulator -Description -`ofstream flush` -Write contents of buffer to file. -`ofstream endl` -Line terminator. -`osstream ends` -char[] string terminator. -`ifstream ws` -Eat white-spaces. -`ofstream boolalpha` -Prints bool as true/false. -`ofstream noboolalpha` -Opposite. -`fstream n setw` -Set width of input/output fields to `n`. -`stream (c) setfill` -Defines a fill symbol `c` for the field. -`ostream left` -Allign to left of the field. -`ostream right` -Allign to right of the field. -`ostream internal` -Sign left and number right. -`ostream showpos` -Print positive sign. -`ostream noshowpos` -Opposite. -`stream uppercase` -`ostream nouppercase` -`ostream oct` -Switch to octal notation. -`ostream dec` -Switch to decimal notation. -`ostream hex` -Switch to hexadecimal notation. -`ostream showbase` -Show base according to use of oct/dec/hex. -`ostream noshowbase` -Don't show base according to use of oct/dec/hex. -`ostream showpoint` -Decimal point is always printed. -`ostream noshowpoint` -Decimal point is never printed. -`ostream n setprecision` -Set number of decimal places to `n`. -`ostream fixed` -Use fixed point notation. -`ostream scientific` -Use scientific notation. diff --git a/extras/userdoc/md/documentation/using_nest_with_music.md b/extras/userdoc/md/documentation/using_nest_with_music.md deleted file mode 100644 index dd9cedc5da..0000000000 --- a/extras/userdoc/md/documentation/using_nest_with_music.md +++ /dev/null @@ -1,307 +0,0 @@ -Using NEST with MUSIC -===================== - - Introduction -------------- - -NEST supports the [MUSIC interface](http://software.incf.org/software/music), a -standard by the INCF, which allows the transmission of data between applications -at runtime. It can be used to couple NEST with other simulators, with -applications for stimulus generation and data analysis and visualization and -with custom applications that also use the MUSIC interface. - -Basically, all communication with MUSIC is mediated via *proxies* that -receive/send data from/to remote applications using MUSIC. Different proxies are -used for the different types of data. At the moment, NEST supports sending and -receiving spike events and receiving continuous data and string messages. - -### Publication - -The implementation of the MUSIC interface for NEST is published as -*Mikael Djurfeldt, Johannes Hjorth, Jochen Martin Eppler, Niraj Dudani, -Moritz Helias, Tobias C Potjans, Upinder S Bhalla, Markus Diesmann, -Jeanette Hellgren Kotaleski, and Örjan Ekeberg. Run-time interoperability -between neuronal simulators based on the MUSIC framework. -Neuroinformatics, 8, 2010. doi:10.1007/s12021-010-9064-z* and available from [here](http://www.springerlink.com/content/r6j425027lmv1251/). - -Sending and receiving spike events ------------------------------------ - -A minimal example for the exchange of spikes between two independent instances -of NEST is given in the example `examples/nest/music/minimalmusicsetup.music`. -It uses one [SLI script](../an_introduction_to_sli/index.html "An Introduction -to SLI"), which sends spikes using a `music_event_out_proxy` and one SLI script, -which receives the spikes using a `music_event_in_proxy`. The configuration file -is shown in the following listing: - - [from] - binary=nest - np=1 - args=minimalmusicsetup_sendnest.sli - - [to] - binary=nest - np=1 - args=minimalmusicsetup_receivenest.sli - from.spikes_out -> to.spikes_in [1] - -This configuration file sets up two applications, `from` and `to`, which are -both instances of `NEST`. The first runs a script to send spike events on the -MUSIC port `spikes_out` to the second, which receives the events on the port -`spikes_in`. The width of the port is 1. The content of -`minimalmusicsetup_sendnest.sli` is contained in the following listing: - - /spike_generator Create /sg Set - sg << /spike_times [1.0 1.5 2.0 ]>> SetStatus - /iaf_neuron Create /n Set - sg n << /weight 750.0 >> Connect - /voltmeter Create /vm Set - vm << /to_memory false /to_screen true >> SetStatus - vm n Connect - /music_event_out_proxy Create /meop Set - meop << /port_name (spikes_out) >> SetStatus - sg meop << /music_channel 0 >> Connect - 10 Simulate - -Line 1 creates a `spike_generator`, which sends three spikes. The spike times -are specified in line 2. The script then creates an `iaf_neuron` in line 3 and -connects the `spike_generator` to the `iaf_neuron` in line 4. The membrane -potential of the `iaf_neuron` is measured by a `voltmeter`, which is created in -line 5 and set to print the measured values in line 6. The connection between -the `voltmeter` and the `iaf_neuron` is established in line 7. Line 8 creates a -`music_event_out_proxy`, which forwards the spikes it receives directly to the -MUSIC event output port `spikes_out` (set in line 9). The `spike_generator` is -connected to the MUSIC channel 0 on the `music_event_out_proxy` in line 10. -Finally, the network is simulated for 10 miliseconds. - -The next listing contains the content of `minimalmusicsetup_receivenest.sli`: - -/music_event_in_proxy Create /meip Set -meip << /port_name (spikes_in) /music_channel 0 >> SetStatus -/iaf_neuron Create /n Set -meip n << /weight 750.0 >> Connect -/voltmeter Create /vm Set -vm << /to_memory false /to_screen true >> SetStatus -vm n Connect -10 Simulate - -Running the example using `mpirun -np 2 music minimalmusicsetup.music` yields -the following output, which shows that the neurons in both processes receive the -same input from the `spike_generator` in the first NEST process and show the -same membrane potential trace. - - NEST v1.9.svn (C) 1995-2008 The NEST Initiative - -70 - -70 - -68.1559 - -61.9174 - -70 - -70 - -70 - -65.2054 - -62.1583 - - NEST v1.9.svn (C) 1995-2008 The NEST Initiative - -70 - -70 - -68.1559 - -61.9174 - -70 - -70 - -70 - -65.2054 - -62.1583 - -Receiving string messages ---------------------------- - -Currently, NEST is only able to receive, but not to send string messages. We -thus use MUSIC's `messagesource` program for the generation of messages in the -following example. The configuration file (`msgtest.music`) is shown in the -following listing: - - stoptime=1.0 - np=1 - [from] - binary=messagesource - args=messages - [to] - binary=./msgtest.py - - from.out -> to.msgdata [0] - -This configuration file connects MUSIC's `messagesource` program to the port -`msgdata` of a NEST instance. The `messagesource` program needs a data file, -which contains the messages and the corresponding time stamps. The data file -(`messages0.dat`) is shown in the following listing: - - 0.3 Hello - 0.7  ! - -Please note that MUSIC uses a default unit of seconds for the specification of -times, while NEST uses miliseconds. The example uses the [PyNEST](../introduction-to-pynest/index.html "PyNEST") -syntax instead of SLI for the NEST part. The script that sets up the receiving -side (`msgtest.py`) of the exampe is shown in the following listing: - - #!/usr/bin/python - - import nest - - mmip = nest.Create ('music_message_in_proxy') - nest.SetStatus (mmip, {'port_name' : 'msgdata'}) - - # Simulate and get message data with a granularity of 10 ms: - time = 0 - while time < 1000: - nest.Simulate (10) - data = nest.GetStatus(mmip, 'data') - print data - time += 10 - - -We first import the `nest` in line 2 and create an instance of the -`music_message_in_proxy` in line 3. In line 4, we set the name of the port it -listens to to `msgdata`. Lines 6 through 11 simulate the network in steps of -10 ms. Running the example using `mpirun -np 2 music msgtest.music` yields the -following output: - - -- N E S T 2 beta -- - Neural Simulation Tool - Copyright 1995-2009 The NEST Initiative - Version 1.9-svn Sep 22 2010 16:50:01 - - This program is provided AS IS and comes with - NO WARRANTY. See the file LICENSE for details. - - Problems or suggestions? - Website  : http://www.nest-initiative.org - Mailing list: nest_user@nest-initiative.org - - Type 'nest.help()' to find out more about NEST. - - Sep 23 16:09:12 Simulate [Info]: - Simulating 10 ms. - - Sep 23 16:09:12 Scheduler::prepare_nodes [Info]: - Please wait. Preparing elements. - - Sep 23 16:09:12 music_message_in_proxy::calibrate() [Info]: - Mapping MUSIC input port 'msgdata' with width=0 and acceptable latency=0 - ms. - - Sep 23 16:09:12 Scheduler::prepare_nodes [Info]: - Simulating 1 nodes. - - Sep 23 16:09:12 Scheduler::resume [Info]: - Entering MUSIC runtime with tick = 0.1 ms - - Sep 23 16:09:12 Scheduler::resume [Info]: - Simulation finished. - [{'messages': [], 'message_times': array([], dtype=float64)}] - - : - - Sep 23 16:13:36 Simulate [Info]: - Simulating 10 ms. - - Sep 23 16:13:36 Scheduler::prepare_nodes [Info]: - Please wait. Preparing elements. - - Sep 23 16:13:36 Scheduler::prepare_nodes [Info]: - Simulating 1 nodes. - - Sep 23 16:13:36 Scheduler::resume [Info]: - Simulation finished. - [{'messages': ['Hello', '!'], 'message_times': array([ 300., 700.])}] - -Receiving continuous data --------------------------- - -As in the case of string message, NEST currently only supports receiving -continuous data, but not sending. This means that we have to use another of -MUSIC's test programs to generate the data for us. This time, we use -`constsource`, which generates a sequence of numbers form 0 to w, where w is the -width of the port. The MUSIC configuration file (`conttest.music`) is shown in -the following listing: - - stoptime=1.0 - [from] - np=1 - binary=constsource - [to] - np=1 - binary=./conttest.py - - from.contdata -> to.contdata [10] - -The receiving side is again implemented using a [PyNEST](/introduction-to-pynest/index.html "PyNEST") -script (`conttest.py`): - - #!/usr/bin/python - - import nest - - mcip = nest.Create('music_cont_in_proxy') - nest.SetStatus(mcip, {'port_name' : 'contdata'}) - - # Simulate and get vector data with a granularity of 10 ms: - time = 0 - while time < 1000: - nest.Simulate (10) - data = nest.GetStatus (mcip, 'data') - print data - time += 10 - -We first import the nest in line 2 and create an instance of the -music\_cont\_in\_proxy in line 3. In line 4, we set the name of the port it -listens to to msgdata. Lines 6 through 11 simulate the network in steps of -10 ms. Running the example using `mpirun -np 2 music conttest.music` yields the -following output: - - -- N E S T 2 beta -- - Neural Simulation Tool - Copyright 1995-2009 The NEST Initiative - Version 1.9-svn Sep 22 2010 16:50:01 - - This program is provided AS IS and comes with - NO WARRANTY. See the file LICENSE for details. - - Problems or suggestions? - Website  : http://www.nest-initiative.org - Mailing list: nest_user@nest-initiative.org - - Type 'nest.help()' to find out more about NEST. - - Sep 23 16:49:09 Simulate [Info]: - Simulating 10 ms. - - Sep 23 16:49:09 Scheduler::prepare_nodes [Info]: - Please wait. Preparing elements. - - Sep 23 16:49:09 music_cont_in_proxy::calibrate() [Info]: - Mapping MUSIC input port 'contdata' with width=10. - - Sep 23 16:49:09 Scheduler::prepare_nodes [Info]: - Simulating 1 nodes. - - Sep 23 16:49:09 Scheduler::resume [Info]: - Entering MUSIC runtime with tick = 0.1 ms - - Sep 23 16:49:09 Scheduler::resume [Info]: - Simulation finished. - [array([ 0., 1., 2., 3., 4., 5., 6., 7., 8., 9.])] - - : - - Sep 23 16:47:24 Simulate [Info]: - Simulating 10 ms. - - Sep 23 16:47:24 Scheduler::prepare_nodes [Info]: - Please wait. Preparing elements. - - Sep 23 16:47:24 Scheduler::prepare_nodes [Info]: - Simulating 1 nodes. - - Sep 23 16:47:24 Scheduler::resume [Info]: - Simulation finished. - [array([ 0., 1., 2., 3., 4., 5., 6., 7., 8., 9.])] diff --git a/pynest/examples/sinusoidal_gamma_generator.py b/pynest/examples/sinusoidal_gamma_generator.py index a47b82ea50..ffe635d415 100644 --- a/pynest/examples/sinusoidal_gamma_generator.py +++ b/pynest/examples/sinusoidal_gamma_generator.py @@ -20,7 +20,8 @@ # along with NEST. If not, see . # -'''Sinusoidal gamma generator example +''' +Sinusoidal gamma generator example ---------------------------------- This script demonstrates the use of the `sinusoidal_gamma_generator` From 92302955a47a9d9d1677f581313814a7d7e248b4 Mon Sep 17 00:00:00 2001 From: steffen Date: Wed, 25 May 2016 08:33:42 +0200 Subject: [PATCH 03/20] repaired some relative links (https://help.github.com/articles/relative-links-in-readmes/) --- .../scheduling-and-simulation-flow.md | 41 ++++++++++++------- 1 file changed, 27 insertions(+), 14 deletions(-) diff --git a/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md b/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md index 15b5fff851..d3c79dd9cf 100644 --- a/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md +++ b/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md @@ -1,30 +1,32 @@ -Scheduling and simulation flow -============================== +# Scheduling and simulation flow -Introduction ------------- +## Introduction -To drive the simulation in time, neurons and devices (*nodes*) are updated in a +To drive the simulation, neurons and devices (*nodes*) are updated in a time-driven fashion by calling a member function on each of them in a regular interval. The spacing of the grid is called the *simulation resolution* (default 0.1ms) and can be set using `SetKernelStatus`: SetKernelStatus("resolution", 0.1) +Even though a neuron model can use smaller time steps internally, the membrane +potential will only be visible to a `multimeter` on the outside at time points +that are multiples of the simulation resolution. + In contrast to the update of nodes, an event-driven approach is used for the synapses, meaning that they are only updated when an event is transmitted through them ([Morrison et al. 2005](http://dx.doi.org/10.1162/0899766054026648)). To speed up the simulation and allow the efficient use of computer clusters, -NEST uses a [hybrid parallelization strategy](../parallel-computing.md). +NEST uses a [hybrid parallelization strategy](../parallel_computing.md). The following figure shows the basic loop that is run upon a call to `Simulate`: ![Simulation Loop](../../img/simulation_loop-241x300.png) + The simulation loop. Light gray boxes denote thread parallel parts, dark gray boxes denote MPI parallel parts. U(St) is the update operator that propagates the internal state of a neuron or device. -Simulation resolution and update interval ------------------------------------------ +## Simulation resolution and update interval Each connection in NEST has it's own specific *delay* that defines the time it takes until an event reaches the target node. We define the minimum delay @@ -34,6 +36,7 @@ influence another node during at least a time of *dmin*, i.e. the elements are effectively decoupled for this interval. ![Definitions of the minimimum delay and the simulation resolution.](../../img/time_definitions-300x61.png) + Definitions of minimum delay (dmin) and simulation resolution (h). Two major optimizations in NEST are built on this decoupling: @@ -52,7 +55,7 @@ NEST will figure out the correct value of *dmin* and *dmax* based on the actual delays used during connection setup. Their actual values can be retrieved using `GetKernelStatus`: - GetKernelStatus("min_delay")   # (A corresponding entry exists for max_delay) + GetKernelStatus("min_delay") # (A corresponding entry exists for max_delay) ### Setting *dmin* and *dmax* manually @@ -77,9 +80,19 @@ wide without need leads to decreased performance due to more update calls and communication cycles (small *dmin*), or increased memory consumption of NEST (large *dmax*). -Related topics --------------- - -Please see the [FAQ on precise spike time neurons](../qa-precise-spike-times.md) -for details about neuron update in continuous time and the [documentation on connection management](../connection-management.md) +## Spike generation and precision + +A neuron fires a spike when the membrane potential is above threshold at the end of an +update interval (i.e., a multiple of the simulation resolution). For most models, the +membrane potential is then reset to some fixed value and clamped to that value during +the refractory time. This means that the last membrane potential value at the last time +step before the spike can vary, while the potential right after the step will usually +be the reset potential (some models may deviate from this). This also means that the +membrane potential recording will never show values above the threshold. The time of +the spike is always the time at *the end of the interval* during which the threshold was +crossed. + +NEST also has a some models that determine the precise time of the threshold crossing +during the interval. Please see the documentation on [precise spike time neurons](simulations-with-precise-spike-times.md) +for details about neuron update in continuous time and the [documentation on connection management](connection_management.md) for how to set the delay when creating synapses. From 8e113fbf3504cfc3ebcf8d77b185d658abb16ccd Mon Sep 17 00:00:00 2001 From: steffen Date: Wed, 25 May 2016 08:52:41 +0200 Subject: [PATCH 04/20] repaired some relative links --- .../md/documentation/scheduling-and-simulation-flow.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md b/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md index d3c79dd9cf..e85faa43f5 100644 --- a/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md +++ b/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md @@ -17,10 +17,10 @@ In contrast to the update of nodes, an event-driven approach is used for the synapses, meaning that they are only updated when an event is transmitted through them ([Morrison et al. 2005](http://dx.doi.org/10.1162/0899766054026648)). To speed up the simulation and allow the efficient use of computer clusters, -NEST uses a [hybrid parallelization strategy](../parallel_computing.md). +NEST uses a [hybrid parallelization strategy](parallel-computing.md). The following figure shows the basic loop that is run upon a call to `Simulate`: -![Simulation Loop](../../img/simulation_loop-241x300.png) +![Simulation Loop](../../img/simulation-loop-241x300.png) The simulation loop. Light gray boxes denote thread parallel parts, dark gray boxes denote MPI parallel parts. U(St) is the update operator that @@ -94,5 +94,5 @@ crossed. NEST also has a some models that determine the precise time of the threshold crossing during the interval. Please see the documentation on [precise spike time neurons](simulations-with-precise-spike-times.md) -for details about neuron update in continuous time and the [documentation on connection management](connection_management.md) +for details about neuron update in continuous time and the [documentation on connection management](connection-management.md) for how to set the delay when creating synapses. From dd20c308809f642deebda4753d1a29a2914e8883 Mon Sep 17 00:00:00 2001 From: steffen Date: Wed, 25 May 2016 09:09:24 +0200 Subject: [PATCH 05/20] added relative links --- extras/userdoc/md/documentation/parallel-computing.md | 8 ++++---- .../part-1-neurons-and-simple-neural-networks.md | 6 +++--- .../md/documentation/part-2-populations-of-neurons.md | 2 +- .../part-3-connecting-networks-with-synapses.md | 4 ++-- .../part-4-topologically-structured-networks.md | 2 +- extras/userdoc/md/documentation/quickref.md | 2 +- extras/userdoc/md/documentation/random-numbers.md | 8 ++++---- .../documentation/simulations-with-precise-spike-times.md | 4 ++-- extras/userdoc/md/documentation/using-nest-with-music.md | 6 +++--- 9 files changed, 21 insertions(+), 21 deletions(-) diff --git a/extras/userdoc/md/documentation/parallel-computing.md b/extras/userdoc/md/documentation/parallel-computing.md index a225c998a3..cd6ff978a1 100644 --- a/extras/userdoc/md/documentation/parallel-computing.md +++ b/extras/userdoc/md/documentation/parallel-computing.md @@ -22,7 +22,7 @@ describe the facilities for parallel and distributed computing in detail. See [Plesser et al (2007)](http://dx.doi.org/10.1007/978-3-540-74466-5_71) for more information on NEST parallelization and be sure to check the documentation -on [Random numbers in NEST](../random-numbers.md "Random numbers in NEST"). +on [Random numbers in NEST](random-numbers.md "Random numbers in NEST"). Concepts and definitions ------------------------ @@ -111,7 +111,7 @@ Using distributed computing To compile NEST for distributed computing, you need a library implementation of MPI on your system. If you are on a cluster, you most likely have this already. Note, that in the case of a pre-packaged MPI library you will need both, the -library and the development packages. Please see the [Installation instructions](../installation.md "Installation") +library and the development packages. Please see the [Installation instructions](installation.md "Installation") for general information on installing NEST. Please be advised that NEST should currently only be run in a homogeneous MPI environment. Running in a heterogenenous environment can lead to unexpected results or even crashes. Please contact the [NEST community](http://www.nest-simulator.org/community/) if you require support for exotic setups. @@ -132,7 +132,7 @@ In some cases it might be necessary to specify MPI compiler wrappers explicitly: $NEST_SOURCE_DIR/configure CC=mpicc CXX=mpicxx --with-mpi -Additional information concerning MPI on OSX can be found [here](../installation.md "Installation"). +Additional information concerning MPI on OSX can be found [here](installation.md "Installation"). ### Running distributed simulations @@ -177,7 +177,7 @@ strategies, the number of virtual processes has to be kept constant. A simulation with a specific number of virtual processes will always yield the same results, no matter how they are distributed over threads and processes, given that the seeds for the random number generators of the different virtual -processes are the same (see [Random numbers in NEST](../random-numbers.md "Random numbers in NEST")). +processes are the same (see [Random numbers in NEST](random-numbers.md "Random numbers in NEST")). In order to achieve a constant number of virtual processes, NEST provides the property *total\_num\_virtual\_procs* to adapt the number of local threads diff --git a/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md b/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md index 4d31a340a6..dda8e2c6e2 100644 --- a/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md +++ b/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md @@ -19,7 +19,7 @@ discusses in this primer, please visit [nest-initiative.org/](http://nest-initia or have a look at the source directory of your NEST installation in the subdirectory: `pynest/examples/`. For the internals of the NEST simulator you may refer -to the [publications](../publications.md "Publications"). +to the [publications](publications.md "Publications"). PyNEST - an interface to the NEST simulator ------------------------------------------- @@ -32,7 +32,7 @@ high-level API. These functions generate code in SLI (Simulation Language Interpreter), the native language of the interpreter of NEST. This interpreter, in turn, controls the NEST simulation kernel. -The NEural Simulation Tool (NEST: [www.nest-initiative.org](../part-1-neurons-and-simple-neural-networks.md)) +The NEural Simulation Tool (NEST: [www.nest-initiative.org](part-1-neurons-and-simple-neural-networks.md)) is designed for the simulation of large heterogeneous networks of point neurons. It is open source software released under the GPL licence. The simulator comes with an interface to Python . illustrates the interaction between the user’s @@ -372,7 +372,7 @@ Here we have just used very simple connection schemes. Connectivity patterns requiring the specification of further parameters, such as in-degree or connection probabilities, must be defined in a dictionary containing the key `"rule"` and the key for parameters associated to the rule. Please see -<../connection-management.md> for an illustrated guide to the usage of + for an illustrated guide to the usage of `Connect`. Command overview diff --git a/extras/userdoc/md/documentation/part-2-populations-of-neurons.md b/extras/userdoc/md/documentation/part-2-populations-of-neurons.md index 7ac38a73b5..4d86843bdc 100644 --- a/extras/userdoc/md/documentation/part-2-populations-of-neurons.md +++ b/extras/userdoc/md/documentation/part-2-populations-of-neurons.md @@ -17,7 +17,7 @@ to: - reset simulations For more information on the usage of NEST, please visit: -[Documentation](../documentation.md). To carry out the code snippets in +[Documentation](documentation.md). To carry out the code snippets in this handout, you need to import `nest` and `numpy`. Creating parameterised populations of nodes diff --git a/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md b/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md index 22ae017c9b..1b2e7caa9b 100644 --- a/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md +++ b/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md @@ -14,7 +14,7 @@ have worked through this material, you will know how to: - set synapse values during and after connection For more information on the usage of NEST, please visit: -[Documentation](../documentation.md). To carry out the code snippets in +[Documentation](documentation.md). To carry out the code snippets in this handout, you need to import `nest` and `numpy`. Parameterising synapse models @@ -146,7 +146,7 @@ set (for example `mu`). Here we show an example where the parameters `alpha` and "delay": 1.0 } nest.Connect(epop1, neuron, "all_to_all", syn_dict) -Available distributions and associated parameters are described in [Connection_Management](../connection-management.md)), +Available distributions and associated parameters are described in [Connection_Management](connection-management.md)), the most common ones are: | Distributions | Keys | diff --git a/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md b/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md index aa973bb14d..ed9a743841 100644 --- a/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md +++ b/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md @@ -13,7 +13,7 @@ networks. When you have worked through this material you will be able to: - Visualise the connectivity For more information on the usage of NEST, please visit: -[http://www.nest-simulator.org/documentation/](../documentation.md))> +[http://www.nest-simulator.org/documentation/](documentation.md))> Incorporating structure in networks of point neurons ---------------------------------------------------- diff --git a/extras/userdoc/md/documentation/quickref.md b/extras/userdoc/md/documentation/quickref.md index 84f58af902..155e44de17 100644 --- a/extras/userdoc/md/documentation/quickref.md +++ b/extras/userdoc/md/documentation/quickref.md @@ -35,7 +35,7 @@ Table of Contents - [Parallel computing](#parallel-computing) -- [Alphabetical command index](../helpindex/cmd_index.html) +- [Alphabetical command index](../helpindex/cmd_index.md) Introduction ------------ diff --git a/extras/userdoc/md/documentation/random-numbers.md b/extras/userdoc/md/documentation/random-numbers.md index c7020d5538..1eef9d2f1c 100644 --- a/extras/userdoc/md/documentation/random-numbers.md +++ b/extras/userdoc/md/documentation/random-numbers.md @@ -36,15 +36,15 @@ uniformly distributed integers in {0, 1, ..., N}. Random *deviate* generators, on the other hand, provide random numbers drawn from a range of distributions, such as the normal or binomial distributions. In most cases, you will be using random deviate generators. They are in particular used to initialize properties -during network construction, as described in the sections [Changes in NEST 2.4](../random-numbers.md#Changes-in-random-number-generation-in-NEST-2.4) and [Examples](../random-numbers.md#Examples) below. +during network construction, as described in the sections [Changes in NEST 2.4](random-numbers.md#Changes-in-random-number-generation-in-NEST-2.4) and [Examples](random-numbers.md#Examples) below. Changes in random number generation in NEST 2.4 ------------------------------------------------- Random deviate generation has become significantly more powerful in NEST 2.4, to fully support randomization of connections parameters offered by the revised -`Connect` function, as described in [Connection Management](../connection-management.md "Connection Management") -and illustrated by the [examples](../random-numbers.md#examples) below. +`Connect` function, as described in [Connection Management](connection-management.md "Connection Management") +and illustrated by the [examples](random-numbers.md#examples) below. We have also made minor changes to make to achieve greater similarity between NEST, PyNN, and NumPy. For most users, these changes only add new features. Only existing scripts using @@ -125,7 +125,7 @@ The changes are as follows: Basics of parallel simulation in NEST -------------------------------------- -For details of parallelization in NEST, please see [Parallel Computing](../parallel-computing.md "Parallel Computing") +For details of parallelization in NEST, please see [Parallel Computing](parallel-computing.md "Parallel Computing") and [Plesser et al (2007)](http://dx.doi.org/10.1007/978-3-540-74466-5_71). Here, we just summarize a few basics. diff --git a/extras/userdoc/md/documentation/simulations-with-precise-spike-times.md b/extras/userdoc/md/documentation/simulations-with-precise-spike-times.md index 4b7fd146eb..d8effd78d7 100644 --- a/extras/userdoc/md/documentation/simulations-with-precise-spike-times.md +++ b/extras/userdoc/md/documentation/simulations-with-precise-spike-times.md @@ -2,7 +2,7 @@ Simulations with precise spike times ==================================== The simulation resolution *h* and the minimum synaptic transmission delay -*dmin* define the two major time intervals of the [scheduling and simulation flow of NEST](../scheduling-and-simulation-flow.md): +*dmin* define the two major time intervals of the [scheduling and simulation flow of NEST](scheduling-and-simulation-flow.md): neurons update their state variables in steps of *h*, whereas spikes are communicated and delivered to their targets in steps of *dmin*, where *dmin* is a multiple of *h*. @@ -89,4 +89,4 @@ Questions and answers about precise neurons During the review process of the above mentioned papers, we came up with a list of questions and answers pertaining to the implementation and usage of precise -spiking neurons. This list can be found [here](../qa-precise-spike-times.md). +spiking neurons. This list can be found [here](qa-precise-spike-times.md). diff --git a/extras/userdoc/md/documentation/using-nest-with-music.md b/extras/userdoc/md/documentation/using-nest-with-music.md index 3b9254ea00..67d14bba8f 100644 --- a/extras/userdoc/md/documentation/using-nest-with-music.md +++ b/extras/userdoc/md/documentation/using-nest-with-music.md @@ -29,7 +29,7 @@ Sending and receiving spike events A minimal example for the exchange of spikes between two independent instances of NEST is given in the example `examples/nest/music/minimalmusicsetup.music`. -It uses one [SLI script](../an-introduction-to-sli.md "An Introduction +It uses one [SLI script](an-introduction-to-sli.md "An Introduction to SLI"), which sends spikes using a `music_event_out_proxy` and one SLI script, which receives the spikes using a `music_event_in_proxy`. The configuration file is shown in the following listing: @@ -139,7 +139,7 @@ which contains the messages and the corresponding time stamps. The data file 0.7  ! Please note that MUSIC uses a default unit of seconds for the specification of -times, while NEST uses miliseconds. The example uses the [PyNEST](../introduction-to-pynest.md "PyNEST") +times, while NEST uses miliseconds. The example uses the [PyNEST](introduction-to-pynest.md "PyNEST") syntax instead of SLI for the NEST part. The script that sets up the receiving side (`msgtest.py`) of the exampe is shown in the following listing: @@ -234,7 +234,7 @@ the following listing: from.contdata -> to.contdata [10] -The receiving side is again implemented using a [PyNEST](/introduction-to-pynest.md "PyNEST") +The receiving side is again implemented using a [PyNEST](introduction-to-pynest.md "PyNEST") script (`conttest.py`): #!/usr/bin/python From e49959ff62ce926826c06c1cff069f5611ed3efe Mon Sep 17 00:00:00 2001 From: steffen Date: Wed, 25 May 2016 10:16:49 +0200 Subject: [PATCH 06/20] changed site internal links --- .../userdoc/md/documentation/connection-management.md | 10 +++++----- extras/userdoc/md/documentation/index.md | 2 +- extras/userdoc/md/documentation/installation.md | 8 ++++---- extras/userdoc/md/documentation/random-numbers.md | 2 +- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/extras/userdoc/md/documentation/connection-management.md b/extras/userdoc/md/documentation/connection-management.md index e0af02a6b3..4dd8719b42 100644 --- a/extras/userdoc/md/documentation/connection-management.md +++ b/extras/userdoc/md/documentation/connection-management.md @@ -11,11 +11,11 @@ function has been renamed to `OneToOneConnect()`. However, simple cases, which are just creating one-to-one connections between two lists of nodes are still working with the new command without the need to change the code. Note that the topology-module is not effected by theses changes. The translation between the -old and the new connect routines is described in [Old Connection Routines](connection-management.md#Old-Connection-Routines). +old and the new connect routines is described in [Old Connection Routines](connection-management.md#old-connection-Routines). The connectivity pattern is defined inside the `Connect()` function under the key 'rule'. The patterns available are described in -[Connection Rules](connection-management.md#Connection-Rules). In +[Connection Rules](connection-management.md#connection-rules). In addition the synapse model can be specified within the connect function and all synaptic parameters can be randomly distributed. @@ -46,7 +46,7 @@ string defining the synapse model (default: 'static\_synapse') or as a dictionary. By using the key-word variant (`Connect(pre, post, syn_spec=syn_spec_dict)`), the conn\_spec can be omitted in the call to connect and 'all\_to\_all' is assumed as the default. -The exact usage of the synapse dictionary is described in [Synapse Specification](connection-management.md#Synapse-Specification). +The exact usage of the synapse dictionary is described in [Synapse Specification](connection-management.md#synapse-specification). Connection Rules ---------------- @@ -162,7 +162,7 @@ Example: The synapse properties can be given as a string or a dictionary. The string can be the name of a pre-defined synapse which can be found in the synapsedict (see -[Synapse Types](connection-management.md#Synapse-Types)) or a +[Synapse Types](connection-management.md#synapse-types)) or a manually defined synapse via `CopyModel()`. Example: @@ -185,7 +185,7 @@ parameter types, as long as they agree with the connection routine ('rule'). **Scalar** parameters must be given as floats except for the 'receptor\_type' which has to be initialized as an integer. For more information on the receptor -type see [Receptor Types](connection-management.md#Synapse-Types) . +type see [Receptor Types](connection-management.md#synapse-types) . Example: diff --git a/extras/userdoc/md/documentation/index.md b/extras/userdoc/md/documentation/index.md index 8625525bd1..5fab6b51f3 100644 --- a/extras/userdoc/md/documentation/index.md +++ b/extras/userdoc/md/documentation/index.md @@ -7,7 +7,7 @@ The Neural Simulation Tool Use NEST for your research, modify and improve it - Current Release [NEST 2.10.0 (Dec 31 2015)](download.md#h1-17987) + Current Release [NEST 2.10.0 (Dec 31 2015)](download.md) - *Tools for modern computational neuroscience* diff --git a/extras/userdoc/md/documentation/installation.md b/extras/userdoc/md/documentation/installation.md index 61f8f29b2a..19ad4c1906 100644 --- a/extras/userdoc/md/documentation/installation.md +++ b/extras/userdoc/md/documentation/installation.md @@ -5,7 +5,7 @@ Introduction ------------ NEST compiles and runs on most Unix-like operating systems including Linux and -Mac OS X. For using NEST on Microsoft Windows, see [below](installation.md#Windows). +Mac OS X. For using NEST on Microsoft Windows, see [below](installation.md#windows). The installation instructions here should work on all recent versions of Debian or Ubuntu. For more generic installation instructions, see the files README and INSTALL in the top source directory. @@ -30,8 +30,8 @@ Following are the basic steps to compile and install NEST from source code: 8. See the [Getting started](getting-started.md "Getting started") pages to find out how to get going with NEST -Please see the sections on [minimal](installation.md#Minimal_configuration) and -[standard configuration](installation.md#Standard_configuration "Installation") +Please see the sections on [minimal](installation.md#minimal-configuration) and +[standard configuration](installation.md#standard-configuration "Installation") below for details. What gets installed where @@ -77,7 +77,7 @@ Dependencies NEST needs a few third party tools and libraries to work. On many operating systems, these can be installed using a *package manager* like `apt`, `port` or `fink` -(see [Standard configuration](installation.md#Standard_configuration "Software:Installation")). +(see [Standard configuration](installation.md#standard-configuration "Software:Installation")). If you are building NEST from the SVN sources, you need the GNU autotools installed on your system to bootstrap the build system. These consist of diff --git a/extras/userdoc/md/documentation/random-numbers.md b/extras/userdoc/md/documentation/random-numbers.md index 1eef9d2f1c..7e3bf13029 100644 --- a/extras/userdoc/md/documentation/random-numbers.md +++ b/extras/userdoc/md/documentation/random-numbers.md @@ -36,7 +36,7 @@ uniformly distributed integers in {0, 1, ..., N}. Random *deviate* generators, on the other hand, provide random numbers drawn from a range of distributions, such as the normal or binomial distributions. In most cases, you will be using random deviate generators. They are in particular used to initialize properties -during network construction, as described in the sections [Changes in NEST 2.4](random-numbers.md#Changes-in-random-number-generation-in-NEST-2.4) and [Examples](random-numbers.md#Examples) below. +during network construction, as described in the sections [Changes in NEST 2.4](random-numbers.md#changes-in-random-number-generation-in-NEST-2.4) and [Examples](random-numbers.md#examples) below. Changes in random number generation in NEST 2.4 ------------------------------------------------- From 6d8a3614cf93fa7c7f4f744a9e9eff84dc1e4b80 Mon Sep 17 00:00:00 2001 From: steffen Date: Mon, 30 May 2016 08:32:14 +0200 Subject: [PATCH 07/20] changed to atx header style --- .../documentation/an-introduction-to-sli.md | 12 +-- .../analog-recording-with-multimeter.md | 9 +- extras/userdoc/md/documentation/community.md | 12 +-- .../md/documentation/connection-management.md | 30 +++---- .../documentation/continuous-integration.md | 12 +-- .../userdoc/md/documentation/documentation.md | 21 ++--- extras/userdoc/md/documentation/download.md | 9 +- extras/userdoc/md/documentation/features.md | 27 ++---- .../userdoc/md/documentation/first-steps.md | 27 ++---- .../frequently-asked-questions.md | 15 ++-- .../md/documentation/getting-started.md | 12 +-- extras/userdoc/md/documentation/index.md | 21 ++--- .../userdoc/md/documentation/installation.md | 30 +++---- .../documentation/introduction-to-pynest.md | 3 +- extras/userdoc/md/documentation/license.md | 12 +-- .../md/documentation/neural-simulations.md | 24 ++---- .../documentation/objects-and-data-types.md | 32 +++---- .../md/documentation/parallel-computing.md | 24 +++--- ...rt-1-neurons-and-simple-neural-networks.md | 33 +++----- .../part-2-populations-of-neurons.md | 24 ++---- ...art-3-connecting-networks-with-synapses.md | 24 ++---- ...art-4-topologically-structured-networks.md | 34 +++----- .../md/documentation/programming-in-sli.md | 30 +++---- .../documentation/qa-precise-spike-times.md | 3 +- extras/userdoc/md/documentation/quickref.md | 84 +++++++------------ .../md/documentation/random-numbers.md | 18 ++-- .../scheduling-and-simulation-flow.md | 24 +++--- .../simulations-with-precise-spike-times.md | 9 +- .../using-files-and-keyboard-input.md | 20 ++--- .../md/documentation/using-nest-with-music.md | 16 ++-- 30 files changed, 226 insertions(+), 425 deletions(-) diff --git a/extras/userdoc/md/documentation/an-introduction-to-sli.md b/extras/userdoc/md/documentation/an-introduction-to-sli.md index 55122dce5a..e68cf46e53 100644 --- a/extras/userdoc/md/documentation/an-introduction-to-sli.md +++ b/extras/userdoc/md/documentation/an-introduction-to-sli.md @@ -1,8 +1,6 @@ -An Introduction to SLI -====================== +# An Introduction to SLI -Introduction ------------- +## Introduction NEST can be started by typing @@ -25,8 +23,7 @@ at the command prompt. You should then see something like this: Type 'help' to get more information. Type 'quit' or CTRL-D to quit NEST. -Command line switches ---------------------- +## Command line switches Type @@ -74,8 +71,7 @@ to an integer. Using `mark` and `>>`, the content of the userargs array is added to a dictionary, which is stored under the name `args`. The second line just prints the content of the lamda variable. -SLI user manual ---------------- +## SLI user manual This manual gives a brief overview of the SLI programming language. diff --git a/extras/userdoc/md/documentation/analog-recording-with-multimeter.md b/extras/userdoc/md/documentation/analog-recording-with-multimeter.md index f01480b3a3..997c93692e 100644 --- a/extras/userdoc/md/documentation/analog-recording-with-multimeter.md +++ b/extras/userdoc/md/documentation/analog-recording-with-multimeter.md @@ -1,5 +1,4 @@ -Analog recording with multimeter -================================ +# Analog recording with multimeter As of r89xx, NEST replaces a range of analog recording devices, such as voltmeter, conductancemeter and aeif\_w\_meter with a universal *multimeter*, @@ -32,8 +31,7 @@ Multimeter works essentially as the old-style voltmeter, but with a few changes: - Any node can only be recorded from by one multimeter. -Adapting scripts using voltmeter --------------------------------- +## Adapting scripts using voltmeter Many NEST users have scripts that use voltmeter to record membrane potential. To ease the transition to the new-style analog recording, NEST still provides a @@ -48,8 +46,7 @@ events/V\_m instead of from events/potentials, e.g. array([-70. , -70. , -70. , -70. , -70. , -70. , -70. , -70. , -An example ----------- +## An example As an example, here is the multimeter.py example from the PyNEST examples set: diff --git a/extras/userdoc/md/documentation/community.md b/extras/userdoc/md/documentation/community.md index 8860277285..3eebe91f0e 100644 --- a/extras/userdoc/md/documentation/community.md +++ b/extras/userdoc/md/documentation/community.md @@ -1,8 +1,6 @@ -Community -========= +# Community -Getting support ---------------- +## Getting support The NEST User Mailing list is intended to be a forum for questions on the usage of NEST, the exchange of code and general discussions about NEST. @@ -18,8 +16,7 @@ Subscription Archive (only subscribed users) -Contributing ------------- +## Contributing NEST draws its strength from the many people that use and improve it. We are happy to consider your contributions (e.g. own models, bug or documentation @@ -29,8 +26,7 @@ Please see the [NEST developer space](http://nest.github.io/nest-simulator) for information about the development workflow of NEST and for how to create a fork of our Git repository and pull requests against it. -Reporting bugs --------------- +## Reporting bugs The primary place to go to if you find an error is the [GitHub issue tracker for NEST](https://github.com/nest/nest-simulator/issues). Please take the time diff --git a/extras/userdoc/md/documentation/connection-management.md b/extras/userdoc/md/documentation/connection-management.md index 4dd8719b42..e8023b0a40 100644 --- a/extras/userdoc/md/documentation/connection-management.md +++ b/extras/userdoc/md/documentation/connection-management.md @@ -1,5 +1,4 @@ -Connection Management -===================== +# Connection Management From NEST 2.4 onwards the old connection routines (i.e. `(Random)ConvergentConnect`, `(Random)DivergentConnect` and plain `Connect`) are @@ -48,8 +47,7 @@ syn_spec=syn_spec_dict)`), the conn\_spec can be omitted in the call to connect and 'all\_to\_all' is assumed as the default. The exact usage of the synapse dictionary is described in [Synapse Specification](connection-management.md#synapse-specification). -Connection Rules ----------------- +## Connection Rules Connection rules are specified using the `conn_spec` parameter, which can be a string naming a connection rule or a dictionary containing a rule specification. @@ -57,8 +55,7 @@ Only connection rules requiring no parameters can be given as strings, for all other rules, a dictionary specifying the rule and its parameters, such as in- or out-degrees, is required. -one-to-one ----------- +## one-to-one The ith node in `pre` is connected to the ith node in `post`. The node lists pre and post have to be of the same length. @@ -84,8 +81,7 @@ Example: delay = 0.5 Connect(A[0], B[0], weight, delay) -all-to-all ----------- +## all-to-all ![all-to-all connections](../../img/All_to_all.png) all-to-all connections @@ -306,8 +302,7 @@ needs to be defined in two steps: For further information on the distributions see [Random numbers in NEST](random-numbers.md "Random numbers in NEST"). -Old Connection Routines ------------------------ +## Old Connection Routines The old connection routines are still available in NEST 2.4, apart from the old `Connect()` which has been renamed to `OneToOneConnect()` and whose the support @@ -442,8 +437,7 @@ Example new connection routine: syn_dict = {'model': 'my_synapse', 'weight': w0, 'delay': w0} nest.Connect(A, B, conn_dict, syn_dict) -Topological Connections ------------------------ +## Topological Connections If the connect functions above are not sufficient, the topology provides more sophisticated functions. For example, it is possible to create receptive field @@ -451,8 +445,7 @@ structures and much more! See [Topological Connections](Topology_UserManual.pdf) for more information. -Receptor Types --------------- +## Receptor Types Each connection in NEST targets a specific receptor type on the post-synaptic node. Receptor types are identified by integer numbers, the default receptor @@ -491,8 +484,7 @@ The code block above connects a standard integrate-and-fire neuron to a somatic excitatory receptor of a multi-compartment integrate-and-fire neuron model. The result is illustrated in the figure. -Synapse Types -------------- +## Synapse Types NEST supports multiple synapse types that are specified during connection setup. The default synapse type in NEST is `static_synapse`. Its weight does not change @@ -550,8 +542,7 @@ copied model are taken. events a synapse type is able to transmit is documented in the *Transmits* section of the model documentation. -Inspecting Connections ----------------------- +## Inspecting Connections `GetConnections(source=None, target=None, synapse_model=None)`: Return an array of identifiers for connections that match the given parameters. source and @@ -581,8 +572,7 @@ function, which will then return a list with the parameters of the connections: 'source': 1, 'receptor': 0}] -Modifying existing Connections ------------------------------- +## Modifying existing Connections To modify the connections of an existing connection, one also has to obtain handles to the connections with `GetConnections()` first. These can then be diff --git a/extras/userdoc/md/documentation/continuous-integration.md b/extras/userdoc/md/documentation/continuous-integration.md index 36c0353902..fab7c4e52e 100644 --- a/extras/userdoc/md/documentation/continuous-integration.md +++ b/extras/userdoc/md/documentation/continuous-integration.md @@ -1,8 +1,6 @@ -Continuous Integration -====================== +# Continuous Integration -Introduction ------------- +## Introduction [**Continuous Integration**](http://en.wikipedia.org/wiki/Continuous_integration) (CI) is a software development practice where quality control is continuously @@ -29,8 +27,7 @@ getting into the tree and timely reporting of identified problems. This way, issues will be discovered earlier and the amount of efforts to fix them will be significantly decreased (hopefully). -Continuous Integration at NEST Initiative --------------------------------------------------------------------------------------------------------------------------- +## Continuous Integration at NEST Initiative The current CI implementation is now available at the following URL: @@ -115,8 +112,7 @@ to the build system: - Yury V. Zaytsev -Further reading ---------------- +## Further reading - [Martin Fowler's paper on Continuous Integration](http://martinfowler.com/articles/continuousIntegration.html) diff --git a/extras/userdoc/md/documentation/documentation.md b/extras/userdoc/md/documentation/documentation.md index eb21f17e10..3268e21680 100644 --- a/extras/userdoc/md/documentation/documentation.md +++ b/extras/userdoc/md/documentation/documentation.md @@ -1,14 +1,10 @@ -Documentation -============= +# Documentation -[Installing NEST](installation.md "Installation") ------------------------------------------------------------------------------ +## [Installing NEST](installation.md "Installation") -[Introduction to PyNEST](introduction-to-pynest.md "Introduction to PyNEST") --------------------------------------------------------------------------------------------------------- +## [Introduction to PyNEST](introduction-to-pynest.md "Introduction to PyNEST") -NEST User Manual ---------------------------------------------------------------------------- +## NEST User Manual - [Frequently Asked Questions](frequently-asked-questions.md "Frequently Asked Questions") - [Analog recording with multimeter](analog-recording-with-multimeter.md "Analog recording with multimeter") @@ -23,8 +19,7 @@ NEST User Manual - [NEST/SLI Quick Reference](quickref.md) - [NEST Command Index](helpindex.md) -Example Networks ----------------- +## Example Networks - [brunel_alpha_nest](py_samples/brunel_alpha_nest.md) - [precise_spiking](py_samples/precise_spiking.md) @@ -62,15 +57,13 @@ Example Networks - [if_curve](py_samples/if_curve.md) - [sinusoidal_gamma_generator](py_samples/sinusoidal_gamma_generator.md) -Further Reading ---------------- +## Further Reading - [NEST by Example](wp-content/uploads/2015/02/NEST_by_Example.pdf) - Read and improve the [NEST article on Scholarpedia.org](cholarpedia.org/article/NEST_\(NEural_Simulation_Tool)) - Read and improve the [NEST article on Wikipedia](http://en.wikipedia.org/wiki/NEST_\(software)) -NEST Developer Manual ---------------------- +## NEST Developer Manual For information about modifying and extending NEST and contributing your code to the official version, please head over to the [NEST Developer Space](http://nest.github.io/nest-simulator.html). diff --git a/extras/userdoc/md/documentation/download.md b/extras/userdoc/md/documentation/download.md index f0ff1673bc..6f6cc9632d 100644 --- a/extras/userdoc/md/documentation/download.md +++ b/extras/userdoc/md/documentation/download.md @@ -1,5 +1,4 @@ -Download & Releases -=================== +# Download & Releases NEST is available under the [GNU General Public License 2 or later](license.md "License"). This means that you can @@ -12,8 +11,7 @@ To find out more about NEST, see the [list of features](features.md "Features") and the [user documentation](documentation.md "Documentation"). For details about how to contribute to the development of NEST, see the [developer space](http://nest.github.io/nest-simulator "Development"). -Citing NEST ------------ +## Citing NEST Please cite NEST in any of your work which is based on NEST. @@ -41,8 +39,7 @@ Here is a suitable BibTeX entry: If you tell us about your publications that used NEST, we will add it to our publication list, thus making it visible to potential readers. -Ubuntu 15.10 Live Media with NEST 2.8.0 ---------------------------------------- +## Ubuntu 15.10 Live Media with NEST 2.8.0 **[Download](http://www.nest-simulator.org/downloads/gplreleases/lubuntu-15.10_nest-2.8.0.ova)** (OVA, ~2.3G)          **[Checksum](http://www.nest-simulator.org/downloads/gplreleases/lubuntu-15.10_nest-2.8.0.ova.sha512sum)** (sha512sum) diff --git a/extras/userdoc/md/documentation/features.md b/extras/userdoc/md/documentation/features.md index 0242237873..b52f223d67 100644 --- a/extras/userdoc/md/documentation/features.md +++ b/extras/userdoc/md/documentation/features.md @@ -1,16 +1,13 @@ -Features -======== +# Features -General ------------------------------------------------------- +## General - Python based user interface ([PyNEST](introduction-to-pynest.md )) - Built-in simulation language interpreter ([SLI](an-introduction-to-sli.md "An Introduction to SLI")) - Multi-threading to use multi-processor machines efficiently - MPI-parallelism to use computer clusters and super computers -Neuron models -------------- +## Neuron models - Integrate and fire (IAF) neuron models with current based synapses (delta-, exponential- and alpha-function shaped) @@ -27,27 +24,23 @@ Neuron models - Neuron models with few compartments -Synapse models --------------- +## Synapse models - Static synapses - Spike-timing dependent plasticity (STDP) - Short-term plasticity ([Tsodyks et al. 2000](http://neuro.cjb.net/cgi/content/abstract/20/1/RC50)) - Neuromodulatory synapses using dopamine -Network models --------------- +## Network models - Topology Module for creating complex networks ([Topology Module User Manual (PDF)](http://www.nest-simulator.org/wp-content/uploads/2014/12/NESTTopologyUserManual.pdf "NESTTopologyUserManual.pdf")) -Interoperability ----------------- +## Interoperability - Interface to the Multi Simulator Coordinator [MUSIC](using-nest-with-music.md "Using NEST with MUSIC") - Backend for the simulator-independent modeling tool [PyNN](http://neuralensemble.org/trac/PyNN/) -Accuracy --------- +## Accuracy - Each neuron model is assigned an appropriate solver @@ -60,16 +53,14 @@ Accuracy - For some neuron models [spike interaction in continuous time](simulations-with-precise-spike-times/) is available -Verification ------------- +## Verification - After installation NEST can be verified by an automatic testsuite - The testsuite is automatically run after each modification of the NEST sources. You can watch the current status on our [Continuous Integration](continuous-integration.md "Continuous Integration") system. -Supported platforms -------------------- +## Supported platforms - Linux - Mac OS X diff --git a/extras/userdoc/md/documentation/first-steps.md b/extras/userdoc/md/documentation/first-steps.md index 5e8266c586..620cee8b3d 100644 --- a/extras/userdoc/md/documentation/first-steps.md +++ b/extras/userdoc/md/documentation/first-steps.md @@ -1,8 +1,6 @@ -First Steps -=========== +# First Steps -Overview --------- +## Overview SLI is the simulation language interface of NEST. It is a stack language where each command expects to find its arguments on the stack. @@ -31,8 +29,7 @@ Each command expects to find its arguments on the stack. When a - Any results which are produced by the command are returned to the stack, so you can use them in other operations. -Commands with one argument --------------------------- +## Commands with one argument Commands which need one argument take their argument from the top of the stack. If the command produces a result, it is placed on @@ -47,8 +44,7 @@ Commands which need one argument take their argument from the top Here, the command `log` is used to compute the decadic logarithm of 10. Then, the command `=` is used to display the result of this computation. -Commands with more arguments ----------------------------- +## Commands with more arguments Commands which need more than one argument, take their arguments from level 0, 1, 2, and so forth and return their result to level 0, the top of the stack. @@ -73,8 +69,7 @@ stack without changing it. 3 SLI [1] -Using previous results ----------------------- +## Using previous results Chain calculations are calculations which involve more than one operation. A stack is particularly useful for chaining operations,because it retains @@ -93,8 +88,7 @@ This example shows, how the stack can be used for chain calculations. Calculate Notice that the results of the fist two operations remain on the stack, until they are used in the multiplication. -Exchanging the first two stack levels -------------------------------------- +## Exchanging the first two stack levels The command `exch` exchanges the contents of the levels 0 and 1. This is useful, if the order of objects on the stack does not match the order required by the @@ -110,8 +104,7 @@ Calculate 1/ln(2). SLI [1] = 1.4427 -Removing stack elements ------------------------ +## Removing stack elements The command `pop` removes the top object (level 0) of the stack. The remaining items move up on the stack, so that the object which was at level 1 is now at @@ -119,8 +112,7 @@ level 0. The command `clear` clears the entire stack. -Duplicating the top element ---------------------------- +## Duplicating the top element The command `dup` duplicates the contents of the object at level 0 and pushes the other element down one level. @@ -138,8 +130,7 @@ Calculate (1+4/2) + exp(1+4/2) SLI [1] = 23.0855 -Important stack commands ------------------------- +## Important stack commands Command Description diff --git a/extras/userdoc/md/documentation/frequently-asked-questions.md b/extras/userdoc/md/documentation/frequently-asked-questions.md index 5a2da4f051..20b6dfc27e 100644 --- a/extras/userdoc/md/documentation/frequently-asked-questions.md +++ b/extras/userdoc/md/documentation/frequently-asked-questions.md @@ -1,8 +1,6 @@ -Frequently Asked Questions -========================== +# Frequently Asked Questions -Installation ------------- +## Installation 1. **If I compile NEST with MPI support, I get errors about `SEEK_SET`, `SEEK_CUR` and `SEEK_END` being defined** This is a known issue in some MPI @@ -43,8 +41,7 @@ Installation problem is to import SciPy before PyNEST. See for the official bug report in NumPy. -Neuron models -------------- +## Neuron models 1. **I cannot see any of the conductance based models. Where are they?** Some neuron model need the GNU Scientific Library (GSL) to work. The @@ -53,8 +50,7 @@ Neuron models installed. To solve this problem, install the GSL and its development headers. Then reconfigure and recompile NEST. -Connections ------------ +## Connections 1. **How can I create connections to multicompartment neurons?** You need to create a synapse type with the proper receptor\_type as in this @@ -66,8 +62,7 @@ Connections nest.Connect(n, n[:1], sync_spec={'model'='exc_dist_syn'}) nest.Simulate(10) -Physical units in nest ----------------------- +## Physical units in nest - time - ms - voltage - mV diff --git a/extras/userdoc/md/documentation/getting-started.md b/extras/userdoc/md/documentation/getting-started.md index 908225c6e9..58b1105901 100644 --- a/extras/userdoc/md/documentation/getting-started.md +++ b/extras/userdoc/md/documentation/getting-started.md @@ -1,5 +1,4 @@ -Getting started -=============== +# Getting started [Documentation](documentation.md "Documentation") This page contains the steps that you should follow right after you @@ -7,8 +6,7 @@ This page contains the steps that you should follow right after you starting point is the help page, which is available as command `help` in SLI and `nest.help()` in PyNEST -Set up the integrated helpdesk ------------------------------- +## Set up the integrated helpdesk The command `helpdesk` needs to know which browser to launch in order to display the help pages. The browser is set as an option of `helpdesk`. Please see the @@ -20,16 +18,14 @@ replace `$PREFIX` with the prefix you chose during the configuration of NEST. If you did not explicitly specify one, it is most likely set to `/usr` or `/usr/local` depending on what system you are. -Tell NEST about your MPI setup ------------------------------- +## Tell NEST about your MPI setup If you compiled NEST with support for distributed computing via MPI, you have to tell it how your `mpirun`/`mpiexec` command works by defining the function mpirun in your `~/.nestrc` file. This file already contains an example implementation that should work with [OpenMPI](http://www.openmpi.org) library. -Creating Models with NEST -------------------------- +## Creating Models with NEST After NEST is installed and configured properly, you can start to build your model. diff --git a/extras/userdoc/md/documentation/index.md b/extras/userdoc/md/documentation/index.md index 5fab6b51f3..3aed2be878 100644 --- a/extras/userdoc/md/documentation/index.md +++ b/extras/userdoc/md/documentation/index.md @@ -1,5 +1,4 @@ -The Neural Simulation Tool -========================== +# The Neural Simulation Tool - *Download NEST* @@ -27,8 +26,7 @@ The Neural Simulation Tool Regular open source releases under the terms of the GPL -What is NEST -------------- +## What is NEST NEST is a simulator for spiking neural network models that focuses on the dynamics, size and structure of neural systems rather than on the exact @@ -50,8 +48,7 @@ Learn more about NEST: **\>\> NEST:: documented movie ** **[(short version](http://www.youtube.com/watch?v=K7KXmIv6ROY),** **[long version)](http://www.youtube.com/watch?v=v0YEiren7D0)\>\> NEST information brochure** **[PDF](http://www.nest-simulator.org/wp-content/uploads/2015/04/JARA_NEST_final.pdf)** -How do I use NEST ------------------- +## How do I use NEST You can use NEST either as a for the interpreted programming language Python (PyNEST) or as a stand alone application (`nest`). @@ -84,8 +81,7 @@ added. To get started with NEST, please see the [Documentation Page for Tutorials](documentation.md "Documentation"). -Why should I use NEST ----------------------- +## Why should I use NEST To learn more about the capabilities of NEST, see the [Feature summary](features.md "Features"). @@ -127,8 +123,7 @@ To learn more about the capabilities of NEST, see the [Feature summary](features 11. NEST is open source software and is licensed under the [GNU General Public License v2 or later](http://www.gnu.org/licenses/). -Please cite NEST and tell us about your work --------------------------------------------- +## Please cite NEST and tell us about your work If you have used NEST for your work either directly or via PyNN, please cite it in your publications as: @@ -153,8 +148,7 @@ we will add it to our [publication list](publications.md "Publications"), thus making it visible to potential readers. Send us your reference or even a reprint, using the mail address given on the [contact page](impressum.md "Impressum"). -NEST logo for your poster or presentation ------------------------------------------ +## NEST logo for your poster or presentation If you like NEST, why not show it on your poster or on your slides? @@ -162,8 +156,7 @@ If you like NEST, why not show it on your poster or on your slides? ![](../../../logos/nest-simulated.png) -Nest Models on [Open Source Brain](http://www.opensourcebrain.org/) -------------------------------------------------------------------- +## Nest Models on [Open Source Brain](http://www.opensourcebrain.org/) - [Connection Set Algebra Showcase](http://www.opensourcebrain.org/projects/44) - [Network models of V1](http://www.opensourcebrain.org/projects/111) diff --git a/extras/userdoc/md/documentation/installation.md b/extras/userdoc/md/documentation/installation.md index 19ad4c1906..fab5a9e68c 100644 --- a/extras/userdoc/md/documentation/installation.md +++ b/extras/userdoc/md/documentation/installation.md @@ -1,8 +1,6 @@ -Installation -============ +# Installation -Introduction ------------- +## Introduction NEST compiles and runs on most Unix-like operating systems including Linux and Mac OS X. For using NEST on Microsoft Windows, see [below](installation.md#windows). @@ -34,8 +32,7 @@ Please see the sections on [minimal](installation.md#minimal-configuration) and [standard configuration](installation.md#standard-configuration "Installation") below for details. -What gets installed where --------------------------- +## What gets installed where By default, everything will be installed to the subdirectories `$PREFIX/{bin,lib,share}`, where `$PREFIX=$HOME/opt/nest`: @@ -71,8 +68,7 @@ search paths. For example, if you are using bash: export PATH=$PATH:$PREFIX/bin export PYTHONPATH=$PREFIX/lib/pythonX.Y/site-packages:$PYTHONPATH -Dependencies ------------- +## Dependencies NEST needs a few third party tools and libraries to work. On many operating systems, these can be installed using a *package manager* like `apt`, `port` or @@ -116,8 +112,7 @@ wonder why NEST is difficult to compile on Windows, it is because of these: - libpthread, for threading support - libregexp, for regular expressions. -Minimal configuration ---------------------- +## Minimal configuration NEST can be compiled without any external packages; such configuration may be useful e.g. for initial porting to a new supercomputer. However, this implies @@ -140,8 +135,7 @@ configure it: --without-readline --without-pthread -Standard configuration ----------------------- +## Standard configuration To install the packages required for the standard installation use the following command line: @@ -154,8 +148,7 @@ Then configure NEST using: ../nest-x.y.z/configure --prefix=$HOME/opt/nest -Choice of compiler ------------------- +## Choice of compiler **Caveat:** you should compile NEST with the same compiler and version as your Python. Strange crashes have been observed on importing NEST when compiling @@ -177,8 +170,7 @@ common compilers. When compiling with the Portland compiler, use the -Kieee flag to ensure that computations obey the IEEE754 standard for floating point numerics. -Configuration options ---------------------- +## Configuration options If you need special features, like e.g. support for [distributed computing](Parallel_Computing "Parallel Computing"), you can add command line switches to the call to configure. `./configure --help` @@ -204,8 +196,7 @@ to tell it how your`mpirun`/`mpiexec` command works by defining the function mpirun in your `~/.nestrc` file. This file already contains an example implementation that should work with [OpenMPI](http://www.openmpi.org/) library. -Mac OS X --------- +## Mac OS X ### Installation on OSX 10.9 Mavericks @@ -437,8 +428,7 @@ please try making NEST as follows: Thanks to Harold Gutch for this hint. -Windows -------- +## Windows Windows and Linux differ considerably. This is the reason why it is difficult to compile NEST natively under Windows. However, it is still possible to use diff --git a/extras/userdoc/md/documentation/introduction-to-pynest.md b/extras/userdoc/md/documentation/introduction-to-pynest.md index 9cfcb3da8d..fa48192fd3 100644 --- a/extras/userdoc/md/documentation/introduction-to-pynest.md +++ b/extras/userdoc/md/documentation/introduction-to-pynest.md @@ -1,5 +1,4 @@ -Introduction to PyNEST -====================== +# Introduction to PyNEST - [Part 1: Neurons and simple neural networks](part-1-neurons-and-simple-neural-networks.md) - [Part 2: Populations of neurons](part-2-populations-of-neurons.md) diff --git a/extras/userdoc/md/documentation/license.md b/extras/userdoc/md/documentation/license.md index 4341f35949..9309e01e3d 100644 --- a/extras/userdoc/md/documentation/license.md +++ b/extras/userdoc/md/documentation/license.md @@ -1,8 +1,6 @@ -License -======= +# License -GNU GENERAL PUBLIC LICENSE --------------------------- +## GNU GENERAL PUBLIC LICENSE Version 2, June 1991 @@ -12,8 +10,7 @@ Street, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. -Preamble --------- +## Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is @@ -61,8 +58,7 @@ be licensed for everyone's free use or not licensed at all. The precise terms and conditions for copying, distribution and modification follow. -GNU GENERAL PUBLIC LICENSE --------------------------- +## GNU GENERAL PUBLIC LICENSE ### TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION diff --git a/extras/userdoc/md/documentation/neural-simulations.md b/extras/userdoc/md/documentation/neural-simulations.md index 30f5af7f5a..c49d1fea2f 100644 --- a/extras/userdoc/md/documentation/neural-simulations.md +++ b/extras/userdoc/md/documentation/neural-simulations.md @@ -1,8 +1,6 @@ -Neural simulations -================== +# Neural simulations -Overview ---------- +## Overview A simulation of a network is like an experiment with the difference that it takes place inside the computer's memory rather than in the physical world. @@ -17,8 +15,7 @@ simple simulation. The following sections will then give a step-by-step introduction to the main concepts of NEST simulations. Finally, we will discuss a complex example. -A simple simulation --------------------- +## A simple simulation The simplest simulation in NEST is that of a network which contains just one neuron: @@ -164,8 +161,7 @@ value for 2 ms, the refractory period of the neuron. After the refractory period, the membrane continues to depolarize due to the continuing input current. -Nodes and Models ------------------ +## Nodes and Models In NEST, the neural system is a collection of nodes and their interactions. Nodes correspond to things like neurons, synapses, and devices, and are @@ -218,8 +214,7 @@ purpose. The following line of code create 10 integrate and fire neurons: SLI ] /iaf_neuron 10 Create == 11 -Status information -------------------- +## Status information Nodes have a state which can be extracted and modified. In the follwing example, we display the status information of one the neurons in the layer we have @@ -285,8 +280,7 @@ complain if the new value does not match in the expected type: In order to find out, which properties of a given model can be changed an which not, you have to refer to the model's documentation. -Connections ------------- +## Connections Connections between nodes define possible channels for interactions between them. A connection between two nodes is established, using the command @@ -350,8 +344,7 @@ for nodes. SLI ] c1 0 get GetStatus /weight get == 2.000000e+00 -Devices --------- +## Devices Devices are network nodes which provide input to the network or record its output. They encapsulate the stimulation and measurement process. If you want @@ -455,8 +448,7 @@ Please note that the connection direction for analog recorders (all except SLI ] vm n Connect SLI ] n sd Connect -Simulation ------------ +## Simulation NEST simulations are time driven. The simulation time proceeds in discrete steps of size `dt`, set using the property `resolution` of the root node. In each time diff --git a/extras/userdoc/md/documentation/objects-and-data-types.md b/extras/userdoc/md/documentation/objects-and-data-types.md index 70bdeb5abd..70d95b3499 100644 --- a/extras/userdoc/md/documentation/objects-and-data-types.md +++ b/extras/userdoc/md/documentation/objects-and-data-types.md @@ -1,8 +1,6 @@ -Objects and data types -====================== +# Objects and data types -Overview --------- +## Overview Anything that can be put on the stack is called object. There are several different types of objects, which can store different types of data. For a @@ -12,8 +10,7 @@ objects are the majority and are simply pushed on the stack when they are entered. By contrast, executable objects perform some operation when they are entered and cannot easily be pushed on the stack. -Numbers -------- +## Numbers SLI distinguishes between real and integer numbers. Real numbers correspond to the type `double` in C/C++. Integer numbers @@ -25,14 +22,14 @@ Real numers are: `1.4`, `.5`, `1.`, `1e-2` Integer numers are `1`, `2`, `3000` -Arrays ------- +## Arrays Arrays are sequential containers which can hold any SLI object. The elements of an array are indexed, starting with zero (0) as the first index. SLI arrays are heterogeneous. Objects of different type may be mixed within one -array. Arrays may also be nested to define matrices or tensors of arbitrary rank. +array. Arrays may also be nested to define matrices or tensors of arbitrary +rank. Arrays are delimited by square brackets. The different elements of an array are separated by white-spaces. @@ -43,15 +40,14 @@ separated by white-spaces. [1 a b]  % a mixed array [[1 2 3] [4 5 6]] % a 2x3 Matrix defined by nested array -Calculate the dot product of the vectors \\([1 2 3]cdot[4 5 6]\\) +Calculate the dot product of the vectors \\(\[1 2 3\]cdot\[4 5 6\]\\) SLI ] [1 2 3] SLI [1] [4 5 6] SLI [2] Dot = 32 -Names ------ +## Names Names are used to create variables and to identify specific SLI objects. If a name is entered, it is immediately executed. @@ -91,8 +87,7 @@ Define the variables *a* and *b* with values 1 and 2 and calculate *a+b* -------------------------------------------------- Total number of dictionary entries: 3 -Strings -------- +## Strings Strings are sequences of characters, delimited by parenthesis. In SLI, characters are represented by interger numbers, e.g. 97 represents the letter @@ -107,8 +102,7 @@ Matched pairs of parentheses may be used inside strings. SLI ] (Hello World!) = Hello World! -Procedures ----------- +## Procedures Procedures are a sequence of SLI commands, enclosed by the delimiters `{` and `}`. The delimiters prevent the objects from being executed as you enter @@ -126,8 +120,7 @@ Print the string *Hello World!*. (Hello World !) = } def -Dictionaries ------------- +## Dictionaries A dictionary is an associative array. It stores pairs of names and objects, where the name acts as a key to access the object inside the dictionary. @@ -159,8 +152,7 @@ The command `info` can be used to examine the contents of a dictionary. -------------------------------------------------- Total number of dictionary entries: 3 -Object types ------------- +## Object types There are a number of different object types in SLI. Each type is represented by a literal name (i.e. a name with a prepended slash). Here is a list of the most diff --git a/extras/userdoc/md/documentation/parallel-computing.md b/extras/userdoc/md/documentation/parallel-computing.md index cd6ff978a1..e3a07283b5 100644 --- a/extras/userdoc/md/documentation/parallel-computing.md +++ b/extras/userdoc/md/documentation/parallel-computing.md @@ -1,8 +1,6 @@ -Parallel Computing -================== +# Parallel Computing -Introduction ------------- +## Introduction Parallelization is a means to run simulations faster and use the capabilities of computer clusters and supercomputers to run large-scale simulations. @@ -24,8 +22,7 @@ See [Plesser et al (2007)](http://dx.doi.org/10.1007/978-3-540-74466-5_71) for more information on NEST parallelization and be sure to check the documentation on [Random numbers in NEST](random-numbers.md "Random numbers in NEST"). -Concepts and definitions ------------------------- +## Concepts and definitions In order to ease the handling of neuron and synapse distribution with both thread and process based parallelization, we use the concept of local and remote @@ -84,8 +81,7 @@ spike files and `dat` for analog recordings from the `multimeter`. The `label` and `file_extension` of a recording device can be set like any other parameter of a node using `SetStatus`. -Using multiple threads ----------------------- +## Using multiple threads Thread-parallelism is compiled into NEST by default and should work on all MacOS and Linux machines without additional requirements. In order to keep results @@ -103,8 +99,7 @@ machine. In some situations, oversubscribing can yield 20-30% improvement in simulation speed. Finding the optimal thread number for a specific situation might require a bit of experimenting. -Using distributed computing ---------------------------- +## Using distributed computing ### Build requirements @@ -113,7 +108,11 @@ MPI on your system. If you are on a cluster, you most likely have this already. Note, that in the case of a pre-packaged MPI library you will need both, the library and the development packages. Please see the [Installation instructions](installation.md "Installation") for general information on installing NEST. -Please be advised that NEST should currently only be run in a homogeneous MPI environment. Running in a heterogenenous environment can lead to unexpected results or even crashes. Please contact the [NEST community](http://www.nest-simulator.org/community/) if you require support for exotic setups. +Please be advised that NEST should currently only be run in a homogeneous MPI +environment. Running in a heterogenenous environment can lead to unexpected +results or even crashes. +Please contact the [NEST community](http://www.nest-simulator.org/community/) if +you require support for exotic setups. ### Compilation @@ -169,8 +168,7 @@ The rank of the MPI process. The result differs on each process. `SyncProcesses` Synchronize all MPI processes. -Reproducibility ---------------- +## Reproducibility To achieve the same simulation results even when using different parallelization strategies, the number of virtual processes has to be kept constant. A diff --git a/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md b/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md index dda8e2c6e2..ef9c78cb26 100644 --- a/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md +++ b/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md @@ -1,8 +1,6 @@ -Part 1: Neurons and simple neural networks -========================================== +# Part 1: Neurons and simple neural networks -Introduction ------------- +## Introduction In this handout we cover the first steps in using PyNEST to simulate neuronal networks. When you have worked through this material, you will know how to: @@ -21,8 +19,7 @@ subdirectory: `pynest/examples/`. For the internals of the NEST simulator you may refer to the [publications](publications.md "Publications"). -PyNEST - an interface to the NEST simulator -------------------------------------------- +## PyNEST - an interface to the NEST simulator ![Python Interface](../../img/python_interface.png) The Python interpreter imports NEST as a module and dynamically loads the NEST simulator kernel @@ -69,8 +66,7 @@ function. There is a help system within NEST as well. You can open the help pages in a browser using `nest.helpdesk()` and you can get the help page for a particular object using `nest.help(object)`. -Creating Nodes --------------- +## Creating Nodes A neural network in NEST consists of two basic element types: nodes and connections. Nodes are either neurons, devices or sub-networks. Devices are used @@ -164,8 +160,7 @@ A short note on naming: here we have called the neuron `neuron`, the multimeter variable names you like, but the script is easier to read if you choose names that reflect the concepts in your simulation. -Connecting nodes with default connections ------------------------------------------ +## Connecting nodes with default connections Now we know how to create individual nodes, we can start connecting them to form a small network. @@ -194,8 +189,7 @@ $$1000ms.$$ Congratulations, you have just simulated your first network in NEST! -Extracting and plotting data from devices ------------------------------------------ +## Extracting and plotting data from devices After the simulation has finished, we can obtain the data recorded by the multimeter. @@ -255,8 +249,7 @@ named, say, `one-neuron.py` . You can then run it from the command line by prefixing the file name with `python`, or from the Python or ipython prompt, by prefixing it with `run`. -Connecting nodes with specific connections ------------------------------------------- +## Connecting nodes with specific connections A commonly used model of neural activity is the Poisson process. We now adapt the previous example such that the neuron receives $$2$$ Poisson spike trains, @@ -300,8 +293,7 @@ see a membrane potential as in Fig 3. In the next part of the introduction we will look at more methods for connecting many neurons at once. -Two connected neurons ---------------------- +## Two connected neurons There is no additional magic involved in connecting neurons. To demonstrate this, we start from our original example of one neuron with a constant input @@ -335,8 +327,7 @@ between two nodes, it cannot be applied to populations of nodes as before, you should then see the postsynaptic potentials of `neuron2` evoked by the spikes of `neuron1` as in . -Connected populations of neurons --------------------------------- +## Connected populations of neurons In the previous section we demonstrated how synapse parameters can be set in the synapse specifications. The connection patterns can be chosen by altering the @@ -375,8 +366,7 @@ connection probabilities, must be defined in a dictionary containing the key for an illustrated guide to the usage of `Connect`. -Command overview ----------------- +## Command overview These are the functions we introduced for the examples in this handout; as the week progresses we will add more. @@ -456,8 +446,7 @@ distribution-specific paramters (such as `"mu"` and `"sigma"`). `Simulate(t)`: Simulate the network for `t` milliseconds. -References ----------- +## References - Marc-Oliver Gewaltig and Markus Diesmann. (NEural Simulation Tool). , 2(4):1430, 2007. diff --git a/extras/userdoc/md/documentation/part-2-populations-of-neurons.md b/extras/userdoc/md/documentation/part-2-populations-of-neurons.md index 4d86843bdc..db8e263139 100644 --- a/extras/userdoc/md/documentation/part-2-populations-of-neurons.md +++ b/extras/userdoc/md/documentation/part-2-populations-of-neurons.md @@ -1,8 +1,6 @@ -Part 2: Populations of neurons -============================== +# Part 2: Populations of neurons -Introduction ------------- +## Introduction In this handout we look at creating and parameterising batches of `neurons`, and connecting them. When you have worked through this material, you will know how @@ -20,8 +18,7 @@ For more information on the usage of NEST, please visit: [Documentation](documentation.md). To carry out the code snippets in this handout, you need to import `nest` and `numpy`. -Creating parameterised populations of nodes -------------------------------------------- +## Creating parameterised populations of nodes In the previous handout, we introduced the function `Create(model, n=1, params=None)`. Its mandatory argument is the model name, @@ -86,8 +83,7 @@ Once you have set up your populations of neurons, the function `PrintNetwork()` gives you a simple text output of the network that can help you to check whether you have done what you intended to. -Setting parameters for populations of neurons ---------------------------------------------- +## Setting parameters for populations of neurons It is not always possible to set all parameters for a neuron model at or before creation. A classic example of this is when some parameter should be drawn from @@ -119,8 +115,7 @@ Note that we are being rather lax with random numbers here. Really we have to take more care with them, especially if we are using multiple threads or distributing over multiple machines. We will worry about this later. -Connecting populations with random connections ----------------------------------------------- +## Connecting populations with random connections In the previous handout we looked at the connectivity patterns `one_to_one` and `all_to_all`. However, we often want to look at networks with a sparser @@ -176,8 +171,7 @@ same population simultaneously in the role of `pre` and `post`. For more information on connecting neurons, please read the documentation of the `Connect` function and consult the guide at . -Specifying the behaviour of devices ------------------------------------ +## Specifying the behaviour of devices All devices implement a basic timing capacity; the parameter `start` (default $$0$$) determines the beginning of the device’s activity and the @@ -211,8 +205,7 @@ process and/or thread. For more information on how to customise the behaviour and output format of recording devices, please read the documentation for `RecordingDevice`. -Resetting simulations ---------------------- +## Resetting simulations It often occurs that we need to reset a simulation. For example, if you are developing a script, then you may need to run it from the `ipython` console @@ -231,8 +224,7 @@ is often helpful to call the function `ResetNetwork()` within each loop iteration. It resets all nodes to their default configuration and wipes the data from recording devices. -Command overview\[sec:Command-overview\] --------------------------------------- +## Command overview\[sec:Command-overview\] These are the new functions we introduced for the examples in this handout. diff --git a/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md b/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md index 1b2e7caa9b..bacd360e7d 100644 --- a/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md +++ b/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md @@ -1,8 +1,6 @@ -Part 3: Connecting networks with synapses -========================================= +# Part 3: Connecting networks with synapses -Introduction ------------- +## Introduction In this handout we look at using synapse models to connect neurons. After you have worked through this material, you will know how to: @@ -17,8 +15,7 @@ For more information on the usage of NEST, please visit: [Documentation](documentation.md). To carry out the code snippets in this handout, you need to import `nest` and `numpy`. -Parameterising synapse models ------------------------------ +## Parameterising synapse models NEST provides a variety of different synapse models. You can see the available models by using the command `Models(synapses)`, which picks only the synapse @@ -55,8 +52,7 @@ post-synaptic neuron. It can be set as follows: or by using any of the other methods of parameterising neurons demonstrated in the first two parts of this introduction. -Connecting with synapse models ------------------------------- +## Connecting with synapse models The synapse model as well as parameters associated with the synapse type can be set in the synapse specification dictionary accepted by the connection routine. @@ -68,8 +64,7 @@ set in the synapse specification dictionary accepted by the connection routine. If no synapse model is given, connections are made using the model `static_synapse`. -Querying the synapses ---------------------- +## Querying the synapses The function `GetConnections(source=None, target=None, synapse_model=None)` returns a list of connection identifiers that match the given specifications. @@ -128,8 +123,7 @@ The variable `conn_vals` is now a list of lists, containing the `target` and To get used to these methods of querying the synapses, it is recommended to try them out on a small network where all connections are known. -Distributing synapse parameters -------------------------------- +## Distributing synapse parameters The synapse parameters are specified in the synapse dictionary which is passed to the Connect-function. If the parameter is set to a scalar all connections @@ -160,8 +154,7 @@ the most common ones are: | `gamma` | `order`, `scale` | | `poisson` | `lambda` | -Coding style ------------- +## Coding style As your simulations become more complex, it is very helpful to develop a clean coding style. This reduces the number of errors in the first place, but also @@ -294,8 +287,7 @@ the neuronal population itself. In the case of loops, check first whether you can avoid it entirely by passing the entire population into the function - you usually can. -Command overview\[sec:Command-overview\] --------------------------------------- +## Command overview\[sec:Command-overview\] These are the new functions we introduced for the examples in this handout. diff --git a/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md b/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md index ed9a743841..7c58041180 100644 --- a/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md +++ b/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md @@ -1,8 +1,6 @@ -Part 4: Topologically structured networks -========================================= +# Part 4: Topologically structured networks -Introduction ------------- +## Introduction This handout covers the use of NEST’s `topology` library to construct structured networks. When you have worked through this material you will be able to: @@ -15,8 +13,7 @@ networks. When you have worked through this material you will be able to: For more information on the usage of NEST, please visit: [http://www.nest-simulator.org/documentation/](documentation.md))> -Incorporating structure in networks of point neurons ----------------------------------------------------- +## Incorporating structure in networks of point neurons If we use biologically detailed models of a neuron, then it’s easy to understand and implement the concepts of topology, as we already have dendritic arbors, @@ -38,11 +35,10 @@ selected connections between networks using `Connect()`. If we want to create network models that incorporate the spatial location and spatial connectivity profiles, it is time to turn to the `topology` module. **NOTE:** Full documentation for usage of the topology module is present in NEST Topology -Users Manual (NTUM) [^1], which in the following pages is referenced as a +Users Manual (NTUM) \[1\], which in the following pages is referenced as a full-source. -The nest.topology module ------------------------- +## The nest.topology module The `nest.topology` module allows us to create populations of nodes with a given spatial organisation, connection profiles which specify how neurons are to be @@ -73,8 +69,7 @@ which will be explained in the subsequent sections in more detail: by `nest.PrintNetwork()` or visualization functions included in the topology module and query the connections for further analysis. -Defining layers ---------------- +## Defining layers The code for defining a layer follows this template: @@ -171,8 +166,7 @@ generator. The corresponding code is: comp_layer = topp.CreateLayer({"rows":5,"columns":5, "elements": ["pyr",4,"inh","poisson_generator","noise_generator"]}) -Defining connection profiles ----------------------------- +## Defining connection profiles To define the types of connections that we want between populations of neurons, we specify a *connection dictionary*. @@ -247,8 +241,7 @@ mentioned in the following Python code snippet. | allow\_multapses | Whether we want to have multiple connections between the same source-target pair, or ensure unique connections. | boolean | | allow\_autapses | Whether we want to allow a neuron to connect to itself | boolean | -Connecting layers ------------------ +## Connecting layers Connecting layers is the easiest step: having defined a source layer, a target layer and a connection dictionary, we simply use the function @@ -271,8 +264,7 @@ times and connect to the same layer: topp.ConnectLayers(in_layer,in_layer,conn_dict_in) # Connect I->I topp.ConnectLayers(in_layer,ex_layer,conn_dict_in) # Connect I->E -Visualising and querying the network structure ----------------------------------------------- +## Visualising and querying the network structure There are two main methods that we can use for checking that our network was built correctly: @@ -296,13 +288,11 @@ listed in NTUM Section 4.1, are: | topp.GetPosition(gids) | Returns position of elements specified in input | | nest.GetStatus(layer,“topology”) | Returns the layer dictionary for a layer | -References ----------- +## References -[^1] Hans Ekkehard Plesser and Håkon Enger NEST Topology User Manual +\[1\] Hans Ekkehard Plesser and Håkon Enger NEST Topology User Manual -Acknowledgments ---------------- +## Acknowledgments This handout is based on a previous document by Sarah Jarvis, many thanks to her. diff --git a/extras/userdoc/md/documentation/programming-in-sli.md b/extras/userdoc/md/documentation/programming-in-sli.md index 28eaddd825..4acb663025 100644 --- a/extras/userdoc/md/documentation/programming-in-sli.md +++ b/extras/userdoc/md/documentation/programming-in-sli.md @@ -1,8 +1,6 @@ -Programming in SLI -================== +# Programming in SLI -Overview --------- +## Overview A procedure is a sequence of SLI objects whose execution is delayed until the procedure is executed. Because procedures are objects, they can be: @@ -19,8 +17,7 @@ A program is a sequence of SLI objects and procedures which are This chapter covers the basic programming concepts of the SLI language features. -Entering and executing programs -------------------------------- +## Entering and executing programs A program is a sequence of SLI objects and procedures which are defined in a file. Program files are ordinary ASCII text files, which can be created and @@ -57,8 +54,7 @@ Write the program `hello_world.sli` according to the Note that the procedure is not immediately executed by `run`. Rather, all objects which are contained in the file are read and executed. -Using local variables ---------------------- +## Using local variables Usually, all names you define are globally accessible. But, if you use a lot of procedures that define their own variables, there is an increasing danger that @@ -81,8 +77,7 @@ Compute the alpha-function of *t* according to *a(t)=t\*Exp(-t/tau)* end  % close local name space } def -Conditionals ------------- +## Conditionals Conditional expressions allow a program to ask questions and make decisions: @@ -124,8 +119,7 @@ This example also shows how procedures can be called *recursively*. It is, however, important to supply a *termination condition* for the recursion like in this example. -Comparison functions --------------------- +## Comparison functions Comparison functions are used to compare objects. The result of comparison functions are of type `/booltype` and can be used for logical functions and @@ -148,8 +142,7 @@ Test whether the object at level 1 is less than or equal to the object at level Test whether the object at level 1 is greater than or equal to the object at level 0. -Logical functions ------------------ +## Logical functions Command Description @@ -163,8 +156,7 @@ Returns true if at least one of the arguments is true. Returns true if and only if one of the arguments is true.   -The *if-ifelse* structure -------------------------- +## The *if-ifelse* structure Command Description @@ -180,8 +172,7 @@ Executes `proc_1` if the boolean is true and `proc_2` otherwise. SLI ] 2 2 eq {(Equal!) = } { (Not equal !) =} ifelse Equal! -The *case-switch* structure ---------------------------- +## The *case-switch* structure While the commands `if` and `ifelse` test only one condition, the *case-switch* structure can be used to test a number of different conditions. @@ -213,8 +204,7 @@ The *case-switchdefault* structure has the general form Here, `procdefault` is executed if none of the booleans was true. -Loops ------ +## Loops Loops and control structures are commands that take procedure objects as arguments. diff --git a/extras/userdoc/md/documentation/qa-precise-spike-times.md b/extras/userdoc/md/documentation/qa-precise-spike-times.md index 2da8278f49..278466e440 100644 --- a/extras/userdoc/md/documentation/qa-precise-spike-times.md +++ b/extras/userdoc/md/documentation/qa-precise-spike-times.md @@ -1,5 +1,4 @@ -Questions and answers about precise neurons -=========================================== +# Questions and answers about precise neurons (1) Q: **Is it meaningful to compare the precise sequences of spikes generated by diff --git a/extras/userdoc/md/documentation/quickref.md b/extras/userdoc/md/documentation/quickref.md index 155e44de17..c905f7ae52 100644 --- a/extras/userdoc/md/documentation/quickref.md +++ b/extras/userdoc/md/documentation/quickref.md @@ -1,8 +1,6 @@ -NEST/SLI Quick Reference -======================== +# NEST/SLI Quick Reference -Table of Contents ------------------ +## Table of Contents - [Introduction](#introduction) - [The online-help system](#the-online-help-system) @@ -37,8 +35,7 @@ Table of Contents - [Alphabetical command index](../helpindex/cmd_index.md) -Introduction ------------- +## Introduction SLI is the simulation language of the NEST simulation system. SLI is a stack oriented language, i.e. each command expects to find its arguments on the stack. @@ -49,8 +46,7 @@ This document presents a directory of the most important SLI operators, grouped into sections. Since this document is not automatically generated from the help pages, it might not contain the latest additions to SLI. -The on-line help system ------------------------ +## The on-line help system ### Layout of help pages @@ -124,8 +120,7 @@ commands. [apropos](../helpindex/cmds/apropos.md) Search the command index for a regular expression. -Simulation kernel ------------------ +## Simulation kernel ### Controlling the simulation @@ -161,8 +156,7 @@ usage. [memory\_thisjob](../helpindex/cmds/memory_thisjob.md) Report virtual memory size for current NEST process. -Models and network nodes ------------------------- +## Models and network nodes All nodes in NEST (i.e. neurons, devices, and subnetworks.md) are derived from a common base class. Therefore they share some general properties. @@ -247,8 +241,7 @@ Device to observe membrane potentials. [conductancemeter](../helpindex/cmds/conductancemeter.md) Device to observe synaptic conductances. -Connecting nodes ----------------- +## Connecting nodes [synapsedict](../helpindex/cmds/synapsedict.md) Dictionary containing all synapse models. @@ -282,8 +275,7 @@ Prints layer node positions to file. [topology::PrintLayerConnections](../helpindex/cmds/topology::PrintLayerConnections.md) Prints a list of the connections of the nodes in the layer to file. -Looking at node, networks, and connectivity -------------------------------------------- +## Looking at node, networks, and connectivity ### Navigating the network @@ -335,8 +327,7 @@ Reset the dynamic state of the network. [reset](../helpindex/cmds/reset.md) Reset dictionary stack and clear the userdict. -Stacks ------- +## Stacks ### Operand stack @@ -403,8 +394,7 @@ execution stack as array. [restoreestack](../helpindex/cmds/restoreestack.md) Restore the execution stack from an array. -Arithmetic functions --------------------- +## Arithmetic functions [abs](../helpindex/cmds/abs.md) Absolute value of a number. [add](../helpindex/cmds/add.md) @@ -453,8 +443,7 @@ Return the greater of two values. [min](../helpindex/cmds/min.md) Return the smaller of two values. -Boolean functions ------------------ +## Boolean functions ### Comparison functions @@ -483,8 +472,7 @@ Logical or operator. operator. [xor](../helpindex/cmds/xor.md) Logical xor operator. -Special mathematical functions ------------------------------- +## Special mathematical functions [Erf](../helpindex/cmds/Erf.md) Error function. [Erfc](../helpindex/cmds/Erfc.md) @@ -510,8 +498,7 @@ Simple iteration implementing the Lambert-W function. [Pi](../helpindex/cmds/Pi.md) Pi constant. -Random number generation ------------------------- +## Random number generation [seed](../helpindex/cmds/seed.md) Set the seed of a random number generator. @@ -559,8 +546,7 @@ Poisson random deviate generator. [uniform\_int](../helpindex/cmds/rdevdict::uniformint.md) Uniform integer random deviate generator. -Statistics ----------- +## Statistics [Min](../helpindex/cmds/Min.md) Returns the smallest element of an array. @@ -575,8 +561,7 @@ Returns the unbiased variance of the elements of an array. [StandardDeviation](../helpindex/cmds/StandardDeviation.md) Returns the standard deviation of the element of an array. -Arrays, vectors, and matrices ------------------------------ +## Arrays, vectors, and matrices ### Construction @@ -790,8 +775,7 @@ Change the internal size of an array. [shrink](../helpindex/cmds/shrink.md) Reduce the capacity of an array to its minimum. -Strings -------- +## Strings ### Construction @@ -911,8 +895,7 @@ Replace all occurences of a regex. [regexec](../helpindex/cmds/regexec.md) Compare string and regular expression. -Dictionaries ------------- +## Dictionaries ### Construction @@ -1026,8 +1009,7 @@ dictionary. dictionary, see above). [::](../helpindex/cmds/::.md.md) Execute a symbol from a nested namespace. -Names, functions, and variabes ------------------------------- +## Names, functions, and variabes ### Defining variables and functions @@ -1059,8 +1041,7 @@ a key in each dictionay on the dictionary stack. [load](../helpindex/cmds/load.md) Search for a key in each dictionay on the dictionary stack. -Loops ------ +## Loops ### Infinite loops @@ -1098,8 +1079,7 @@ Repeatedly apply a function with two parameters. [exit](../helpindex/cmds/exit.md) Exit a loop construct. -Control structures ------------------- +## Control structures [if](../helpindex/cmds/if.md) Conditionaly execute a procedure. [ifelse](../helpindex/cmds/ifelse.md) @@ -1115,8 +1095,7 @@ Raise a stop signal. [stopped](../helpindex/cmds/stopped.md) Returns true if execution was stopped by stop. -Functions and procedures ------------------------- +## Functions and procedures ### Object oriented techniques @@ -1194,8 +1173,7 @@ Dictionary for global options. [bind](../helpindex/cmds/bind.md) Recursively replaces executable operator names by their values. -Error handling and debugging ----------------------------- +## Error handling and debugging If an error occurs, execution is usually interrupted and a diagnostic message is printed. In most cases, the stack is restored to the state where it was @@ -1228,8 +1206,7 @@ Returns the most recently resolved name. [debug.sli](../helpindex/cmds/debug.sli.md) Debugging support for SLI. -Files and Streams ------------------ +## Files and Streams ### Standard input and output @@ -1368,8 +1345,7 @@ format. [edit](../helpindex/cmds/edit.md) .Edit a file. -Executing SLI programs ----------------------- +## Executing SLI programs [run](../helpindex/cmds/run.md) Execute a .sli file. [spoon](../helpindex/cmds/spoon.md) Execute a parallel SLI-process. @@ -1377,8 +1353,7 @@ Executing SLI programs [addpath](../helpindex/cmds/addpath.md) Append a path to SLISearchPath. [path](../helpindex/cmds/path.md) Return current search path as array. -Interfacing the hosts file-system ---------------------------------- +## Interfacing the hosts file-system [Directory](../helpindex/cmds/Directory.md) Return current working directory. [cd](../helpindex/cmds/cd.md) Change working directory. @@ -1398,8 +1373,7 @@ pathnames of given file in given. [CompareFiles](../helpindex/cmds/CompareFiles.md) Compare two files for equality. -Process control ---------------- +## Process control ### Executing UNIX commands and external programs @@ -1450,8 +1424,7 @@ SI units. [mV](../helpindex/cmds/mV.md) Specification in mV (for readability). [spikes](../helpindex/cmds/spikes.md) Specification in spikes (for readability). -SLI Interpreter control ------------------------ +## SLI Interpreter control ### Startup and initialization @@ -1516,8 +1489,7 @@ system time. second. [ptimes](../helpindex/cmds/ptimes.md) Returns real, user, and system time. -Parallel computing ------------------- +## Parallel computing [Rank](../helpindex/cmds/Rank.md) Return the MPI rank (MPI\_Comm\_rank.md) of the process. diff --git a/extras/userdoc/md/documentation/random-numbers.md b/extras/userdoc/md/documentation/random-numbers.md index 7e3bf13029..3462e87d9f 100644 --- a/extras/userdoc/md/documentation/random-numbers.md +++ b/extras/userdoc/md/documentation/random-numbers.md @@ -1,8 +1,6 @@ -Random numbers -============== +# Random numbers -Introduction -------------- +## Introduction Random numbers are used for a variety of purposes in neuronal network simulations, e.g. @@ -38,8 +36,7 @@ such as the normal or binomial distributions. In most cases, you will be using random deviate generators. They are in particular used to initialize properties during network construction, as described in the sections [Changes in NEST 2.4](random-numbers.md#changes-in-random-number-generation-in-NEST-2.4) and [Examples](random-numbers.md#examples) below. -Changes in random number generation in NEST 2.4 -------------------------------------------------- +## Changes in random number generation in NEST 2.4 Random deviate generation has become significantly more powerful in NEST 2.4, to fully support randomization of connections parameters offered by the revised @@ -122,8 +119,7 @@ The changes are as follows: - We believe that these variants should *not* be used for new studies. -Basics of parallel simulation in NEST --------------------------------------- +## Basics of parallel simulation in NEST For details of parallelization in NEST, please see [Parallel Computing](parallel-computing.md "Parallel Computing") and [Plesser et al (2007)](http://dx.doi.org/10.1007/978-3-540-74466-5_71). @@ -175,8 +171,7 @@ Here, we just summarize a few basics. print nest.GetStatus(n, 'vp') # virtual process "owning" node print nest.GetStatus(n, 'thread') # thread in calling process "owning" node -Random numbers in parallel simulations ---------------------------------------- +## Random numbers in parallel simulations Ideally, all random numbers in a simulation should come from a single RNG. This would require shipping truckloads of random numbers from a central RNG process @@ -319,8 +314,7 @@ The following happens here: - This array is then passed to the `/rngs` status variable of the kernel. This variable is invisible as well. -Examples --------- +## Examples **NOTE: These examples are not yet updated for NEST 2.4** diff --git a/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md b/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md index e85faa43f5..cce391effb 100644 --- a/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md +++ b/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md @@ -82,17 +82,17 @@ of NEST (large *dmax*). ## Spike generation and precision -A neuron fires a spike when the membrane potential is above threshold at the end of an -update interval (i.e., a multiple of the simulation resolution). For most models, the -membrane potential is then reset to some fixed value and clamped to that value during -the refractory time. This means that the last membrane potential value at the last time -step before the spike can vary, while the potential right after the step will usually -be the reset potential (some models may deviate from this). This also means that the -membrane potential recording will never show values above the threshold. The time of -the spike is always the time at *the end of the interval* during which the threshold was -crossed. - -NEST also has a some models that determine the precise time of the threshold crossing -during the interval. Please see the documentation on [precise spike time neurons](simulations-with-precise-spike-times.md) +A neuron fires a spike when the membrane potential is above threshold at the end +of an update interval (i.e., a multiple of the simulation resolution). For most +models, the membrane potential is then reset to some fixed value and clamped to +hat value during the refractory time. This means that the last membrane +potential value at the last time step before the spike can vary, while the +potential right after the step will usually be the reset potential (some models +may deviate from this). This also means that the membrane potential recording +will never show values above the threshold. The time of the spike is always the +time at *the end of the interval* during which the threshold was crossed. + +NEST also has a some models that determine the precise time of the threshold +crossing during the interval. Please see the documentation on [precise spike time neurons](simulations-with-precise-spike-times.md) for details about neuron update in continuous time and the [documentation on connection management](connection-management.md) for how to set the delay when creating synapses. diff --git a/extras/userdoc/md/documentation/simulations-with-precise-spike-times.md b/extras/userdoc/md/documentation/simulations-with-precise-spike-times.md index d8effd78d7..a4d49e55d9 100644 --- a/extras/userdoc/md/documentation/simulations-with-precise-spike-times.md +++ b/extras/userdoc/md/documentation/simulations-with-precise-spike-times.md @@ -1,5 +1,4 @@ -Simulations with precise spike times -==================================== +# Simulations with precise spike times The simulation resolution *h* and the minimum synaptic transmission delay *dmin* define the two major time intervals of the [scheduling and simulation flow of NEST](scheduling-and-simulation-flow.md): @@ -45,8 +44,7 @@ neuron determines the precise offset of the outgoing spike with respect to the next point on the time grid. This grid point marks the spike's time stamp. The neuron then emits the spike and resets its membrane potential. -Models with precise spike times in NEST ---------------------------------------- +## Models with precise spike times in NEST `poisson_generator_ps` creates Poissonian spike trains, where spike times have an integer time stamp and a double precision offset. It is hence dedicated to @@ -84,8 +82,7 @@ the simulation resolution h. The model can also be used through the [PyNN interf The source code of these models is in the [*precise* module of NEST](https://github.com/nest/nest-simulator/tree/master/precise). -Questions and answers about precise neurons -------------------------------------------- +## Questions and answers about precise neurons During the review process of the above mentioned papers, we came up with a list of questions and answers pertaining to the implementation and usage of precise diff --git a/extras/userdoc/md/documentation/using-files-and-keyboard-input.md b/extras/userdoc/md/documentation/using-files-and-keyboard-input.md index ee9a5749ae..88b2d34298 100644 --- a/extras/userdoc/md/documentation/using-files-and-keyboard-input.md +++ b/extras/userdoc/md/documentation/using-files-and-keyboard-input.md @@ -1,8 +1,6 @@ -Using files and keyboard input -============================== +# Using files and keyboard input -Overview ---------- +## Overview SLI's input/output fascilities differ from those of PostScript and are close to the stream concept of C++. However, for compatibility some PostScript output @@ -33,8 +31,7 @@ stream argument on the stack. Now, the abbreviated form of `pop`, i.e. the command `;`, is used to remove the stream object from the stack. -Standard streams ------------------ +## Standard streams The standard streams of a UNIX program are mapped to the following names. Note that these streams should not be closed by a SLI program, since the result is @@ -49,8 +46,7 @@ Standart output stream. `cerr` Standart error output stream. -Opening and closing a stream ----------------------------- +## Opening and closing a stream Streams are objects which handle the input and output of data to or from some external target. The target of a stream can be a file, a string, a devide, or @@ -75,8 +71,7 @@ Extract a string from a string-stream. `stream close` Close the stream. -Writing to streams ------------------- +## Writing to streams Command Description @@ -89,7 +84,7 @@ Print ASCII representation of `obj` to `cout`. `stream obj ==` Print detailed ASCII representation of `obj` to `cout`. -### Example +### Example Print *Hello World* to a text file. @@ -98,8 +93,7 @@ Print *Hello World* to a text file. SLI [1] endl SLI [1] ; -Manipulators -------------- +## Manipulators Manipulators are used to manipulate the state of a stream object. Such changes can, for instance, affect the precision with which numbers are printed. diff --git a/extras/userdoc/md/documentation/using-nest-with-music.md b/extras/userdoc/md/documentation/using-nest-with-music.md index 67d14bba8f..016e2bdf20 100644 --- a/extras/userdoc/md/documentation/using-nest-with-music.md +++ b/extras/userdoc/md/documentation/using-nest-with-music.md @@ -1,8 +1,6 @@ -Using NEST with MUSIC -===================== +# Using NEST with MUSIC - Introduction -------------- +## Introduction NEST supports the [MUSIC interface](http://software.incf.org/software/music), a standard by the INCF, which allows the transmission of data between applications @@ -24,8 +22,7 @@ Jeanette Hellgren Kotaleski, and Örjan Ekeberg. Run-time interoperability between neuronal simulators based on the MUSIC framework. Neuroinformatics, 8, 2010. doi:10.1007/s12021-010-9064-z* and available from [here](http://www.springerlink.com/content/r6j425027lmv1251/). -Sending and receiving spike events ------------------------------------ +## Sending and receiving spike events A minimal example for the exchange of spikes between two independent instances of NEST is given in the example `examples/nest/music/minimalmusicsetup.music`. @@ -112,8 +109,7 @@ same membrane potential trace. -65.2054 -62.1583 -Receiving string messages ---------------------------- +## Receiving string messages Currently, NEST is only able to receive, but not to send string messages. We thus use MUSIC's `messagesource` program for the generation of messages in the @@ -158,7 +154,6 @@ side (`msgtest.py`) of the exampe is shown in the following listing: print data time += 10 - We first import the `nest` in line 2 and create an instance of the `music_message_in_proxy` in line 3. In line 4, we set the name of the port it listens to to `msgdata`. Lines 6 through 11 simulate the network in steps of @@ -214,8 +209,7 @@ following output: Simulation finished. [{'messages': ['Hello', '!'], 'message_times': array([ 300., 700.])}] -Receiving continuous data --------------------------- +## Receiving continuous data As in the case of string message, NEST currently only supports receiving continuous data, but not sending. This means that we have to use another of From 282ccfa9d204299a7ee2f9fdb3b3aaa6a7f7aff1 Mon Sep 17 00:00:00 2001 From: steffen Date: Mon, 30 May 2016 09:47:48 +0200 Subject: [PATCH 08/20] added internal links --- .../md/documentation/connection-management.md | 2 +- extras/userdoc/md/documentation/documentation.md | 8 ++++---- extras/userdoc/md/documentation/features.md | 2 +- .../userdoc/md/documentation/getting-started.md | 3 +-- extras/userdoc/md/documentation/installation.md | 2 +- .../part-1-neurons-and-simple-neural-networks.md | 2 +- .../part-2-populations-of-neurons.md | 2 +- .../part-3-connecting-networks-with-synapses.md | 2 +- .../part-4-topologically-structured-networks.md | 2 +- extras/userdoc/md/documentation/quickref.md | 16 ++++++++-------- 10 files changed, 20 insertions(+), 21 deletions(-) diff --git a/extras/userdoc/md/documentation/connection-management.md b/extras/userdoc/md/documentation/connection-management.md index e8023b0a40..769c95f328 100644 --- a/extras/userdoc/md/documentation/connection-management.md +++ b/extras/userdoc/md/documentation/connection-management.md @@ -10,7 +10,7 @@ function has been renamed to `OneToOneConnect()`. However, simple cases, which are just creating one-to-one connections between two lists of nodes are still working with the new command without the need to change the code. Note that the topology-module is not effected by theses changes. The translation between the -old and the new connect routines is described in [Old Connection Routines](connection-management.md#old-connection-Routines). +old and the new connect routines is described in [Old Connection Routines](connection-management.md#old-connection-routines). The connectivity pattern is defined inside the `Connect()` function under the key 'rule'. The patterns available are described in diff --git a/extras/userdoc/md/documentation/documentation.md b/extras/userdoc/md/documentation/documentation.md index 3268e21680..1cb23cdfd4 100644 --- a/extras/userdoc/md/documentation/documentation.md +++ b/extras/userdoc/md/documentation/documentation.md @@ -9,7 +9,7 @@ - [Frequently Asked Questions](frequently-asked-questions.md "Frequently Asked Questions") - [Analog recording with multimeter](analog-recording-with-multimeter.md "Analog recording with multimeter") - [Connection Management](connection-management.md "Connection Management") -- [Topological Connections](wp-content/uploads/2015/04/Topology_UserManual.pdf "Topological Connections") +- [Topological Connections](http://www.nest-simulator.org/wp-content/uploads/2015/04/Topology_UserManual.pdf "Topological Connections") - [Random numbers in NEST](random-numbers.md "Random numbers in NEST") - [Parallel Computing](parallel-computing.md "Parallel Computing") - [Scheduling and simulation flow](scheduling-and-simulation-flow.md) @@ -60,10 +60,10 @@ ## Further Reading - [NEST by Example](wp-content/uploads/2015/02/NEST_by_Example.pdf) -- Read and improve the [NEST article on Scholarpedia.org](cholarpedia.org/article/NEST_\(NEural_Simulation_Tool)) -- Read and improve the [NEST article on Wikipedia](http://en.wikipedia.org/wiki/NEST_\(software)) +- Read and improve the [NEST article on Scholarpedia.org](http://scholarpedia.org/article/NEST_\(NEural_Simulation_Tool\) "") +- Read and improve the [NEST article on Wikipedia](http://en.wikipedia.org/wiki/NEST_\(software\) "") ## NEST Developer Manual For information about modifying and extending NEST and contributing your code -to the official version, please head over to the [NEST Developer Space](http://nest.github.io/nest-simulator.html). +to the official version, please head over to the [NEST Developer Space](http://nest.github.io/nest-simulator.html ""). diff --git a/extras/userdoc/md/documentation/features.md b/extras/userdoc/md/documentation/features.md index b52f223d67..ee337c2136 100644 --- a/extras/userdoc/md/documentation/features.md +++ b/extras/userdoc/md/documentation/features.md @@ -50,7 +50,7 @@ - By default spikes are restricted to the grid spanned by the computation time step -- For some neuron models [spike interaction in continuous time](simulations-with-precise-spike-times/) +- For some neuron models [spike interaction in continuous time](simulations-with-precise-spike-times-md "spike interaction in continuous time") is available ## Verification diff --git a/extras/userdoc/md/documentation/getting-started.md b/extras/userdoc/md/documentation/getting-started.md index 58b1105901..5ac9e5c1e3 100644 --- a/extras/userdoc/md/documentation/getting-started.md +++ b/extras/userdoc/md/documentation/getting-started.md @@ -33,8 +33,7 @@ model. ### Examples A good starting point to learn more about modeling in NEST are the -[example networks](more-example-networks.md "Example networks") -that come together with NEST. +example networks that come together with NEST. ### Where does data get stored diff --git a/extras/userdoc/md/documentation/installation.md b/extras/userdoc/md/documentation/installation.md index fab5a9e68c..4f66ff1c4f 100644 --- a/extras/userdoc/md/documentation/installation.md +++ b/extras/userdoc/md/documentation/installation.md @@ -172,7 +172,7 @@ computations obey the IEEE754 standard for floating point numerics. ## Configuration options -If you need special features, like e.g. support for [distributed computing](Parallel_Computing "Parallel Computing"), +If you need special features, like e.g. support for [distributed computing](parallel-computing.md "Parallel Computing"), you can add command line switches to the call to configure. `./configure --help` will show you all available options. For more information on the installation of NEST, please see the file INSTALL that is included in the distribution archive. diff --git a/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md b/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md index ef9c78cb26..e71ec9e720 100644 --- a/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md +++ b/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md @@ -406,7 +406,7 @@ given, `params` has to be the name of a property, which is set to `val` on the ### Connections This is an abbreviated version of the documentation for the `Connect` function, -please see NEST’s online help for the full version and +please see NEST’s online help for the full version and [Connection Management](connection-management.md "Connection Management") for an introduction and worked examples. `Connect(pre, post, conn_spec=None, syn_spec=None, model=None)`: diff --git a/extras/userdoc/md/documentation/part-2-populations-of-neurons.md b/extras/userdoc/md/documentation/part-2-populations-of-neurons.md index db8e263139..2080684c15 100644 --- a/extras/userdoc/md/documentation/part-2-populations-of-neurons.md +++ b/extras/userdoc/md/documentation/part-2-populations-of-neurons.md @@ -169,7 +169,7 @@ In addition to the rule specific parameters `indegree`, `outdegree`, `N` and Note that for all connectivity rules, it is perfectly legitimate to have the same population simultaneously in the role of `pre` and `post`. For more information on connecting neurons, please read the documentation of the -`Connect` function and consult the guide at . +`Connect` function and consult the guide at [Connection Management](connection-management.md "Connection Management"). ## Specifying the behaviour of devices diff --git a/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md b/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md index bacd360e7d..34abf7770d 100644 --- a/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md +++ b/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md @@ -140,7 +140,7 @@ set (for example `mu`). Here we show an example where the parameters `alpha` and "delay": 1.0 } nest.Connect(epop1, neuron, "all_to_all", syn_dict) -Available distributions and associated parameters are described in [Connection_Management](connection-management.md)), +Available distributions and associated parameters are described in [Connection Management](connection-management.md "Connection Management"), the most common ones are: | Distributions | Keys | diff --git a/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md b/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md index 7c58041180..430f13fd06 100644 --- a/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md +++ b/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md @@ -11,7 +11,7 @@ networks. When you have worked through this material you will be able to: - Visualise the connectivity For more information on the usage of NEST, please visit: -[http://www.nest-simulator.org/documentation/](documentation.md))> +[Documentation](documentation.md) "Documentation") ## Incorporating structure in networks of point neurons diff --git a/extras/userdoc/md/documentation/quickref.md b/extras/userdoc/md/documentation/quickref.md index c905f7ae52..486f3218ef 100644 --- a/extras/userdoc/md/documentation/quickref.md +++ b/extras/userdoc/md/documentation/quickref.md @@ -3,12 +3,12 @@ ## Table of Contents - [Introduction](#introduction) -- [The online-help system](#the-online-help-system) +- [The online-help system](#the-on-line-help-system) - [Simulation kernel](#simulation-kernel) -- [Models and nodes](#models-and-nodes) -- [Connections](#connection) -- [Network access](#network-access) -- [Stack Commands](#stack-commands) +- [Models and nodes](#models-and-network-nodes) +- [Connections](#connection-nodes) +- [Network access](#looking-at-node-networks-and-connectivity) +- [Stack Commands](#stacks) - [Arithmetic functions](#arithmetic-functions) - [Boolean functions](#boolean-functions) - [Special mathematical functions](#special-mathematical-functions) @@ -19,15 +19,15 @@ - [Strings](#strings) -- [Dictionaries and Namespaces](#dictionaries-and-Namespaces) +- [Dictionaries and Namespaces](#dictionaries) - [Names, functions, and variables](#names-functions-and-variables) -- [Loop structures](#loop-structures) +- [Loop structures](#loops) - [Control structures](#control-structures) - [Functions and procedures](#functions-and-procedures) - [Error handling and debugging](#error-handling-and-debugging]) - [Files and streams](#files-and-streams) - [Executing SLI programs](#executing-sli-programs) -- [Interfacing the host's file-system](#interfacing-the-host-s-file-system) +- [Interfacing the host's file-system](#interfacing-the-hosts-file-system) - [Process control](#process-control) - [SLI Interpreter Control](#sli-interpreter-control) - [Parallel computing](#parallel-computing) From ab60c8b656d81761dd7179bab6fe0668e32d7622 Mon Sep 17 00:00:00 2001 From: steffen Date: Mon, 30 May 2016 11:32:34 +0200 Subject: [PATCH 09/20] minor change --- .../userdoc/md/documentation/scheduling-and-simulation-flow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md b/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md index cce391effb..d63c14b88c 100644 --- a/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md +++ b/extras/userdoc/md/documentation/scheduling-and-simulation-flow.md @@ -20,7 +20,7 @@ To speed up the simulation and allow the efficient use of computer clusters, NEST uses a [hybrid parallelization strategy](parallel-computing.md). The following figure shows the basic loop that is run upon a call to `Simulate`: -![Simulation Loop](../../img/simulation-loop-241x300.png) +![Simulation Loop](../../img/simulation_loop-241x300.png) The simulation loop. Light gray boxes denote thread parallel parts, dark gray boxes denote MPI parallel parts. U(St) is the update operator that From f1b3d0de0bf892fce0c353db31d05080575e8dea Mon Sep 17 00:00:00 2001 From: steffen Date: Tue, 31 May 2016 10:17:47 +0200 Subject: [PATCH 10/20] Added README.md --- extras/userdoc/md/documentation/README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 extras/userdoc/md/documentation/README.md diff --git a/extras/userdoc/md/documentation/README.md b/extras/userdoc/md/documentation/README.md new file mode 100644 index 0000000000..f80832729d --- /dev/null +++ b/extras/userdoc/md/documentation/README.md @@ -0,0 +1,18 @@ +# NEST User Documentation in Markdown + +This directory contains the NEST user documentation written in markdown. +These files are the basis of the public site. + +Please follow these short authoring instructions: + +## Note these conventions + +- Name files with '-' as separator only. + +- Use the atx header style. + + # This is an

tag + ## This is an

tag + ###### This is an

tag + +- Use relative links regarding the need of GitHub From e91aef1171327a212c43b590aaa37f9ef4d9496f Mon Sep 17 00:00:00 2001 From: steffen Date: Tue, 31 May 2016 10:21:21 +0200 Subject: [PATCH 11/20] features.md - repair links index.md - changing some minor things --- extras/userdoc/md/documentation/features.md | 2 +- extras/userdoc/md/documentation/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/extras/userdoc/md/documentation/features.md b/extras/userdoc/md/documentation/features.md index ee337c2136..2423002768 100644 --- a/extras/userdoc/md/documentation/features.md +++ b/extras/userdoc/md/documentation/features.md @@ -50,7 +50,7 @@ - By default spikes are restricted to the grid spanned by the computation time step -- For some neuron models [spike interaction in continuous time](simulations-with-precise-spike-times-md "spike interaction in continuous time") +- For some neuron models [spike interaction in continuous time](simulations-with-precise-spike-times.md "spike interaction in continuous time") is available ## Verification diff --git a/extras/userdoc/md/documentation/index.md b/extras/userdoc/md/documentation/index.md index 3aed2be878..62117db4cc 100644 --- a/extras/userdoc/md/documentation/index.md +++ b/extras/userdoc/md/documentation/index.md @@ -128,7 +128,7 @@ To learn more about the capabilities of NEST, see the [Feature summary](features If you have used NEST for your work either directly or via PyNN, please cite it in your publications as: -Gewaltig M-O & Diesmann M (2007) [NEST (Neural Simulation Tool)](http://www.scholarpedia.org/article/NEST_(Neural_Simulation_Tool)) +Gewaltig M-O & Diesmann M (2007) [NEST (Neural Simulation Tool)](http://www.scholarpedia.org/article/NEST_(Neural_Simulation_Tool) "") *Scholarpedia* 2(4):1430. Here is suitable BibTeX entry: From 22714e4644dcf30cabf852aa7abdde54b49fca6d Mon Sep 17 00:00:00 2001 From: steffen Date: Tue, 31 May 2016 11:05:54 +0200 Subject: [PATCH 12/20] Description about OSX install via homebrew added. --- .../userdoc/md/documentation/installation.md | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/extras/userdoc/md/documentation/installation.md b/extras/userdoc/md/documentation/installation.md index 4f66ff1c4f..a526afa77e 100644 --- a/extras/userdoc/md/documentation/installation.md +++ b/extras/userdoc/md/documentation/installation.md @@ -198,6 +198,27 @@ implementation that should work with [OpenMPI](http://www.openmpi.org/) library. ## Mac OS X +The easiest way to install NEST on a Mac is to install it via the Homebrew +package manager: + +1. To install homebrew, follow the instructions here: + +2. Then, in a terminal + + 1. Add the homebrew/science tap: execute 'brew tap homebrew/science' + + 2. For information on what options NEST has and what will be installed, + execute 'brew info nest' + + 3. To install nest, execute 'brew install nest' + +Options have to be appended, e.g. to install NEST with PyNEST execute +'brew install nest --with-python'. + +#Sorry, the following instructions are a little bit outdated!# +A more detailed up-to-date instruction for installation on OSX will +follow soon. + ### Installation on OSX 10.9 Mavericks The clang compiler that ships with OSX 10.9 does not support OpenMP threads. @@ -283,6 +304,8 @@ need to trick MacPorts into installing OpenMPI 1.6.4. Proceed as follows: ### Installation for Older OSX Versions +#Outdated# + Before you can build NEST under Mac OS X, you need to install Xcode from the Apple Developer tools installation DVD that came with your Mac (the packages are called Xcode and Optional on Mac OS X 10.6 Snow Leopard). If you are running From 7395cf69deed90458a15a5586d85d81af531f948 Mon Sep 17 00:00:00 2001 From: steffen Date: Tue, 31 May 2016 15:51:22 +0200 Subject: [PATCH 13/20] removed title element from links --- .../documentation/an-introduction-to-sli.md | 10 +++---- .../md/documentation/connection-management.md | 6 ++--- .../userdoc/md/documentation/documentation.md | 26 +++++++++---------- extras/userdoc/md/documentation/download.md | 10 +++---- extras/userdoc/md/documentation/features.md | 12 ++++----- .../md/documentation/getting-started.md | 4 +-- extras/userdoc/md/documentation/index.md | 14 +++++----- .../userdoc/md/documentation/installation.md | 14 +++++----- .../md/documentation/parallel-computing.md | 8 +++--- ...rt-1-neurons-and-simple-neural-networks.md | 10 +++---- .../part-2-populations-of-neurons.md | 2 +- ...art-3-connecting-networks-with-synapses.md | 2 +- ...art-4-topologically-structured-networks.md | 14 +++++----- .../md/documentation/random-numbers.md | 4 +-- .../md/documentation/using-nest-with-music.md | 4 +-- 15 files changed, 70 insertions(+), 70 deletions(-) diff --git a/extras/userdoc/md/documentation/an-introduction-to-sli.md b/extras/userdoc/md/documentation/an-introduction-to-sli.md index e68cf46e53..ffd4ab8735 100644 --- a/extras/userdoc/md/documentation/an-introduction-to-sli.md +++ b/extras/userdoc/md/documentation/an-introduction-to-sli.md @@ -75,8 +75,8 @@ prints the content of the lamda variable. This manual gives a brief overview of the SLI programming language. -1. [First Steps](first-steps.md "First Steps") -2. [Objects and data types](objects-and-data-types.md "Objects and data types") -3. [Programming in SLI](programming-in-sli.md "Programming in SLI") -4. [Using files and keyboard input](using-files-and-keyboard-input.md "Using files and keyboard input") -5. [Neural simulations](neural-simulations.md "Neural simulations") +1. [First Steps](first-steps.md) +2. [Objects and data types](objects-and-data-types.md) +3. [Programming in SLI](programming-in-sli.md) +4. [Using files and keyboard input](using-files-and-keyboard-input.md) +5. [Neural simulations](neural-simulations.md) diff --git a/extras/userdoc/md/documentation/connection-management.md b/extras/userdoc/md/documentation/connection-management.md index 769c95f328..a506a81ad7 100644 --- a/extras/userdoc/md/documentation/connection-management.md +++ b/extras/userdoc/md/documentation/connection-management.md @@ -3,9 +3,9 @@ From NEST 2.4 onwards the old connection routines (i.e. `(Random)ConvergentConnect`, `(Random)DivergentConnect` and plain `Connect`) are replaced by one unified `Connect` function. In -[SLI](an-introduction-to-sli.md "An Introduction to SLI") +[SLI](an-introduction-to-sli.md) ,the old syntax of the function still works, while in -[PyNEST](introduction-to-pynest.md "PyNEST"), the `Connect()` +[PyNEST](introduction-to-pynest.md), the `Connect()` function has been renamed to `OneToOneConnect()`. However, simple cases, which are just creating one-to-one connections between two lists of nodes are still working with the new command without the need to change the code. Note that the @@ -300,7 +300,7 @@ needs to be defined in two steps: Connect(A, B, syn_spec=syn_dict) For further information on the distributions see -[Random numbers in NEST](random-numbers.md "Random numbers in NEST"). +[Random numbers in NEST](random-numbers.md). ## Old Connection Routines diff --git a/extras/userdoc/md/documentation/documentation.md b/extras/userdoc/md/documentation/documentation.md index 1cb23cdfd4..da1f7b8642 100644 --- a/extras/userdoc/md/documentation/documentation.md +++ b/extras/userdoc/md/documentation/documentation.md @@ -1,21 +1,21 @@ # Documentation -## [Installing NEST](installation.md "Installation") +## [Installing NEST](installation.md) -## [Introduction to PyNEST](introduction-to-pynest.md "Introduction to PyNEST") +## [Introduction to PyNEST](introduction-to-pynest.md) ## NEST User Manual -- [Frequently Asked Questions](frequently-asked-questions.md "Frequently Asked Questions") -- [Analog recording with multimeter](analog-recording-with-multimeter.md "Analog recording with multimeter") -- [Connection Management](connection-management.md "Connection Management") -- [Topological Connections](http://www.nest-simulator.org/wp-content/uploads/2015/04/Topology_UserManual.pdf "Topological Connections") -- [Random numbers in NEST](random-numbers.md "Random numbers in NEST") -- [Parallel Computing](parallel-computing.md "Parallel Computing") +- [Frequently Asked Questions](frequently-asked-questions.md) +- [Analog recording with multimeter](analog-recording-with-multimeter.md) +- [Connection Management](connection-management.md) +- [Topological Connections](http://www.nest-simulator.org/wp-content/uploads/2015/04/Topology_UserManual.pdf) +- [Random numbers in NEST](random-numbers.md) +- [Parallel Computing](parallel-computing.md) - [Scheduling and simulation flow](scheduling-and-simulation-flow.md) - [Simulations with precise spike times](simulations-with-precise-spike-times.md) -- [Using NEST with MUSIC](using-nest-with-music.md "Using NEST with MUSIC") -- [Using NEST with the SLI interpreter](an-introduction-to-sli.md "An Introduction to SLI") +- [Using NEST with MUSIC](using-nest-with-music.md) +- [Using NEST with the SLI interpreter](an-introduction-to-sli.md) - [NEST/SLI Quick Reference](quickref.md) - [NEST Command Index](helpindex.md) @@ -60,10 +60,10 @@ ## Further Reading - [NEST by Example](wp-content/uploads/2015/02/NEST_by_Example.pdf) -- Read and improve the [NEST article on Scholarpedia.org](http://scholarpedia.org/article/NEST_\(NEural_Simulation_Tool\) "") -- Read and improve the [NEST article on Wikipedia](http://en.wikipedia.org/wiki/NEST_\(software\) "") +- Read and improve the [NEST article on Scholarpedia.org](http://scholarpedia.org/article/NEST_\(NEural_Simulation_Tool\)) +- Read and improve the [NEST article on Wikipedia](http://en.wikipedia.org/wiki/NEST_\(software\)) ## NEST Developer Manual For information about modifying and extending NEST and contributing your code -to the official version, please head over to the [NEST Developer Space](http://nest.github.io/nest-simulator.html ""). +to the official version, please head over to the [NEST Developer Space](http://nest.github.io/nest-simulator.html). diff --git a/extras/userdoc/md/documentation/download.md b/extras/userdoc/md/documentation/download.md index 6f6cc9632d..1519e905df 100644 --- a/extras/userdoc/md/documentation/download.md +++ b/extras/userdoc/md/documentation/download.md @@ -1,15 +1,15 @@ # Download & Releases -NEST is available under the [GNU General Public License 2 or later](license.md "License"). +NEST is available under the [GNU General Public License 2 or later](license.md). This means that you can - use NEST for your research, - modify and improve NEST according to your needs, - distribute NEST to others under the same license. -To find out more about NEST, see the [list of features](features.md "Features") -and the [user documentation](documentation.md "Documentation"). -For details about how to contribute to the development of NEST, see the [developer space](http://nest.github.io/nest-simulator "Development"). +To find out more about NEST, see the [list of features](features.md) +and the [user documentation](documentation.md). +For details about how to contribute to the development of NEST, see the [developer space](http://nest.github.io/nest-simulator). ## Citing NEST @@ -21,7 +21,7 @@ The full citation is available in different formats on [Zenodo](http://dx.doi.org/10.5281/zenodo.44222). For all other versions below NEST v2.8.0 use: Gewaltig M-O & Diesmann M (2007) -[NEST (Neural Simulation Tool)](http://www.scholarpedia.org/article/NEST_(Neural_Simulation_Tool) "") +[NEST (Neural Simulation Tool)](http://www.scholarpedia.org/article/NEST_(Neural_Simulation_Tool)) *Scholarpedia* 2(4):1430. Here is a suitable BibTeX entry: diff --git a/extras/userdoc/md/documentation/features.md b/extras/userdoc/md/documentation/features.md index 2423002768..e01aa8868c 100644 --- a/extras/userdoc/md/documentation/features.md +++ b/extras/userdoc/md/documentation/features.md @@ -2,8 +2,8 @@ ## General -- Python based user interface ([PyNEST](introduction-to-pynest.md )) -- Built-in simulation language interpreter ([SLI](an-introduction-to-sli.md "An Introduction to SLI")) +- Python based user interface ([PyNEST](introduction-to-pynest.md)) +- Built-in simulation language interpreter ([SLI](an-introduction-to-sli.md)) - Multi-threading to use multi-processor machines efficiently - MPI-parallelism to use computer clusters and super computers @@ -33,11 +33,11 @@ ## Network models -- Topology Module for creating complex networks ([Topology Module User Manual (PDF)](http://www.nest-simulator.org/wp-content/uploads/2014/12/NESTTopologyUserManual.pdf "NESTTopologyUserManual.pdf")) +- Topology Module for creating complex networks ([Topology Module User Manual (PDF)](http://www.nest-simulator.org/wp-content/uploads/2014/12/NESTTopologyUserManual.pdf)) ## Interoperability -- Interface to the Multi Simulator Coordinator [MUSIC](using-nest-with-music.md "Using NEST with MUSIC") +- Interface to the Multi Simulator Coordinator [MUSIC](using-nest-with-music.md) - Backend for the simulator-independent modeling tool [PyNN](http://neuralensemble.org/trac/PyNN/) ## Accuracy @@ -50,7 +50,7 @@ - By default spikes are restricted to the grid spanned by the computation time step -- For some neuron models [spike interaction in continuous time](simulations-with-precise-spike-times.md "spike interaction in continuous time") +- For some neuron models [spike interaction in continuous time](simulations-with-precise-spike-times.md) is available ## Verification @@ -58,7 +58,7 @@ - After installation NEST can be verified by an automatic testsuite - The testsuite is automatically run after each modification of the NEST - sources. You can watch the current status on our [Continuous Integration](continuous-integration.md "Continuous Integration") system. + sources. You can watch the current status on our [Continuous Integration](continuous-integration.md) system. ## Supported platforms diff --git a/extras/userdoc/md/documentation/getting-started.md b/extras/userdoc/md/documentation/getting-started.md index 5ac9e5c1e3..b56b2d5dab 100644 --- a/extras/userdoc/md/documentation/getting-started.md +++ b/extras/userdoc/md/documentation/getting-started.md @@ -1,8 +1,8 @@ # Getting started -[Documentation](documentation.md "Documentation") +[Documentation](documentation.md) This page contains the steps that you should follow right after you -[installed NEST](installation.md "Installation"). Another good +[installed NEST](installation.md). Another good starting point is the help page, which is available as command `help` in SLI and `nest.help()` in PyNEST diff --git a/extras/userdoc/md/documentation/index.md b/extras/userdoc/md/documentation/index.md index 62117db4cc..b2db601bf5 100644 --- a/extras/userdoc/md/documentation/index.md +++ b/extras/userdoc/md/documentation/index.md @@ -79,11 +79,11 @@ memory or to file. NEST is extensible and new models for neurons, synapses, and devices can be added. -To get started with NEST, please see the [Documentation Page for Tutorials](documentation.md "Documentation"). +To get started with NEST, please see the [Documentation Page for Tutorials](documentation.md). ## Why should I use NEST -To learn more about the capabilities of NEST, see the [Feature summary](features.md "Features"). +To learn more about the capabilities of NEST, see the [Feature summary](features.md). 1. NEST provides over 50 neuron models many of which have been published. Choose from simple integrate-and-fire neurons with current or conductance @@ -113,7 +113,7 @@ To learn more about the capabilities of NEST, see the [Feature summary](features 8. NEST has minimal dependencies. All it really needs is a C++ compiler. Everything else is optional. -9. NEST developers are using agile [continuous integration](continuous-integration.md "Continuous Integration")-based +9. NEST developers are using agile [continuous integration](continuous-integration.md)-based workflows in order to maintain high code quality standards for correct and reproducible simulations. @@ -128,7 +128,7 @@ To learn more about the capabilities of NEST, see the [Feature summary](features If you have used NEST for your work either directly or via PyNN, please cite it in your publications as: -Gewaltig M-O & Diesmann M (2007) [NEST (Neural Simulation Tool)](http://www.scholarpedia.org/article/NEST_(Neural_Simulation_Tool) "") +Gewaltig M-O & Diesmann M (2007) [NEST (Neural Simulation Tool)](http://www.scholarpedia.org/article/NEST_(Neural_Simulation_Tool)) *Scholarpedia* 2(4):1430. Here is suitable BibTeX entry: @@ -143,10 +143,10 @@ Here is suitable BibTeX entry: number = {4} } -If you tell us about your publications that used [NEST](download.md "Download"), -we will add it to our [publication list](publications.md "Publications"), +If you tell us about your publications that used [NEST](download.md), +we will add it to our [publication list](publications.md), thus making it visible to potential readers. Send us your reference or even a -reprint, using the mail address given on the [contact page](impressum.md "Impressum"). +reprint, using the mail address given on the [contact page](impressum.md). ## NEST logo for your poster or presentation diff --git a/extras/userdoc/md/documentation/installation.md b/extras/userdoc/md/documentation/installation.md index a526afa77e..39541938af 100644 --- a/extras/userdoc/md/documentation/installation.md +++ b/extras/userdoc/md/documentation/installation.md @@ -10,7 +10,7 @@ INSTALL in the top source directory. Following are the basic steps to compile and install NEST from source code: -1. [Download NEST](download.md "Download") +1. [Download NEST](download.md) 2. Unpack the tarball: `tar -xzvf nest-x.y.z.tar.gz` @@ -25,11 +25,11 @@ Following are the basic steps to compile and install NEST from source code: 7. Install by running `make install` -8. See the [Getting started](getting-started.md "Getting started") pages to +8. See the [Getting started](getting-started.md) pages to find out how to get going with NEST Please see the sections on [minimal](installation.md#minimal-configuration) and -[standard configuration](installation.md#standard-configuration "Installation") +[standard configuration](installation.md#standard-configuration) below for details. ## What gets installed where @@ -73,7 +73,7 @@ search paths. For example, if you are using bash: NEST needs a few third party tools and libraries to work. On many operating systems, these can be installed using a *package manager* like `apt`, `port` or `fink` -(see [Standard configuration](installation.md#standard-configuration "Software:Installation")). +(see [Standard configuration](installation.md#standard-configuration)). If you are building NEST from the SVN sources, you need the GNU autotools installed on your system to bootstrap the build system. These consist of @@ -172,7 +172,7 @@ computations obey the IEEE754 standard for floating point numerics. ## Configuration options -If you need special features, like e.g. support for [distributed computing](parallel-computing.md "Parallel Computing"), +If you need special features, like e.g. support for [distributed computing](parallel-computing.md), you can add command line switches to the call to configure. `./configure --help` will show you all available options. For more information on the installation of NEST, please see the file INSTALL that is included in the distribution archive. @@ -463,14 +463,14 @@ This is the easiest way to use NEST without having to install anything on your computer. The LiveCD can be used in almost any computer and boots directly into a complete Ubuntu system, which already has NEST, Python, and some analysis tools installed. -The CD image is available on the [download page](download.md "Download"). +The CD image is available on the [download page](download.md). ### Virtual Machines A virtual machine is a software that lets you use Linux in parallel to Windows. We recommend to use VirtualBox, which is free software and can be downloaded from . Another popular virtual machine software is . -The easiest way to get started is to download the NEST LiveCD from the [download page](download.md "Download") +The easiest way to get started is to download the NEST LiveCD from the [download page](download.md) and either just boot the CD image directly or install it into a virtual hard disk. diff --git a/extras/userdoc/md/documentation/parallel-computing.md b/extras/userdoc/md/documentation/parallel-computing.md index e3a07283b5..3ea32008b9 100644 --- a/extras/userdoc/md/documentation/parallel-computing.md +++ b/extras/userdoc/md/documentation/parallel-computing.md @@ -20,7 +20,7 @@ describe the facilities for parallel and distributed computing in detail. See [Plesser et al (2007)](http://dx.doi.org/10.1007/978-3-540-74466-5_71) for more information on NEST parallelization and be sure to check the documentation -on [Random numbers in NEST](random-numbers.md "Random numbers in NEST"). +on [Random numbers in NEST](random-numbers.md). ## Concepts and definitions @@ -106,7 +106,7 @@ might require a bit of experimenting. To compile NEST for distributed computing, you need a library implementation of MPI on your system. If you are on a cluster, you most likely have this already. Note, that in the case of a pre-packaged MPI library you will need both, the -library and the development packages. Please see the [Installation instructions](installation.md "Installation") +library and the development packages. Please see the [Installation instructions](installation.md) for general information on installing NEST. Please be advised that NEST should currently only be run in a homogeneous MPI environment. Running in a heterogenenous environment can lead to unexpected @@ -131,7 +131,7 @@ In some cases it might be necessary to specify MPI compiler wrappers explicitly: $NEST_SOURCE_DIR/configure CC=mpicc CXX=mpicxx --with-mpi -Additional information concerning MPI on OSX can be found [here](installation.md "Installation"). +Additional information concerning MPI on OSX can be found [here](installation.md). ### Running distributed simulations @@ -175,7 +175,7 @@ strategies, the number of virtual processes has to be kept constant. A simulation with a specific number of virtual processes will always yield the same results, no matter how they are distributed over threads and processes, given that the seeds for the random number generators of the different virtual -processes are the same (see [Random numbers in NEST](random-numbers.md "Random numbers in NEST")). +processes are the same (see [Random numbers in NEST](random-numbers.md)). In order to achieve a constant number of virtual processes, NEST provides the property *total\_num\_virtual\_procs* to adapt the number of local threads diff --git a/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md b/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md index e71ec9e720..7f57c9af70 100644 --- a/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md +++ b/extras/userdoc/md/documentation/part-1-neurons-and-simple-neural-networks.md @@ -17,7 +17,7 @@ discusses in this primer, please visit [nest-initiative.org/](http://nest-initia or have a look at the source directory of your NEST installation in the subdirectory: `pynest/examples/`. For the internals of the NEST simulator you may refer -to the [publications](publications.md "Publications"). +to the [publications](publications.md). ## PyNEST - an interface to the NEST simulator @@ -170,7 +170,7 @@ form a small network. A![A Membrane potential of integrate-and-fire neuron with constant input current. B Spikes of the neuron.](../../img/vm_one_neuron.pdf.png) & -B![A Membrane potential of integrate-and-fire neuron with constant input current. B Spikes of the neuron.](../../img/spikes_one_neuron.pdf.png "fig:") +B![A Membrane potential of integrate-and-fire neuron with constant input current. B Spikes of the neuron.](../../img/spikes_one_neuron.pdf.png) Figure 2: A Membrane potential of integrate-and-fire neuron with constant input current. B Spikes of the neuron. @@ -227,9 +227,9 @@ window and the fourth line actually produces the plot. You can’t see it yet because we have not used `pylab.show()`. Before we do that, we proceed analogously to obtain and display the spikes from the spike detector. -A![A Membrane potential of integrate-and-fire neuron with Poisson noise as input. B Spikes of the neuron.](../../img/vm_one_neuron_noise.pdf.png "fig:") & +A![A Membrane potential of integrate-and-fire neuron with Poisson noise as input. B Spikes of the neuron.](../../img/vm_one_neuron_noise.pdf.png) & -B![A Membrane potential of integrate-and-fire neuron with Poisson noise as input. B Spikes of the neuron.](../../img/spikes_one_neuron_noise.pdf.png "fig:") +B![A Membrane potential of integrate-and-fire neuron with Poisson noise as input. B Spikes of the neuron.](../../img/spikes_one_neuron_noise.pdf.png) Figure 3: A Membrane potential of integrate-and-fire neuron with Poisson noise as input. B Spikes of the neuron. @@ -406,7 +406,7 @@ given, `params` has to be the name of a property, which is set to `val` on the ### Connections This is an abbreviated version of the documentation for the `Connect` function, -please see NEST’s online help for the full version and [Connection Management](connection-management.md "Connection Management") +please see NEST’s online help for the full version and [Connection Management](connection-management.md) for an introduction and worked examples. `Connect(pre, post, conn_spec=None, syn_spec=None, model=None)`: diff --git a/extras/userdoc/md/documentation/part-2-populations-of-neurons.md b/extras/userdoc/md/documentation/part-2-populations-of-neurons.md index 2080684c15..49f826659f 100644 --- a/extras/userdoc/md/documentation/part-2-populations-of-neurons.md +++ b/extras/userdoc/md/documentation/part-2-populations-of-neurons.md @@ -169,7 +169,7 @@ In addition to the rule specific parameters `indegree`, `outdegree`, `N` and Note that for all connectivity rules, it is perfectly legitimate to have the same population simultaneously in the role of `pre` and `post`. For more information on connecting neurons, please read the documentation of the -`Connect` function and consult the guide at [Connection Management](connection-management.md "Connection Management"). +`Connect` function and consult the guide at [Connection Management](connection-management.md). ## Specifying the behaviour of devices diff --git a/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md b/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md index 34abf7770d..69ad2a26fb 100644 --- a/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md +++ b/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md @@ -140,7 +140,7 @@ set (for example `mu`). Here we show an example where the parameters `alpha` and "delay": 1.0 } nest.Connect(epop1, neuron, "all_to_all", syn_dict) -Available distributions and associated parameters are described in [Connection Management](connection-management.md "Connection Management"), +Available distributions and associated parameters are described in [Connection Management](connection-management.md), the most common ones are: | Distributions | Keys | diff --git a/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md b/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md index 430f13fd06..acc586ae06 100644 --- a/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md +++ b/extras/userdoc/md/documentation/part-4-topologically-structured-networks.md @@ -11,7 +11,7 @@ networks. When you have worked through this material you will be able to: - Visualise the connectivity For more information on the usage of NEST, please visit: -[Documentation](documentation.md) "Documentation") +[Documentation](documentation.md)) ## Incorporating structure in networks of point neurons @@ -91,8 +91,8 @@ We next have to decide whether the nodes should be placed in a **grid-based** or of our network be regularly and evenly placed within a 2D network, or do we need to tell them where they should be located?". -A ![Example of (A) on-grid and (B) off-grid, in which the neurons are positioned as grid+jitter.](../../img/grid.png "fig:") -B ![Example of (A) on-grid and (B) off-grid, in which the neurons are positioned as grid+jitter.](../../img/free.png "fig:") +A ![Example of (A) on-grid and (B) off-grid, in which the neurons are positioned as grid+jitter.](../../img/grid.png) +B ![Example of (A) on-grid and (B) off-grid, in which the neurons are positioned as grid+jitter.](../../img/free.png) Figure 1: Example of (A) on-grid and (B) off-grid, in which the neurons are positioned as grid+jitter. @@ -184,12 +184,12 @@ constraints, as well as reading through the different examples listed there. Here are some representative examples for setting up a connectivity profile, and the following table lists the parameters that can be used. -A ![Examples of connectivity for each of the connectivity dictionaries mentioned in the following Python code snippet.](../../img/sample1_circgauss.png "fig:") +A ![Examples of connectivity for each of the connectivity dictionaries mentioned in the following Python code snippet.](../../img/sample1_circgauss.png) -B ![Examples of connectivity for each of the connectivity dictionaries mentioned in the following Python code snippet.](../../img/sample2_rectanchor.png "fig:") - C ![Examples of connectivity for each of the connectivity dictionaries mentioned in the following Python code snippet.](../../img/sample3_doughnutlinear.png "fig:") +B ![Examples of connectivity for each of the connectivity dictionaries mentioned in the following Python code snippet.](../../img/sample2_rectanchor.png) + C ![Examples of connectivity for each of the connectivity dictionaries mentioned in the following Python code snippet.](../../img/sample3_doughnutlinear.png) -D ![Examples of connectivity for each of the connectivity dictionaries mentioned in the following Python code snippet.](../../img/sample4_gaussweights.png "fig:") +D ![Examples of connectivity for each of the connectivity dictionaries mentioned in the following Python code snippet.](../../img/sample4_gaussweights.png) Figure 2: Examples of connectivity for each of the connectivity dictionaries mentioned in the following Python code snippet. diff --git a/extras/userdoc/md/documentation/random-numbers.md b/extras/userdoc/md/documentation/random-numbers.md index 3462e87d9f..c751ef30b7 100644 --- a/extras/userdoc/md/documentation/random-numbers.md +++ b/extras/userdoc/md/documentation/random-numbers.md @@ -40,7 +40,7 @@ during network construction, as described in the sections [Changes in NEST 2.4]( Random deviate generation has become significantly more powerful in NEST 2.4, to fully support randomization of connections parameters offered by the revised -`Connect` function, as described in [Connection Management](connection-management.md "Connection Management") +`Connect` function, as described in [Connection Management](connection-management.md) and illustrated by the [examples](random-numbers.md#examples) below. We have also made minor changes to make to achieve greater similarity between NEST, PyNN, and NumPy. For most users, these changes only add new features. @@ -121,7 +121,7 @@ The changes are as follows: ## Basics of parallel simulation in NEST -For details of parallelization in NEST, please see [Parallel Computing](parallel-computing.md "Parallel Computing") +For details of parallelization in NEST, please see [Parallel Computing](parallel-computing.md) and [Plesser et al (2007)](http://dx.doi.org/10.1007/978-3-540-74466-5_71). Here, we just summarize a few basics. diff --git a/extras/userdoc/md/documentation/using-nest-with-music.md b/extras/userdoc/md/documentation/using-nest-with-music.md index 016e2bdf20..1894b93289 100644 --- a/extras/userdoc/md/documentation/using-nest-with-music.md +++ b/extras/userdoc/md/documentation/using-nest-with-music.md @@ -135,7 +135,7 @@ which contains the messages and the corresponding time stamps. The data file 0.7  ! Please note that MUSIC uses a default unit of seconds for the specification of -times, while NEST uses miliseconds. The example uses the [PyNEST](introduction-to-pynest.md "PyNEST") +times, while NEST uses miliseconds. The example uses the [PyNEST](introduction-to-pynest.md) syntax instead of SLI for the NEST part. The script that sets up the receiving side (`msgtest.py`) of the exampe is shown in the following listing: @@ -228,7 +228,7 @@ the following listing: from.contdata -> to.contdata [10] -The receiving side is again implemented using a [PyNEST](introduction-to-pynest.md "PyNEST") +The receiving side is again implemented using a [PyNEST](introduction-to-pynest.md) script (`conttest.py`): #!/usr/bin/python From 36c7908084cea63acad528eeaf1e5f2279841b09 Mon Sep 17 00:00:00 2001 From: steffen Date: Wed, 1 Jun 2016 07:03:37 +0200 Subject: [PATCH 14/20] new link to community.md --- extras/userdoc/md/documentation/parallel-computing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extras/userdoc/md/documentation/parallel-computing.md b/extras/userdoc/md/documentation/parallel-computing.md index 3ea32008b9..b1c1ebfe42 100644 --- a/extras/userdoc/md/documentation/parallel-computing.md +++ b/extras/userdoc/md/documentation/parallel-computing.md @@ -111,7 +111,7 @@ for general information on installing NEST. Please be advised that NEST should currently only be run in a homogeneous MPI environment. Running in a heterogenenous environment can lead to unexpected results or even crashes. -Please contact the [NEST community](http://www.nest-simulator.org/community/) if +Please contact the [NEST community](community.md) if you require support for exotic setups. ### Compilation From 526dab5c89a230fc30051d2b532a6db19aa176db Mon Sep 17 00:00:00 2001 From: steffen Date: Wed, 1 Jun 2016 07:05:36 +0200 Subject: [PATCH 15/20] better title for command overview --- .../userdoc/md/documentation/part-2-populations-of-neurons.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extras/userdoc/md/documentation/part-2-populations-of-neurons.md b/extras/userdoc/md/documentation/part-2-populations-of-neurons.md index 49f826659f..5122ec361c 100644 --- a/extras/userdoc/md/documentation/part-2-populations-of-neurons.md +++ b/extras/userdoc/md/documentation/part-2-populations-of-neurons.md @@ -224,7 +224,7 @@ is often helpful to call the function `ResetNetwork()` within each loop iteration. It resets all nodes to their default configuration and wipes the data from recording devices. -## Command overview\[sec:Command-overview\] +## Command overview These are the new functions we introduced for the examples in this handout. From 31449f1aace00b38ef8a2bf1c95621a86826b296 Mon Sep 17 00:00:00 2001 From: steffen Date: Wed, 1 Jun 2016 07:12:56 +0200 Subject: [PATCH 16/20] better link to SLI introduction --- extras/userdoc/md/documentation/using-nest-with-music.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/extras/userdoc/md/documentation/using-nest-with-music.md b/extras/userdoc/md/documentation/using-nest-with-music.md index 1894b93289..e128cee49a 100644 --- a/extras/userdoc/md/documentation/using-nest-with-music.md +++ b/extras/userdoc/md/documentation/using-nest-with-music.md @@ -26,10 +26,10 @@ Neuroinformatics, 8, 2010. doi:10.1007/s12021-010-9064-z* and available from [he A minimal example for the exchange of spikes between two independent instances of NEST is given in the example `examples/nest/music/minimalmusicsetup.music`. -It uses one [SLI script](an-introduction-to-sli.md "An Introduction -to SLI"), which sends spikes using a `music_event_out_proxy` and one SLI script, -which receives the spikes using a `music_event_in_proxy`. The configuration file -is shown in the following listing: +It uses one [SLI script](an-introduction-to-sli.md), which sends spikes using a +`music_event_out_proxy` and one SLI script, which receives the spikes using a +`music_event_in_proxy`. The configuration file is shown in the following +listing: [from] binary=nest From e1ebf43eab59b7d377c834db57584c76cf689485 Mon Sep 17 00:00:00 2001 From: steffen Date: Wed, 1 Jun 2016 07:24:13 +0200 Subject: [PATCH 17/20] changed link to Topology_UserManual.pdf --- extras/userdoc/md/documentation/connection-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extras/userdoc/md/documentation/connection-management.md b/extras/userdoc/md/documentation/connection-management.md index a506a81ad7..acbf13e4f5 100644 --- a/extras/userdoc/md/documentation/connection-management.md +++ b/extras/userdoc/md/documentation/connection-management.md @@ -442,7 +442,7 @@ Example new connection routine: If the connect functions above are not sufficient, the topology provides more sophisticated functions. For example, it is possible to create receptive field structures and much more! See -[Topological Connections](Topology_UserManual.pdf) +[Topological Connections](wp-content/uploads/2015/04/Topology_UserManual.pdf) for more information. ## Receptor Types From f2575495d88aca30898d76a5ba87311caa416f4e Mon Sep 17 00:00:00 2001 From: steffen Date: Wed, 1 Jun 2016 07:54:24 +0200 Subject: [PATCH 18/20] Use raw html to resize logo --- extras/userdoc/md/documentation/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extras/userdoc/md/documentation/index.md b/extras/userdoc/md/documentation/index.md index b2db601bf5..a25e80cdf5 100644 --- a/extras/userdoc/md/documentation/index.md +++ b/extras/userdoc/md/documentation/index.md @@ -154,7 +154,7 @@ If you like NEST, why not show it on your poster or on your slides? -![](../../../logos/nest-simulated.png) + ## Nest Models on [Open Source Brain](http://www.opensourcebrain.org/) From 4517e048286f643db6d8158b61bb32b164bc01dc Mon Sep 17 00:00:00 2001 From: steffen Date: Wed, 1 Jun 2016 09:07:00 +0200 Subject: [PATCH 19/20] right link for Topology_UserManual.pdf --- extras/userdoc/md/documentation/connection-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extras/userdoc/md/documentation/connection-management.md b/extras/userdoc/md/documentation/connection-management.md index acbf13e4f5..bc28625fd3 100644 --- a/extras/userdoc/md/documentation/connection-management.md +++ b/extras/userdoc/md/documentation/connection-management.md @@ -442,7 +442,7 @@ Example new connection routine: If the connect functions above are not sufficient, the topology provides more sophisticated functions. For example, it is possible to create receptive field structures and much more! See -[Topological Connections](wp-content/uploads/2015/04/Topology_UserManual.pdf) +[Topological Connections](http://www.nest-simulator.org/wp-content/uploads/2015/04/Topology_UserManual.pdf) for more information. ## Receptor Types From 5a84c1c9486ecea371f4291ed5ebf29b9f2d0f81 Mon Sep 17 00:00:00 2001 From: steffen Date: Tue, 21 Jun 2016 13:00:37 +0200 Subject: [PATCH 20/20] some minor changes --- extras/userdoc/md/documentation/installation.md | 2 +- .../documentation/part-3-connecting-networks-with-synapses.md | 2 +- extras/userdoc/md/documentation/random-numbers.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/extras/userdoc/md/documentation/installation.md b/extras/userdoc/md/documentation/installation.md index 39541938af..84ebbef5e6 100644 --- a/extras/userdoc/md/documentation/installation.md +++ b/extras/userdoc/md/documentation/installation.md @@ -184,7 +184,7 @@ the help pages. The browser is set as an option of `helpdesk`. Please see the file `~/.nestrc` for an example setting `firefox` as browser. Please note that the command `helpdesk` does not work if you have compiled NEST with MPI support, but you have to enter the address of the helpdesk -(`file://$PREFIX/share/doc/nest.md`) manually into the browser. +(`file://$PREFIX/share/doc/nest/index.html`) manually into the browser. Please replace `$PREFIX` with the prefix you chose during the configuration of NEST. If you did not explicitly specify one, it is most likely set to `/usr` or `/usr/local` depending on what system you are. diff --git a/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md b/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md index 69ad2a26fb..ca65954ce7 100644 --- a/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md +++ b/extras/userdoc/md/documentation/part-3-connecting-networks-with-synapses.md @@ -287,7 +287,7 @@ the neuronal population itself. In the case of loops, check first whether you can avoid it entirely by passing the entire population into the function - you usually can. -## Command overview\[sec:Command-overview\] +## Command overview These are the new functions we introduced for the examples in this handout. diff --git a/extras/userdoc/md/documentation/random-numbers.md b/extras/userdoc/md/documentation/random-numbers.md index c751ef30b7..7c4ee243e7 100644 --- a/extras/userdoc/md/documentation/random-numbers.md +++ b/extras/userdoc/md/documentation/random-numbers.md @@ -34,7 +34,7 @@ uniformly distributed integers in {0, 1, ..., N}. Random *deviate* generators, on the other hand, provide random numbers drawn from a range of distributions, such as the normal or binomial distributions. In most cases, you will be using random deviate generators. They are in particular used to initialize properties -during network construction, as described in the sections [Changes in NEST 2.4](random-numbers.md#changes-in-random-number-generation-in-NEST-2.4) and [Examples](random-numbers.md#examples) below. +during network construction, as described in the sections [Changes in NEST 2.4](random-numbers.md#changes-in-random-number-generation-in-nest-2.4) and [Examples](random-numbers.md#examples) below. ## Changes in random number generation in NEST 2.4