engine.scenarios.Scenario
engine.scenarios.Scenario()Concrete executable case: a workload on a system with constraints.
application names the product/domain context, while the scenario itself is what the simulator can evaluate. Model facts stay in Models.*; hardware and fleet facts stay in Hardware.* / Systems.*.
Attributes
| Name | Description |
|---|---|
| is_distributed | Identify whether the scenario supplies a fleet object. |
Methods
| Name | Description |
|---|---|
| evaluate | Compose feasibility, performance, and annual accounting summaries. |
| validate | Raise when the scenario’s implemented feasibility or latency check fails. |
evaluate
engine.scenarios.Scenario.evaluate(batch_size=1, precision='fp16')Compose feasibility, performance, and annual accounting summaries.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| batch_size | int | Positive batch count forwarded to the selected performance solver. Its work unit follows that solver: samples for generic single-node inference and the distributed solver’s default training convention. | 1 |
| precision | str | Registered weight format used for weight size and performance. | 'fp16' |
Returns
| Name | Type | Description |
|---|---|---|
| SystemEvaluation | Three levels containing status, explanation, and metrics: weight/data feasibility, latency/SLA performance, and annual carbon/TCO estimates. Results include quantities with units; carbon_kg and tco_usd are scalars in kilograms and USD. A FAIL level does not stop later calculations. |
Notes
Equation: feasible = (weight_bytes <= one_accelerator_capacity) and not data_stalled. Performance passes when no latency SLA is supplied or modeled_latency <= sla_latency. Macro metrics come from EconomicsModel with duration_days=365 and its other default assumptions.
Assumptions: a Fleet uses DistributedModel; a HardwareNode uses SingleNodeModel. The initial memory check is weights on one accelerator, even for a Fleet. The single-node accounting branch constructs a one-node fleet with an Ethernet_10G fabric. Declared data_rate is checked through DataModel. Macro status is always PASS because it has no threshold here.
Excludes: validation of target_accuracy or power_budget (stored fields not evaluated by this method), KV-aware serving capacity, allocator reserve, an explicit training-memory feasibility test at the first level, and matching macro utilization to the performance result. Solver defaults must be reviewed before treating the combined scorecard as a deployment.
References
Derivation: this orchestration method composes existing solver results and applies explicit comparisons to weight capacity, data supply, and latency. It does not introduce a new performance law; annual economics is a separate default scenario rather than measured operating cost.
Examples
>>> from mlsysim import Scenario, Models, Hardware
>>> scenario = Scenario(name='Example', description='Single device', workload=Models.Vision.ResNet50, system=Hardware.Cloud.H100)
>>> result = scenario.evaluate()
>>> result.feasibility.metrics['weight_size'] == scenario.workload.size_in_bytes('fp16')
True
>>> result.macro.status
'PASS'validate
engine.scenarios.Scenario.validate(batch_size=1, precision='fp16')Raise when the scenario’s implemented feasibility or latency check fails.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| batch_size | int | Positive batch count forwarded unchanged to evaluate. | 1 |
| precision | str | Registered numeric format forwarded unchanged to evaluate. | 'fp16' |
Returns
| Name | Type | Description |
|---|---|---|
| bool | True when the feasibility and performance levels do not report FAIL. |
Raises
| Name | Type | Description |
|---|---|---|
| OOMError | The first evaluation level fails, including a data-pipeline failure as well as insufficient single-accelerator weight capacity. | |
| SLAViolation | The modeled latency exceeds the supplied SLA after feasibility passes. |
Notes
Equation: validate returns True iff evaluate’s feasibility and performance statuses are not FAIL; feasibility failures are raised first.
Assumptions: evaluate defines the entire check scope. This method reruns that evaluation, including annual accounting, rather than using a cache.
Excludes: checks for target_accuracy, power_budget, macro thresholds, KV residency, physical deployment safety, and validity of every modeling assumption. A passing result covers only the implemented comparisons.
References
Derivation: translate the two evaluation statuses into exceptions in feasibility-first order. No new numerical calculation is performed beyond the delegated scenario evaluation.
Examples
>>> from mlsysim import Scenario, Models, Hardware
>>> scenario = Scenario(name='Example', description='Single device', workload=Models.Vision.ResNet50, system=Hardware.Cloud.H100)
>>> scenario.validate()
True