Runtime API

Move playhead to a retained scan and return that snapshot.

Move playhead backward in time by seconds and return snapshot.

Return rung firings for the given scan (default: playhead).

Returns PMap[int, PMap[str, Any]] mapping each rung index that fired (had any write, even if all were filtered by PDG) during the scan to the filtered {tag_name: value_written} map. Synthesized on demand from per-rung range-encoded timelines (:class:RungFiringTimelines); rungs with no timeline covering scan_id contribute nothing.

Populated uniformly by both the non-debug (step() / run()) and debug (DAP pyrungStepScan / continue) scan paths via ScanContext.capturing_rung.

Values are attempted writes, including a later writer reasserting the already-pending value. Transition consumers compare committed state; causal execution consumers retain the exact writer occurrence.

Return changed tag values between two retained historical scans.

Explain what caused a tag to transition.

Recorded (default, to omitted): walks recorded history backward from the transition. Returns None if no transition was found. With deep=True, each fired rung's steady enablers are recursively explained through their establishing transitions or an observed writer of their current value. Non-firing static writers are not swept into the result. Terminals are classified in :attr:~pyrung.core.analysis.causal.CausalChain.roots.

Projected (to=value): projects forward from the current state, finding reachable paths that would drive the tag to value. Returns a CausalChain with mode='projected' (reachable) or mode='unreachable' (stranded, with blockers). Never returns None in projected mode.

Parameters:

Returns:

Trace the downstream effects of a tag transition.

Recorded (default, from_ omitted): walks recorded history forward from an actual transition. Returns None if no transition was found.

Projected (from_=value): what-if analysis — if the tag transitioned from value right now, what downstream effects would follow? Returns mode='projected' (possibly empty steps for dead-end) or mode='unreachable' if the trigger can't fire. Never returns None in projected mode.

Parameters:

Returns:

Explain how tags reached their current values from a snapshot.

No history required. Walks the program graph backward from each tag, using the current state as evidence. Terminates at external inputs.

Multiple tags produce one unified tree — a single explanation consistent with all observations.

Parameters:

Returns:

Find an input-change sequence that reaches a target state.

For a target with more than one route — a Bool (Running, Running == False) or a word value (State == 5) — PILOT never reports ambiguous: it picks a deterministic default route, reaches the goal, and records where it went on Path.route. Exclude a reported route with avoid= and PILOT will look for another.

avoid X = do not take a path that depends on X. It excludes routes, operator actions, and observed scan states that satisfy the predicate — momentary commands are treated as actions, not just settled states (so avoid=C_Complete will not press C_Complete even though it settles back to rest). A path is excluded if it depends on the avoided condition at any of these three gates, and if every path is excluded the returned Path is unreachable with a reason that names the violated avoid condition(s).

Parameters:

Returns:

True if tag has a reachable clear path from the current state.

Convenience predicate: cause(tag, to=resting).mode != 'unreachable'. For the underlying chain (witness or blockers), call cause() directly.

Tags marked external=True always return True — the recovery path exists outside the ladder by declaration. When assume is provided the external shortcut is skipped so the analysis runs with the given overrides.

Parameters:

Create an independent runner from retained historical state.

Parameters:

Create an independent runner from a retained historical snapshot.

Reconstruct historical state, preferring compiled replay when supported.

Reconstruct the rung-trace dict for a historical scan.

Runs the same replay walk as replay_to up to target_scan_id - 1 on the plain scan path, then drives _scan_steps_debug for target_scan_id so the replay fork's _current_rung_traces gets populated. Returns a copy of that dict; the replay fork is discarded.

The _replay_mode guards in _commit_scan (monitors, breakpoints) and _set_rtc_and_record cover the debug path too — both generators funnel through the same commit sink.

A one-slot cache (_cached_replay_trace) hits when the same target_scan_id is requested back-to-back. It is cleared on any tip advance (_run_single_scan) and on reset paths that reset the log (reboot, stop→run, via _clear_retained_debug_trace_caches).

