canvas_engineering.clock_ir

Composable AST for region firing rules. ClockExpr nodes can be attached to a ClockSpec via the expr= field; when set, the expression supersedes the flat mode / period / event_source fields. The full IR serializes to a plain dict for JSON persistence.

Base

canvas_engineering.clock_ir.ClockExpr

Base class for clock expression AST nodes.

evaluate(ctx)

Evaluate this expression in the given context.

from_dict(d) classmethod

Deserialize from a dict. Dispatches on the 'type' key.

to_dict()

Serialize to a JSON-compatible dict.

canvas_engineering.clock_ir.ClockContext dataclass

Runtime context for evaluating clock expressions.

Attributes:

Name	Type	Description
external_t	int	Current external timestep.
summaries	Optional[Dict[str, Dict[str, float]]]	Residual summaries dict {region: {kind: float}}.
boundary	Optional[str]	Optional named boundary event this step.
last_fired	int	Timestep the owning region last fired (or -1 if never).
cooldown_until	int	Timestep until which cooldown is active (0 if none).

Leaves

canvas_engineering.clock_ir.Periodic

Bases: ClockExpr

Fire every period steps in the given time domain.

canvas_engineering.clock_ir.OnEvent

Bases: ClockExpr

Fire when a residual summary crosses a threshold.

The source string has the format "region_name.kind_name" and is looked up in ctx.summaries. At least one of gt or lt must be supplied; when both are given the condition is gt < val < lt (i.e., value must be within a band).

canvas_engineering.clock_ir.BoundaryExpr

Bases: ClockExpr

Fire on a named lifecycle boundary event.

Combinators and decorators

canvas_engineering.clock_ir.And

Bases: ClockExpr

Fire when both children fire.

canvas_engineering.clock_ir.Or

Bases: ClockExpr

Fire when either child fires.

canvas_engineering.clock_ir.Not

Bases: ClockExpr

Invert: fire when the child does NOT fire.

canvas_engineering.clock_ir.Cooldown

Bases: ClockExpr

Suppress re-firing for steps steps after the child fires.

canvas_engineering.clock_ir.MaxSilence

Bases: ClockExpr

Force fire after steps steps of silence regardless of child.

Sugar

canvas_engineering.clock_ir.periodic(n=1, domain='external')

Create a Periodic clock expression.

canvas_engineering.clock_ir.on(source, gt=None, lt=None, domain='external')

Create an OnEvent clock expression.

canvas_engineering.clock_ir.boundary(name)

Create a BoundaryExpr clock expression.