Skip to content

docs: add the visualization and parallel-reproducibility tutorials #59

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wenh06 merged 2 commits into from
Oct 29, 2026
Merged

docs: add the visualization and parallel-reproducibility tutorials #59

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2d10b79
docs: add the visualization and parallel-reproducibility tutorials
wenh06 Oct 27, 2026
d155122
docs: tighten the tone of the two new tutorial pages
wenh06 Oct 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/source/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ Project Links: `GitHub <https://github.com/wenh06/fl-sim>`_ | `gitee <https://gi

tutorial-first-experiment
tutorial-cli-matrix
tutorial-visualization
tutorial-parallel-reproducible

.. toctree::
:caption: API Reference
Expand Down
96 changes: 47 additions & 49 deletions docs/source/locale/zh_CN/LC_MESSAGES/tutorial-first-experiment.po
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ msgid ""
msgstr ""
"Project-Id-Version: fl-sim \n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2026-10-27 08:46+0800\n"
"POT-Creation-Date: 2026-10-28 07:53+0800\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language: zh_CN\n"
Expand All @@ -31,9 +31,9 @@ msgid ""
"ratios, then dissect what \"communication cost\" actually means in fl-"
"sim."
msgstr ""
":doc:`Quickstart <quickstart>` 只跑了一次训练。真正的实验要在相同条件下比较不同配置，"
"并把结果读回来。本教程将比较三个算法在两种采样比例下的表现，然后剖析 fl-sim 中"
"\"通信开销\"究竟指什么。"
":doc:`Quickstart <quickstart>` "
"只跑了一次训练。真正的实验要在相同条件下比较不同配置，并把结果读回来。本教程将比较三个算法在两种采样比例下的表现，然后剖析 fl-sim "
"中\"通信开销\"究竟指什么。"

#: ../../source/tutorial-first-experiment.rst:11
msgid ""
Expand All @@ -42,17 +42,15 @@ msgid ""
"downloads, seconds per run. The full script shown below lives at ``test-"
"files/tutorial_first_experiment.py`` and is exercised in CI."
msgstr ""
"全部运行基于 :class:`~fl_sim.data_processing.fed_synthetic.FedSynthetic`——"
"无需下载，每次运行只需几秒。下文展示的完整脚本位于 "
"``test-files/tutorial_first_experiment.py``，并在 CI 中被执行。"
"全部运行基于 "
":class:`~fl_sim.data_processing.fed_synthetic.FedSynthetic`——无需下载，每次运行只需几秒。下文展示的完整脚本位于"
" ``test-files/tutorial_first_experiment.py``，并在 CI 中被执行。"

#: ../../source/tutorial-first-experiment.rst:15
msgid ""
"Prerequisites: :doc:`quickstart` (the three-object model: dataset, model,"
" server) and :doc:`concepts` (what a round does)."
msgstr ""
"前置阅读： :doc:`quickstart` （三对象模型：数据集、模型、服务器）与 "
" :doc:`concepts` （一轮训练做了什么）。"
msgstr "前置阅读： :doc:`quickstart` （三对象模型：数据集、模型、服务器）与 :doc:`concepts` （一轮训练做了什么）。"

#: ../../source/tutorial-first-experiment.rst:19
msgid "Set up the comparison"
Expand All @@ -65,9 +63,8 @@ msgid ""
"gradient, proximal and variance-reduction axes — each at **sampling "
"ratios 0.5 and 1.0**."
msgstr ""
"六次运行： **FedAvg** （朴素平均）、 **FedProx** （近端正则的本地目标）与 "
" **SCAFFOLD** （控制变量）——梯度、近端、方差缩减三条经典轴线——各自在 "
" **采样比例 0.5 与 1.0** 下运行。"
"六次运行： **FedAvg** （朴素平均）、 **FedProx** （近端正则的本地目标）与 **SCAFFOLD** "
"（控制变量）——梯度、近端、方差缩减三条经典轴线——各自在 **采样比例 0.5 与 1.0** 下运行。"

#: ../../source/tutorial-first-experiment.rst:26
msgid ""
Expand All @@ -77,9 +74,8 @@ msgid ""
"sampling stream of everything after it. The order *dataset → config → "
"server* keeps every run reproducible:"
msgstr ""
"一个刻意的选择：数据集 **只构造一次，且先于任何配置或服务器** 。配置类的构造器在"
"构建时会重置全局 RNG，谁最后构造谁生效，其后的采样流都会被移动。按 "
"*数据集 → 配置 → 服务器* 的顺序构造，每次运行都可复现："
"一个刻意的选择：数据集 **只构造一次，且先于任何配置或服务器** 。配置类的构造器在构建时会重置全局 "
"RNG，谁最后构造谁生效，其后的采样流都会被移动。按 *数据集 → 配置 → 服务器* 的顺序构造，每次运行都可复现："

#: ../../source/tutorial-first-experiment.rst:37
msgid ""
Expand All @@ -89,9 +85,9 @@ msgid ""
"frequency parameter later. Both are per-algorithm server keywords, "
"collected in ``SERVER_KW``."
msgstr ""
"``final_accuracy`` 读取一次运行的 JSON 日志——与 :doc:`quickstart` 中相同的文件"
"格式。SCAFFOLD 需要显式传入全局步长 ``lr``（它的配置没有默认值）；FedPD 稍后也需要"
"一个频率参数。两者都是算法各自的服务器关键字，统一收在 ``SERVER_KW`` 里。"
"``final_accuracy`` 读取一次运行的 JSON 日志——与 :doc:`quickstart` 中相同的文件格式。SCAFFOLD"
" 需要显式传入全局步长 ``lr``（它的配置没有默认值）；FedPD 稍后也需要一个频率参数。两者都是算法各自的服务器关键字，统一收在 "
"``SERVER_KW`` 里。"

#: ../../source/tutorial-first-experiment.rst:44
msgid "Run and read the results"
Expand Down Expand Up @@ -120,9 +116,9 @@ msgid ""
"harder, more heterogeneous tasks (see the :doc:`algorithm theory pages "
"<algorithms/overview>` for when each helps)."
msgstr ""
"这个合成任务 *太容易* ——全采样下 FedProx 与 SCAFFOLD 达到了和 FedAvg 相同的精度"
"天花板。它们的优势要在更难、异质性更强的任务上才显现（何时用哪个，见 "
":doc:`算法理论页 <algorithms/overview>` ）。"
"这个合成任务 *太容易* ——全采样下 FedProx 与 SCAFFOLD 达到了和 FedAvg "
"相同的精度天花板。它们的优势要在更难、异质性更强的任务上才显现（何时用哪个，见 :doc:`算法理论页 "
"<algorithms/overview>` ）。"

