cleaned up dyn-syn/lesson

Alexander Ororbia · Alexander Ororbia · commit 9e71263d87bc · 2025-04-28T12:20:47.000-04:00
diff --git a/docs/images/tutorials/neurocog/expsyn.jpg b/docs/images/tutorials/neurocog/expsyn.jpg
diff --git a/docs/museum/rl_snn.md b/docs/museum/rl_snn.md
@@ -13,9 +13,8 @@ exhibit can be found
 
 Operant conditioning refers to the idea that there are environmental stimuli that can either increase or decrease the occurrence of (voluntary) behaviors; in other words, positive stimuli can lead to future repeats of a certain behavior whereas negative stimuli can lead to (i.e., punish) a decrease in future occurences. Ultimately, operant conditioning, through consequences, shapes voluntary behavior where actions followed by rewards are repeated and actions followed by punished/negative outcomes diminish. 
 
-In this lesson, we will model very simple case of operant conditioning for a neuronal motor circuit used to engage in the navigation of a simple maze. The maze's design will be the rat T-maze and the "rat" will be allowed to move, at a particular point in the maze, in one of four directions (North, South, West, and East). A positive reward will be supplied to our rat neuronal circuit if it makes progress towards the direction of food (placed in the upper right corner of the T-maze) and a negative reward will be provided if fails to make progress/gets stuck, i.e., a dense reward functional will be employed.
-
-
+In this lesson, we will model very simple case of operant conditioning for a neuronal motor circuit used to engage in the navigation of a simple maze. 
+The maze's design will be the rat T-maze and the "rat" will be allowed to move, at a particular point in the maze, in one of four directions (North, South, West, and East). A positive reward will be supplied to our rat neuronal circuit if it makes progress towards the direction of food (placed in the upper right corner of the T-maze) and a negative reward will be provided if fails to make progress/gets stuck, i.e., a dense reward functional will be employed. For the exhibit code that goes with this lesson, an implementation of this T-maze environment is provided, modeled in the same style/with the same agent API as the OpenAI gymnasium. 
 
 ### Reward-Modulated Spike-Timing-Dependent Plasticity (R-STDP)
 
diff --git a/docs/tutorials/neurocog/dynamic_synapses.md b/docs/tutorials/neurocog/dynamic_synapses.md
@@ -20,14 +20,10 @@ response (as opposed to a chemical one, e.g., an influx of calcium), such models
 to emulate the time-course of what is known as post-synaptic receptor conductance. Note 
 that these dynamic synapse models will end being a bit more sophisticated than the strength
 value matrices we might initially employ (as in synapse components such as the 
-[DenseSynapse](ngclearn.components.synapses.DenseSynapse)).
-
-Building a dynamic synapse can be done by importing 
-[ExponentialSynapse](ngclearn.components.synapses.ExponentialSynapse) or  
-[AlphaSynapse](ngclearn.components.synapses.AlphaSynapse)
-from ngc-learn's in-built components and setting them up within a model 
-context for easy analysis. For the first part of this lesson, we will import 
-both of these and compare their behavior. 
+[DenseSynapse](ngclearn.components.synapses.denseSynapse)).
+
+Building a dynamic synapse can be done by importing [ExponentialSynapse](ngclearn.components.synapses.exponentialSynapse) or 
+[AlphaSynapse](ngclearn.components.synapses.alphaSynapse) from ngc-learn's in-built components and setting them up within a model context for easy analysis. For the first part of this lesson, we will import both of these and compare their behavior. 
 This can be done as follows (using the meta-parameters we provide in the 
 code block below to ensure reasonable dynamics):
 
@@ -49,8 +45,6 @@ dkey, *subkeys = random.split(dkey, 6)
 dt = 0.1 # ms ## integration time constant
 T = 8. # ms ## total duration time
 
