Adding back externally defined constant dendritic delays and other small features and fixes for the compartmental feature. [WIP]

doc/running/running_nest_compartmental.rst

@@ -19,7 +19,7 @@ Writing a compartmental NESTML model
 Defining the membrane potential variable
 ----------------------------------------
 
-One variable in the model represents the local membrane potential in a compartment. By default, it is called ``v_comp``. (This name is defined in the compartmental code generator options as the ``compartmental_variable_name`` option.). This variable needs to be defined as a state in any compartmental model to be referenced in the equations describing channels and synapses.
+One variable in the model represents the local membrane potential in a compartment. By default, it is called ``v_comp``. (This name is defined in the compartmental code generator options as the ``compartmental_variable_name`` option.) This variable needs to be defined as a state in any compartmental model to be referenced in the equations describing channels and receptors.
 
 .. code-block:: nestml
 
@@ -113,12 +113,12 @@ The only difference here is that the equation that is marked with the ``@mechani
 
 For a complete example, please see `concmech.nestml <https://github.com/nest/nestml/blob/master/tests/nest_compartmental_tests/resources/concmech.nestml>`_ and its associated unit test, `test__concmech_model.py <https://github.com/nest/nestml/blob/master/tests/nest_compartmental_tests/test__concmech_model.py>`_.
 
-Synapse description
+Receptor description
 -------------------
 
-Here synapse models are based on convolutions over a buffer of incoming spikes. This means that the equation for the
+Here receptor models are based on convolutions over a buffer of incoming spikes. This means that the equation for the
 current-contribution must contain a convolve() call and a description of the kernel used for that convolution is needed.
-The descriptor for synapses is ``@mechanism::receptor``.
+The descriptor for receptors is ``@mechanism::receptor``.
 
 .. code-block:: nestml
 
@@ -160,8 +160,29 @@ For a complete example, please see `continuous_test.nestml <https://github.com/n
 Mechanism interdependence
 -------------------------
 
-Above examples of explicit interdependence inbetween concentration and channel models where already described. Note that it is not necessary to describe the basic interaction inherent through the contribution to the overall current of the compartment. During a simulation step all currents of channels and synapses are added up and contribute to the change of the membrane potential (v_comp) in the next timestep. Thereby one must only express a dependence explicitly if the mechanism depends on the activity of a specific channel- or synapse-type amongst multiple in a given compartment or some concentration.
+Above examples of explicit interdependence inbetween concentration and channel models were already described. Note that it is not necessary to describe the basic interaction inherent through the contribution to the overall current of the compartment. During a simulation step all currents of channels and receptors are added up and contribute to the change of the membrane potential (v_comp) in the next timestep. Thereby one must only express a dependence explicitly if the mechanism depends on the activity of a specific channel- or receptor-type amongst multiple in a given compartment or some concentration.
 
+General compartment scripting
+-----------------------------
+Update block
+~~~~~~~~~~~~~
+Even though the intended focus of the compartmental feature is the usage of the above mechanisms whose influence on the compartment and overall neurons is implicit, it is still possible to use the ``update`` block. The ``update`` block does not control the overall behaviour of the neuron but its computation may support the behaviour of mechanisms within a compartment. All states occuring inside of the ``update`` block or within the called functions and inlines etc. become part of a general computation block that is always executed once for each compartment. These states may be used by the mechanisms. The ODEs owned by the update block are still integrated automatically and ``integrate_odes()`` shall not be used in this context.
+
+onReceive(self_spikes)
+~~~~~~~~~~~~~~~~~~~~~~~
+We also introduce a new special case of the ``onReceive`` block with the compartmental feature-specific variable ``self_spikes``, which is just a boolean that is true if and only if the neuron has spiked in the last timestep. The code within this block is only executed if the neuron spikes (somatic). Otherwise, the same rules as for the ``update`` block apply.
+
+Application
+~~~~~~~~~~~~
+This feature has been implemented with the implementation of IAF behaviour or backpropagation in mind. For examples see these model files:
+`cm_iaf_psc_exp_dend_neuron.nestml <https://github.com/nest/nestml/blob/master/tests/nest_compartmental_tests/resources/cm_iaf_psc_exp_dend_neuron.nestml>`_
+
+Synapses
+--------
+We have also changed the way synapses may interact with the neuron. The background to this is that NESTML STDP-synapse models are always co-generated with the postsynaptic neuron model to communicate certain variables, such as the postsynaptic spike trace. We found this to be insufficient; instead, the synapse models are fully integrated with the receptor mechanisms of the neuron. This enables the user to access any receptor variables and other mechanism values within the synapse model by simply declaring them as states in the synapse model, without requiring further assignments. Another result of this merge is that all ODE equations in the synapse model are implicitly continuously integrated at each timestep, making unnecessary the calls to integrate_odes().
+
+An example of such a model is implemented here:
+`third_factor_stdp_synapse.nestml <https://github.com/nest/nestml/blob/master/tests/nest_compartmental_tests/resources/third_factor_stdp_synapse.nestml>`_
 Technical Notes
 ---------------
 

