This notebook introduces Cycle, a state def ToastingSystem exhibits, with a heating state whose do action invokes the heat-generation step and transitions that return ready and cancelled to idle; after running it you can trace the toaster’s own operating modes as the model itself defines them.
No earlier chapter built a state machine: the toaster’s modes have never been part of the model before this notebook. Building Cycle here means getting three things right from the start, not repairing them: Cycle needs a real owner, its heating state needs to invoke a real function rather than being an inert label, and ready and cancelled need a way back to idle or the chapter’s own name, “cycle,” would not be true of the model.
from pathlib import Path
import opensysml
from toaster.report import format_diagnostics
conn = opensysml.connect(version="v0.9.0")
STATE_CYCLE_OPEN = "state def Cycle {"
ENTRY = " entry; then idle;"
IDLE_STATE = " state idle;"
print(STATE_CYCLE_OPEN)
print(ENTRY)
print(IDLE_STATE)state def Cycle {
entry; then idle;
state idle;
idle is the machine’s own entry state: waiting holds for any solution, a pop-up toaster and tongs with a blowtorch alike.
HEATING_STATE = """\
state heating {
do action generateHeat : GenerateHeat;
}"""
print(HEATING_STATE) state heating {
do action generateHeat : GenerateHeat;
}
heating’s do action invokes GenerateHeat, not the full ApplyHeat: ApplyHeat’s own bread input has no value at this level of decomposition, and only its already-[0..*] parameters stay executable when left unbound in the OpenSysML runtime v0.9.0 (DEFERRED.md D-026, and D-026’s own addendum recording this exact case). GenerateHeat’s own input is already [0..*], so invoking it directly keeps the state genuinely executable: the invocation is real, confirmed by the runtime actually attempting it (an unbound parameter inside GenerateHeat raises from inside the state, not silently). GenerateHeat itself has no body yet, though: Chapter 6 built it as a typed signature only, so nothing is computed when it runs. The state’s own transition table is what changes here, not any quantity: once a state actually carries an action with a computed result and a duration, a trace could yield a derived quantity; that threshold is still not met here.
READY_CANCELLED = """\
state ready;
state cancelled;"""
print(READY_CANCELLED) state ready;
state cancelled;
ready and cancelled hold for any solution too: finishing and stopping on demand are both intents, not mechanisms.
TRIGGERED_TRANSITIONS = """\
transition first idle accept Start then heating;
transition first heating accept Finish then ready;
transition first heating accept Cancel then cancelled;"""
print(TRIGGERED_TRANSITIONS) transition first idle accept Start then heating;
transition first heating accept Finish then ready;
transition first heating accept Cancel then cancelled;
accept Start, accept Finish and accept Cancel name the events that move the machine between modes. The OpenSysML runtime v0.9.0 keeps a transition’s trigger only as a string and never resolves it against Start, Finish or Cancel: a typo, or a reference to a name the model never declares, loads without error and simply never fires (DEFERRED.md D-023). The tutorial’s own guard, language_gap_findings, catches what the runtime does not; the cell after the negative control below demonstrates it directly.
COMPLETION_TRANSITIONS = """\
transition first ready then idle;
transition first cancelled then idle;"""
print(COMPLETION_TRANSITIONS) transition first ready then idle;
transition first cancelled then idle;
These two transitions carry no accept: they fire as soon as their source state is entered, with no event required. They are what makes Cycle actually cycle: a finished or a cancelled run returns to idle, ready for another.
CYCLE_DEF = (
f"{STATE_CYCLE_OPEN}\n{ENTRY}\n{IDLE_STATE}\n{HEATING_STATE}\n{READY_CANCELLED}\n"
f"{TRIGGERED_TRANSITIONS}\n{COMPLETION_TRANSITIONS}\n}}"
)
print(CYCLE_DEF)state def Cycle {
entry; then idle;
state idle;
state heating {
do action generateHeat : GenerateHeat;
}
state ready;
state cancelled;
transition first idle accept Start then heating;
transition first heating accept Finish then ready;
transition first heating accept Cancel then cancelled;
transition first ready then idle;
transition first cancelled then idle;
}
Cycle is now a complete state def. It still needs an owner: nothing exhibits it yet.
# exhibit state cannot be added to ToastingSystem in a separate statement, so its
# full declaration is reprinted here with the new line included.
TOASTING_SYSTEM_INCREMENT = """\
abstract part def ToastingSystem {
perform action toastBread : ToastBread;
exhibit state cycle : Cycle;
}"""
print(TOASTING_SYSTEM_INCREMENT)abstract part def ToastingSystem {
perform action toastBread : ToastBread;
exhibit state cycle : Cycle;
}
ToastingSystem, not Toaster, is the subject the functional, logical and physical layers all describe (Chapter 1’s own ruling): Toaster is presently the tutorial’s only concrete realization of it. A functional mode machine belongs on the subject itself, so it is ToastingSystem that exhibits Cycle. Toaster, and any usage of it, inherits the machine and can execute it, the same way it already inherits and performs toastBread.
TOASTER_INCREMENT = f"{CYCLE_DEF}\n{TOASTING_SYSTEM_INCREMENT}"
source = Path("../../models/ch07-cumulative.sysml").read_text()
model = conn.load_from_content(source, strict=False)
assert model.ok, f"Model failed: {format_diagnostics(model.diagnostics)}"Cycle’s own transition table, drawn: the tutorial’s first state diagram.
from toaster.render import render_state_flow
from IPython.display import SVG
out_path = Path("../../figures/ch07-cycle-state.svg")
out_path.parent.mkdir(exist_ok=True)
render_state_flow(model, "ToasterDemo::Cycle", out_path)
SVG(filename=str(out_path))A state machine referencing an undefined transition target fails to parse. The negative control below points a transition at a state the machine never declares.
bad_source = """
package P {
item def Go;
state def S {
entry; then a;
state a;
transition first a accept Go then missing_state;
}
}
"""
bad = conn.load_from_content(bad_source, strict=False)
assert not bad.ok, "Expected failure for undefined transition target"
print(f"Negative control ok: bad.ok={bad.ok}")Negative control ok: bad.ok=False
The diagnostic reports an unresolved reference: missing_state was never declared as a state of S. This catches an undefined target; it says nothing about an undefined trigger, which the next cell probes directly.
typo_source = source.replace("accept Start then heating", "accept Strat then heating")
typo_model = conn.load_from_content(typo_source, strict=False)
assert typo_model.ok, "OpenSysML itself accepts the typo'd trigger with no diagnostic"
print(f"OpenSysML itself: typo_model.ok={typo_model.ok}")
from toaster.conformance import language_gap_findings
findings = [
f for f in language_gap_findings(typo_model) if f["rule"] == "unresolved-transition-trigger"
]
assert findings, "Expected the tutorial's own guard to flag the typo'd trigger"
# The rule's own constraint citation uses an em-dash; the printed form here uses a
# plain hyphen instead (a display-only substitution; the finding itself is untouched).
for finding in findings:
print({k: v.replace(chr(0x2014), "-") if isinstance(v, str) else v for k, v in finding.items()})OpenSysML itself: typo_model.ok=True
{'rule': 'unresolved-transition-trigger', 'constraint': "SysML v2.0 formal/2026-03-02: 8.3.18.9 TransitionUsage (/triggerAction : AcceptActionUsage), 8.3.18.8 TransitionFeatureMembership (validateTransitionFeatureMembershipTriggerAction), 8.3.17.2 AcceptActionUsage (PDF p. 341-342, payloadParameter) - a trigger is a structured, resolvable element, so an `accept` trigger's payload name must resolve to a defined element in scope", 'element': 'ToasterDemo::Cycle::@6', 'message': "transition ToasterDemo::Cycle::@6 accepts trigger 'Strat', whose payload 'Strat' resolves to no element in scope"}
The OpenSysML runtime loads the typo cleanly (the OpenSysML itself line printed above is the runtime’s verdict): Strat never fires, and nothing in the runtime says so; sysml-toolkit v0.9.1 resolves trigger names and warns on a broken reference (D-023). The tutorial’s own guard catches it: language_gap_findings flags Strat as an unresolved trigger, close enough to the locally-declared Start to be a plausible typo (D-023). The runtime has a real hole here, and the tutorial supplies the check that closes it: exactly the construct-and-analyze loop this tutorial builds throughout.
typo_out_path = Path("../../figures/ch07-cycle-state-typo.svg")
render_state_flow(typo_model, "ToasterDemo::Cycle", typo_out_path)
SVG(filename=str(typo_out_path))The same transition drawn with the typo’d trigger: the edge now reads accept Strat, visible in the picture the same way it is invisible to the OpenSysML runtime’s own loader.
cycle = model.find("ToasterDemo::ToastingSystem::cycle")
print(f"ToastingSystem::cycle: kind={cycle.kind!r}, id={cycle.id!r}")
normal = model.execute_state(
"ToasterDemo::Cycle", events=["Start", "Finish"], performer="ToasterDemo::nominal"
)
print(f"Start, Finish (run through nominal): {normal['states_visited']}")
assert normal["states_visited"] == ["idle", "heating", "ready", "idle"]ToastingSystem::cycle: kind='stateUsage', id='ToasterDemo::ToastingSystem::cycle'
Start, Finish (run through nominal): ['idle', 'heating', 'ready', 'idle']
ToastingSystem::cycle is a stateUsage, the exhibited occurrence of the Cycle state def; Toaster::cycle does not resolve by that name, the same way Toaster::toastBread does not, since both are inherited members of ToastingSystem, not redeclared on Toaster. That inheritance is a fact about the model’s structure, shown by model.find above, not by the trace below: in the OpenSysML runtime v0.9.0, execute_state’s performer argument has no effect on the result (a documented runtime gap, D-028); the same trace comes back whether performer names nominal, a usage that exhibits nothing at all, or is omitted entirely. The trace below runs Cycle’s own transition table: heating invokes GenerateHeat, ready follows Finish, and the machine returns to idle on its own, a real completion of the modeled cycle. No quantity is computed along the way; what changes is which mode the machine is in.
cancelled = model.execute_state("ToasterDemo::Cycle", events=["Start", "Cancel"])
print(f"Start, Cancel: {cancelled['states_visited']}")
assert cancelled["states_visited"] == ["idle", "heating", "cancelled", "idle"]
repeated = model.execute_state("ToasterDemo::Cycle", events=["Start", "Finish", "Start", "Finish"])
print(f"Start, Finish, Start, Finish: {repeated['states_visited']}")
assert repeated["states_visited"] == ["idle", "heating", "ready", "idle", "heating", "ready", "idle"]Start, Cancel: ['idle', 'heating', 'cancelled', 'idle']
Start, Finish, Start, Finish: ['idle', 'heating', 'ready', 'idle', 'heating', 'ready', 'idle']
Both traces above run against the same transition table the first diagram in this notebook already drew — idle → heating → ready → idle and idle → heating → cancelled → idle are two paths through that one picture, not two different machines.
Both traces are derived from Cycle’s own transition table, not entered as a choice: they show the machine can be run twice in a row and return to idle each time, catching a mistake in the table rather than establishing anything about the toaster in use. A trace like this is specification analysis, not a simulation of behavior.
The definitions printed above loaded without error, and model.find and execute_state both confirm Cycle is now part of the model, shown by the traces printed above.
Try the chapter exercise in exercises/ch07/exercise.ipynb: add a BrewCycle state machine mirroring Cycle exactly — an idle entry state, a brewing state whose do action invokes moveWater, two exit states, and completion transitions back to idle — and trace it with execute_state.