mirror of
https://github.com/harvard-edge/cs249r_book.git
synced 2026-05-07 10:08:50 -05:00
3ba3858b74
* docs(mlsysim): release-prep audit fixes for 0.1.0
Fixes the broken links, stale numerical claims, and naming inconsistencies
surfaced by the 0.1.0 release-prep review. Output of the docs site now matches
what the engine actually computes, internal navigation has no unresolved targets,
and the Hatch announcement banner uses an absolute URL so sub-pages render the
"Get started" link correctly.
Notable changes:
- Hero example on docs/index.qmd and getting-started.qmd now reflect the actual
Engine.solve(ResNet50, A100, bs=1, fp16) output (Memory / 0.54 ms / 1843).
- Update Python version requirement (3.10+) and document the editable-install
limitation (Hatch sources rewrite is not supported by editables).
- Standardize the typographic brand to "MLSys·im" in the navbar, OG/Twitter
metadata, and the shared cross-site dropdown.
- Add the four solvers missing from the quartodoc list
(BatchingOptimizer, ForwardModel, NetworkRooflineModel, PlacementOptimizer)
and surface the orphan tutorials (01_pipeline_callbacks,
02_differential_explainer, 12_design_space_exploration) in the sidebar.
- Rename every reference to the now-deleted hello_world / llm_serving /
sustainability / 11_full_stack_audit tutorials to their current filenames.
- Add the missing @mlsysbook2024 entry to references.bib so whitepaper.qmd
no longer logs a citeproc warning.
- Fix the CLI sample on the parent site/index.qmd card to use real model
identifiers (Llama3_70B H100 --batch-size 1).
- Soften the Colab/Binder copy until launch buttons are wired in.
- Remove the duplicate "Differential Explainer" card on tutorials/index.qmd.
* release(mlsysim): add 0.1.0 release notes and runbook
- RELEASE_NOTES_0.1.0.md: GitHub-release-ready notes promoted from CHANGELOG
with install/quickstart copy and a "known limitations & gotchas" section
covering the editable-install issue, broken example scripts, and unpublished
slide tag.
- RELEASE.md: copy-pasteable runbook for cutting a release (pre-flight check,
tag, build, twine upload, docs deploy via workflow_dispatch, GitHub release,
and post-release verification).
- CHANGELOG.md: corrected the test count from 334 to the actual 367 currently
passing on dev.
* mlsysim: nest package layout, enable editable installs, clean lint
Restructure mlsysim into the standard nested layout (`mlsysim/mlsysim/...`)
so `pip install -e .` works out of the box. The previous flat layout used
a Hatch `sources = {"." = "mlsysim"}` prefix-add rewrite that the
`editables` backend cannot handle, breaking editable installs entirely.
Packaging
- pyproject.toml: drop `sources` rewrite, set `packages = ["mlsysim"]`,
add explicit `[tool.hatch.build.targets.sdist]` include list.
- Wheel and sdist now contain only the package and project metadata
(no `tests/`, `docs/`, `examples/`, `paper/`, `vscode-ext/` leakage).
- Update `pyright.exclude` for nested layout.
- Update GitHub source links in `docs/math.qmd` and
`docs/models-and-solvers.qmd` to point to `mlsysim/mlsysim/...`.
Lint configuration
- Add `[tool.ruff]` to pyproject.toml with sensible per-file ignores:
`__init__.py` re-export pattern (F401/F403/F405/F811),
`core/constants.py` star import from unit registry,
tests/examples idioms.
- `ruff check .` reports zero issues (down from 621).
Real bug fixes uncovered by lint cleanup
- `core/solver.py`: remove unused `from pydantic import BaseModel` that
was being shadowed by the local `BaseModel = ForwardModel` alias.
- `sim/simulations.py`: remove redundant local `Fleet` import that was
shadowing the module-level import and triggering F823 (referenced
before assignment) on the earlier `isinstance(..., Fleet)` check.
- `cli/commands/audit.py`, `cli/commands/eval.py`: narrow three bare
`except:` clauses to specific exception types.
- `tests/test_sota.py`: add the missing speculative-decoding ITL
assertion (`res_opt.itl < res_base.itl`) — `res_base` was previously
computed but never compared.
- `cli/commands/eval.py`: drop unused `is_json` local.
- `labs/components.py`: drop unused `energy` placeholder local.
Examples
- `examples/06_multi_objective_pareto.py`: rewrite around the actual
`BatchingOptimizerResult` API (which has no `pareto_front` attribute);
build the front explicitly by sweeping batch sizes through
`ServingModel` + `TailLatencyModel`, then highlight the optimum
returned by `BatchingOptimizer`.
- `examples/gemini_design_loop.py`: fix multi-line f-string syntax errors
(`f"\n[…]"` instead of an embedded literal newline) so the file imports
on every supported Python version.
Dev scripts
- `generate_appendix.py` and `paper/scripts/validate_anchors.py`: switch
from package-relative imports to absolute `from mlsysim... import` so
they run cleanly under the nested layout.
Docs / release notes
- `docs/getting-started.qmd`: replace the editable-install caveat with
`pip install -e ".[dev]"` (now supported).
- `RELEASE_NOTES_0.1.0.md`: drop the three "known limitations" entries
that this commit resolves (editable install, pareto example, gemini
example).
- `CHANGELOG.md`: add a "Packaging & Tooling" section describing the
layout change and the resolver bug fixes.
Verification
- `python -m pytest tests/` → 367 passed (was 367, no regressions).
- `ruff check .` → All checks passed.
- `pip install -e .` → succeeds; live source picked up.
- Fresh-venv wheel install + CLI smoke test → succeeds.
- `examples/06_multi_objective_pareto.py` and
`examples/gemini_design_loop.py` → both exit 0.
* fix(mlsysim): repair docs build + lab test after nested-package restructure
The 0.1.0 release prep moved the package from `mlsysim/` to `mlsysim/mlsysim/`
to support `pip install -e .`. Two CI jobs still depended on the old layout:
1. **Docs build (`mlsysim-preview-dev`)** — every tutorial and zoo page used
a hand-rolled `importlib.util.spec_from_file_location` block to load
`<repo>/mlsysim/__init__.py` directly from source. After the restructure,
that path no longer exists. Replaced the hack in 17 docs/.qmd files with
a plain `import mlsysim` — the package is already pip-installed in the
docs build environment via `pip install ".[docs]"`. Updated the matching
guidance in `contributing.qmd`.
2. **Lab static tests** — `test_no_localstorage_import` hard-coded
`mlsysim/labs/state.py`; updated to the new nested path
`mlsysim/mlsysim/labs/state.py`.
Verified locally: `pytest labs/tests/test_static.py::TestStateImplementation`
passes, and `quarto render docs/zoo/models.qmd` succeeds end-to-end.
80 lines
2.6 KiB
Python
80 lines
2.6 KiB
Python
import pytest
|
|
from mlsysim.models.types import TransformerWorkload
|
|
from mlsysim.hardware.registry import Hardware
|
|
from mlsysim.systems.registry import Systems
|
|
from mlsysim.core.solver import DistributedModel, ServingModel
|
|
from mlsysim.core.constants import Q_
|
|
|
|
# Cross-solver integration tests combining multiple features
|
|
pytestmark = pytest.mark.integration
|
|
|
|
|
|
def test_distributed_zero_lora_overlap():
|
|
model = TransformerWorkload(
|
|
name="Llama-3-70B",
|
|
architecture="Transformer",
|
|
parameters=Q_("70e9 param"),
|
|
layers=80,
|
|
hidden_dim=8192,
|
|
heads=64
|
|
)
|
|
fleet = Systems.Clusters.Frontier_8K
|
|
|
|
# Baseline
|
|
solver = DistributedModel()
|
|
base_res = solver.solve(model, fleet, batch_size=4096, tp_size=8, pp_size=4, zero_stage=0, is_lora=False, overlap_comm=False)
|
|
|
|
# With optimizations
|
|
opt_res = solver.solve(model, fleet, batch_size=4096, tp_size=8, pp_size=4, zero_stage=3, is_lora=True, overlap_comm=True)
|
|
|
|
# Memory should be radically smaller due to LoRA and ZeRO-3
|
|
assert opt_res.node_profile.memory_footprint < base_res.node_profile.memory_footprint
|
|
# Step latency should be lower due to comm overlap and smaller gradient comm size
|
|
assert opt_res.step_latency_total < base_res.step_latency_total
|
|
|
|
def test_serving_disaggregated_speculative():
|
|
target = TransformerWorkload(
|
|
name="Llama-3-70B",
|
|
architecture="Transformer",
|
|
parameters=Q_("70e9 param"),
|
|
layers=80,
|
|
hidden_dim=8192,
|
|
heads=64
|
|
)
|
|
draft = TransformerWorkload(
|
|
name="Llama-3-8B",
|
|
architecture="Transformer",
|
|
parameters=Q_("8e9 param"),
|
|
layers=32,
|
|
hidden_dim=4096,
|
|
heads=32
|
|
)
|
|
|
|
hw_prefill = Hardware.Cloud.H100
|
|
hw_decode = Hardware.Cloud.A100 # Change from L40S to A100 to pass hardware lookup
|
|
|
|
solver = ServingModel()
|
|
|
|
# Standard single node
|
|
res_base = solver.solve(target, hw_prefill, seq_len=1024, batch_size=1)
|
|
|
|
# Disaggregated + Speculative
|
|
res_opt = solver.solve(
|
|
target,
|
|
hw_prefill,
|
|
seq_len=1024,
|
|
batch_size=1,
|
|
decode_hardware=hw_decode,
|
|
network_bandwidth=Q_("100 GB/s"),
|
|
draft_model=draft,
|
|
draft_acceptance_rate=0.7
|
|
)
|
|
|
|
# ITL should be faster despite running decode on slower A100, due to
|
|
# speculative decoding amortizing the per-token cost across draft tokens.
|
|
assert res_opt.itl.magnitude > 0
|
|
assert res_opt.itl < res_base.itl, (
|
|
f"Speculative decoding should reduce ITL (got base={res_base.itl}, "
|
|
f"opt={res_opt.itl})"
|
|
)
|