pynestml/cocos/co_co_cm_channel_model.py

@@ -26,10 +26,10 @@
 
 class CoCoCmChannelModel(CoCo):
     @classmethod
-    def check_co_co(cls, model: ASTModel):
+    def check_co_co(cls, model: ASTModel, global_info):
         """
         Checks if this compartmental condition applies to the handed over neuron.
         If yes, it checks the presence of expected functions and declarations.
         :param model: a single neuron instance.
         """
-        return ChannelProcessing.check_co_co(model)
+        return ChannelProcessing.check_co_co(model, global_info)

pynestml/cocos/co_co_cm_concentration_model.py

@@ -27,10 +27,10 @@
 class CoCoCmConcentrationModel(CoCo):
 
     @classmethod
-    def check_co_co(cls, model: ASTModel):
+    def check_co_co(cls, model: ASTModel, global_info):
         """
         Check if this compartmental condition applies to the handed over neuron.
         If yes, it checks the presence of expected functions and declarations.
         :param model: a single neuron instance.
         """
-        return ConcentrationProcessing.check_co_co(model)
+        return ConcentrationProcessing.check_co_co(model, global_info)

pynestml/cocos/co_co_cm_continuous_input_model.py

@@ -26,11 +26,11 @@
 
 class CoCoCmContinuousInputModel(CoCo):
     @classmethod
-    def check_co_co(cls, neuron: ASTModel):
+    def check_co_co(cls, neuron: ASTModel, global_info):
         """
         Checks if this compartmental condition applies to the handed over neuron.
         If yes, it checks the presence of expected functions and declarations.
         :param neuron: a single neuron instance.
         :type neuron: ast_neuron
         """
-        return ContinuousInputProcessing.check_co_co(neuron)
+        return ContinuousInputProcessing.check_co_co(neuron, global_info)

pynestml/cocos/co_co_cm_global.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+#
+# co_co_cm_global.py
+#
+# This file is part of NEST.
+#
+# Copyright (C) 2004 The NEST Initiative
+#
+# NEST is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# NEST is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with NEST.  If not, see <http://www.gnu.org/licenses/>.
+
+from pynestml.cocos.co_co import CoCo
+from pynestml.meta_model.ast_model import ASTModel
+from pynestml.utils.global_processing import GlobalProcessing
+
+
+class CoCoCmGlobal(CoCo):
+    @classmethod
+    def check_co_co(cls, neuron: ASTModel):
+        """
+        Checks if this compartmental condition applies to the handed over neuron.
+        If yes, it checks the presence of expected functions and declarations.
+        :param neuron: a single neuron instance.
+        :type neuron: ast_neuron
+        """
+        return GlobalProcessing.check_co_co(neuron)

pynestml/cocos/co_co_cm_mech_shared_code.py

@@ -0,0 +1,55 @@
+# -*- coding: utf-8 -*-
+#
+# co_co_cm_mech_shared_code.py
+#
+# This file is part of NEST.
+#
+# Copyright (C) 2004 The NEST Initiative
+#
+# NEST is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# NEST is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with NEST.  If not, see <http://www.gnu.org/licenses/>.
+
+from pynestml.cocos.co_co import CoCo
+from pynestml.utils.logger import LoggingLevel, Logger
+from pynestml.utils.messages import Messages
+from pynestml.utils.channel_processing import ChannelProcessing
+from pynestml.utils.concentration_processing import ConcentrationProcessing
+from pynestml.utils.receptor_processing import ReceptorProcessing
+from pynestml.utils.continuous_input_processing import ContinuousInputProcessing
+from pynestml.meta_model.ast_model import ASTModel
+
+
+class CoCoCmMechSharedCode(CoCo):
+    @classmethod
+    def check_co_co(cls, model: ASTModel):
+        chan_info = ChannelProcessing.get_mechs_info(model)
+        conc_info = ConcentrationProcessing.get_mechs_info(model)
+        rec_info = ReceptorProcessing.get_mechs_info(model)
+        con_in_info = ContinuousInputProcessing.get_mechs_info(model)
+
+        used_vars = dict()
+        all_info = chan_info | conc_info | rec_info | con_in_info
+        for info_name, info in all_info.items():
+            all_vars = list(set(info['States'].keys()) | set(info["Parameters"].keys()) | set(
+                info["Internals"].keys()))  # + [e.get_name() for e in info["Dependencies"]["global"]]
+            for var in all_vars:
+                if var not in used_vars.keys():
+                    used_vars[var] = list()
+                used_vars[var].append(info_name)
+
+        for var_name, var in used_vars.items():
+            if len(var) > 1:
+                code, message = Messages.cm_shared_variables_not_allowed(var_name, var)
+                Logger.log_message(error_position=None,
+                                   code=code, message=message,
+                                   log_level=LoggingLevel.ERROR)

