Add attributes to spike events

doc/nestml_language/neurons_in_nestml.rst

@@ -31,48 +31,7 @@ A neuron model written in NESTML can be configured to receive two distinct types
        AMPA_spikes <- spike
        I_stim pA <- continuous
 
-The general syntax is:
-
-::
-
-    port_name <- inputQualifier spike
-    port_name dataType <- continuous
-
 The spiking input ports are declared without a data type, whereas the continuous input ports must have a data type.
-For spiking input ports, the qualifier keywords decide whether inhibitory and excitatory inputs are lumped together into a single named input port, or if they are separated into differently named input ports based on their sign. When processing a spike event, some simulators (including NEST) use the sign of the amplitude (or weight) property in the spike event to indicate whether it should be considered an excitatory or inhibitory spike. By using the qualifier keywords, a single spike handler can route each incoming spike event to the correct input buffer (excitatory or inhibitory). Compare:
-
-.. code-block:: nestml
-
-   input:
-       # [...]
-       all_spikes <- spike
-
-In this case, all spike events will be processed through the ``all_spikes`` input port. A spike weight could be positive or negative, and the occurrences of ``all_spikes`` in the model should be considered a signed quantity.
-
-.. code-block:: nestml
-
-   input:
-       # [...]
-       AMPA_spikes <- excitatory spike
-       GABA_spikes <- inhibitory spike
-
-In this case, spike events that have a negative weight are routed to the ``GABA_spikes`` input port, and those that have a positive weight to the ``AMPA_spikes`` port.
-
-It is equivalent if either both `inhibitory` and `excitatory` are given, or neither: an unmarked port will by default handle all incoming presynaptic spikes.
-
-.. list-table::
-   :header-rows: 1
-   :widths: 10 60
-
-   * - Keyword
-     - The incoming weight :math:`w`...
-   * - none, or ``excitatory`` and ``inhibitory``
-     - ... may be positive or negative. It is added to the buffer with signed value :math:`w` (positive or negative).
-   * - ``excitatory``
-     - ... should not be negative. It is added to the buffer with non-negative magnitude :math:`w`.
-   * - ``inhibitory``
-     - ... should be negative. It is added to the buffer with non-negative magnitude :math:`-w`.
-
 
 
 Integrating current input
@@ -92,14 +51,6 @@ The current port symbol (here, ``I_stim``) is available as a variable and can be
 Integrating spiking input
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Spikes arriving at the input port of a neuron can be written as a spike train :math:`s(t)`:
-
-.. math::
-
-   \large s(t) = \sum_{i=1}^N w_i \cdot \delta(t - t_i)
-
-where :math:`w_i` is the weight of spike :math:`i`.
-
 To model the effect that an arriving spike has on the state of the neuron, a convolution with a kernel can be used. The kernel defines the postsynaptic response kernel, for example, an alpha (bi-exponential) function, decaying exponential, or a delta function. (See :ref:`Kernel functions` for how to define a kernel.) The convolution of the kernel with the spike train is defined as follows:
 
 .. math::
@@ -110,16 +61,20 @@ To model the effect that an arriving spike has on the state of the neuron, a con
                         &= \sum_{i=1}^N w_i \cdot f(t - t_i)
    \end{align*}
 
-For example, say there is a spiking input port defined named ``spikes``. A decaying exponential with time constant ``tau_syn`` is defined as postsynaptic kernel ``G``. Their convolution is expressed using the ``convolve()`` function, which takes a kernel and input port, respectively, as its arguments:
+For example, say there is a spiking input port defined named ``spikes``, which receives weighted spike events:
+
+.. code-block:: nestml
+
+   input:
+       spikes <- spike(weight pA)
+
+A decaying exponential with time constant ``tau_syn`` is defined as postsynaptic kernel ``G``. Their convolution is expressed using the ``convolve()`` function, which takes a kernel and input port, respectively, as its arguments:
 
 .. code-block:: nestml
 
    equations:
        kernel G = exp(-t / tau_syn)
