update documentations

Author: chaoming0625

docs/core_concept/brainpy_dynamical_system.ipynb

@@ -21,7 +21,7 @@
   {
    "cell_type": "markdown",
    "source": [
-    "BrainPy supports models in brain simulation and brain-inspired computing.\n",
+    "BrainPy supports modelings in brain simulation and brain-inspired computing.\n",
     "\n",
     "All these supports are based on one common concept: **Dynamical System** via ``brainpy.DynamicalSystem``.\n",
     "\n",
@@ -71,7 +71,26 @@
   {
    "cell_type": "markdown",
    "source": [
-    "All models used in brain simulation and brain-inspired computing is ``DynamicalSystem``.\n",
+    "All models used in brain simulation and brain-inspired computing is ``DynamicalSystem``.\n"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "```{note}\n",
+    "``DynamicalSystem`` is a subclass of ``BrainPyOject``. Therefore it supports to use [object-oriented transformations](./brainpy_transform_concept.ipynb) as stated in the previous tutorial.\n",
+    "```"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
     "\n",
     "A ``DynamicalSystem`` defines the updating rule of the model at single time step.\n",
     "\n",
@@ -117,14 +136,20 @@
     "\n",
     "First, *all ``DynamicalSystem`` should implement ``.update()`` function*, which receives two arguments:\n",
     "\n",
+    "```\n",
+    "class YourModel(bp.DynamicalSystem):\n",
+    "  def update(self, s, x):\n",
+    "    pass\n",
+    "```\n",
+    "\n",
     "- `s` (or named as others): A dict, to indicate shared arguments across all nodes/layers in the network, like\n",
     "    - the current time ``t``, or\n",
     "    - the current running index ``i``, or\n",
     "    - the current time step ``dt``, or\n",
     "    - the current phase of training or testing ``fit=True/False``.\n",
     "- `x` (or named as others): The individual input for this node/layer.\n",
     "\n",
-    "We call `s` as shared arguments because they are shared and same for all nodes/layers at current time step. On the contrary, different nodes/layers have different input `x`."
+    "We call `s` as shared arguments because they are same and shared for all nodes/layers. On the contrary, different nodes/layers have different input `x`."
    ],
    "metadata": {
     "collapsed": false
@@ -180,7 +205,7 @@
     "  def update(self, s, x):\n",
     "    # define how the model states update\n",
     "    # according to the external input\n",
-    "    t, dt = s.get('t'), s.get('dt', bm.dt)\n",
+    "    t, dt = s.get('t'), s.get('dt')\n",
     "    V = self.integral(self.V, t, x, dt=dt)\n",
     "    spike = V >= self.V_th\n",
     "    self.V.value = bm.where(spike, self.V_rest, V)\n",
@@ -198,9 +223,9 @@
     "\n",
     "Second, **explicitly consider which computing mode your ``DynamicalSystem`` supports**.\n",
     "\n",
-    "Brain simulation usually constructs models without batching dimension (we refer to it as *non-batching mode*, as seen in above LIF model), while brain-inspired computation trains models with a batch of data (*batching mode* or *training mode*).\n",
+    "Brain simulation usually builds models without batching dimension (we refer to it as *non-batching mode*, as seen in above LIF model), while brain-inspired computation trains models with a batch of data (*batching mode* or *training mode*).\n",
     "\n",
-    "So, to write a model applicable to the abroad applications in brain simulation and brain-inspired computing, you need to consider which mode your model supports, one of them, or both of them."
+    "So, to write a model applicable to abroad applications in brain simulation and brain-inspired computing, you need to consider which mode your model supports, one of them, or both of them."
    ],
    "metadata": {
     "collapsed": false
@@ -213,13 +238,13 @@
     "\n",
     "When considering the computing mode, we can program a general LIF model for brain simulation and brain-inspired computing.\n",
     "\n",
-    "To overcome the non-differential property of the spike in the LIF model for brain simulation, for the code\n",
+    "To overcome the non-differential property of the spike in the LIF model for brain simulation, i.e., at the code of\n",
     "\n",
     "```python\n",
     "spike = V >= self.V_th\n",
     "```\n",
     "\n",
-    "LIF models used in brain-inspired computing calculate the spiking state using the surrogate gradient function, i.e., replacing the backward gradient with a smooth function, like\n",
+    "LIF models used in brain-inspired computing calculate the spiking state using the surrogate gradient function. Usually, we replace the backward gradient of the spike with a smooth function, like\n",
     "\n",
     "$$\n",
     "g'(x) = \\frac{1}{(\\alpha * |x| + 1.) ^ 2}\n",
@@ -289,6 +314,15 @@
     "collapsed": false
    }
   },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "The following code snippet utilizes the LIF model to build an E/I balanced network ``EINet``, which is a classical network model in brain simulation."
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
   {
    "cell_type": "code",
    "execution_count": 21,
@@ -327,7 +361,7 @@
   {
    "cell_type": "markdown",
    "source": [
-    "Here the ``EINet`` defines an E/I balanced network which is a classical network model in brain simulation. The following ``AINet`` utilizes the LIF model to construct a model for AI training."
+    "Moreover, our LIF model can also be used in brain-inspired computing scenario. The following ``AINet`` uses the LIF model to construct a model for AI training."
    ],
    "metadata": {
     "collapsed": false
@@ -389,7 +423,7 @@
    "source": [
     "### 1. ``brainpy.math.for_loop``\n",
     "\n",
-    "``for_loop`` is a structural control flow API which runs a function with the looping over the inputs.\n",
+    "``for_loop`` is a structural control flow API which runs a function with the looping over the inputs. Moreover, this API just-in-time compile the looping process into the machine code.\n",
     "\n",
     "Suppose we have 200 time steps with the step size of 0.1, we can run the model with:"
    ],
@@ -430,9 +464,9 @@
   {
    "cell_type": "markdown",
    "source": [
-    "### 2. ``brainpy.DSRunner`` and ``brainpy.DSTrainer``\n",
+    "### 2. ``brainpy.DSRunner``\n",
     "\n",
-    "Another way to run the model in BrainPy is using the structural running object ``DSRunner`` and ``DSTrainer``. They provide more flexible way to monitoring the variables in a ``DynamicalSystem``.\n"
+    "Another way to run the model in BrainPy is using the structural running object ``DSRunner`` and ``DSTrainer``. They provide more flexible way to monitoring the variables in a ``DynamicalSystem``. The details users should refer to the [DSRunner tutorial](../tutorial_simulation/simulation_dsrunner.ipynb).\n"
    ],
    "metadata": {
     "collapsed": false

docs/core_concept/brainpy_transform_concept.ipynb

@@ -556,31 +556,6 @@
     "![](./imgs/grad_with_loss.png)"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "To inspect what OO transformations currently BrainPy supports, you can use"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 19,
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": "['grad',\n 'vector_grad',\n 'jacobian',\n 'jacrev',\n 'jacfwd',\n 'hessian',\n 'make_loop',\n 'make_while',\n 'make_cond',\n 'cond',\n 'ifelse',\n 'for_loop',\n 'while_loop',\n 'jit',\n 'to_object']"
-     },
-     "execution_count": 19,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "bm.object_transform.__all__"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},

docs/quickstart/analysis.ipynb

@@ -339,7 +339,7 @@
    "execution_count": 8,
    "outputs": [],
    "source": [
-    "class GJCoupledFHN(bp.dyn.DynamicalSystem):\n",
+    "class GJCoupledFHN(bp.DynamicalSystem):\n",
     "  def __init__(self, num=4, method='exp_auto'):\n",
     "    super(GJCoupledFHN, self).__init__()\n",
     "\n",
@@ -421,7 +421,7 @@
     "\n",
     "# simulation with an input\n",
     "Iext = bm.asarray([0., 0., 0., 0.6])\n",
-    "runner = bp.dyn.DSRunner(model, monitors=['V'], inputs=['Iext', Iext])\n",
+    "runner = bp.DSRunner(model, monitors=['V'], inputs=['Iext', Iext])\n",
     "runner.run(300.)\n",
     "\n",
     "# visualization\n",

docs/quickstart/training.ipynb

@@ -983,20 +983,18 @@
     "    self.num_out = num_out\n",
     "\n",
     "    # neuron groups\n",
-    "    self.i = bp.neurons.InputGroup(num_in, mode=bp.modes.training)\n",
-    "    self.r = bp.neurons.LIF(num_rec, tau=10, V_reset=0, V_rest=0, V_th=1., mode=bp.modes.training)\n",
-    "    self.o = bp.neurons.LeakyIntegrator(num_out, tau=5, mode=bp.modes.training)\n",
+    "    self.i = bp.neurons.InputGroup(num_in)\n",
+    "    self.r = bp.neurons.LIF(num_rec, tau=10, V_reset=0, V_rest=0, V_th=1.)\n",
+    "    self.o = bp.neurons.LeakyIntegrator(num_out, tau=5)\n",
     "\n",
     "    # synapse: i->r\n",
     "    self.i2r = bp.synapses.Exponential(self.i, self.r, bp.conn.All2All(), tau=10.,\n",
     "                                       output=bp.synouts.CUBA(target_var=None),\n",
-    "                                       g_max=bp.init.KaimingNormal(scale=20.),\n",
-    "                                       mode=bp.modes.training)\n",
+    "                                       g_max=bp.init.KaimingNormal(scale=20.))\n",
     "    # synapse: r->o\n",
     "    self.r2o = bp.synapses.Exponential(self.r, self.o, bp.conn.All2All(), tau=10.,\n",
     "                                       output=bp.synouts.CUBA(target_var=None),\n",
-    "                                       g_max=bp.init.KaimingNormal(scale=20.),\n",
-    "                                       mode=bp.modes.training)\n",
+    "                                       g_max=bp.init.KaimingNormal(scale=20.))\n",
     "\n",
     "    # whole model\n",
     "    self.model = bp.Sequential(self.i, self.i2r, self.r, self.r2o, self.o)\n",