mirror of
https://github.com/harvard-edge/cs249r_book.git
synced 2026-03-11 17:49:25 -05:00
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`
85 lines
2.7 KiB
Python
85 lines
2.7 KiB
Python
# ledger.py
|
|
"""
|
|
MLSys Scorecard Module
|
|
======================
|
|
The multi-dimensional 'Scorecard' for MLSys simulations.
|
|
It tracks metrics across four primary engineering axes:
|
|
Performance, Sustainability, Economics, and Reliability.
|
|
"""
|
|
|
|
from dataclasses import dataclass, field
|
|
from typing import Optional, Dict, Any
|
|
import pandas as pd
|
|
from ..core.constants import ureg, Q_
|
|
|
|
@dataclass(frozen=True)
|
|
class PerformanceMetrics:
|
|
"""🚀 Performance: Speed and Utilization metrics."""
|
|
latency: Q_
|
|
throughput: Q_
|
|
mfu: float
|
|
hfu: float
|
|
bottleneck: str
|
|
|
|
@dataclass(frozen=True)
|
|
class SustainabilityMetrics:
|
|
"""🌍 Sustainability: Environmental impact and resource efficiency."""
|
|
energy: Q_
|
|
carbon_kg: float
|
|
pue: float
|
|
water_liters: float
|
|
|
|
@dataclass(frozen=True)
|
|
class EconomicMetrics:
|
|
"""💰 Economics: Total Cost of Ownership (TCO) and unit economics."""
|
|
capex: float
|
|
opex: float
|
|
tco: float
|
|
cost_per_million: float
|
|
|
|
@dataclass(frozen=True)
|
|
class ReliabilityMetrics:
|
|
"""🛡️ Reliability: Resilience, uptime, and recovery metrics."""
|
|
mttf: Q_
|
|
goodput: float
|
|
recovery_time: Q_
|
|
|
|
@dataclass(frozen=True)
|
|
class SystemLedger:
|
|
"""
|
|
The Universal Scorecard for all MLSys simulation results.
|
|
Binds the four dimensions into a single immutable result object.
|
|
"""
|
|
performance: PerformanceMetrics
|
|
sustainability: SustainabilityMetrics
|
|
economics: EconomicMetrics
|
|
reliability: ReliabilityMetrics
|
|
|
|
mission_name: str
|
|
track_name: str
|
|
choice_summary: str
|
|
|
|
def validate(self) -> None:
|
|
"""Ensures physical invariants are maintained."""
|
|
assert 0 <= self.performance.mfu <= 1.0, f"MFU {self.performance.mfu} must be between 0 and 1"
|
|
assert self.performance.latency.m >= 0, "Latency cannot be negative"
|
|
assert self.sustainability.carbon_kg >= 0, "Carbon footprint cannot be negative"
|
|
|
|
def to_dict(self) -> Dict[str, Any]:
|
|
"""Flattens the ledger into a simple dictionary for JSON/UI consumption."""
|
|
return {
|
|
"mission": self.mission_name,
|
|
"track": self.track_name,
|
|
"choice": self.choice_summary,
|
|
"latency_ms": self.performance.latency.m_as("ms"),
|
|
"throughput_sps": self.performance.throughput.m_as("1/second"),
|
|
"mfu_pct": self.performance.mfu * 100,
|
|
"carbon_kg": self.sustainability.carbon_kg,
|
|
"tco_usd": self.economics.tco,
|
|
"goodput_pct": self.reliability.goodput * 100
|
|
}
|
|
|
|
def to_df(self) -> pd.DataFrame:
|
|
"""Converts the metrics to a single-row Pandas DataFrame for easy plotting."""
|
|
return pd.DataFrame([self.to_dict()])
|