docs: add The MLSysim Philosophy explaining analytical rigor and no hallucinations

mlsysim/docs/philosophy.qmd

@@ -0,0 +1,69 @@
+---
+title: "The MLSys·im Philosophy"
+subtitle: "First-Principles Analytical Modeling with Zero Hallucinations"
+---
+
+MLSys·im was built to solve a specific problem in machine learning systems education and engineering: **the gap between abstract intuition and cycle-accurate simulation.**
+
+When reasoning about ML infrastructure—whether sizing a serving fleet for LLaMA-3 or estimating the carbon footprint of a 10,000-GPU training run—engineers often rely on messy spreadsheets filled with hidden assumptions, unit-conversion errors, and "magic numbers." Conversely, cycle-accurate simulators require weeks of setup, deep proprietary knowledge, and hours to run a single workload.
+
+MLSys·im provides a third path: **First-Principles Analytical Modeling**.
+
+To achieve textbook-grade rigor, the framework is built on four non-negotiable design principles.
+
+---
+
+## 1. No Hallucinations, No Magic Numbers
+
+In an era of generative AI, it is easy to ask a language model to "estimate the latency of ResNet-50 on an A100." The model will confidently output a number—often a hallucination based on an unverified blend of internet forum posts.
+
+**MLSys·im does not guess.** It computes.
+
+Every single number in the MLSys·im ecosystem is mathematically derived from explicit, vetted constants. If a solver needs the memory bandwidth of an H100 GPU, it does not use a hardcoded float `3000.0`. It queries the `Hardware` registry, which returns a `Sourced` object containing exactly `3.35 TB/s`, complete with a `Provenance` struct linking directly to the NVIDIA H100 PCIe Datasheet.
+
+If a student or engineer asks, *"Where did this number come from?"*, the framework provides the exact URL, the academic paper, or the empirical methodology used to derive it. There are no "magic numbers" hidden in the source code.
+
+## 2. Dimensional Strictness (SI Units Everywhere)
+
+The most common source of error in back-of-the-envelope systems analysis is unit mismatch (e.g., dividing gigabytes by gigabits per second without a factor of 8).
+
+To physically prevent these errors, MLSys·im enforces **strict dimensional analysis at runtime** using the `pint` unit library.
+
+*   A workload does not require `140` memory; it requires `140 * ureg.GB`.
+*   A network does not deliver `400` bandwidth; it delivers `400 * ureg.Gbps`.
+*   If a user accidentally attempts to add a latency (`ms`) to a throughput (`1/s`), the Python interpreter will instantly raise a `DimensionalityError`.
+
+By forcing every input, intermediate variable, and output to carry physical SI units, the framework guarantees that the mathematical "physics" of the engine are structurally sound.
+
+## 3. Analytical Speed over Cycle-Accurate Simulation
+
+MLSys·im is an **analytical engine**, not a discrete-event simulator.
+
+We do not track individual packets across a network switch, nor do we simulate warp-scheduler occupancies inside a GPU streaming multiprocessor. Instead, we use closed-form equations (like the Roofline model, the $\alpha$-$\beta$ communication model, and Erlang-C queueing theory) to establish the **hard physical bounds** of a system.
+
+By relying on analytical math ($Y = f(X)$):
+*   **Evaluation is instantaneous:** A full-stack analysis of a 100,000-GPU cluster takes less than 0.3 seconds on a standard laptop.
+*   **Bottlenecks are explicit:** The math makes it trivial to calculate gradients (Sensitivity Analysis) or invert equations to solve for required hardware (Synthesis Analysis).
+*   **Intuition is preserved:** Analytical models expose *why* a system is slow (e.g., "Arithmetic Intensity < Ridge Point"), whereas detailed simulations only tell you *that* it is slow.
+
+To bridge the gap between theoretical peaks and realized performance, MLSys·im introduces a single, explicit **Efficiency Coefficient ($\eta$)** into compute-bound solvers (like Model FLOPs Utilization, MFU). This clearly separates the raw physics of the hardware from the software friction of the framework.
+
+## 4. Separation of Demand and Supply
+
+A recurring anti-pattern in systems modeling is tightly coupling a model to the hardware it runs on (e.g., writing a script specifically for "GPT-3 on A100").
+
+MLSys·im enforces a strict **Demand vs. Supply abstraction**:
+*   **Demand (Workloads):** A `TransformerWorkload` only knows about its parameters, sequence length, and arithmetic intensity. It has no concept of what a GPU is.
+*   **Supply (Hardware/Systems):** A `HardwareNode` only knows about its peak TFLOP/s, memory hierarchy, and power draw. It has no concept of what a Transformer is.
+
+The magic happens in the **Solvers** (Layer E). Solvers act as the brokers. They take the abstract Demand, project it onto the physical Supply, and apply the mathematical laws of the universe to predict the outcome.
+
+This decoupling means you can define a workload once and instantly sweep it across every hardware device in the `Silicon Zoo`, from a 1-Watt microcontroller to a 100-MegaWatt supercomputer.
+
+---
+
+## Conclusion
+
+MLSys·im is the executable companion to the [Machine Learning Systems](https://mlsysbook.ai) textbook. It is designed to replace "gut feelings" and fragile spreadsheets with a composable, unit-safe, mathematically rigorous engineering tool.
+
+When MLSys·im tells you a system will bottleneck on memory bandwidth, you can trust the math, check the units, and audit the datasheets.