mirror of
https://github.com/harvard-edge/cs249r_book.git
synced 2026-07-16 06:07:17 -05:00
c53f3fe238
- Complete the MLSYSIM -> MLSys.im display-name migration across mlsysim/docs, instructors, and shared config (code identifiers stay lowercase mlsysim) - Fix broken TinyTorch module links (_ABOUT.html -> .html) - Route the navbar Subscribe action to the newsletter page so Safari content blockers stop hiding the #subscribe anchor - Add the Accelerator Memory Tiers figure to compute_infrastructure with a registry-driven log-log capacity/bandwidth scatter - Add four sourced cloud accelerator specs (Groq LPU, Graphcore GC200, Untether speedAI240, d-Matrix Corsair) feeding the local-SRAM tier - Remove the unshipped Coming Soon audio-lectures placeholder and related Binder/audio references
88 lines
3.5 KiB
Plaintext
88 lines
3.5 KiB
Plaintext
---
|
|
title: "Provenance"
|
|
subtitle: "Where MLSys·im numbers come from and how to audit them"
|
|
---
|
|
|
|
Every **Tier A** number in MLSys·im — registry entries and public sourced scalars — carries
|
|
structured lineage via the `Provenance` model. Citation managers and prose live outside
|
|
the package; MLSys·im stores audit metadata only.
|
|
|
|
`Provenance` answers "how do we know this number?" It is not a registry category. A number can
|
|
have provenance whether it lives under `Hardware`, `Systems`, `Infrastructure`, `Ops`,
|
|
`Scenarios`, or `Literature`. `Literature.*` is the registry for cited scalar anchors from
|
|
papers/tables; those entries use the same provenance machinery as every other sourced value.
|
|
|
|
::: {.callout-note}
|
|
## There is no `mlsysim.core.defaults`
|
|
Constants were reorganized into semantic registries (`Hardware`, `Models`, `Systems`,
|
|
`Infrastructure`, `Ops`, `Scenarios`, `Literature`) plus `engine.calibration`. See the [Zoo overview](zoo/index.qmd) and
|
|
[DATA_MODEL.md](DATA_MODEL.md).
|
|
:::
|
|
|
|
## Where constants live
|
|
|
|
| Namespace | Examples |
|
|
|:----------|:---------|
|
|
| **`Hardware.*`** | Peak FLOPs, HBM bandwidth, TDP — datasheet truth |
|
|
| **`Hardware.Tech.*`** | Technology-class latency, op energy, movement energy |
|
|
| **`Literature.*`** | MFU bands, Chinchilla ratio, communication and batch-size literature anchors |
|
|
| **`Infrastructure.Grids` / `Pricing` / `Capacity`** | Carbon, PUE, cloud \$ anchors |
|
|
| **`Systems.Reliability` / `Nodes` / `Racks` / `Fabrics` / `Clusters`** | MTTF, server/rack profiles, fabrics, fleet tiers |
|
|
| **`Ops.Monitoring` / `TrainingRunOverheads`** | PSI thresholds, KS coefficient, goodput-loss profiles |
|
|
| **`Scenarios.*`** | Executable workload + system + constraint bundles |
|
|
| **`ReferenceStats.*`** | Non-executable sourced world statistics and case-study anchors |
|
|
| **`engine.calibration`** | Solver/engine default kwargs — **not** cited in appendix tables |
|
|
|
|
Do **not** duplicate registry fields across namespaces (chip `unit_cost` lives on
|
|
`Hardware.Cloud.*` only).
|
|
|
|
## Registry entries
|
|
|
|
Hardware and model zoo entries attach provenance via `metadata.provenance`:
|
|
|
|
```python
|
|
import mlsysim
|
|
|
|
hw = mlsysim.Hardware.Cloud.H100
|
|
prov = hw.metadata.provenance
|
|
print(prov.kind, prov.ref)
|
|
```
|
|
|
|
## Literature scalars
|
|
|
|
Standalone scalar anchors use the `Sourced` type and `sourced()` factory:
|
|
|
|
```python
|
|
mfu = mlsysim.Literature.Training.MfuHigh
|
|
print(mfu, mfu.provenance.ref)
|
|
```
|
|
|
|
Browse the full catalog in the [Literature Zoo](zoo/literature.qmd).
|
|
|
|
## Audit gates
|
|
|
|
Contributors should run before opening a PR:
|
|
|
|
```bash
|
|
python -m mlsysim.tools.audit_provenance --scope all --strict
|
|
```
|
|
|
|
| Gate | What it catches |
|
|
|:-----|:----------------|
|
|
| Registry metadata | Hardware/model nodes without `metadata.provenance` |
|
|
| Sourced scalars | `Literature.*`, `Ops.*`, `ReferenceStats.*`, `Infrastructure.Capacity.*`, `engine.calibration.*` without lineage |
|
|
| Appendix lineage | Stale paths or missing provenance in assumption appendices |
|
|
|
|
Downstream lineage checks consume MLSys·im through public registry paths; the
|
|
package audit stays focused on package registries and sourced scalars.
|
|
|
|
Full contributor rules: [Contributing — Provenance](contributing.qmd#provenance-rules).
|
|
|
|
## Canonical Python paths
|
|
|
|
Use **nested registry paths** in Python (`Hardware.Cloud.H100`, `Models.Language.Llama3_8B`).
|
|
The CLI accepts short names (`mlsysim eval Llama3_8B H100`) via internal lookup — that
|
|
convenience does not apply to `import mlsysim` code.
|
|
|
|
See [API Stability](api-stability.md#registry-paths).
|