-       inline I_syn pA = convolve(G, spikes) * pA
-       V_m' = -V_m / tau_m + I_syn / C_m
-
-Note that in this example, the intended physical unit (pA) was assigned by multiplying the scalar convolution result with the unit literal. By the definition of convolution, ``convolve(G, spikes)`` will have the unit of kernel ``G`` multiplied by the unit of ``spikes`` and unit of time, i.e., ``[G] * [spikes] * s``. Kernel functions in NESTML are always untyped and the unit of spikes is :math:`1/s` as discussed above. As a result, the unit of convolution is :math:`(1/s) * s`, a scalar quantity without a unit.
+       inline I_syn pA = convolve(G, spikes.weight)
 
 The incoming spikes could have been equivalently handled with an ``onReceive`` event handler block:
 
@@ -130,12 +85,9 @@ The incoming spikes could have been equivalently handled with an ``onReceive`` e
 
    equations:
        I_syn' = -I_syn / tau_syn
-       V_m' = -V_m / tau_m + I_syn / C_m
 
    onReceive(spikes):
-       I_syn += spikes * pA * s
-
-Note that in this example, the intended physical unit (pA) was assigned by multiplying the type of the input port ``spikes`` (which is 1/s) by pA·s, resulting in a unit of pA for ``I_syn``.
+       I_syn += integrate(spikes.weight, t, t + timestep())
 
 
 (Re)setting synaptic integration state
@@ -217,12 +169,12 @@ The input ports can also be defined as vectors. For example,
 
    neuron multi_synapse_vectors:
        input:
-           AMPA_spikes <- excitatory spike
-           GABA_spikes <- inhibitory spike
+           AMPA_spikes <- spike
+           GABA_spikes <- spike
            NMDA_spikes <- spike
            foo[2] <- spike
-           exc_spikes[3] <- excitatory spike
-           inh_spikes[3] <- inhibitory spike
+           exc_spikes[3] <- spike
+           inh_spikes[3] <- spike
 
        equations:
            kernel I_kernel_exc = exp(-1 / tau_syn_exc * t)

doc/pynestml_toolchain/front.rst

@@ -267,8 +267,6 @@ Given the fact that context conditions have the commonality of checking the cont
 
 -  *CoCoConvolveHasCorrectParameter*: Checks that *convolve* calls are not provided with complex expressions, but only variables.
 
--  *CoCoTypeOfBufferUnique*: Checks that no keyword is stated twice in an input buffer declaration, e.g., *inhibitory inhibitory spike*.
-
 -  *CoCoUserDeclaredFunctionCorrectlyDefined*: Checks that user-defined functions are correctly defined, i.e., only parameters of the function are used, and the return type is correctly stated.
 
 -  *CoCoVariableOncePerScope*: Checks that each variable is defined at most once per scope, i.e., no variable is redefined.

doc/running/running_nest.rst