-Tsteps = int(T/dt) + 1
-
 ## ---- build a dual-synapse system ----
 with Context("dual_syn_system") as ctx:
     Wexp = ExponentialSynapse( ## exponential dynamic synapse
@@ -107,10 +101,10 @@ Finally, we seek model the electrical current that results from some amount of n
 Thus, for both the exponential and the alpha synapse, the changes in conductance are finally converted (via Ohm's law) to electrical current to produce the final derived variable $j_{\text{syn}}(t)$:
 
 $$
-j_{\text{syn}}(t) = g_{\text{syn}}(t) (v(t) - E_{\text{rest}})
+j_{\text{syn}}(t) = g_{\text{syn}}(t) (v(t) - E_{\text{rev}})
 $$
 
-where $v_{\text{rest}$ (or $E_{\text{rest}}$) is the post-synaptic reverse potential of the ion channels that mediate the synaptic current; this is typically set to $E_{\text{rest}} = 0$ (millivolts; mV)for the case of excitatory changes and $E_{\text{rest}} = -75$ (mV) for the case of inhibitory changes. $v(t)$ is the voltage/membrane potential of the post-synaptic the synaptic cable wires to, meaning that the conductance models above are voltage-dependent (in ngc-learn, if you want voltage-independent conductance, then set `syn_rest = None`). 
+where $E_{\text{rev}}$ is the post-synaptic reverse potential of the ion channels that mediate the synaptic current; this is typically set to $E_{\text{rev}} = 0$ (millivolts; mV)for the case of excitatory changes and $E_{\text{rev}} = -75$ (mV) for the case of inhibitory changes. $v(t)$ is the voltage/membrane potential of the post-synaptic the synaptic cable wires to, meaning that the conductance models above are voltage-dependent (in ngc-learn, if you want voltage-independent conductance, then set `syn_rest = None`). 
 
 
 ### Examining the Conductances of Dynamic Synapses
@@ -121,6 +115,7 @@ To create the simulation of a single input pulse stream, you can write the follo
 ```python
 time_ticks = []
 time_labs = []
+Tsteps = int(T/dt) + 1
 for t in range(Tsteps):
     if t % 10 == 0:
         time_ticks.append(t)
@@ -194,11 +189,11 @@ expoential and alpha synapse conductance trajectories:
 .. table::
    :align: center
 
-   +---------------------------------------------------------+-----------------------------------------------------------+
-   | .. image:: ../docs/images/tutorials/neurocog/expsyn.jpg | .. image:: ../docs/images/tutorials/neurocog/alphasyn.jpg |
-   |   :width: 100px                                         |   :width: 100px                                           |
-   |   :align: center                                        |   :align: center                                          |
-   +---------------------------------------------------------+-----------------------------------------------------------+
+   +--------------------------------------------------------+----------------------------------------------------------+
+   | .. image:: ../../images/tutorials/neurocog/expsyn.jpg  | .. image:: ../../images/tutorials/neurocog/alphasyn.jpg  |
+   |   :width: 400px                                        |   :width: 400px                                          |
+   |   :align: center                                       |   :align: center                                         |
+   +--------------------------------------------------------+----------------------------------------------------------+
 ```
 
 Note that the alpha synapse (right figure) would produce a more realistic fit to recorded synaptic currents (as it attempts to model 
@@ -213,7 +208,7 @@ and often-used conductance model that is paired with spiking cells such as the l
 we seek to simulate the following post-synaptic conductance dynamics for a single LIF unit:
 
 $$
-\tau_{m} \frac{\partial v(t)}{\partial t} = -(v(t) - E_{L}) - \frac{g_{E}(t)}{g_{L}} (v(t) - E_{E}) - \frac{g_{I}(t)}{g_{L}} (v(t) - E_{I})
+\tau_{m} \frac{\partial v(t)}{\partial t} = -\big( v(t) - E_{L} \big) - \frac{g_{E}(t)}{g_{L}} \big( v(t) - E_{E} \big) - \frac{g_{I}(t)}{g_{L}} \big( v(t) - E_{I} \big)
 $$
 
 where $g_{L}$ is the leak conductance value for the post-synaptic LIF, $g_{E}(t)$ is the post-synaptic conductance produced by excitatory pre-synaptic spike trains (with excitatory synaptic reverse potential $E_{E}$), and $g_{I}(t)$ is the post-synaptic conductance produced by inhibitory pre-synaptic spike trains (with inhibitory synaptic reverse potential $E_{I}$). Note that the first term of the above ODE is the normal leak portion of the LIF's standard dynamics (scaled by conductance factor $g_{L}$) and the last two terms of the above ODE can be modeled each separately with a dynamic synapse. To differentiate between excitatory and inhibitory conductance changes, we will just configure a different reverse potential for each to induce either excitatory (i.e., $E_{\text{syn}} = E_{E} = 0$ mV) or inhibitory (i.e., $E_{\text{syn}} = E_{I} = -80$ mV) pressure/drive. 
@@ -364,10 +359,10 @@ voltage threshold.
 .. table::
    :align: center
 
-   +----------------------------------------------------------------------+
-   | .. image:: ../docs/images/tutorials/neurocog/ei_circuit_dynamics.jpg |
-   |   :width: 100px                                                      |
-   |   :align: center                                                     |
-   +----------------------------------------------------------------------+
+   +--------------------------------------------------------------------+
+   | .. image:: ../../images/tutorials/neurocog/ei_circuit_dynamics.jpg |
+   |   :width: 400px                                                    |
+   |   :align: center                                                   |
+   +--------------------------------------------------------------------+
 ```
 
diff --git a/docs/tutorials/neurocog/index.rst b/docs/tutorials/neurocog/index.rst
@@ -60,7 +60,7 @@ work towards more advanced concepts.
   :maxdepth: 1
   :caption: Synapses and Forms of Plasticity
 
-  synaptic_conductance
+  dynamic_synapses
   hebbian
   stdp
   mod_stdp
diff --git a/ngclearn/components/synapses/alphaSynapse.py b/ngclearn/components/synapses/alphaSynapse.py
@@ -97,6 +97,7 @@ def advance_state(
 
         dgsyn_dt = -g_syn/tau_syn + h_syn # or -g_syn/tau_syn + h_syn/tau_syn
         g_syn = g_syn + dgsyn_dt * dt ## run Euler step to move conductance g
+        g_syn = g_syn * Rscale
 
         i_syn = -g_syn
         if syn_rest is not None:
diff --git a/ngclearn/components/synapses/exponentialSynapse.py b/ngclearn/components/synapses/exponentialSynapse.py
@@ -92,6 +92,7 @@ def advance_state(
         _out = jnp.matmul(s, weights) ## sum all pre-syn spikes at t going into post-neuron)
         dgsyn_dt = -g_syn/tau_syn + _out * g_syn_bar
         g_syn = g_syn + dgsyn_dt * dt ## run Euler step to move conductance
+        g_syn = g_syn * Rscale
         i_syn = -g_syn
         if syn_rest is not None:
             i_syn =  -g_syn * (v - syn_rest)
diff --git a/ngclearn/utils/jaxProcess.py b/ngclearn/utils/jaxProcess.py
@@ -7,9 +7,9 @@
 
 class JaxProcess(Process):
     """
-    The JaxProcess is a subclass of the ngcsimlib Process class. The
-    functionality added by this subclass is the use of the jax scanner to run a
-    process quickly through the use of jax's JIT compiler.
+        The JaxProcess is a subclass of the ngcsimlib Process class. The
+        functionality added by this subclass is the use of the jax scanner to run a
+        process quickly through the use of jax's JIT compiler.
     """
 
     def __init__(self, name):
@@ -30,8 +30,9 @@ def _pure(current_state, x):
     def watch(self, compartment):
         """
         Adds a compartment to the process to watch during a scan
+
         Args:
-            compartment: The compartment to watch
+            compartment: the compartment to watch
         """
         if not isinstance(compartment, Compartment):
             warn(
@@ -51,12 +52,12 @@ def transition(self, transition_call):
         """
         Appends to the base transition call to create pure method for use by its
         scanner
-        Args:
-            transition_call: the transition being passed into the default
-                process
 
-        Returns: this JaxProcess instance for chaining
+        Args:
+            transition_call: the transition being passed into the default process
 
+        Returns:
+            this JaxProcess instance for chaining
         """
         super().transition(transition_call)
         self._process_scan_method = self._make_scanner()
@@ -93,10 +94,11 @@ def scan(self, save_state=True, scan_length=None, **kwargs):
 
 
         Args:
-            save_state: A boolean flag to indicate if the model state should be
-            saved
-            scan_length: a value to be used to denote the number of iterations
-            of the scanner if all keyword arguments are passed as ints or floats
+            save_state: A boolean flag to indicate if the model state should be saved
+
+            scan_length: a value to be used to denote the number of iterations of the scanner if all keyword
+                arguments are passed as ints or floats
+
             **kwargs: the required keyword arguments for the process to run
 
         Returns: the final state of the model, the stacked output of the scan method
