CanaryScheduleScenario
Economics scenarios · Implementation: mlsysim/engine/scenario_definitions/economics.py.
Construct this scenario with keyword inputs. The fields below show the types and defaults declared by this class.
A staged rollout that needs samples_per_variant guardrail samples per stage at request_rate; stages is the configured ladder of (traffic share, duration).
Optional (added 2026-10-20): label_delay is the time from admission to a verdict, so labeled_by_completion counts the candidate tasks whose labels exist when the ladder ends (admitted at least that long before the end).
Notes
Equation: Admission counts integrate share*rate over stages; labeled counts truncate admissions at total_time-label_delay.
Assumptions: Constant request rate within every stage and one deterministic label delay. Set label_delay before requesting labeled_by_completion.
Excludes: Label failures, stochastic traffic, and power calculations beyond the supplied sample target.
References
Derivation: Each stage contributes traffic_share*request_rate*duration admissions. Only admissions before completion-label_delay have available labels at completion, so the labeled count integrates each stage only up to that cutoff. Collection time delegates to mlsysim.physics.statistics.calc_sample_collection_time.
Examples
>>> from mlsysim import Scenarios
>>> s = Scenarios.CanaryGuardrailSchedule
>>> s = s.variant(label_delay=s.total / 2)
>>> s.labeled_by_completion <= s.admitted_by_completion
TrueAttributes
| Name | Description |
|---|---|
| admitted_by_completion | Candidate tasks admitted over the whole ladder. |
| first_stage_buffer | Dimensionless first-stage duration divided by its minimum collection time. |
| label_delay | |
| labeled_by_completion | Candidate tasks whose verdicts have arrived when the last stage ends. |
| request_rate | |
| samples_per_variant | |
| stages | |
| total | Total rollout duration in hours, summing staged durations without overlap. |
Methods
| Name | Description |
|---|---|
| stage_minimum | Hours needed to collect the sample target at the supplied traffic share. |
stage_minimum
engine.scenario_types.CanaryScheduleScenario.stage_minimum(share)Hours needed to collect the sample target at the supplied traffic share.
Equation: calc_sample_collection_time(samples_per_variant, request_rate, share).to('hour').
samples_per_variant
Type: float.
Declared default: required.
request_rate
Type: Quantity.
Declared default: required.
stages
Type: List[Any].
Declared default: required.
label_delay
Type: Optional[Quantity].
Declared default: None.
total
engine.scenario_types.CanaryScheduleScenario.total
Total rollout duration in hours, summing staged durations without overlap.
Equation: sum((d for _, d in stages), Q_(0, 'hour')).to('hour').
first_stage_buffer
engine.scenario_types.CanaryScheduleScenario.first_stage_buffer
Dimensionless first-stage duration divided by its minimum collection time.
Equation: share, duration = stages[0]; (duration / stage_minimum(share)).to('').magnitude.
admitted_by_completion
engine.scenario_types.CanaryScheduleScenario.admitted_by_completion
Candidate tasks admitted over the whole ladder.
Equation: sum(((share * request_rate * d).to('').magnitude for share, d in stages)).
labeled_by_completion
engine.scenario_types.CanaryScheduleScenario.labeled_by_completion
Candidate tasks whose verdicts have arrived when the last stage ends.
Equation: Sum traffic_share * request_rate * max(0, min(stage_end, total_time - label_delay) - stage_start) over stages.