Skip to content

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

Merged
wenh06 merged 2 commits into
masterfrom
docs-tutorials-c
Oct 29, 2026
Merged

wenh06 merged 2 commits into
masterfrom
docs-tutorials-c

Conversation

@wenh06

@wenh06 wenh06 commented Oct 27, 2026

Copy link
Copy Markdown
Owner

Summary

  • tutorial-visualization: merge a two-seed experiment into one mean curve with error bounds (find_log_files → aggregate_results_from_json_log_with_custom_axis → plot_mean_curve_with_error_bounds), export to PDF, and introduce the interactive Panel dashboard for notebook use. The x-axis guidance follows the cumulative-communications metric dissected in the first-experiment tutorial.
  • tutorial-parallel-reproducible: switch to the threads executor with one config line, then demonstrate the reproducibility contract end to end — with rng_mode="per_client" the sequential and threads backends produce bitwise identical final weights (torch.equal), while the global mode keeps participation and aggregation backend-independent but may interleave local trajectories. The script prints the contrast honestly (global-mode weights matched on the development machine; the page marks that as luck, not a guarantee).
  • test-files/tutorial_first_experiment.py: every run now takes a fresh model from the candidate_models property. The server trains the model it is given in place (self.model = model, no copy), so sharing one module across runs would warm-start every run after the first and contaminate the comparison. The documented table is unchanged (all algorithms saturate at this task's accuracy ceiling), and the run() docstring teaching the rule is shown on the page via literalinclude.
  • test/test_tutorial_scripts.py: two new behavioral smoke tests — curve merge with non-empty curves and PDF export inside a temporary working directory; bitwise sequential-vs-threads equality with per-client RNG plus global-mode communication equality.
  • zh_CN translations for the new and updated pages.

Validation

  • pytest test/test_tutorial_scripts.py: 7 passed (~22 s, real runs included).
  • English and zh_CN docs builds: zero warnings.

- tutorial-visualization.rst: merge a two-seed experiment into one mean
  curve with error bounds and export it to PDF; the interactive Panel
  dashboard is introduced for notebook use; the shown code is embedded
  via literalinclude from test-files/tutorial_visualization.py
- tutorial-parallel-reproducible.rst: one-line switch to the threads
  executor, then verify bitwise-identical final weights across backends
  with rng_mode per_client, and contrast the statistical-level global
  mode; embedded from test-files/tutorial_parallel_check.py
- tutorial_first_experiment.py: every run now takes a fresh model from
  the candidate-models property; the server trains the model it is
  given in place, so sharing one module across runs would warm-start
  every run after the first
- test/test_tutorial_scripts.py: two new behavioral smoke tests (curve
  merge and PDF export in a temporary working directory; bitwise
  sequential-vs-threads equality with per-client RNG)
- zh_CN translations for the new and updated pages
@codecov

codecov Bot commented Oct 28, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.79%. Comparing base (b31a5db) to head (d155122).

Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##           master      #59      +/-   ##
==========================================
+ Coverage   83.63%   83.79%   +0.15%     
==========================================
  Files          55       55              
  Lines        5640     5640              
==========================================
+ Hits         4717     4726       +9     
+ Misses        923      914       -9     

see 4 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Align the phrasing with the rest of the documentation: "Experiments
grow; wall-clock time should not" becomes a plain declarative opening,
question/imperative headings become noun phrases ("One line of
parallelism" -> "Enabling parallel execution", "Explore
interactively" -> "Interactive exploration", "Get some logs" ->
"Preparing the logs"), and metaphorical wording is replaced ("what
the global RNG mode buys (and costs)" -> "Behavior of the global RNG
mode", "treat that as luck, not a guarantee" -> "incidental rather
than guaranteed", "the rule of thumb" -> "Practical guidance").
The zh_CN translations are reworded to match. Script comments and
docstrings shown on the pages are adjusted in the same pass. No
technical content changes.
@wenh06
wenh06 merged commit 3cec68e into master Oct 29, 2026
28 of 29 checks passed
@wenh06
wenh06 deleted the docs-tutorials-c branch October 29, 2026 15:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant