docs: add quickstart and concepts pages with drift-proof code blocks

docs/source/cli.rst

@@ -9,56 +9,8 @@ For example, in the `all-alg-fedprox-femnist.yml <https://github.com/wenh06/fl-s
 .. dropdown:: [example-configs/all-alg-fedprox-femnist.yml]
     :animate: fade-in-slide-down
 
-    .. code-block:: yaml
-
-        # Example config file for fl-sim command line interface
-
-        strategy:
-        matrix:
-            algorithm:
-            - Ditto
-            - FedDR
-            - FedAvg
-            - FedAdam
-            - FedProx
-            - FedPD
-            - FedSplit
-            - IFCA
-            - pFedMac
-            - pFedMe
-            - ProxSkip
-            - SCAFFOLD
-            clients_sample_ratio:
-            - 0.1
-            - 0.3
-            - 0.7
-            - 1.0
-
-        algorithm:
-        name: ${{ matrix.algorithm }}
-        server:
-            num_clients: null
-            clients_sample_ratio: ${{ matrix.clients_sample_ratio }}
-            num_iters: 100
-            p: 0.3  # for FedPD, ProxSkip
-            lr: 0.03  # for SCAFFOLD
-            num_clusters: 10  # for IFCA
-            log_dir: all-alg-fedprox-femnist
-        client:
-            lr: 0.03
-            num_epochs: 10
-            batch_size: null  # null for default batch size
-            scheduler:
-            name: step  # StepLR
-            step_size: 1
-            gamma: 0.99
-        dataset:
-        name: FedProxFEMNIST
-        datadir: null  # default dir
-        transform: none  # none for static transform (only normalization, no augmentation)
-        model:
-        name: cnn_femmist_tiny
-        seed: 0
+    .. literalinclude:: ../../example-configs/all-alg-fedprox-femnist.yml
+        :language: yaml
 
 |
 

docs/source/concepts.rst

@@ -0,0 +1,154 @@
+.. _concepts:
+
+Core concepts
+=============
+
+This page is the map of fl-sim: the four building blocks of every
+experiment and what happens during one round of federated training. It
+explains *how the framework thinks* — for a hands-on walk-through, start
+with :doc:`quickstart`.
+
+Four building blocks
+----------------------
+
+FedDataset — the data and how it is split
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A :class:`~fl_sim.data_processing.fed_dataset.FedDataset` bundles a raw
+dataset with a **partitioning scheme**: it decides how the data is spread
+across the simulated clients and hands each client its own dataloaders
+through ``get_dataloader(client_idx)``. Built-in datasets (FEMNIST,
+CIFAR10, …) download on first use; :class:`~fl_sim.data_processing.fed_synthetic.FedSynthetic`
+generates synthetic data locally, which is why every tutorial here runs in
+seconds. Each dataset also declares ``candidate_models`` — the models it
+is meant to be paired with (``dataset.candidate_models["mlp_d1"]``, as in
+the quickstart). Datasets are **immutable during training**: partitioning
+happens once, up front. Custom datasets are covered in a how-to guide.
+
+Model — a plain PyTorch module
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Models are ordinary :class:`torch.nn.Module` objects; fl-sim does not
+wrap them. Whatever ``candidate_models`` offers or you bring yourself
+works. The server holds the *global* copy; every sampled client gets its
+own copy each round, trains it on its local data slice, and sends the
+result back.
+
+Server — the orchestrator
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :class:`~fl_sim.nodes.Server` owns the global model and the
+federated schedule (how many rounds, how many clients, how they are
+sampled), and drives the loop you will see below. It never touches
+client-local data. Algorithm-specific behavior lives in subclasses:
+:class:`~fl_sim.algorithms.fedopt.FedAvgServer`,
+:class:`~fl_sim.algorithms.fedprox.FedProxServer`, and 15+ others — each
+customizes a handful of well-defined hooks:
+
+- ``communicate(target)`` — the **downlink**: what the server sends to a
+  sampled client (typically the current global model);
+- ``update()`` — the **aggregation**: how client replies are turned into
+  the new global model.
+
+Client — one participant's local state
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each :class:`~fl_sim.nodes.Client` holds its own model copy, its data
+slice, and its training state. Its hooks are the mirror image of the
+server's:
+
+- ``update()`` — the **local training**: fit the received model on local
+  data (local epochs, local optimizer — all from the client config);
+- ``communicate()`` — the **uplink**: build the message sent back to the
+  server. Messages are typed objects (:class:`~fl_sim.messages.ClientToServer`)
+  carrying the updated model state plus algorithm-specific extras.
+
+Algorithms customize the hooks, not the loop
+--------------------------------------------
+
+fl-sim ships 20 registered algorithms — FedAvg, FedProx, SCAFFOLD,
+FedPD, ProxSkip, Ditto, … — and they all run in the *same* loop. An
+algorithm is only a pair of config classes plus hook overrides: FedProx
+changes the client's local objective; SCAFFOLD adds control variates to
+the uplink; FedPD lets clients *skip* some uplinks entirely. The
+framework calls the hooks in a fixed order (below), so algorithms compose
+with the infrastructure — logging, evaluation, reproducibility, parallel
+execution — without any of them knowing about each other.
+
+Registering your own makes it usable from the CLI and experiment
+matrices by name:
+
+.. code-block:: python
+
+    from fl_sim.algorithms._register import register_algorithm
+
+    @register_algorithm()
+    class MyServer(FedAvgServer):
+        ...
+
+.. seealso::
+
+   The how-to guide on custom algorithms walks through a complete,
+   runnable example; :doc:`parallel_execution` documents the hook
+   contract that keeps custom algorithms compatible with every executor.
+
+One round of training
+---------------------
+
+``server.train()`` runs ``num_iters`` rounds. Every round proceeds in a
+fixed order:
+
+1. **Sampling** — the server picks this round's participants (the
+   ``clients_sample_ratio`` fraction of ``num_clients``).
+2. **Uplink decision** — per algorithm: most algorithms have every
+   sampled client respond; communication-skipping algorithms (FedPD,
+   ProxSkip) decide *now*, on the main thread, which clients will upload
+   this round.
+3. **Downlink broadcast** — the server sends the global model to each
+   sampled client (``server.communicate(target)``).
+4. **Local steps** — each selected client runs evaluate → local training
+   → build the uplink message. Clients never see each other or the
+   global state; they touch only their own slice.
+5. **Uplink + aggregation** — replies are consumed **in sampled-client
+   order** and the algorithm's ``update()`` produces the new global
+   model. Metrics (server-side and per-client) are logged here.
+6. **Repeat** — for ``num_iters`` rounds; logs and metrics land in
+   ``~/.cache/fl-sim/.logs/`` (see :doc:`quickstart`).
+
+Because steps 1–2 and 5 happen on the main thread in fixed order, the
+*aggregation arithmetic* is identical no matter how the local steps of
+step 4 are executed — sequentially, or concurrently on a thread pool
+(:doc:`parallel_execution`). That invariant is what makes parallel runs
+trustworthy.
+
+The cast in one table
+---------------------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Object
+     - Configured by
+     - Knows about
+     - Never touches
+   * - :class:`~fl_sim.data_processing.fed_dataset.FedDataset`
+     - constructor args
+     - raw data, partitioning, dataloaders
+     - training state
+   * - :class:`~fl_sim.nodes.Client`
+     - ``ClientConfig`` subclass
+     - its own data slice and model copy
+     - other clients, the global model's evolution
+   * - :class:`~fl_sim.nodes.Server`
+     - ``ServerConfig`` subclass
+     - global model, sampling, aggregation, logging
+     - client-local data
+
+Where to go next
+----------------
+
+- :doc:`quickstart` — run all of this in five rounds on synthetic data.
+- :doc:`api/nodes` — the full Server/Client API reference.
+- :ref:`config reference <config_reference>` — every config field
+  of every algorithm.
+- :doc:`viz` — explore the produced logs interactively.

docs/source/examples.rst

@@ -1,4 +1,10 @@
+:orphan:
+
 Usage examples
-^^^^^^^^^^^^^^^^
+==============
+
+.. seealso::
 
-to write....
+   The usage examples now live in :doc:`quickstart`, with
+   :doc:`concepts` as the conceptual map and task-oriented tutorials
+   building on both.

docs/source/index.rst

@@ -15,7 +15,8 @@ Project Links: `GitHub <https://github.com/wenh06/fl-sim>`_ | `gitee <https://gi
    :maxdepth: 1
 
    install
-   examples
+   quickstart
+   concepts
 
 .. toctree::
    :caption: API Reference