pynestml/cocos/co_co_cm_receptor_model.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+#
+# co_co_cm_receptor_model.py
+#
+# This file is part of NEST.
+#
+# Copyright (C) 2004 The NEST Initiative
+#
+# NEST is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# NEST is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with NEST.  If not, see <http://www.gnu.org/licenses/>.
+
+from pynestml.cocos.co_co import CoCo
+from pynestml.meta_model.ast_model import ASTModel
+from pynestml.utils.receptor_processing import ReceptorProcessing
+
+
+class CoCoCmReceptorModel(CoCo):
+
+    @classmethod
+    def check_co_co(cls, model: ASTModel, global_info):
+        """
+        Checks if this compartmental condition applies to the handed over neuron.
+        If yes, it checks the presence of expected functions and declarations.
+        :param model: a single neuron instance.
+        """
+        return ReceptorProcessing.check_co_co(model, global_info)

pynestml/cocos/co_co_cm_synapse_model.py

@@ -31,6 +31,6 @@ def check_co_co(cls, model: ASTModel):
         """
         Checks if this compartmental condition applies to the handed over neuron.
         If yes, it checks the presence of expected functions and declarations.
-        :param model: a single neuron instance.
+        :param model: a single synapse instance.
         """
         return SynapseProcessing.check_co_co(model)

pynestml/cocos/co_co_v_comp_exists.py

@@ -49,6 +49,9 @@ def check_co_co(cls, neuron: ASTModel):
         if not FrontendConfiguration.get_target_platform().upper() == 'NEST_COMPARTMENTAL':
             return
 
+        if not isinstance(neuron, ASTModel):
+            return
+
         enforced_variable_name = NESTCompartmentalCodeGenerator._default_options["compartmental_variable_name"]
 
         state_blocks = neuron.get_state_blocks()

pynestml/cocos/co_cos_manager.py

@@ -22,11 +22,11 @@
 from typing import Union
 
 from pynestml.cocos.co_co_all_variables_defined import CoCoAllVariablesDefined
+from pynestml.cocos.co_co_cm_global import CoCoCmGlobal
+from pynestml.cocos.co_co_cm_mech_shared_code import CoCoCmMechSharedCode
+from pynestml.cocos.co_co_cm_synapse_model import CoCoCmSynapseModel
 from pynestml.cocos.co_co_cm_channel_model import CoCoCmChannelModel
-from pynestml.cocos.co_co_cm_concentration_model import CoCoCmConcentrationModel
 from pynestml.cocos.co_co_cm_continuous_input_model import CoCoCmContinuousInputModel
-from pynestml.cocos.co_co_cm_synapse_model import CoCoCmSynapseModel
-from pynestml.cocos.co_co_convolve_has_correct_parameter import CoCoConvolveHasCorrectParameter
 from pynestml.cocos.co_co_convolve_cond_correctly_built import CoCoConvolveCondCorrectlyBuilt
 from pynestml.cocos.co_co_correct_numerator_of_unit import CoCoCorrectNumeratorOfUnit
 from pynestml.cocos.co_co_correct_order_in_equation import CoCoCorrectOrderInEquation
@@ -36,13 +36,11 @@
 from pynestml.cocos.co_co_function_calls_consistent import CoCoFunctionCallsConsistent
 from pynestml.cocos.co_co_function_unique import CoCoFunctionUnique
 from pynestml.cocos.co_co_illegal_expression import CoCoIllegalExpression
-from pynestml.cocos.co_co_input_port_not_assigned_to import CoCoInputPortNotAssignedTo
 from pynestml.cocos.co_co_integrate_odes_params_correct import CoCoIntegrateODEsParamsCorrect
 from pynestml.cocos.co_co_inline_expressions_have_rhs import CoCoInlineExpressionsHaveRhs
 from pynestml.cocos.co_co_inline_expression_not_assigned_to import CoCoInlineExpressionNotAssignedTo
 from pynestml.cocos.co_co_inline_max_one_lhs import CoCoInlineMaxOneLhs
 from pynestml.cocos.co_co_input_port_not_assigned_to import CoCoInputPortNotAssignedTo
-from pynestml.cocos.co_co_input_port_qualifier_unique import CoCoInputPortQualifierUnique
 from pynestml.cocos.co_co_internals_assigned_only_in_internals_block import CoCoInternalsAssignedOnlyInInternalsBlock
 from pynestml.cocos.co_co_integrate_odes_called_if_equations_defined import CoCoIntegrateOdesCalledIfEquationsDefined
 from pynestml.cocos.co_co_invariant_is_boolean import CoCoInvariantIsBoolean
