c24ab1ccb9
Refactors numerous embedded TikZ diagrams in Quarto markdown files to external SVG images. This improves rendering performance, streamlines content management, and enhances cross-platform consistency. Introduces interactive "Napkin Math" `callout-notebook` blocks, featuring Python code to generate dynamic visualizations for key system trade-offs and scenarios. Expands the `mlsysim` library with new constants and plotting utilities to support these interactive calculations and comparisons.
🚀 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.