Traces only exist for scans that actually executed — the fork anchor / initial scan was never stepped in debug mode — so target_scan_id must be strictly greater than _initial_scan_id.

Transition PLC to STOP mode.

Power-cycle the runner and return the reset state.

Reboot is destructive: tags reset to defaults (except battery-preserved retentive values), state.scan_id and state.timestamp return to 0. Because post-reboot scan_ids would alias pre-reboot entries in every sparse channel (patches, forces, rtc_base_changes, dts), the scan log and checkpoints are reset to a fresh recording session rooted at the post-reboot scan 0. Pre-reboot history is not replay-addressable — users who need that should fork() before rebooting.

Set the current RTC value for the runner.

Queue tag values for next scan (one-shot).

Values are applied at the start of the next step() call, then cleared. Use for momentary inputs like button presses.

Parameters:

Persistently override a tag value until explicitly removed.

The forced value is applied at the pre-logic force pass (phase 3) and re-applied at the post-logic force pass (phase 5) every scan. Logic may temporarily diverge the value mid-scan, but the post-logic pass restores it before outputs are written.

Forces persist across scans until unforce() or clear_forces() is called. Multiple forces may be active simultaneously.

If a tag is both patched and forced in the same scan, the force overwrites the patch during the pre-logic pass.

Parameters:

Raises:

Remove a single persistent force override.

After removal the tag resumes its logic-computed value starting from the next scan.

Parameters:

Remove all active persistent force overrides.

All forced tags resume their logic-computed values starting from the next scan.

Temporarily apply forces for the duration of the context.

On entry, saves the current force map and adds the given overrides. On exit (normally or on exception), the exact previous force map is restored — forces that existed before the context are reinstated, and forces added inside the context are removed.

Safe for nesting: inner forced() contexts layer on top of outer ones without disrupting them.

Parameters:

with plc.forced({"AutoMode": True, "Fault": False}):
    plc.run(5)
# AutoMode and Fault forces released here

Call callback(current, previous) after commit when tag value changes.

Create a breakpoint builder evaluated after each committed scan.

Accepts Tag/Condition expressions (implicit AND) or a single callable predicate receiving SystemState.

Execute one full scan cycle and return the committed state.

Execute up to cycles scans, stopping early on pause breakpoints.

Parameters:

Returns:

Run until simulation time advances by N seconds or a pause breakpoint fires.

Parameters:

Returns:

Run until condition is true, pause breakpoint fires, or max_cycles reached.

Accepts Tag/Condition expressions (implicit AND) or a single callable predicate receiving SystemState.

Parameters:

Returns:

Create a copy of this harness installed on plc.

The fork inherits the parent's committed state — including each bool timer's accumulator registers — so the dwell carries over with no re-seed; only the (stateless) timer instructions and the fractional remainder are copied. This is the seam the synthesis-overlay install grows into.

Remove couplings for the named feedback tags.

After unlinking, the Harness no longer synthesizes feedback for these tags — they become free inputs the caller can steer directly. Models a broken sensor or fault scenario.

Iterate over all discovered couplings (bool and profile).

Yield every harness-owned :class:AdvanceProfile.

This is the static reading of "En drives Fb toward a threshold" that PILOT's accumulator resolver consumes exactly like a timer's profile — so how(Fb >= threshold) learns "hold En, coast N scans" without running anything.

Bool couplings are real synthesized on/off-delay instructions. They do not belong to the user's :class:Program, so a program-only walk cannot see them; expose their own profiles here instead of making consumers understand synthesis-private accumulator names. An analog coupling is a per-scan profile tick with no instruction owner, so its adapter also lives here.

The comment-field serialization: ramp:up=<up>|down=<down>.

The comment-field serialization: approach:toward=<toward>|rate=<rate>.

The comment-field serialization: pulse:on_dwell=<..>|off_dwell=<..>.