Add STDP code generation for SpiNNaker target

.gitignore

@@ -1,3 +1,12 @@
+nestml_python_target*
+spinnaker-target*
+spinnaker-install*
+*_BACKUP_*
+*_BASE_*
+*_LOCAL_*
+*_REMOTE_*
+*.orig
+*.save
 .settings/
 target/
 .idea/

doc/running/running_spinnaker.rst

@@ -1,13 +1,16 @@
 SpiNNaker target
 ----------------
 
-*NESTML features supported:* :doc:`neurons </nestml_language/neurons_in_nestml>`
+*NESTML features supported:* :doc:`neurons </nestml_language/neurons_in_nestml>`, :doc:`synapses </nestml_language/synapses_in_nestml>`
+
+.. warning::
+
+   SpiNNaker support is in an early stage of development. Expect missing features and bugs. If you want to use or contribute to this target, please reach out to the developers via GitHub or the NEST-users mailing list.
 
 Introduction
 ~~~~~~~~~~~~
 
-SpiNNaker [FB20]_ was first publicly mentioned in 1998. It is a neuromorphic architecture based on ARM microprocessors connected into a network. The project emerged from the research question of efficiently integrating associative memory in Very Large Scale Integration (VLSI) architectures. After some research, it was clear that the architecture would come down to a neuromorphic architecture. Earlier implementations mainly focused on analog implementations of neurons and synapses combined with digital communication, However, Furber's previous involvement with ARM and asynchronous digital circuits led to a design based on ARM microprocessors implementing the model and network details in software. As mentioned in the introduction to neuromorphic computing, handling many communication messages is a challenge. Following the biological example is hard to achieve, as to be generally applicable would mean building a physical connection between each neuron, which apart from spatial problems also hinders scalability. This was previously solved by using a bus system with, compared to biological spikes, short digital messages encoding a unique address of the source neuron as the spike. Because of the short pulse, spikes generated simultaneously can be serialized without breaking the concepts found in nature. This protocol is called Address Event Representation (AER [Mah92]_). Each spike is a broadcast message on the bus, where
-each neuron determines if it should receive the spike through the address of the source neuron [Mah92]_.
+SpiNNaker [FB20]_ was first publicly mentioned in 1998. It is a neuromorphic architecture based on ARM microprocessors connected into a network. The project emerged from the research question of efficiently integrating associative memory in Very Large Scale Integration (VLSI) architectures. After some research, it was clear that the architecture would come down to a neuromorphic architecture. Earlier implementations mainly focused on analog implementations of neurons and synapses combined with digital communication, However, Furber's previous involvement with ARM and asynchronous digital circuits led to a design based on ARM microprocessors implementing the model and network details in software. As mentioned in the introduction to neuromorphic computing, handling many communication messages is a challenge. Following the biological example is hard to achieve, as to be generally applicable would mean building a physical connection between each neuron, which apart from spatial problems also hinders scalability. This was previously solved by using a bus system with, compared to biological spikes, short digital messages encoding a unique address of the source neuron as the spike. Because of the short pulse, spikes generated simultaneously can be serialized without breaking the concepts found in nature. This protocol is called Address Event Representation (AER [Mah92]_). Each spike is a broadcast message on the bus, where each neuron determines if it should receive the spike through the address of the source neuron [Mah92]_.
 
 As this solution uses a single bus, the scalability of the system is dependent on the bus throughput. This let the team around SpiNNaker to switch from a bus system to a packet-switched network, where packets can be routed to specified targets. Instead of being bound to the fixed specification of bus throughput, this now also allows scaling the network capacity by adding more routers. They call this Multicast Packet-Switched AER. With this architecture, they were able to achieve a system with 1 million processors called SpiNNaker1M. All information about SpiNNaker presented in this chapter comes from the book "SpiNNaker: A Spiking Neural Network Architecture" [FB20]_.
 
@@ -21,9 +24,46 @@ Generating code
 
    .. code-block:: bash
 
-      apptainer build spinnaker-apptainer.sif spinnaker-apptainer.def 
+      apptainer build spinnaker-apptainer.sif spinnaker-apptainer.def
       apptainer overlay create --size 4096 spinnaker-overlay.img
 
