Merge branch 'master' of https://github.com/brainpy/BrainPy

brainpy · Aug 13, 2023 · c0e8972 · c0e8972
2 parents d113a00 + f568a6a
commit c0e8972
Show file tree

Hide file tree

Showing 16 changed files with 539 additions and 346 deletions.
diff --git a/docs/FAQ.rst b/docs/FAQ.rst
@@ -0,0 +1,12 @@
+Frequently Asked Questions
+==========================
+This section contains answers to frequently asked questions about BrainPy.
+
+.. toctree::
+   :maxdepth: 1
+
+   tutorial_FAQs/how_to_debug.ipynb
+   tutorial_FAQs/gotchas_of_brainpy_transforms.ipynb
+   tutorial_FAQs/citing_and_publication
+   tutorial_FAQs/uniqueness_of-brainpy-math
+   tutorial_FAQs/brainpy_ecosystem.ipynb
diff --git a/docs/_static/surrogate_gradient.png b/docs/_static/surrogate_gradient.png
diff --git a/docs/advanced_tutorials.rst b/docs/advanced_tutorials.rst
@@ -0,0 +1,10 @@
+Advanced Tutorials
+==================
+This section contains tutorials that illustrate more advanced features of BrainPy.
+
+.. toctree::
+   :maxdepth: 2
+
+   tutorial_advanced/math.rst
+   tutorial_advanced/interoperation.rst
+   tutorial_advanced/analysis.rst
diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,35 @@
+API Documentation
+======
+
+.. toctree::
+   :maxdepth: 1
+
+   apis/auto/changelog.rst
+   apis/auto/brainpy.rst
+   apis/auto/math.rst
+   apis/auto/dnn.rst
+   apis/auto/dyn.rst
+   apis/auto/integrators.rst
+   apis/auto/analysis.rst
+   apis/auto/connect.rst
+   apis/auto/encoding.rst
+   apis/auto/initialize.rst
+   apis/auto/inputs.rst
+   apis/auto/losses.rst
+   apis/auto/measure.rst
+   apis/auto/optim.rst
+   apis/auto/running.rst
+   apis/auto/mixin.rst
+
+The following APIs will no longer be maintained in the future, but you can still use them normally.
+
+.. toctree::
+   :maxdepth: 1
+
+   apis/channels.rst
+   apis/neurons.rst
+   apis/rates.rst
+   apis/synapses.rst
+   apis/synouts.rst
+   apis/synplast.rst
+   apis/layers.rst
diff --git a/docs/brain_dynamics_tutorials.rst b/docs/brain_dynamics_tutorials.rst
@@ -0,0 +1,12 @@
+Brain Dynamics Tutorials
+========================
+This section contains tutorials on how to use BrainPy to accomplish model building, simulation, training, and analysis.
+
+.. toctree::
+   :maxdepth: 2
+
+   tutorial_math/index
+   tutorial_building/index
+   tutorial_simulation/index
+   tutorial_training/index
+   tutorial_analysis/index
diff --git a/docs/conf.py b/docs/conf.py
@@ -71,14 +71,16 @@
   'myst_nb',
   'matplotlib.sphinxext.plot_directive',
   'sphinx_thebe',
-
+  'sphinx_design'
   # 'sphinx-mathjax-offline',
 ]
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
+source_suffix = ['.rst', '.ipynb', '.md']
+
 
 # source_suffix = '.rst'
 autosummary_generate = True

diff --git a/docs/core_concepts.rst b/docs/core_concepts.rst
@@ -0,0 +1,9 @@
+Core Concepts
+==================
+This section contains the core principles and concepts that are designed in BrainPy.
+
+.. toctree::
+   :maxdepth: 1
+
+   core_concept/brainpy_transform_concept
+   core_concept/brainpy_dynamical_system
diff --git a/docs/index.rst b/docs/index.rst
@@ -4,128 +4,194 @@ BrainPy documentation
 `BrainPy`_ is a highly flexible and extensible framework targeting on the
 general-purpose Brain Dynamics Programming (BDP). Among its key ingredients, BrainPy supports:
 