#: ../../source/tutorial-first-experiment.rst:74
msgid ""
Expand All @@ -131,8 +127,8 @@ msgid ""
"1.0 used exactly 180 — regardless of the algorithm. That number deserves "
"a closer look, because it is easy to misread."
msgstr ""
"精度的故事饱和了， **通信** 的故事没有：比例 0.5 的每次运行都恰好用了 90 次通信，"
"比例 1.0 的都恰好 180 次——与算法无关。这个数字值得细看，因为它很容易被误读。"
"精度的故事饱和了， **通信** 的故事没有：比例 0.5 的每次运行都恰好用了 90 次通信，比例 1.0 的都恰好 180 "
"次——与算法无关。这个数字值得细看，因为它很容易被误读。"

#: ../../source/tutorial-first-experiment.rst:80
msgid "What ``num_communications`` counts"
Expand All @@ -147,8 +143,8 @@ msgid ""
" doubles to 180."
msgstr ""
"``num_communications`` 统计的是 **消息数，不是轮数** ：每轮对 *每个被采样客户端* "
"加一次下行广播，再加一次上行回复。30 个客户端、比例 0.5 时，每轮是 15 下行 + "
"15 上行 = 30 条消息，3 轮 = 90；比例 1.0 时翻倍为 180。"
"加一次下行广播，再加一次上行回复。30 个客户端、比例 0.5 时，每轮是 15 下行 + 15 上行 = 30 条消息，3 轮 = 90；比例 "
"1.0 时翻倍为 180。"

#: ../../source/tutorial-first-experiment.rst:88
msgid ""
Expand Down Expand Up @@ -176,8 +172,8 @@ msgid ""
"round's full cost — read the final count from the server, as the scripts "
"here do.)"
msgstr ""
"（另注：JSON 日志里记录的 ``step`` 是 *每轮开始时* 的快照：它比最终计数少最后一轮的"
"全部开销——最终值请从服务器读取，正如本页脚本的做法。）"
"（另注：JSON 日志里记录的 ``step`` 是 *每轮开始时* "
"的快照：它比最终计数少最后一轮的全部开销——最终值请从服务器读取，正如本页脚本的做法。）"

#: ../../source/tutorial-first-experiment.rst:106
msgid "Sampling is not communicating"
Expand All @@ -191,9 +187,8 @@ msgid ""
"every ``int(1/p)``-th round — for five rounds next to a five-round "
"FedAvg:"
msgstr ""
"上面三个算法每一轮都在通信。fl-sim 还内置 **可跳过通信** 的算法，它们会以很有启发性的"
"方式打破 ``2 × 采样数 × 轮数`` 的恒等式。让 FedPD（每 ``int(1/p)`` 轮才上传一次）"
"与五轮 FedAvg 并排各跑五轮："
"上面三个算法每一轮都在通信。fl-sim 还内置 **可跳过通信** 的算法，它们会以很有启发性的方式打破 ``2 × 采样数 × 轮数`` "
"的恒等式。让 FedPD（每 ``int(1/p)`` 轮才上传一次）与五轮 FedAvg 并排各跑五轮："

