R23-T060: Explain the randomized heap and add a module docstring with a seeded doctest - #70

Description

Explains data_structures/heap/randomized_heap.py well enough to re-implement it (idea, worked example, diagram, why merging is randomised) and improves the file's own documentation: a module docstring with a summary, a reference link, and a seeded doctest that builds a heap from 1,000 random values, pops them all and checks the order is sorted.

Related Issue

Fixes: #60

Type of Change

• Bug Fix
• New Feature
• UI/UX Improvement
• Performance Improvement
• Tests
• Documentation
• Refactoring / Maintenance
• CI/CD

Changes Made

• data_structures/heap/randomized_heap.py: added a module docstring (one-paragraph summary, Wikipedia reference) and a seeded doctest (1,000 random values, pop all, check == sorted(values)). No code changes; the 54 existing doctests are unchanged (61 total).
• work/R23-T060/EXPLAINER.md: the idea, the algorithm, a worked merge and pop by hand with diagrams, why merging is randomised (O(log n) expected path length), pitfalls.
• work/R23-T060/experiment.py and experiment_output.txt: sorted-pop check and a comparison of merge cost with and without the coin flip.
• work/R23-T060/FEEDBACK.md: a classmate's attempt at re-deriving a doctest from the explainer.

Screenshots / Recordings

Not applicable (no UI changes; diagrams are text in EXPLAINER.md).

Testing

• python -m pytest --doctest-modules data_structures/heap/randomized_heap.py -> passed (61 doctests)
• ruff check data_structures/heap/randomized_heap.py -> all checks passed
• python work/R23-T060/experiment.py -> 200/200 seeds: popping a heap built from 1,000 random values returns sorted(values)

Checklist

• I have tested my changes locally.
• I have added or updated tests, if needed.
• I have updated documentation, if needed.
• I have followed the project's coding guidelines.
• I have run the relevant tests and checks.
• I have addressed previous review feedback, if applicable.

Additional Notes

Findings: with the coin flip, an insert costs about 7-11 merge calls and a pop 10-13 for n = 1,000 to 4,000 (about log2 n); with a "never swap" variant, inserting ascending values costs about n/2 calls each, which is linear. Without the flip the tree becomes a left chain and pop is O(1) while insert is O(n); the coin flip balances the two. Classmate feedback is recorded in work/R23-T060/FEEDBACK.md.