-- **JIT compilation** and **automatic differentiation** for class objects.
-- **Numerical methods** for ordinary differential equations (ODEs),
-  stochastic differential equations (SDEs),
-  delay differential equations (DDEs),
-  fractional differential equations (FDEs), etc.
-- **Dynamics building** with the modular and composable programming interface.
-- **Dynamics simulation** for various brain objects with parallel supports.
-- **Dynamics training** with various machine learning algorithms,
-  like FORCE learning, ridge regression, back-propagation, etc.
-- **Dynamics analysis** for low- and high-dimensional systems, including
-  phase plane analysis, bifurcation analysis, linearization analysis,
-  and fixed/slow point finding.
-- And more others ......
+.. _BrainPy: https://github.com/brainpy/BrainPy
 
 
-.. _BrainPy: https://github.com/brainpy/BrainPy
+Features
+^^^^^^^^^
 
+.. grid::
 
-.. note::
-   BrainPy is still an experimental research project.
-   APIs may be changed over time. Please always keeps
-   in mind what BrainPy version you are using.
+   .. grid-item::
+      :columns: 12 12 12 6
 
+      .. card:: OO Transformations
+         :class-card: sd-border-0
+         :shadow: none
+         :class-title: sd-fs-5
 
+         .. div:: sd-font-normal
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Quickstart
+            BrainPy supports object-oriented transformations, including
+            :meth:`JIT <brainpy.math.jit>` compilation, :meth:`Autograd <brainpy.math.grad>`.
 
-   quickstart/installation
-   quickstart/simulation
-   quickstart/training
-   quickstart/analysis
+   .. grid-item::
+      :columns: 12 12 12 6
 
+      .. card:: Numerical Integrators
+         :class-card: sd-border-0
+         :shadow: none
+         :class-title: sd-fs-5
 
-.. toctree::
-   :maxdepth: 1
-   :caption: BrainPy Core Concepts
+         .. div:: sd-font-normal
 
-   core_concept/brainpy_transform_concept
-   core_concept/brainpy_dynamical_system
+            Numerical methods for ordinary differential equations (ODEs), stochastic differential equations (SDEs), delay differential equations (DDEs), fractional differential equations (FDEs), etc.
 
+   .. grid-item::
+      :columns: 12 12 12 6
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Brain Dynamics Tutorials
+      .. card:: Dynamics Building
+         :class-card: sd-border-0
+         :shadow: none
+         :class-title: sd-fs-5
 
-   tutorial_math/index
-   tutorial_building/index
-   tutorial_simulation/index
-   tutorial_training/index
-   tutorial_analysis/index
+         .. div:: sd-font-normal
 
+            BrainPy provides a modular and composable programming interface for building dynamics.
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Advanced Tutorials
+   .. grid-item::
+      :columns: 12 12 12 6
 
-   tutorial_advanced/math.rst
-   tutorial_advanced/interoperation.rst
-   tutorial_advanced/analysis.rst
+      .. card:: Dynamics Simulation
+         :class-card: sd-border-0
+         :shadow: none
+         :class-title: sd-fs-5
 
+         .. div:: sd-font-normal
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Toolboxes
+            BrainPy supports dynamics simulation for various brain objects with parallel supports.
 
-   tutorial_toolbox/ode_numerical_solvers
-   tutorial_toolbox/sde_numerical_solvers
-   tutorial_toolbox/fde_numerical_solvers
-   tutorial_toolbox/dde_numerical_solvers
-   tutorial_toolbox/joint_equations
-   tutorial_toolbox/synaptic_connections
-   tutorial_toolbox/synaptic_weights
-   tutorial_toolbox/optimizers
-   tutorial_toolbox/saving_and_loading
-   tutorial_toolbox/inputs
 
+   .. grid-item::
+      :columns: 12 12 12 6
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Frequently Asked Questions
+      .. card:: Dynamics Training
+         :class-card: sd-border-0
+         :shadow: none
+         :class-title: sd-fs-5
+
+         .. div:: sd-font-normal
+
+            BrainPy supports dynamics training with various machine learning algorithms, like FORCE learning, ridge regression, back-propagation, etc.
+
+   .. grid-item::
+      :columns: 12 12 12 6
+
+      .. card:: Dynamics Analysis
+         :class-card: sd-border-0
+         :shadow: none
+         :class-title: sd-fs-5
+
+         .. div:: sd-font-normal
+
+            BrainPy supports dynamics analysis for low- and high-dimensional systems, including phase plane analysis, bifurcation analysis, linearization analysis, and fixed/slow point finding.
+
+----
+
+Installation
+^^^^^^^^^^^^
+.. tab-set::
+
+    .. tab-item:: CPU
+
+       .. code-block:: bash
+
+          pip install brainpy
+
+    .. tab-item:: GPU (CUDA)
 
