Follow a Calculation Through the Code

Find the inputs, equations, and result behind a serving scenario.

A named scenario connects an input configuration to a calculation. To understand its result, follow that connection through the implementation. The same route helps a contributor find the file that owns a proposed change.

Start from the public call

The named serving case below selects a workload, a device, a context length, and a batch size. Its result property invokes the serving model.

from mlsysim import Scenarios

case = Scenarios.Llama3_70B_ServingH100
result = case.result
print("Scenario type:", type(case).__name__)
print("Result type:", type(result).__name__)
print("Fits modeled memory:", result.feasible)

Scenario type: ServingScenario
Result type: ServingResult
Fits modeled memory: False

Feasibility is part of the result. A latency estimate alone does not establish that the selected workload fits the device. For an introduction to the public interfaces and their different scopes, see Choosing a Python API.

Find the owner of each part

The serving domain uses the same name across scenario definitions, named configurations, and result schemas. These files have different responsibilities.

Part	File under mlsysim/engine/	What to read
Named inputs	scenario_catalog/serving/foundations.py	Llama3_70B_ServingH100: the selected workload, hardware, and scenario assumptions
Typed scenario	scenario_definitions/serving.py	ServingScenario: its input fields and result property
Solver	solvers/serving.py	ServingModel.solve: the parameters, accounting, validity regime, and exclusions
Result	result_types/serving.py	ServingResult: returned fields, units, and feasibility semantics

ServingScenario.result passes the configured inputs to ServingModel.solve. The solver combines reusable equations and shared serving accounting. Its imports point to the specific owners: transformer work in physics/transformer.py, KV storage in physics/memory.py, and the shared decode calculation in engine/solvers/_decode.py. Read the solver’s docstring before interpreting a helper in isolation; it states which costs the composed estimate includes.

The serving scenario reference links related contracts. Each class page identifies the file that defines it. The domain directory follows the same organization for training, communication, data, and the other modeling subjects.

Keep public imports stable

Textbooks and applications continue to import Scenarios, mlsysim.solvers, and the established scenario and result classes. The modules engine/scenario_types.py, engine/scenarios.py, and engine/results.py forward those imports to the domain implementations. They provide compatibility; a calculation has one implementation in its defining module.

Historical class metadata is preserved for serialization compatibility. It may therefore identify the older public module rather than the file that now owns the class. Use the source locations in the generated reference when navigating the implementation.

A domain describes a modeling subject, not a textbook volume. A serving scenario can support several volumes, a lab, and a paper without moving or acquiring a second implementation.

Make a change reviewable

First identify whether the proposal changes a specification, a scenario input, an equation, or a result’s presentation. Edit its owner. A hardware specification belongs with its sourced registry data; a different context length belongs in a scenario configuration; a different accounting assumption belongs with the calculation and its documented contract.

For serving behavior, start with tests/test_physical_contracts.py, tests/test_shared_accounting.py, and tests/test_solver_suite.py. tests/test_calculation_scenarios.py exercises named cases. The test directory’s README.md maps these checks to the broader suite. Documentation examples check that the stated calls run; physical contracts check the calculation’s units, accounting, and limiting behavior.

A source move should preserve those behaviors. A numerical correction needs a separate explanation of the changed assumption and its downstream consequences. Run the modeling documentation checks, then compare the affected textbook and paper consumers using the release runbook’s downstream snapshot workflow. Surface changed prose claims for editorial review rather than silently updating their numbers.