c30f2a3bfd
Moves the mlsysim package from book/quarto/mlsysim/ to the repo root so it is importable as a proper top-level package across the codebase. Key changes: - mlsysim/fmt.py: new top-level module for all formatting helpers (fmt, sci, check, md_math, fmt_full, fmt_split, etc.), moved out of viz/ - mlsysim/viz/__init__.py: now exports only plot utilities; dashboard.py (marimo-only) is no longer wildcard-exported and must be imported explicitly by marimo labs - mlsysim/__init__.py: added `from . import fmt` and `from .core import constants`; removed broken `from .viz import plots as viz` alias - execute-env.yml: fixed PYTHONPATH from "../../.." to "../.." so chapters resolve to repo root, not parent of repo - 51 QMD files: updated `from mlsysim.viz import <fmt-fns>` to `from mlsysim.fmt import <fmt-fns>` - book/quarto/mlsys/: legacy shadow package contents cleaned up; stub __init__.py remains for backward compat - All Vol1 and Vol2 chapters verified to build with `binder build pdf`
🚀 mlsysim
The ML Systems Infrastructure & Modeling Platform
mlsysim is the high-performance, physics-grounded analytical engine powering the Machine Learning Systems textbook ecosystem (mlsysbook.ai). It provides a unified "Single Source of Truth" (SSoT) for modeling systems from sub-watt microcontrollers to exaflop-scale global fleets.
🏗 One Core, Multiple Worlds
mlsysim is designed to be the shared brain for every product in the ecosystem:
- 📚 The Book: Powers the precise "Napkin Math" and invariant checks in every chapter.
- 🧪 The Labs: Drives the interactive "Persona-based" simulations and trade-off explorers.
- 🛠 The Kits: Interfaces with physical hardware kits to bridge theory and measurement.
- 🔥 Tito (TinyTorch): Provides the analytical baseline for custom framework profiling.
📐 Architecture (The 3-Layer Stack)
The package is organized into three professional domains:
mlsysim.core(The Physics & Definitions):- Constants: Immutable physical truths (H100 specs, Grid carbon intensity).
- Formulas: The "Iron Laws" of ML systems (Stateless math via
pint). - Scenarios: Definitive workloads like Doorbell, AV, and GPT-4.
- Engine: The analytical solver for single-node performance (Latency, MFU, Energy).
mlsysim.sim(The Analytical Simulator):- Personas: Scale multipliers and constraints (Cloud Titan, Tiny Pioneer).
- Simulations: Domain logic (Sustainability, Reliability) that processes choices into ledgers.
- Ledger: The universal multi-dimensional scorecard.
mlsysim.viz(The Presentation):- Presentation logic: LaTeX formatting, Markdown helpers, and professional plotting.
🚀 Getting Started
Installation (Developer Mode)
To use mlsysim across the monorepo (Labs, Book, etc.), perform an editable install from the root:
pip install -e .
Quick Usage
import mlsysim
from mlsysim.sim import ResourceSimulation
# 1. Setup Scenario & Persona
scenario = mlsysim.Applications.Doorbell
persona = mlsysim.sim.Personas.TinyPioneer
# 2. Run an analytical simulation
sim = ResourceSimulation(scenario, persona)
ledger = sim.evaluate({"region": "Quebec", "duration_days": 365})
# 3. Inspect the results
print(f"Annual Carbon: {ledger.sustainability.carbon_kg:,.0f} kg CO2e")
🛡 Stability & Integrity
Because this core powers a printed textbook, we enforce strict Invariant Verification: All math cells in the book use check() guards. If a core formula change breaks the book's narrative, the build system will fail immediately.
👩💻 For Contributors & TAs
We built mlsysim to be extensible. To add a new domain lab, simply subclass BaseSimulation in the sim sub-package.
See the Developer Documentation for full API details and the "Wicked Sick" guide to building custom systems models.