[update] Refine installation instructions and improve docstring formatting (#767)

* [update] Refine installation instructions and improve docstring formatting

* [update] Add note about BrainPy's rewrite based on brainstate

* [update] Remove redundant installation information from index

Author: chaoming0625

README.md

@@ -6,31 +6,28 @@
 
 <p align="center">
 	<a href="https://pypi.org/project/brainpy/"><img alt="Supported Python Version" src="https://img.shields.io/pypi/pyversions/brainpy"></a>
-	<a href="https://github.com/brainpy/BrainPy"><img alt="LICENSE" src="https://anaconda.org/brainpy/brainpy/badges/license.svg"></a>
+	<a href="https://github.com/brainpy/BrainPy"><img alt="LICENSE" src="https://img.shields.io/badge/license-%20%20GNU%20GPLv3%20-green?style=plastic"></a>
   	<a href="https://brainpy.readthedocs.io/en/latest/?badge=latest"><img alt="Documentation" src="https://readthedocs.org/projects/brainpy/badge/?version=latest"></a>
   	<a href="https://badge.fury.io/py/brainpy"><img alt="PyPI version" src="https://badge.fury.io/py/brainpy.svg"></a>
     <a href="https://github.com/brainpy/BrainPy/actions/workflows/CI.yml"><img alt="Continuous Integration" src="https://github.com/brainpy/BrainPy/actions/workflows/CI.yml/badge.svg"></a>
     <a href="https://github.com/brainpy/BrainPy/actions/workflows/CI-models.yml"><img alt="Continuous Integration with Models" src="https://github.com/brainpy/BrainPy/actions/workflows/CI-models.yml/badge.svg"></a>
 </p>
 
 
-BrainPy is a flexible, efficient, and extensible framework for computational neuroscience and brain-inspired computation based on the Just-In-Time (JIT) compilation (built on top of [JAX](https://github.com/google/jax), [Taichi](https://github.com/taichi-dev/taichi), [Numba](https://github.com/numba/numba), and others). It provides an integrative ecosystem for brain dynamics programming, including brain dynamics **building**, **simulation**, **training**, **analysis**, etc. 
+BrainPy is a flexible, efficient, and extensible framework for computational neuroscience and brain-inspired computation based on the Just-In-Time (JIT) compilation. It provides an integrative ecosystem for brain dynamics programming, including brain dynamics **building**, **simulation**, **training**, **analysis**, etc. 
 
-- **Website (documentation and APIs)**: https://brainpy.readthedocs.io/en/latest
+- **Website (documentation and APIs)**: https://brainpy.readthedocs.io/
 - **Source**: https://github.com/brainpy/BrainPy
 - **Bug reports**: https://github.com/brainpy/BrainPy/issues
 - **Ecosystem**: https://brainmodeling.readthedocs.io/
-- **Source on OpenI**: https://git.openi.org.cn/OpenI/BrainPy
 
 
+BrainPy now is rewritten based on [brainstate](https://github.com/chaobrain/brainstate), please learn [brainstate documentation](https://brainstate.readthedocs.io/) for the latest updates. 
 
-## Installation
-
-BrainPy is based on Python (>=3.8) and can be installed on Linux (Ubuntu 16.04 or later), macOS (10.12 or later), and Windows platforms. 
 
-BrainPy requires ``jax<0.6.0``. 
+## Installation
 
-For detailed installation instructions, please refer to the documentation: [Quickstart/Installation](https://brainpy.readthedocs.io/en/latest/quickstart/installation.html)
+BrainPy is based on Python (>=3.10) and can be installed on Linux (Ubuntu 16.04 or later), macOS (10.12 or later), and Windows platforms. 
 
 
 ### Using BrainPy with docker
@@ -64,6 +61,7 @@ We provide a Binder environment for BrainPy. You can use the following button to
 - [《神经计算建模实战》 (Neural Modeling in Action)](https://github.com/c-xy17/NeuralModeling)
 - [第一届神经计算建模与编程培训班 (First Training Course on Neural Modeling and Programming)](https://github.com/brainpy/1st-neural-modeling-and-programming-course)
 - [第二届神经计算建模与编程培训班 (Second Training Course on Neural Modeling and Programming)](https://github.com/brainpy/2nd-neural-modeling-and-programming-course)
+- **[brain modeling ecosystem](https://brainmodeling.readthedocs.io/)**: A collection of tools and libraries for brain modeling and simulation.
 
 
 ## Citing 

brainpy/_src/analysis/lowdim/lowdim_analyzer.py

@@ -287,7 +287,7 @@ def F_vmap_fx(self):
 
   @property
   def F_dfxdx(self):
-    """The function to evaluate :math:`\frac{df_x(*\mathrm{vars}, *\mathrm{pars})}{dx}`."""
+    r"""The function to evaluate :math:`\frac{df_x(*\mathrm{vars}, *\mathrm{pars})}{dx}`."""
     if C.F_dfxdx not in self.analyzed_results:
       dfx = bm.vector_grad(self.F_fx, argnums=0)
       self.analyzed_results[C.F_dfxdx] = jax.jit(dfx, device=self.jit_device)
@@ -416,7 +416,7 @@ def __init__(self, *args, **kwargs):
 
   @property
   def F_fy(self):
-    """The function to evaluate :math:`f_y(*\mathrm{vars}, *\mathrm{pars})`.
+    r"""The function to evaluate :math:`f_y(*\mathrm{vars}, *\mathrm{pars})`.
 
     This function has been transformed into the standard call.
     For instance, if the user has the ``target_vars=("v1", "v2")`` and
@@ -525,31 +525,31 @@ def F_vmap_fy(self):
 
   @property
   def F_dfxdy(self):
-    """The function to evaluate :math:`\frac{df_x (*\mathrm{vars}, *\mathrm{pars})}{dy}`."""
+    r"""The function to evaluate :math:`\frac{df_x (*\mathrm{vars}, *\mathrm{pars})}{dy}`."""
     if C.F_dfxdy not in self.analyzed_results:
       dfxdy = bm.vector_grad(self.F_fx, argnums=1)
       self.analyzed_results[C.F_dfxdy] = jax.jit(dfxdy, device=self.jit_device)
     return self.analyzed_results[C.F_dfxdy]
 
   @property
   def F_dfydx(self):
-    """The function to evaluate :math:`\frac{df_y (*\mathrm{vars}, *\mathrm{pars})}{dx}`."""
+    r"""The function to evaluate :math:`\frac{df_y (*\mathrm{vars}, *\mathrm{pars})}{dx}`."""
     if C.F_dfydx not in self.analyzed_results:
       dfydx = bm.vector_grad(self.F_fy, argnums=0)
       self.analyzed_results[C.F_dfydx] = jax.jit(dfydx, device=self.jit_device)
     return self.analyzed_results[C.F_dfydx]
 
   @property
   def F_dfydy(self):
-    """The function to evaluate :math:`\frac{df_y (*\mathrm{vars}, *\mathrm{pars})}{dy}`."""
+    r"""The function to evaluate :math:`\frac{df_y (*\mathrm{vars}, *\mathrm{pars})}{dy}`."""
     if C.F_dfydy not in self.analyzed_results:
       dfydy = bm.vector_grad(self.F_fy, argnums=1)
       self.analyzed_results[C.F_dfydy] = jax.jit(dfydy, device=self.jit_device)
     return self.analyzed_results[C.F_dfydy]
 
   @property
   def F_jacobian(self):
-    """The function to evaluate :math:`J(*\mathrm{vars}, *\mathrm{pars})`."""
+    r"""The function to evaluate :math:`J(*\mathrm{vars}, *\mathrm{pars})`."""
     if C.F_jacobian not in self.analyzed_results:
       @partial(bm.jacobian, argnums=(0, 1))
       def f_jacobian(*var_and_pars):
@@ -1037,7 +1037,7 @@ def __init__(self, *args, **kwargs):
 
   @property
   def F_fz(self):
-    """The function to evaluate :math:`f_y(*\mathrm{vars}, *\mathrm{pars})`."""
+    r"""The function to evaluate :math:`f_y(*\mathrm{vars}, *\mathrm{pars})`."""
     if C.F_fz not in self.analyzed_results:
       variables, arguments = utils.get_args(self.model.f_derivatives[self.z_var])
       wrapper = utils.std_derivative(arguments, self.target_var_names, self.target_par_names)

brainpy/_src/analysis/lowdim/lowdim_bifurcation.py

@@ -172,7 +172,7 @@ def plot_bifurcation(self, with_plot=True, show=False, with_return=False,
                        tol_aux=1e-8, tol_unique=1e-2, tol_opt_candidate=None,
                        num_par_segments=1, num_fp_segment=1, nullcline_aux_filter=1.,
                        select_candidates='aux_rank', num_rank=100):
-    """Make the bifurcation analysis.
+    r"""Make the bifurcation analysis.
 
     Parameters::
 

brainpy/_src/connect/random_conn.py

@@ -31,8 +31,8 @@
 class FixedProb(TwoEndConnector):
   """Connect the post-synaptic neurons with fixed probability.
 
-  Parameters::
-
+  Parameters::
+
   prob: float
     The conn probability.
   pre_ratio: float
@@ -143,8 +143,8 @@ def build_mat(self):
 class FixedTotalNum(TwoEndConnector):
   """Connect the synaptic neurons with fixed total number.
 
-  Parameters::
-
+  Parameters::
+
   num : float,int
     The conn total number.
   allow_multi_conn : bool, optional
@@ -214,8 +214,8 @@ def __repr__(self):
 class FixedPreNum(FixedNum):
   """Connect a fixed number pf pre-synaptic neurons for each post-synaptic neuron.
 
-  Parameters::
-
+  Parameters::
+
   num : float, int
       The conn probability (if "num" is float) or the fixed number of
       connectivity (if "num" is int).
@@ -274,8 +274,8 @@ def single_conn():
 class FixedPostNum(FixedNum):
   """Connect the fixed number of post-synaptic neurons for each pre-synaptic neuron.
 
-  Parameters::
-
+  Parameters::
+
   num : float, int
       The conn probability (if "num" is float) or the fixed number of
       connectivity (if "num" is int).
@@ -374,8 +374,8 @@ class GaussianProb(OneEndConnector):
 
   where :math:`v_k^i` is the :math:`i`-th neuron's encoded value at dimension :math:`k`.
 
-  Parameters::
-
+  Parameters::
+
   sigma : float
       Width of the Gaussian function.
   encoding_values : optional, list, tuple, int, float
@@ -511,10 +511,10 @@ def build_mat(self, isOptimized=True):
 
 
 class SmallWorld(TwoEndConnector):
-  """Build a Watts–Strogatz small-world graph.
+  r"""Build a Watts–Strogatz small-world graph.
+
+  Parameters::
 
-  Parameters::
-
   num_neighbor : int
       Each node is joined with its `k` nearest neighbors in a ring
       topology.
@@ -525,17 +525,17 @@ class SmallWorld(TwoEndConnector):
   include_self : bool
       Whether include the node self.
 
-  Notes::
-
+  Notes::
+
   First create a ring over :math:`num\_node` nodes [1]_.  Then each node in the ring is
   joined to its :math:`num\_neighbor` nearest neighbors (or :math:`num\_neighbor - 1` neighbors
   if :math:`num\_neighbor` is odd). Then shortcuts are created by replacing some edges as
   follows: for each edge :math:`(u, v)` in the underlying ":math:`num\_node`-ring with
   :math:`num\_neighbor` nearest neighbors" with probability :math:`prob` replace it with a new
   edge :math:`(u, w)` with uniformly random choice of existing node :math:`w`.
 
-  References::
-
+  References::
+
   .. [1] Duncan J. Watts and Steven H. Strogatz,
          Collective dynamics of small-world networks,
          Nature, 393, pp. 440--442, 1998.
@@ -655,27 +655,27 @@ def build_conn(self):
 
 
 class ScaleFreeBA(TwoEndConnector):
-  """Build a random graph according to the Barabási–Albert preferential
+  r"""Build a random graph according to the Barabási–Albert preferential
   attachment model.
 
   A graph of :math:`num\_node` nodes is grown by attaching new nodes each with
   :math:`m` edges that are preferentially attached to existing nodes
   with high degree.
 
-  Parameters::
-
+  Parameters::
+
   m : int
       Number of edges to attach from a new node to existing nodes
   seed : integer, random_state, or None (default)
       Indicator of random number generation state.
 
-  Raises::
-
+  Raises::
+
   ConnectorError
       If `m` does not satisfy ``1 <= m < n``.
 
-  References::
-
+  References::
+
   .. [1] A. L. Barabási and R. Albert "Emergence of scaling in
          random networks", Science 286, pp 509-512, 1999.
   """
@@ -774,8 +774,8 @@ class ScaleFreeBADual(TwoEndConnector):
   edges (with probability :math:`p`) or :math:`m_2` edges (with probability :math:`1-p`) that
   are preferentially attached to existing nodes with high degree.
 
-  Parameters::
-
+  Parameters::
+
   m1 : int
       Number of edges to attach from a new node to existing nodes with probability :math:`p`
   m2 : int
@@ -785,13 +785,13 @@ class ScaleFreeBADual(TwoEndConnector):
   seed : integer, random_state, or None (default)
       Indicator of random number generation state.
 
-  Raises::
-
+  Raises::
+
   ConnectorError
       If `m1` and `m2` do not satisfy ``1 <= m1,m2 < n`` or `p` does not satisfy ``0 <= p <= 1``.
 
-  References::
-
+  References::
+
   .. [1] N. Moshiri "The dual-Barabasi-Albert model", arXiv:1810.10538.
   """
 
@@ -900,17 +900,17 @@ class PowerLaw(TwoEndConnector):
   """Holme and Kim algorithm for growing graphs with powerlaw
   degree distribution and approximate average clustering.
 
-  Parameters::
-
+  Parameters::
+
   m : int
       the number of random edges to add for each new node
   p : float,
       Probability of adding a triangle after adding a random edge
   seed : integer, random_state, or None (default)
       Indicator of random number generation state.
 
-  Notes::
-
+  Notes::
+
   The average clustering has a hard time getting above a certain
   cutoff that depends on :math:`m`.  This cutoff is often quite low.  The
   transitivity (fraction of triangles to possible triangles) seems to
@@ -927,14 +927,14 @@ class PowerLaw(TwoEndConnector):
   since the initial :math:`m` nodes may not be all linked to a new node
   on the first iteration like the BA model.
 
-  Raises::
-
+  Raises::
+
   ConnectorError
       If :math:`m` does not satisfy :math:`1 <= m <= n` or :math:`p` does not
       satisfy :math:`0 <= p <= 1`.
 
-  References::
-
+  References::
+
   .. [1] P. Holme and B. J. Kim,
          "Growing scale-free networks with tunable clustering",
          Phys. Rev. E, 65, 026107, 2002.
@@ -1071,8 +1071,8 @@ class ProbDist(TwoEndConnector):
 
   .. versionadded:: 2.1.13
 
-  Parameters::
-
+  Parameters::
+
   dist: float, int
     The maximum distance between two points.
   prob: float

docs/index.rst

@@ -17,24 +17,21 @@ Installation
 
        .. code-block:: bash
 
-          # python 3.9-3.11
-          pip install -U brainpy[cpu]  # windows, linux, macos
+          pip install -U brainpy[cpu]
 
     .. tab-item:: GPU (CUDA 12)
 
        .. code-block:: bash
 
-          pip install -U brainpy[cuda12] -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html
+          pip install -U brainpy[cuda12]
 
     .. tab-item:: TPU
 
        .. code-block:: bash
 
-          pip install -U brainpy[tpu] -f https://storage.googleapis.com/jax-releases/libtpu_releases.html
+          pip install -U brainpy[tpu]
 
 
-For more information, please see `installation <quickstart/installation.html>`_ section.
-
 ----
 
 Learn more
@@ -112,6 +109,10 @@ Learn more
    in mind what BrainPy version you are using.
 
 
+.. note::
+   BrainPy now is rewritten based on [brainstate](https://github.com/chaobrain/brainstate).
+
+
 
 ----
 
@@ -122,7 +123,6 @@ Learn more
    :maxdepth: 1
    :caption: Quickstart
 
-   quickstart/installation
    quickstart/simulation
    quickstart/training
    quickstart/analysis

setup.py

@@ -37,13 +37,10 @@
         "Documentation": "https://brainpy.readthedocs.io/",
         "Source Code": "https://github.com/brainpy/BrainPy",
     },
-    dependency_links=[
-        'https://storage.googleapis.com/jax-releases/jax_cuda_releases.html',
-    ],
     extras_require={
         'cpu': ['jax[cpu]', 'brainstate[cpu]', 'brainunit[cpu]', 'brainevent[cpu]'],
         'cuda12': ['jax[cuda12]', 'brainstate[cuda12]', 'brainunit[cuda12]', 'brainevent[cuda12]'],
-        'tpu': ['jax[tpu]', 'brainstate[cuda12]', 'brainunit[cuda12]', 'brainevent[cuda12]'],
+        'tpu': ['jax[tpu]', 'brainstate[tpu]', 'brainunit[tpu]', 'brainevent[tpu]'],
     },
     keywords=('computational neuroscience, '
               'brain-inspired computation, '