Scheduling API¶

Schedules describe save and action times during relaxation. Prefer the modern identifier-first form, such as every("step", 10).

at ¶

at(identifier: str, value: Any = True) -> When

Create a condition matching one exact clock value or event.

Parameters:

Name	Type	Description	Default
`identifier`	`str`	Clock key or event such as `"step"`, `"time"`, `"convergence"`, or `"stage_end"`.	required
`value`	`Any`	Exact value to match. Boolean events default to true.	`True`

Returns:

Type	Description
`When`	Schedule condition, for example `at("step", 10)`.

every ¶

every(arg1: Any, arg2: Any | None = None, first: Any = 0.0, last: Any | None = None) -> When

Create a periodic clock condition.

Parameters:

Name	Type	Description	Default
`arg1`	`Any`	Preferred clock identifier, such as `"step"` or `"time"`. A legacy delta-first call is also accepted.	required
`arg2`	`Any \| None`	Positive interval in clock units, or the identifier in the legacy argument order.	`None`
`first`	`Any`	First value eligible to match.	`0.0`
`last`	`Any \| None`	Optional final eligible value; it must exceed `first`.	`None`

Returns:

Type	Description
`When`	Periodic condition, for example `every("step", 10)`.

Raises:

Type	Description
`ValueError`	If no identifier is supplied, the interval is non-positive, or the requested range is invalid.

Never¶

when.never is a reusable condition that never matches. It is useful when a schedule is assembled programmatically and an action needs to be disabled.

When ¶

When(spec: _WhenSpec)

Combine a schedule condition with | or & operators.

Users normally create instances with :func:at and :func:every rather than calling this constructor directly.

match_time ¶

match_time(this_time: TimeDict) -> bool

Return whether this condition matches a simulation clock mapping.

next_time ¶

next_time(identifier: str, this_time: TimeDict, tols: dict[str, Any] | None = None) -> NextTime

Return the next match for one clock identifier.

Parameters:

Name	Type	Description	Default
`identifier`	`str`	Clock key such as `step`, `time`, or `stage_time`.	required
`this_time`	`TimeDict`	Current clock-like mapping.	required
`tols`	`dict[str, Any] \| None`	Optional per-identifier tolerance preventing a floating-point boundary from triggering repeatedly.	`None`

Returns:

Type	Description
`NextTime`	Next matching value or a boolean sentinel used by schedule merging.