@@ -12,6 +12,12 @@ After NESTML completes, the NEST extension module (by default called ``"nestmlmo
    Several code generator options are available; for an overview see :class:`pynestml.codegeneration.nest_code_generator.NESTCodeGenerator`.
 
 
+Data types
+----------
+
+- The NESTML data type ``real`` will be rendered as ``double``.
+- The NESTML data type ``integer`` will be rendered as ``long``.
+
 Simulation loop
 ---------------
 
@@ -135,7 +141,7 @@ Multiple spiking input ports with vectors in NEST
 
 See :ref:`Multiple input ports with vectors` for an example with input ports defined as vectors.
 
-Each connection in NEST is denoted by a receiver port or ``rport`` number which is an integer that starts with 0. All default connections in NEST have the ``rport`` 0. NESTML routes the spikes with ``excitatory`` and ``inhibitory`` qualifiers into separate input buffers, whereas NEST identifies them with the same ``rport`` number.
+Each connection in NEST is denoted by a receiver port or ``rport`` number which is an integer that starts with 0. All default connections in NEST have the ``rport`` 0.
 
 During the code generation for NEST, NESTML maintains an internal mapping between NEST ``rports`` and NESTML input ports. A list of port names defined in a model and their corresponding ``rport`` numbers can be queried from the status dictionary using the NEST API. For neurons with multiple input ports, the ``receptor_type`` values in the ``nest.Connect()`` call start from 1 as the default ``receptor_type`` 0 is excluded to avoid any accidental connections.
 
@@ -161,7 +167,7 @@ The above code querying for ``receptor_types`` gives a list of port names and NE
      - 1
    * - NMDA_spikes
      - 2
-   * - FOO_0
+   * - FOO_0 XXXXX _VEC_IDX_
      - 3
    * - FOO_1
      - 4
@@ -263,8 +269,6 @@ By default, the "continuous-time" based buffer is selected. This covers the most
 As a computationally more efficient alternative, a spike-based buffer can be selected. In this case, the third factor is not stored every timestep, but only upon the occurrence of postsynaptic (somatic) spikes. Because of the existence of a nonzero dendritic delay, the time at which the somatic spike is observed at the synapse is delayed, and the time at which the third factor is sampled should match the time of the spike at the synapse, rather than the soma. When the spike-based buffering method is used, the dendritic delay is therefore ignored, because the third factor is sampled instead at the time of the somatic spike.
 
 
-
-
 Dendritic delay and synaptic weight
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -316,6 +320,44 @@ Random numbers
 In case random numbers are needed inside the synapse, the random number generator belonging to the postsynaptic target is used.
 
 
+Performance optimisations
+-------------------------
+
+In neuron models, incoming spikes are by default buffered into a queue (a ``std::vector``) before being processed. This implementation is the most generic, allowing, for example, spikes with both positive and negative weights arriving at one and the same input port to be handled differently according to the sign. However, the queue can cause a degradation in runtime performance on the order of 10%. If no conditional processing of the incoming spikes is necessary, and all spikes are treated in the same, linear, time-invariant (LTI) manner, then no queue is necessary as all spike weights can be simply added together into a single floating-point variable. The code generator option ``linear_time_invariant_spiking_input_ports`` can be used to indicate for which ports the spikes can be treated in an LTI-manner.
+
+For instance, if spikes arriving at the same port are handled differently according to sign of the weight:
+
+.. code:: nestml
+
+   input:
+       spike_in_port <- spike(weight pA)
+
+   onReceive(spike_in_port):
+       # route the incoming spike on the basis of the weight: less than zero means an inhibitory spike; greater than zero means an excitatory spike
+       if spike_in_port.weight > 0:
+           I_syn_exc += spike_in_port.weight
+       else:
+           I_syn_inh -= spike_in_port.weight
+
+then the system is not LTI and a queue is necessary.
+
+However, if two separate ports are used (and weights are subsequently processed in an LTI manner), the model can be formulated in a mathematically equivalent way:
+
+.. code:: nestml
+
+   input:
+       spike_in_port_exc <- spike(weight pA)
+       spike_in_port_inh <- spike(weight pA)
+
+   onReceive(spike_in_port_exc):
+        I_syn_exc += spike_in_port.weight
+
+   onReceive(spike_in_port_exc):
+        I_syn_inh += spike_in_port.weight
+
+In this case, the ``linear_time_invariant_spiking_input_ports`` option can be used to specify that both ``spike_in_port_exc`` and ``spike_in_port_inh`` are LTI ports, for better runtime performance.
+
+
 References
 ----------
 

doc/tutorials/active_dendrite/nestml_active_dendrite_tutorial.ipynb

@@ -124,7 +124,7 @@
     "    equations:\n",
     "        # alpha shaped postsynaptic current kernel\n",
     "        kernel syn_kernel = (e / tau_syn) * t * exp(-t / tau_syn)\n",
-    "        recordable inline I_syn pA = convolve(syn_kernel, spikes_in) * pA\n",
+    "        recordable inline I_syn pA = convolve(syn_kernel, spikes_in.weight)\n",
     "        V_m' = -(V_m - E_L) / tau_m + (I_syn + I_dAP + I_e) / C_m\n",
     "\n",
     "    parameters:\n",
@@ -142,7 +142,7 @@
     "        T_dAP ms = 10 ms         # time window over which the dendritic current clamp is active\n",
     "\n",
     "    input:\n",
-    "        spikes_in <- spike\n",
+    "        spikes_in <- spike(weight pA)\n",
     "\n",
     "    output: \n",
     "        spike\n",
@@ -503,7 +503,7 @@
     "    equations:\n",
     "        # alpha shaped postsynaptic current kernel\n",
     "        kernel syn_kernel = (e / tau_syn) * t * exp(-t / tau_syn)\n",
-    "        recordable inline I_syn pA = convolve(syn_kernel, spikes_in) * pA\n",
+    "        recordable inline I_syn pA = convolve(syn_kernel, spikes_in.weight)\n",
     "        V_m' = -(V_m - E_L) / tau_m + (enable_I_syn * I_syn + I_dAP + I_e) / C_m\n",
     "\n",
     "    parameters:\n",
@@ -521,7 +521,7 @@
     "        T_dAP ms = 10 ms         # time window over which the dendritic current clamp is active\n",
     "\n",
     "    input:\n",
-    "        spikes_in <- spike\n",
+    "        spikes_in <- spike(weight pA)\n",
     "\n",
     "    output:\n",
     "        spike\n",

doc/tutorials/izhikevich/izhikevich_solution.nestml

@@ -25,21 +25,21 @@
 model izhikevich_tutorial_neuron:
 
     state:
-        v mV = -65 mV    # Membrane potential in mV
-        u real = 0    # Membrane potential recovery variable
+        v mV = -65 mV   # Membrane potential in mV
+        u real = 0      # Membrane potential recovery variable
 
     equations:
         v' = (.04 * v * v / mV + 5 * v + (140 - u) * mV + (I_e * GOhm)) / ms
         u' = a * (b * v - u * mV) / (mV * ms)
 
     parameters:
         a real = .02    # describes time scale of recovery variable
-        b real = .2    # sensitivity of recovery variable
-        c mV = -65 mV    # after-spike reset value of v
-        d real = 8.    # after-spike reset value of u
+        b real = .2     # sensitivity of recovery variable
+        c mV = -65 mV   # after-spike reset value of v
+        d real = 8.     # after-spike reset value of u
 
     input:
-        spikes <- spike
+        spikes <- spike(weight mV)
         I_e pA <- continuous
 
     output:
@@ -50,7 +50,7 @@ model izhikevich_tutorial_neuron:
 
     onReceive(spikes):
         # add synaptic current
-        v += spikes * mV * s
+        v += spikes.weight
 
     onCondition(v >= 30mV):
         # threshold crossing

doc/tutorials/izhikevich/izhikevich_task.nestml

@@ -39,7 +39,7 @@ model izhikevich_tutorial_neuron:
         # TODO: add remaining variables
 
     input:
-        spikes <- spike
+        spikes <- spike(weight mV)
         I_e pA <- continuous
 
     output:
@@ -50,7 +50,7 @@ model izhikevich_tutorial_neuron:
 
     onReceive(spikes):
         # add synaptic current
-        v += spikes * mV * s
+        v += spikes.weight
 
     onCondition(v >= 30mV):
         # TODO: implement threshold crossing check

doc/tutorials/sequence_learning/iaf_psc_exp_nonlineardendrite_neuron.nestml

@@ -46,8 +46,8 @@ model iaf_psc_exp_nonlineardendrite_neuron:
         kernel I_kernel3 = exp(-1/tau_syn3*t)
 
         # diff. eq. for membrane potential
-        inline I_syn pA = convolve(I_kernel1, I_1) * pA - convolve(I_kernel3, I_3) * pA + I_e
-        V_m' = -(V_m - E_L)/tau_m + (I_syn + I_dend) / C_m
+        inline I_syn pA = convolve(I_kernel1, I_1.weight) - convolve(I_kernel3, I_3.weight) + I_e
+        V_m' = -(V_m - E_L) / tau_m + (I_syn + I_dend) / C_m
 
         # diff. eq. for dAP trace
         dAP_trace' = -evolve_dAP_trace * dAP_trace / tau_h
@@ -77,17 +77,17 @@ model iaf_psc_exp_nonlineardendrite_neuron:
 
         I_dend_incr pA/ms = pA * exp(1) / tau_syn2
 
-
     input:
-        I_1 <- spike
-        I_2 <- spike
-        I_3 <- spike
+        I_1 <- spike(weight pA)
+        I_2 <- spike(weight real)
+        I_3 <- spike(weight pA)
 
     output:
         spike
 
     onReceive(I_2):
-        I_dend$ += I_2 * s * I_dend_incr
+        spike_weight pA = integral(I_2.weight, t, t + timestep())
+        I_dend$ += spike_weight * I_dend_incr
 
     update:
         # solve ODEs
@@ -136,4 +136,3 @@ model iaf_psc_exp_nonlineardendrite_neuron:
             active_dendrite_readout = 0.
             dAP_counts = 0
             I_dend = 0 pA
-

doc/tutorials/spike_frequency_adaptation/models/iaf_psc_alpha.nestml

@@ -65,7 +65,7 @@ model iaf_psc_alpha_neuron:
     equations:
         kernel I_kernel_inh = (e / tau_syn_inh) * t * exp(-t / tau_syn_inh)
         kernel I_kernel_exc = (e / tau_syn_exc) * t * exp(-t / tau_syn_exc)
-        inline I pA = (convolve(I_kernel_exc, exc_spikes) - convolve(I_kernel_inh, inh_spikes)) * pA + I_e + I_stim
+        inline I pA = convolve(I_kernel_exc, exc_spikes.weight) - convolve(I_kernel_inh, inh_spikes.weight) + I_e + I_stim
         V_m' = -(V_m - E_L) / tau_m + I / C_m
 
     parameters:
@@ -82,8 +82,8 @@ model iaf_psc_alpha_neuron:
         I_e pA = 0 pA
 
     input:
-        exc_spikes <- excitatory spike
-        inh_spikes <- inhibitory spike
+        exc_spikes <- spike(weight pA)
+        inh_spikes <- spike(weight pA)
         I_stim pA <- continuous
 
     output:

doc/tutorials/spike_frequency_adaptation/models/iaf_psc_alpha_adapt_curr.nestml

@@ -68,7 +68,7 @@ model iaf_psc_alpha_adapt_curr_neuron:
     equations:
         kernel I_kernel_inh = (e / tau_syn_inh) * t * exp(-t / tau_syn_inh)
         kernel I_kernel_exc = (e / tau_syn_exc) * t * exp(-t / tau_syn_exc)
-        inline I pA = (convolve(I_kernel_exc, exc_spikes) - convolve(I_kernel_inh, inh_spikes)) * pA - I_sfa + I_e + I_stim
+        inline I pA = convolve(I_kernel_exc, exc_spikes.weight) - convolve(I_kernel_inh, inh_spikes.weight) - I_sfa + I_e + I_stim
         V_m' = -(V_m - E_L) / tau_m + I / C_m
         I_sfa' = -I_sfa / tau_sfa
 
@@ -89,8 +89,8 @@ model iaf_psc_alpha_adapt_curr_neuron:
         I_e pA = 0 pA
 
     input:
-        exc_spikes <- excitatory spike
-        inh_spikes <- inhibitory spike
+        exc_spikes <- spike(weight pA)
+        inh_spikes <- spike(weight pA)
         I_stim pA <- continuous
 
     output: