Merge pull request #771 from apdavison/multisynapse3

Add "composed" models allowing multiple post-synaptic receptor types

Author: apdavison

doc/reference/neuronmodels.txt

@@ -15,7 +15,7 @@ backend simulator.
 .. note:: the development version has some support for specifying cell types
           using the NineML_ and NeuroML_ formats, but this is not yet available
           in the current release.
-   
+
 Standard cell types
 ===================
 
@@ -25,24 +25,33 @@ Standard cell types
   * :class:`IF_curr_alpha`
   * :class:`IF_cond_exp`
   * :class:`IF_cond_alpha`
-    
+
 * Integrate-and-fire with adaptation:
 
   * :class:`IF_cond_exp_gsfa_grr`
   * :class:`EIF_cond_alpha_isfa_ista`
-  * :class:`EIF_cond_exp_isfa_ista`    
+  * :class:`EIF_cond_exp_isfa_ista`
   * :class:`Izhikevich`
-    
+
 * Hodgkin-Huxley model
 
   * :class:`HH_cond_exp`
 
-* Spike sources (input neurons) 
+* Spike sources (input neurons)
 
   * :class:`SpikeSourcePoisson`
   * :class:`SpikeSourceArray`
   * :class:`SpikeSourceInhGamma`
 
+* Composed models:
+
+   * :class:`AdExp`
+   * :class:`LIF`
+   * :class:`~pyNN.standardmodels.receptors.CurrExpPostSynapticResponse`
+   * :class:`~pyNN.standardmodels.receptors.CondExpPostSynapticResponse`
+   * :class:`~pyNN.standardmodels.receptors.CondAlphaPostSynapticResponse`
+   * :class:`~pyNN.standardmodels.receptors.CondBetaPostSynapticResponse`
+
 
 Base class
 ----------
@@ -166,6 +175,51 @@ Spike sources
    .. autoattribute:: conductance_based
 
 
+Composed models
+---------------
+
+.. autoclass:: PointNeuron
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   .. autoattribute:: injectable
+   .. autoattribute:: conductance_based
+
+.. autoclass:: AdExp
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: LIF
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. currentmodule:: pyNN.standardmodels.receptors
+
+.. autoclass:: CurrExpPostSynapticResponse
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: CondExpPostSynapticResponse
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: CondAlphaPostSynapticResponse
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: CondBetaPostSynapticResponse
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
 Native cell types
 =================
 

doc/standardmodels.txt

@@ -29,7 +29,7 @@ Availability: NEST, NEURON, Brian
 ==============  =============  =====  ========================================
 Name            Default value  Units  Description
 ==============  =============  =====  ========================================
-``v_rest``      -65.0          mV     Resting membrane potential 
+``v_rest``      -65.0          mV     Resting membrane potential
 ``cm``            1.0          nF     Capacity of the membrane
 ``tau_m``        20.0          ms     Membrane time constant
 ``tau_refrac``    0.1          ms     Duration of refractory period
@@ -46,9 +46,9 @@ IF_curr_exp
 
 Leaky integrate and fire model with fixed threshold and decaying-exponential post-synaptic current.
 (Separate synaptic currents for excitatory and inhibitory synapses.
-    
+
 Availability: NEST, NEURON, Brian
-    
+
 ==============  =============  =====  =========================================
 Name            Default value  Units  Description
 ==============  =============  =====  =========================================
@@ -74,7 +74,7 @@ Availability: NEST, NEURON, Brian
 ==============  =============  =====  ===================================================
 Name            Default value  Units  Description
 ==============  =============  =====  ===================================================
-``v_rest``      -65.0          mV     Resting membrane potential 
+``v_rest``      -65.0          mV     Resting membrane potential
 ``cm``            1.0          nF     Capacity of the membrane
 ``tau_m``        20.0          ms     Membrane time constant
 ``tau_refrac``    0.1          ms     Duration of refractory period
@@ -92,12 +92,12 @@ IF_cond_exp
 -----------
 
 Leaky integrate and fire model with fixed threshold and decaying-exponential post-synaptic conductance.
-    
+
 Availability: NEST, NEURON, Brian
-    
+
 ==============  =============  =====  ===================================================
 Name            Default value  Units  Description
-==============  =============  =====  =================================================== 
+==============  =============  =====  ===================================================
 ``v_rest``      -65.0          mV     Resting membrane potential
 ``cm``            1.0          nF     Capacity of the membrane
 ``tau_m``        20.0          ms     Membrane time constant
@@ -109,19 +109,19 @@ Name            Default value  Units  Description
 ``v_thresh``    -50.0          mV     Spike threshold
 ``v_reset``     -65.0          mV     Reset potential after a spike
 ``i_offset``      0.0          nA     Offset current
-==============  =============  =====  =================================================== 
+==============  =============  =====  ===================================================
 
 
 HH_cond_exp
 -----------
 
 Single-compartment Hodgkin-Huxley-type neuron with transient sodium and delayed-rectifier potassium currents using the ion channel models from Traub.
-    
+
 Availability: NEST, NEURON, Brian
 
 ==============  =============  =====  ===================================================
 Name            Default value  Units  Description
-==============  =============  =====  =================================================== 
+==============  =============  =====  ===================================================
 ``gbar_Na``        20.0        uS
 ``gbar_K``          6.0        uS
 ``g_leak``         0.01        uS
@@ -135,21 +135,21 @@ Name            Default value  Units  Description
 ``tau_syn_E``       0.2        ms
 ``tau_syn_I``       2.0        ms
 ``i_offset``        0.0        nA
-==============  =============  =====  =================================================== 
+==============  =============  =====  ===================================================
 
 
 EIF_cond_alpha_isfa_ista
 ------------------------
 
-Adaptive exponential integrate and fire neuron according to 
+Adaptive exponential integrate and fire neuron according to
   Brette R and Gerstner W (2005) Adaptive Exponential Integrate-and-Fire Model as
   an Effective Description of Neuronal Activity. J Neurophysiol 94:3637-3642
 
 Availability: NEST, NEURON, Brian
 
 ==============  =============  =====  ===================================================
 Name            Default value  Units  Description
-==============  =============  =====  =================================================== 
+==============  =============  =====  ===================================================
 ``cm``            0.281        nF     Capacity of the membrane
 ``tau_refrac``    0.1          ms     Duration of refractory period
 ``v_spike``     -40.0          mV     Spike detection threshold
@@ -161,12 +161,33 @@ Name            Default value  Units  Description
 ``b``             0.0805       nA     Spike-triggered adaptation
 ``delta_T``       2.0          mV     Slope factor
 ``tau_w``       144.0          ms     Adaptation time constant
-``v_thresh``    -50.4          mV     Spike initiation threshold 
+``v_thresh``    -50.4          mV     Spike initiation threshold
 ``e_rev_E``       0.0          mV     Excitatory reversal potential
 ``tau_syn_E``     5.0          ms     Rise time of excitatory synaptic conductance (alpha function)
 ``e_rev_I``     -80.0          mV     Inhibitory reversal potential
 ``tau_syn_I``     5.0          ms     Rise time of the inhibitory synaptic conductance (alpha function)
-==============  =============  =====  =================================================== 
+==============  =============  =====  ===================================================
+
+
+Composed models
+===============
+
+The models listed above all have two fixed post-synaptic mechanism types, "excitatory" and "inhibitory".
+If you need more than two mechanisms, e.g. AMPA, NMDA and GABA_A, you can build such models by
+combining a "neuron-only" component with one or more "post-synaptic mechanism" components, for example:
+
+::
+
+   celltype = sim.PointNeuron(
+                sim.AdExp(tau_m=10.0, v_rest=-60.0),
+                AMPA=sim.ExpPSR(tau_syn=1.0, e_syn=0.0),
+                NMDA=sim.AlphaPSR(tau_syn=20.0, e_syn=0.0),
+                GABAA=sim.ExpPSR(tau_syn=1.5, e_syn=-70.0),
+                GABAB=sim.AlphaPSR(tau_syn=15.0, e_syn=-90.0))
+
+Not all simulators can handle all combinations of components, and in general it is not possible to
+mix conductance-based and current-based synapses within a single cell type.
+PyNN will emit an error message if this is the case.
 
 
 Spike sources

examples/monolith_vs_composed.py

@@ -0,0 +1,134 @@
+"""
+A demonstration of two different types of neuron model:
+    - "monolithic" (pre-defined synaptic receptor types)
+    - "composed" (the user can choose the synaptic receptor types)
+
+This example shows how to build a composed model that matches the
+built-in "IF_curr_exp" model, and also demonstrates one of the
+additional capabilities of the composed approach, the ability to record
+more of the state variables of the synapse model.
+
+Usage: monolith_vs_composed.py [-h] [--plot-figure] [--debug DEBUG] simulator
+
+positional arguments:
+  simulator      neuron, nest, brian2 or another backend simulator
+
+optional arguments:
+  -h, --help     show this help message and exit
+  --plot-figure  Plot the simulation results to a file.
+  --debug DEBUG  Print debugging information
+
+"""
+
+from datetime import datetime
+from pyNN.parameters import Sequence
+from pyNN.utility import get_simulator, init_logging, normalized_filename
+
+
+# === Configure the simulator ================================================
+
+sim, options = get_simulator(
+    (
+        "--plot-figure",
+        "Plot the simulation results to a file.",
+        {"action": "store_true"},
+    ),
+    ("--debug", "Print debugging information"),
+)
+
+if options.debug:
+    init_logging(None, debug=True)
+
+sim.setup(timestep=0.1, min_delay=1.0)
+
+
+# === Build and instrument the network =======================================
+
+celltype_monolith = sim.IF_curr_exp(
+    tau_m=10.0, v_rest=-60.0, tau_syn_E=1.0, tau_syn_I=2.0
+)
+
+celltype_composed = sim.PointNeuron(
+    sim.LIF(tau_m=10.0, v_rest=-60.0),
+    excitatory=sim.CurrExpPostSynapticResponse(tau_syn=1.0),
+    inhibitory=sim.CurrExpPostSynapticResponse(tau_syn=2.0),
+)
+
+neurons_monolith = sim.Population(1, celltype_monolith, initial_values={"v": -60.0})
+neurons_composed = sim.Population(1, celltype_composed, initial_values={"v": -60.0})
+
+neurons_monolith.record("v")
+neurons_composed.record(["v", "excitatory.isyn", "inhibitory.isyn"])
+
+neurons = neurons_monolith + neurons_composed
+
+inputs = sim.Population(
+    2,
+    sim.SpikeSourceArray(
+        spike_times=[
+            Sequence([30.0]),
+            Sequence([120.0]),
+        ]
+    ),
+)
+
+connections = {
+    "excitatory": sim.Projection(
+        inputs[0:1],
+        neurons,
+        sim.AllToAllConnector(),
+        synapse_type=sim.StaticSynapse(weight=0.5, delay=1.5),
+        receptor_type="excitatory",
+        label="exc",
+    ),
+    "inhibitory": sim.Projection(
+        inputs[1:2],
+        neurons,
+        sim.AllToAllConnector(),
+        synapse_type=sim.StaticSynapse(weight=-0.2, delay=1.5),
+        receptor_type="inhibitory",
+        label="inh",
+    ),
+}
+# === Run the simulation =====================================================
+
+sim.run(200.0)
+
+
+# === Save the results, optionally plot a figure =============================
+
+filename = "Results/monolith_vs_composed_{}.pkl".format(options.simulator)
+data = neurons.get_data().segments[0]
+
+if options.plot_figure:
+    from pyNN.utility.plotting import Figure, Panel
+
+    figure_filename = filename.replace("pkl", "png")
+    Figure(
+        Panel(
+            data.filter(name="v")[0],
+            xticks=False,
+            yticks=True,
+            ylabel="Membrane potential (mV)",
+        ),  # ylim=(-66, -48)),
+        Panel(
+            data.filter(name="excitatory.isyn")[0],
+            xticks=False,
+            yticks=True,
+            ylabel="Excitatory synaptic current (nA)",
+        ),
+        Panel(
+            data.filter(name="inhibitory.isyn")[0],
+            xticks=True,
+            yticks=True,
+            ylabel="Inhibitory synaptic current (nA)",
+            xlabel="Time (ms)"
+        ),
+        title="Comparing 'monolithic' and 'composed' neuron models",
+        annotations=f"Simulated with {options.simulator.upper()} at {datetime.now().isoformat()}",
+    ).save(figure_filename)
+    print(figure_filename)
+
+# === Clean up and quit ========================================================
+
+sim.end()