docs: add build_conn part in docs

Author: ztqakita

docs/tutorial_toolbox/synaptic_connections.ipynb

@@ -109,10 +109,45 @@
     "- `TwoEndConnector`: It has two input parameters `pre_size` and `post_size`, each representing the size of the pre- and post-synaptic neuron group. It will result in a connection matrix with the shape of (pre_num, post_num).\n",
     "- `OneEndConnector`: It has only one parameter `pre_size` which represent the size of the neuron group. It will result in a connection matrix with the shape of (pre_num, pre_num).\n",
     "\n",
-    "The `__call__` function returns the class itself.\n",
+    "The `__call__` function returns the class itself."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "### Connector.build_conn()\n",
+    "Users can customize the connection in `build_conn()` function. Notice there are three connection types users can provide:\n",
+    "| Connection Types | Definition |\n",
+    "| :- | :- |\n",
+    "| 'mat' | Dense conncetion, including a connection matrix. |\n",
+    "| 'ij' | Index projection, including a pre-neuron index vector and a post-neuron index vector. |\n",
+    "| 'csr' | Sparse connection, including a index vector and a indptr vector.  |\n",
+    "\n",
+    "Return type can be either a `dict` or a `tuple`. Here are two examples of how to return your connection data:\n",
+    "\n",
+    "Example 1：\n",
+    "```python\n",
+    "def build_conn(self):\n",
+    "  ind = np.arange(self.pre_num)\n",
+    "  indptr = np.arange(self.pre_num + 1)\n",
+    "\n",
+    "  return dict(csr=(ind, indptr), mat=None, ij=None)\n",
+    "```\n",
+    "\n",
+    "Example 2:\n",
+    "```python\n",
+    "def build_conn(self):\n",
+    "  ind = np.arange(self.pre_num)\n",
+    "  indptr = np.arange(self.pre_num + 1)\n",
+    "\n",
+    "  return 'csr', (ind, indptr)\n",
+    "```\n",
     "\n",
     "After creating the synaptic connection, users can use the `require()` method to access some useful properties of the connection."
-   ]
+   ],
+   "metadata": {
+    "collapsed": false
+   }
   },
   {
    "cell_type": "markdown",
@@ -2006,7 +2041,7 @@
     "\n",
     "- Your connection class should inherit from `brainpy.connect.TwoEndConnector` or `brainpy.connect.OneEndConnector`.\n",
     "- `__init__` function should be implemented and essential parameters should be initialized.\n",
-    "- Users should also overwrite `require()` function to describe how to build your connection. Remember in `require()` users have to call two built-in functions: `self.check(structures)` and `self.make_returns(structures, [csr, mat, ij])`.\n",
+    "- Users should also overwrite `build_conn()` function to describe how to build your connection.\n",
     "\n",
     "Let's take an example to illustrate the details of customization."
    ]
@@ -2038,20 +2073,17 @@
     "    self.seed = seed\n",
     "    self.rng = np.random.RandomState(seed=seed)\n",
     "\n",
-    "  def require(self, *structures):\n",
-    "    # please call this function for auto-checking inputs.\n",
-    "    self.check(structures)\n",
-    "\n",
+    "  def build_conn(self):\n",
     "    ind = []\n",
     "    count = np.zeros(self.pre_num, dtype=np.uint32)\n",
-    "    \n",
+    "\n",
     "    def _random_prob_conn(rng, pre_i, num_post, prob, include_self):\n",
     "      p = rng.random(num_post) <= prob\n",
     "      if (not include_self) and pre_i < num_post:\n",
     "        p[pre_i] = False\n",
     "      conn_j = np.asarray(np.where(p)[0], dtype=np.uint32)\n",
     "      return conn_j\n",
-    "    \n",
+    "\n",
     "    for i in range(self.pre_num):\n",
     "      posts = _random_prob_conn(self.rng, pre_i=i, num_post=self.post_num,\n",
     "                                prob=self.prob, include_self=self.include_self)\n",
@@ -2060,20 +2092,14 @@
     "\n",
     "    ind = np.concatenate(ind)\n",
     "    indptr = np.concatenate(([0], count)).cumsum()\n",
-    "    \n",
-    "    # please use this built-in function to auto-return all data structures you need.\n",
-    "    return self.make_returns(structures, csr=(ind, indptr))"
+    "\n",
+    "    return 'csr', (ind, indptr)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Users can customize the connection in `require()` function. And at last user will call `self.make_returns(structures, [csr, mat, ij])` function to automatically produce the structures in parameters. Notice there are also three optional parameters users can provide:\n",
-    "- csr: sparse connection, including a index vector and a indptr vector. \n",
-    "- mat: dense conncetion, including a connection matrix.\n",
-    "- ij: index projection, including a pre-neuron index vector and a post-neuron index vector.\n",
-    "\n",
     "Then users can initialize the your own connections as below:"
    ]
   },
@@ -2192,4 +2218,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}