@@ -61,6 +59,10 @@
 from pynestml.cocos.co_co_resolution_func_used import CoCoResolutionOrStepsFuncUsed
 from pynestml.cocos.co_co_simple_delta_function import CoCoSimpleDeltaFunction
 from pynestml.cocos.co_co_state_variables_initialized import CoCoStateVariablesInitialized
+from pynestml.cocos.co_co_convolve_has_correct_parameter import CoCoConvolveHasCorrectParameter
+from pynestml.cocos.co_co_cm_receptor_model import CoCoCmReceptorModel
+from pynestml.cocos.co_co_cm_concentration_model import CoCoCmConcentrationModel
+from pynestml.cocos.co_co_input_port_qualifier_unique import CoCoInputPortQualifierUnique
 from pynestml.cocos.co_co_timestep_function_legally_used import CoCoTimestepFuncLegallyUsed
 from pynestml.cocos.co_co_user_defined_function_correctly_defined import CoCoUserDefinedFunctionCorrectlyDefined
 from pynestml.cocos.co_co_v_comp_exists import CoCoVCompDefined
@@ -70,6 +72,7 @@
 from pynestml.cocos.co_co_vector_parameter_declared_in_right_block import CoCoVectorParameterDeclaredInRightBlock
 from pynestml.cocos.co_co_vector_variable_in_non_vector_declaration import CoCoVectorVariableInNonVectorDeclaration
 from pynestml.frontend.frontend_configuration import FrontendConfiguration
+from pynestml.utils.global_processing import GlobalProcessing
 from pynestml.meta_model.ast_model import ASTModel
 from pynestml.utils.logger import Logger
 
@@ -142,17 +145,25 @@ def check_v_comp_requirement(cls, neuron: ASTModel):
         CoCoVCompDefined.check_co_co(neuron)
 
     @classmethod
-    def check_compartmental_model(cls, neuron: ASTModel) -> None:
+    def check_compartmental_neuron_model(cls, neuron: ASTModel) -> None:
         """
         collects all relevant information for the different compartmental mechanism classes for later code-generation
 
         searches for inlines or odes with decorator @mechanism::<type> and performs a base and, depending on type,
         specific information collection process. See nestml documentation on compartmental code generation.
         """
-        CoCoCmChannelModel.check_co_co(neuron)
-        CoCoCmConcentrationModel.check_co_co(neuron)
-        CoCoCmSynapseModel.check_co_co(neuron)
-        CoCoCmContinuousInputModel.check_co_co(neuron)
+        cls.check_v_comp_requirement(neuron)
+        CoCoCmGlobal.check_co_co(neuron)
+        global_info = GlobalProcessing.get_global_info(neuron)
+        CoCoCmChannelModel.check_co_co(neuron, global_info)
+        CoCoCmConcentrationModel.check_co_co(neuron, global_info)
+        CoCoCmReceptorModel.check_co_co(neuron, global_info)
+        CoCoCmContinuousInputModel.check_co_co(neuron, global_info)
+        CoCoCmMechSharedCode.check_co_co(neuron)
+
+    @classmethod
+    def check_compartmental_synapse_model(cls, synapse: ASTModel) -> None:
+        CoCoCmSynapseModel.check_co_co(synapse)
 
     @classmethod
     def check_inline_expressions_have_rhs(cls, model: ASTModel):
@@ -428,7 +439,7 @@ def check_co_co_nest_random_functions_legally_used(cls, model: ASTModel):
         CoCoNestRandomFunctionsLegallyUsed.check_co_co(model)
 
     @classmethod
-    def check_cocos(cls, model: ASTModel, after_ast_rewrite: bool = False):
+    def check_cocos(cls, model: ASTModel, after_ast_rewrite: bool = False, syn_model: bool = False):
         """
         Checks all context conditions.
         :param model: a single model object.
@@ -443,8 +454,8 @@ def check_cocos(cls, model: ASTModel, after_ast_rewrite: bool = False):
         cls.check_variables_defined_before_usage(model)
         if FrontendConfiguration.get_target_platform().upper() == 'NEST_COMPARTMENTAL':
             # XXX: TODO: refactor this out; define a ``cocos_from_target_name()`` in the frontend instead.
-            cls.check_v_comp_requirement(model)
-            cls.check_compartmental_model(model)
+            if not syn_model:
+                cls.check_compartmental_neuron_model(model)
         cls.check_inline_expressions_have_rhs(model)
         cls.check_inline_has_max_one_lhs(model)
         cls.check_input_ports_not_assigned_to(model)