+   Note that for now, the sPyNNaker codebase needs to be manually edited to remove the checks in ``/home/spinnaker/source/sPyNNaker/neural_modelling/makefiles/synapse_only/synapse_build.mk`` on lines 99-104 (see https://github.com/SpiNNakerManchester/sPyNNaker/pull/1679):
+
+   .. code-block::
+
+      diff --git a/neural_modelling/makefiles/synapse_only/synapse_build.mk b/neural_modelling/makefiles/synapse_only/synapse_build.mk
+      index b6bfaffa29..004250ecff 100644
+      --- a/neural_modelling/makefiles/synapse_only/synapse_build.mk
+      +++ b/neural_modelling/makefiles/synapse_only/synapse_build.mk
+      @@ -96,12 +96,6 @@ else
+         ifneq ($(SYNAPSE_DYNAMICS), $(SYNAPSE_DYNAMICS_STATIC))
+               STDP_ENABLED = 1
+
+      -        ifndef TIMING_DEPENDENCE_H
+      -            $(error TIMING_DEPENDENCE_H is not set which is required when SYNAPSE_DYNAMICS ($(SYNAPSE_DYNAMICS_C)) != $(SYNAPSE_DYNAMICS_STATIC))
+      -        endif
+      -        ifndef WEIGHT_DEPENDENCE_H
+      -            $(error WEIGHT_DEPENDENCE_H is not set which is required when SYNAPSE_DYNAMICS ($(SYNAPSE_DYNAMICS_C)) != $(SYNAPSE_DYNAMICS_STATIC))
+      -        endif
+         endif
+      endif
+
+      @@ -205,8 +199,10 @@ endif
+
+      #STDP Build rules If and only if STDP used
+      ifeq ($(STDP_ENABLED), 1)
+      -    STDP_INCLUDES:= -include $(WEIGHT_DEPENDENCE_H) -include $(TIMING_DEPENDENCE_H)
+      -    STDP_COMPILE = $(CC) -DLOG_LEVEL=$(PLASTIC_DEBUG) $(CFLAGS) -DSTDP_ENABLED=$(STDP_ENABLED) -DSYNGEN_ENABLED=$(SYNGEN_ENABLED) $(STDP_INCLUDES)
+
+      +    #STDP_INCLUDES:= -include $(WEIGHT_DEPENDENCE_H) -include $(TIMING_DEPENDENCE_H)
+      +    #STDP_INCLUDES:= -include $(WEIGHT_DEPENDENCE_H) -include $(TIMING_DEPENDENCE_H)
+      +    #STDP_COMPILE = $(CC) -DLOG_LEVEL=$(PLASTIC_DEBUG) $(CFLAGS) -DSTDP_ENABLED=$(STDP_ENABLED) -DSYNGEN_ENABLED=$(SYNGEN_ENABLED) $(STDP_INC
+      LUDES)
+      +    STDP_COMPILE = $(CC) -DLOG_LEVEL=$(PLASTIC_DEBUG) $(CFLAGS) -DSTDP_ENABLED=$(STDP_ENABLED) -DSYNGEN_ENABLED=$(SYNGEN_ENABLED)
+
+         $(SYNAPSE_DYNAMICS_O): $(SYNAPSE_DYNAMICS_C)
+            # SYNAPSE_DYNAMICS_O stdp
+
 3. Run the Apptainer image:
 
    .. code-block:: bash
@@ -61,6 +101,22 @@ Generating code
 
       PYTHONPATH=$HOME/nestml/spinnaker-install python3 -m pytest -s --pdb ./tests/spinnaker_tests/test_spinnaker_iaf_psc_exp.py
 
+Optionally, create a little helper script to run the test anew (replace ``USERNAME`` with your username):
+
+.. code-block:: bash
+
+   #!/bin/bash
+
+   cd $HOME/nestml
+
+   mv -v /users/USERNAME/nestml/spinnaker-target /users/USERNAME/nestml/spinnaker-target-$(date +%Y-%m-%d_%H-%M-%S.%N | cut -b1-23)
+   mv -v /users/USERNAME/nestml/spinnaker-install /users/USERNAME/nestml/spinnaker-install-$(date +%Y-%m-%d_%H-%M-%S.%N | cut -b1-23)
+
+   # need to create this directory first, otherwise it gets ignored in the PYTHONPATH!
+   mkdir /users/USERNAME/nestml/spinnaker-install
+
+   PATH=$PATH:/users/USERNAME/.local/bin PYTHONPATH=/users/USERNAME/nestml/spinnaker-install:$PYTHONPATH python3 -m pytest  -o log_cli=true -o log_cli_level="DEBUG" -s --pdb /home/nestml/tests/spinnaker_tests/test_spinnaker_iaf_psc_exp.py
+
 
 Data types
 ^^^^^^^^^^