-   tutorial_FAQs/citing_and_publication
-   tutorial_FAQs/uniqueness_of-brainpy-math
-   tutorial_FAQs/brainpy_ecosystem.ipynb
+       .. code-block:: bash
+
+          pip install brainpy
+
+For more information about supported accelerators and platforms, and for other installation details, please see installation section.
+
+----
+
+Learn more
+^^^^^^^^^^
+
+.. grid::
+
+   .. grid-item::
+      :columns: 6 6 6 4
+
+      .. card:: :material-regular:`rocket_launch;2em` Installation
+         :class-card: sd-text-black sd-bg-light
+         :link: quickstart/installation.html
+
+   .. grid-item::
+      :columns: 6 6 6 4
+
+      .. card:: :material-regular:`library_books;2em` Core Concepts
+         :class-card: sd-text-black sd-bg-light
+         :link: core_concepts.html
+
+   .. grid-item::
+      :columns: 6 6 6 4
+
+      .. card:: :material-regular:`science;2em` Brain Dynamics Tutorials
+         :class-card: sd-text-black sd-bg-light
+         :link: brain_dynamics_tutorials.html
+
+   .. grid-item::
+      :columns: 6 6 6 4
+
+      .. card:: :material-regular:`science;2em` Advanced Tutorials
+         :class-card: sd-text-black sd-bg-light
+         :link: advanced_tutorials.html
+
+   .. grid-item::
+      :columns: 6 6 6 4
+
+      .. card:: :material-regular:`science;2em` Toolboxes
+         :class-card: sd-text-black sd-bg-light
+         :link: toolboxes.html
+
+   .. grid-item::
+      :columns: 6 6 6 4
+
+      .. card:: :material-regular:`science;2em` Frequently Asked Questions
+         :class-card: sd-text-black sd-bg-light
+         :link: FAQ.html
+
+   .. grid-item::
+      :columns: 6 6 6 4
+
+      .. card:: :material-regular:`science;2em` API documentation
+         :class-card: sd-text-black sd-bg-light
+         :link: api.html
+
+.. note::
+   BrainPy is still an experimental research project.
+   APIs may be changed over time. Please always keeps
+   in mind what BrainPy version you are using.
 
 
 .. toctree::
+   :hidden:
    :maxdepth: 1
-   :caption: API Documentation
-
-   apis/auto/brainpy.rst
-   apis/auto/math.rst
-   apis/auto/dnn.rst
-   apis/auto/dyn.rst
-   apis/auto/integrators.rst
-   apis/auto/analysis.rst
-   apis/auto/connect.rst
-   apis/auto/encoding.rst
-   apis/auto/initialize.rst
-   apis/auto/inputs.rst
-   apis/auto/losses.rst
-   apis/auto/measure.rst
-   apis/auto/optim.rst
-   apis/auto/running.rst
-   apis/auto/mixin.rst
-   apis/auto/changelog.rst
-
-
-The following APIs will no longer be maintained in the future, but you can still use them normally.
+   :caption: Quickstart
+
+   quickstart/installation
+   quickstart/simulation
+   quickstart/training
+   quickstart/analysis
+
+
 
 .. toctree::
-   :maxdepth: 1
+   :hidden:
+   :maxdepth: 2
+   :caption: Tutorials
+
+   core_concepts.rst
+   brain_dynamics_tutorials.rst
+   advanced_tutorials.rst
+   toolboxes.rst
+   FAQ.rst
+   api.rst
 
-   apis/channels.rst
-   apis/neurons.rst
-   apis/rates.rst
-   apis/synapses.rst
-   apis/synouts.rst
-   apis/synplast.rst
-   apis/layers.rst
 
 
 Indices and tables