From 97dfeb363fb5aa45e1af7e568cb0a972136e7432 Mon Sep 17 00:00:00 2001
From: Chaoming Wang <wcm.brainsim@gmail.com>
Date: Wed, 22 Jul 2026 18:01:08 +0800
Subject: [PATCH] docs: declare the brainpy / brainpy.state relationship

Add an additive (non-deprecation) declaration of how classic brainpy and the
state-based brainpy.state layer relate, modeled on Numba's CUDA status notice:
a dedicated docs/project/relationship.rst page plus a short admonition on the
landing page linking to it.
---
 docs/index.rst                | 11 +++++++
 docs/project/relationship.rst | 58 +++++++++++++++++++++++++++++++++++
 2 files changed, 69 insertions(+)
 create mode 100644 docs/project/relationship.rst

diff --git a/docs/index.rst b/docs/index.rst
index bcd8f11..02c3e60 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -16,6 +16,16 @@ ideas — explicit **State**, **physical units**, and the distinctive
 the number of neurons while remaining fully differentiable. See
 :doc:`concepts/alignpre-alignpost` for the keystone chapter.
 
+.. admonition:: ``brainpy`` and ``brainpy.state``
+
+   ``brainpy.state`` is the **state-based modeling layer** of BrainPy — developed and
+   released as the standalone ``brainpy_state`` package and surfaced through the
+   ``brainpy.state`` namespace. It is the recommended starting point for new
+   ``State``-based, differentiable spiking-network models. The classic,
+   ``DynamicalSystem``-based ``brainpy`` API (``brainpy.dyn``, ``brainpy.math``,
+   ``brainpy.integrators``) is unchanged and fully supported — the two paradigms
+   coexist. See :doc:`project/relationship`.
+
 .. figure:: /_static/bridging-concept.png
    :alt: A bridge diagram. On the left, a blue "Brain Simulation" panel with a
          network schematic, a spike raster, and a conductance-versus-time trace;
@@ -282,5 +292,6 @@ See also the ecosystem
    :caption: Project
 
    changelog.md
+   project/relationship
    project/citing
    project/ecosystem
diff --git a/docs/project/relationship.rst b/docs/project/relationship.rst
new file mode 100644
index 0000000..83e9a48
--- /dev/null
+++ b/docs/project/relationship.rst
@@ -0,0 +1,58 @@
+Relationship between ``brainpy`` and ``brainpy.state``
+======================================================
+
+``brainpy.state`` is the state-based modeling layer of `BrainPy
+<https://brainpy.readthedocs.io/>`_. It is developed and released as the standalone
+``brainpy_state`` package and surfaced through the ``brainpy.state`` namespace, so the
+same code is reachable as ``brainpy.state`` whether you install classic ``brainpy`` or
+the layer on its own.
+
+Why a separate package
+----------------------
+
+- **Decoupled release cycle.** ``brainpy.state`` is versioned and released independently
+  of classic ``brainpy``, so its models, fixes, and features ship on their own cadence.
+- **Surfaced through the ``brainpy.state`` namespace.** The standalone ``brainpy_state``
+  distribution is re-exported by classic ``brainpy`` as ``brainpy.state`` — there is no
+  separate import path to learn.
+- **Built on the BrainX substrate.** It is built on ``brainstate`` (State management),
+  ``brainunit`` (physical units), and the rest of the `BrainX ecosystem
+  <https://brainx.chaobrain.com/>`_, and compiles through JAX to CPU, GPU, and TPU.
+
+Which paradigm to use
+---------------------
+
+- Reach for **``brainpy.state``** for new work: ``State``-based models,
+  surrogate-gradient / differentiable training, online learning, and JAX-native
+  pipelines. This is the recommended starting point.
+- Keep using **classic ``brainpy``** for existing ``DynamicalSystem`` models and for the
+  array/operator and integrator API (``brainpy.math``, ``brainpy.integrators``,
+  ``brainpy.dyn``). It is unchanged and fully supported.
+
+The two paradigms coexist; adopting ``brainpy.state`` does not deprecate or remove any
+part of classic ``brainpy``.
+
+Installation
+------------
+
+``brainpy.state`` is bundled with classic ``brainpy`` (``brainpy >= 2.7.6``), so if you
+installed ``brainpy`` you already have it — no code changes are required:
+
+.. code-block:: python
+
+   import brainpy
+
+   neuron = brainpy.state.LIF(...)
+
+To install or upgrade the layer on its own release cycle:
+
+.. code-block:: bash
+
+   pip install -U brainpy.state
+
+See Also
+--------
+
+- :doc:`/project/ecosystem` — the wider BrainX ecosystem ``brainpy.state`` builds on.
+- `Classic BrainPy documentation <https://brainpy.readthedocs.io/>`_ — the
+  ``DynamicalSystem``-based API.