@@ -69,6 +125,53 @@ Data types
 - The NESTML data type ``integer`` will be rendered as ``int32_t``.
 
 
+Code generation for synapses
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Synaptic and neuronal models should ideally be formulated independently of each other, so that each neuron can be combined with each synapse for maximum flexibility. When a synaptic plasticity rule (such as STDP) is formulated as a computational model, the plasticity rule is often expressed as a function of the timing of pre- and postsynaptic spikes, which are used in the dynamics of the weight update for that particular rule. Note that as each neuron is typically connected to hundreds or thousands of other neurons via synapses on its axon, each of those synapses will observe the same presynaptic spike times, and store and numerically integrate them in exactly the same way, causing a very large redundancy in memory and computation.
+
+To prevent this redundancy, these values should only be stored and computed once. To achieve this, during code generation, state variables that depend only on presynaptic spike timing are automatically identified and moved from the NESTML synapse model into a header section in the synaptic row by the toolchain. In the generated code, at the points where the respective variables are used by the synapse (for instance, where they are used in calculating the change in synaptic strength), the variable references are replaced by function calls into the necessary memory space (more precisely, the header words at the start of each row). All parameters that are only used by these presynaptic dynamics (for instance, time constants) are also moved to reduce the memory requirements for the synapse. Detecting and moving the state, parameters, and dynamics (ODEs) from synapse to neuron is carried out fully autonomously. We refer to this feature as the "co-generation" of neuron and synapse. It enables flexibility and separation of concerns in the model formalisations without compromising on performance.
+
+When NESTML is invoked to generate code for plastic synapses, the (neuron, synapse) pairs can be specified as a list of two-element dictionaries of the form :code:`{"neuron": "neuron_model_name", "synapse": "synapse_model_name"}`. Additionally, if the synapse requires it, specify the ``"post_ports"`` entry to connect the postsynaptic spiking input port on the synapse with the postsynaptic neuron. For example:
+
+.. code-block:: python
+
+   generate_target(...,
+                   codegen_opts={...,
+                                 "neuron_synapse_pairs": [{"neuron": "iaf_psc_exp_neuron",
+                                                           "synapse": "stdp_synapse"
+                                                           "post_ports": ["post_spikes"]}]})
+
+
+Use cases/examples
+~~~~~~~~~~~~~~~~~~
+
+Ignore-and-fire neuron
+^^^^^^^^^^^^^^^^^^^^^^
+
+...
+
+
+STDP synapse
+^^^^^^^^^^^^
+
+Additive STDP model.
+
+.. figure:: https://raw.githubusercontent.com/nest/nestml/master/doc/running/running_spinnaker_figs/stdp_window.png
+   :alt: Comparison between STDP window functions based on SpiNNaker simulation (orange crosses) and hand-coded Python "ground truth" simulation.
+
+
+Troubleshooting
+~~~~~~~~~~~~~~~
+
+The build process and simulation produce many log messages, so it can be hard to find the reason for a failing build.
+
+::
+   /home/dev/gcc-arm-none-eabi-10.3-2021.10/bin/../lib/gcc/arm-none-eabi/10.3.1/../../../../arm-none-eabi/bin/ld: /users/.../nestml/spinnaker-install/c_models/build/iaf_psc_exp_neuron_nestml_impl/iaf_psc_exp_neuron_nestml_impl.elf section `RO_DATA' will not fit in region `ITCM'
+
+This error means that the compiled code does not fit into the ITCM memory. Typically this is due to too many logging statements; try commenting out logging statements.
+
+
 Further reading
 ~~~~~~~~~~~~~~~
 
@@ -78,6 +181,6 @@ Levin Schmidt, "Extension of the NEST Modelling Language to the SpiNNaker Archit
 References
 ~~~~~~~~~~
 
-.. [Mah92] M. Mahowald. VLSI analogs of neuronal visual processing: a synthesis of form and function. 1992
+.. [Mah92] M. Mahowald. VLSI analogs of neuronal visual processing: a synthesis of form and function. California Institute of Technology, 1992
 
-.. [FB20] S. Furber and P. Bogdan. SpiNNaker: A Spiking Neural Network Architecture. Boston-Delft: now publishers, 2020
+.. [FB20] S. Furber and P. Bogdan. SpiNNaker: A Spiking Neural Network Architecture. Emerald Publishing Limited, 2020

extras/q15.16_to_string.c