#: ../../source/tutorial-first-experiment.rst:119
msgid "Output on one machine:"
Expand All @@ -207,9 +202,8 @@ msgid ""
"messages as three FedAvg rounds — the same communication budget buys two "
"extra local iterations."
msgstr ""
"分解式把话说得非常准： **下行完全相同** （75 = 5 轮 × 15 客户端——对被采样集合的广播"
"从不跳过）；FedPD 省下的 *全是上行* 。五轮 FedPD 花费的 90 条消息与三轮 FedAvg 相同"
"——同样的通信预算换来了多两轮的本地迭代。"
"分解式把话说得非常准： **下行完全相同** （75 = 5 轮 × 15 客户端——对被采样集合的广播从不跳过）；FedPD 省下的 "
"*全是上行* 。五轮 FedPD 花费的 90 条消息与三轮 FedAvg 相同——同样的通信预算换来了多两轮的本地迭代。"

#: ../../source/tutorial-first-experiment.rst:132
msgid "Three practical details when you run this yourself:"
Expand All @@ -223,9 +217,9 @@ msgid ""
"frequency ``int(1/p)`` always wins — passing a ``comm_freq`` yourself is "
"silently overwritten."
msgstr ""
"``p`` 必须满足 **0 < p < 1** 。p = 1 时 FedPD 每轮都上传（退化为 FedAvg）；p > 1 时"
"上传频率变为零，运行直接崩溃。配置暴露的是 ``p`` ，派生的上传频率 ``int(1/p)`` "
"始终说了算——自己传 ``comm_freq`` 会被静默覆写。"
"``p`` 必须满足 **0 < p < 1** 。p = 1 时 FedPD 每轮都上传（退化为 FedAvg）；p > 1 "
"时上传频率变为零，运行直接崩溃。配置暴露的是 ``p`` ，派生的上传频率 ``int(1/p)`` 始终说了算——自己传 "
"``comm_freq`` 会被静默覆写。"

#: ../../source/tutorial-first-experiment.rst:139
msgid ""
Expand All @@ -238,11 +232,11 @@ msgid ""
"appears once per (skipped client × skipped round), so it dominates the "
"console. Both are how FedPD is designed to behave."
msgstr ""
" **你会看到 RuntimeWarning——那是预期行为，不是错误。** 服务器对每个跳过的轮次记录 "
"``No message received from the clients...`` （\"这轮没人上传，全局模型没有动\"）；"
"每个跳过的客户端记录 ``No parameters received from server...`` （\"这轮没收到新的"
"全局模型，我继续用当前参数\"）。教程规模下，客户端侧的消息每个（跳过客户端 × 跳过轮次）"
"出现一次，会刷满控制台。两者都是 FedPD 的设计行为。"
" **你会看到 RuntimeWarning——那是预期行为，不是错误。** 服务器对每个跳过的轮次记录 ``No message "
"received from the clients...`` （\"这轮没人上传，全局模型没有动\"）；每个跳过的客户端记录 ``No "
"parameters received from server...`` "
"（\"这轮没收到新的全局模型，我继续用当前参数\"）。教程规模下，客户端侧的消息每个（跳过客户端 × 跳过轮次）出现一次，会刷满控制台。两者都是 "
"FedPD 的设计行为。"

#: ../../source/tutorial-first-experiment.rst:147
msgid ""
Expand All @@ -251,9 +245,8 @@ msgid ""
"unlogged), for FedPD at 75 (its last round never uploads). The final "
"counts come from ``server._num_communications``."
msgstr ""
"JSON 的 ``step`` 快照落后多少因算法而异：五轮 FedAvg 终于 120（最后一轮的 30 条消息"
"未入日志），FedPD 终于 75（它的最后一轮从不上传）。最终计数请以 "
"``server._num_communications`` 为准。"
"JSON 的 ``step`` 快照落后多少因算法而异：五轮 FedAvg 终于 120（最后一轮的 30 条消息未入日志），FedPD 终于 "
"75（它的最后一轮从不上传）。最终计数请以 ``server._num_communications`` 为准。"

#: ../../source/tutorial-first-experiment.rst:153
msgid "Next steps"
Expand All @@ -263,12 +256,17 @@ msgstr "下一步"
msgid ""
":doc:`tutorial-cli-matrix` — run the same kind of comparison from the "
"command line, as a YAML-driven experiment matrix."
msgstr ""
":doc:`tutorial-cli-matrix`——用 YAML 实验矩阵从命令行跑同样的对照。"
msgstr ":doc:`tutorial-cli-matrix`——用 YAML 实验矩阵从命令行跑同样的对照。"

#: ../../source/tutorial-first-experiment.rst:157
msgid ""
":doc:`tutorial-visualization` — merge multi-seed runs of this comparison "
"into mean curves with error bounds."
msgstr ""
":doc:`tutorial-visualization`——把本次对照的多 seed 运行合并成带误差带的均值曲线。"

#: ../../source/tutorial-first-experiment.rst:159
msgid ""
":doc:`parallel_execution` — speed these runs up with a parallel executor "
"without changing the results."
msgstr ""
":doc:`parallel_execution`——用并行执行后端加速这些运行，且不改变结果。"
msgstr ":doc:`parallel_execution`——用并行执行后端加速这些运行，且不改变结果。"
Loading
Loading