3a6e5c5ef6
Added formal citations to: - SingleNodeSolver (Roofline Model, Williams 2009) - DistributedSolver (3D Parallelism, Shoeybi 2019; PipePipe, Narayanan 2019) - ServingSolver (LLM Scaling, Pope 2023) - ReliabilitySolver (Young-Daly 1974/2006) - Sustainability/Economics (Patterson 2021; Barroso 2018) - Core Formulas (Amdahl 1967; Patarasuk 2009)
🚀 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.