@@ -0,0 +1,104 @@
+#include <stdio.h>
+#include <stdlib.h>
+#include <stdint.h>
+#include <string.h>
+
+/**
+ * @brief Converts a 32-bit Q15.16 fixed-point number to a decimal string.
+ *
+ * This function extracts the sign, integer, and fractional parts of the Q15.16
+ * number without using floating-point arithmetic. It then constructs a string
+ * representation.
+ *
+ * @param q_num The 32-bit Q15.16 fixed-point number.
+ * @param buffer A character buffer to store the resulting string.
+ * @param buffer_size The size of the buffer.
+ */
+void q15_16_to_string(int32_t q_num, char *buffer, size_t buffer_size) {
+    if (buffer == NULL || buffer_size == 0) {
+        return;
+    }
+
+    // Determine the sign and work with the absolute value for calculations.
+    // The sign bit is the MSB (bit 31)
+    int is_negative = (q_num < 0);
+    if (is_negative) {
+        q_num = -q_num;
+    }
+
+    // Extract the integer part by right-shifting by 16 bits.
+    // The integer part occupies bits 16 to 30 (15 bits)
+    int32_t integer_part = q_num >> 16;
+
+    // Extract the fractional part by masking the lower 16 bits.
+    // The fractional part occupies bits 0 to 15 (16 bits)
+    int32_t fractional_part = q_num & 0xFFFF;
+
+    // To convert the fractional part to a decimal string without floats, we
+    // treat it as a fraction of 2^16 (65536).
+    // For example, if the fractional part is 32768, the value is 32768/65536 = 0.5.
+    // To get a decimal string with, say, 5 digits, we multiply by 10^5 and
+    // then divide by 65536, using a 64-bit integer to avoid overflow.
+    // The fractional part will be (fractional_part * 100000) / 65536.
+    int64_t decimal_fraction = ((int64_t)fractional_part * 100000 + 32768) >> 16;
+    // We add 32768 (0.5 * 65536) for rounding before the bit shift, which is
+    // equivalent to division. This is a common fixed-point rounding technique.
+
+    // Start printing the string.
+    char *ptr = buffer;
+    if (is_negative) {
+        *ptr++ = '-';
+    }
+
+    // Print the integer part.
+    ptr += snprintf(ptr, buffer_size - (ptr - buffer), "%d.", integer_part);
+
+    // Print the fractional part with leading zeros to maintain precision.
+    snprintf(ptr, buffer_size - (ptr - buffer), "%05lld", (long long)decimal_fraction);
+}
+
+/**
+ * @brief Main function to demonstrate the conversion.
+ */
+int main() {
+    // Test cases for various Q15.16 numbers
+    // 1. A positive number: 10.5
+    //    10 << 16 = 655360
+    //    0.5 * 2^16 = 0.5 * 65536 = 32768 = 0x8000
+    //    10.5 = (10 << 16) + 32768 = 688128 = 0xA8000
+    int32_t q_positive = 688128;
+
+    // 2. A negative number: -2.75
+    //    2 << 16 = 131072
+    //    0.75 * 2^16 = 0.75 * 65536 = 49152 = 0xC000
+    //    -2.75 = - (131072 + 49152) = -180224 = -0x2C000
+    int32_t q_negative = -180224;
+
+    // 3. A small number: 0.001
+    //    0.001 * 2^16 = 0.001 * 65536 = 65.536 -> round to 66
+    int32_t q_small = 66;
+
+    // 4. A large number: 30000.12345
+    //    30000 << 16 = 1966080000
+    //    0.12345 * 2^16 = 8090.88 -> round to 8091 = 0x1F9B
+    //    1966080000 + 8091 = 1966088091 = 0x75231F9B
+    int32_t q_large = 1966088091;
+
+    // Buffer to hold the resulting strings
+    char result_buffer[50];
+
+    // Convert and print each number
+    q15_16_to_string(q_positive, result_buffer, sizeof(result_buffer));
+    printf("Q15.16 value 0x%X -> %s\n", q_positive, result_buffer);
+
+    q15_16_to_string(q_negative, result_buffer, sizeof(result_buffer));
+    printf("Q15.16 value 0x%X -> %s\n", q_negative, result_buffer);
+
+    q15_16_to_string(q_small, result_buffer, sizeof(result_buffer));
+    printf("Q15.16 value 0x%X -> %s\n", q_small, result_buffer);
+
+    q15_16_to_string(q_large, result_buffer, sizeof(result_buffer));
+    printf("Q15.16 value 0x%X -> %s\n", q_large, result_buffer);
+
+    return 0;
+}