Scenario schema¶

Every key of a scenario file, generated from the Pydantic schema that validates it. Unknown keys are errors with a suggestion, except where a section says other keys are parameters. The same schema is available as JSON Schema for editors and AI assistants.

Durations are a number of seconds or a string such as 250ms, 30s, 10min, 1.5h, 2d or 3d2h; a leading minus gives a negative duration (for jitters).

Before validation, two things are expanded: any number or choice may be a distribution (see Plant families), and plan.production, recurring plan.maintenance entries and a top-level faults section may be generators (see Self-running plans). The schema below describes the expanded, concrete scenario.

Scenario¶

The top level of a scenario file.

Key	Type	Default	Description
`seed`	integer	`0`	Seed of every random stream.
`duration`	duration	required	Length of the run, a whole multiple of `dt`.
`dt`	duration	`1.0`	Base step; parameters are given in physical units and discretized exactly.
`lanes`	integer	`1`	Number of lanes run side by side as one batch. (≥ 1)
`noise_keys`	list of integer		One noise key per lane; lanes with the same key share their noise (twin runs).
`init`	`steady` or `none` or Burn-in	`"steady"`	`steady` (settle noise-free first), `none`, or `{burn_in: <duration>}`.
`library`	string		Domain library, optionally pinned to a major version: `process` or `process@1`.
`units`	list of Units	`[]`	Template instances.
`exogenous`	list of Exogenous inputs	`[]`	Sources and wiring of template ports and new signals.
`interventions`	list of Interventions	`[]`	Planned changes and faults at given times.
`custom`	list of Custom operators	`[]`	Core operators used directly.
`regimes`	mapping of string to mapping of string to number or string	`{}`	Named sets of values (setpoints, parameters, modes) for the plan.
`plan`	Plan		The starting regime, production transitions and maintenance.
`degradation`	list of Degradations	`[]`	Slow degradations of units.
`family`	Family		Plants and histories drawn by `homeostat.family()`.
`output`	Output		What is recorded.

Units¶

Entries of units. Every other key is a parameter of the template; see the process library.

Key	Type	Default	Description
`id`	string	required	Unit id, for example `TIC-101`; its ISA tags derive from it (`TT-101`, `TV-101`).
`template`	string	required	Template of the domain library, for example `temperature_loop`.
`period`	duration		Update period of every operator of the unit, a multiple of `dt` (default: every step).

Exogenous inputs¶

Entries of exogenous.

Key	Type	Default	Description
`target`	string	required	A template port such as `TIC-101.feed_temp`, or the name of a new signal.
`source`	OU source or AR source or Constant source		A source that creates the signal: `ou`, `ar` or `constant`.
`from`	string		An existing signal that feeds the port instead of a source, for example another unit's output.
`unit`	string		Unit of the signal, for the signal table.
`measured`	Measurements		Also measure the signal with an instrument.

Measurements¶

The measured key of an exogenous input.

Key	Type	Default	Description
`tag`	string	required	Tag of the measured signal, for example `TT-205`.
`sensor`	string		Sensor preset of the domain library (default: the library's first preset).
`span`	[number, number]	required	Measurement span `[low, high]`; noise and quantization are percentages of it.
`installed`	boolean	`true`	Whether the sensor is installed at the start (a removed sensor reads NaN).

OU source¶

A source with kind: ou.

Key	Type	Default	Description
`kind`	`ou`	required	`ou`
`mean`	number	`0.0`	Long-run mean, in the signal's unit.
`std`	number	required	Stationary standard deviation, in the signal's unit (the same whatever `dt`). (≥ 0)
`tau`	duration	required	Correlation time.

AR source¶

A source with kind: ar.

Key	Type	Default	Description
`kind`	`ar`	required	`ar`
`coef`	list of number	required	Coefficients φ₁…φₚ, per base step `dt`; they must give a stationary process. (at least 1 item)
`mean`	number	`0.0`	Mean, in the signal's unit.
`std`	number	required	Stationary standard deviation, in the signal's unit. (≥ 0)

Constant source¶

A source with kind: constant.

Key	Type	Default	Description
`kind`	`constant`	required	`constant`
`value`	number	required	The value, in the signal's unit.

Interventions¶

Entries of interventions: a planned change (target and value) or a fault (target unit and fault).

Key	Type	Default	Description
`at`	duration	required	When the change starts.
`target`	string	required	A setpoint, mode, manual output, port or parameter path; for a fault, a unit id.
`value`	number or string		The value for `set`, the amount for `shift`, the factor for `scale`; a mode may be `MAN`, `AUTO` or `CAS`.
`action`	`set` or `shift` or `scale`	`"set"`	How `value` applies.
`fault`	string		A fault of the domain library, instead of a planned change.
`magnitude`	number		Size of the fault, in the fault's own terms (see the fault's description).
`profile`	`step` or `ramp`		`step`, or `ramp` over `over` (default: step; a fault's own default for faults).
`over`	duration		Duration of a ramp.
`id`	string		Id of the event in the event log (default: its position).
`lanes`	list of integer		The lanes it applies to (default: all).

Custom operators¶

Entries of custom. Every other key is a parameter of the operator; see Operators.

Key	Type	Default	Description
`id`	string	required	Name of the operator; its output signal has the same name.
`op`	string	required	Operator, for example `sum`, `product`, `first_order` or `schedule` (see the operator reference).
`inputs`	mapping of string to string	`{}`	Input port → signal name.
`unit`	string		Unit of the output signal.
`period`	duration		Update period, a multiple of `dt` (default: every step).

Plan¶

The plan section.

Key	Type	Default	Description
`start`	string		The regime at the start of the run; the plant settles in it.
`production`	list of Transitions	`[]`	Production transitions between regimes (or a generator; see Self-running plans).
`maintenance`	list of Maintenance tasks	`[]`	Maintenance tasks (entries may be recurring generators).

Transitions¶

Entries of plan.production.

Key	Type	Default	Description
`at`	duration	required	When the transition starts.
`to`	string	required	The regime to move to.
`over`	duration	`0.0`	Duration of the ramp (0: a step).
`id`	string		Id of the transition in the event log.

Maintenance tasks¶

Entries of plan.maintenance; see the maintenance tasks.

Key	Type	Default	Description
`at`	duration	required	When the task starts.
`task`	string	required	A maintenance task of the domain library, for example `clean` or `calibrate`.
`target`	string or list of string	required	A unit id, or several.
`duration`	duration		How long the task takes, for tasks that need one (for example `stop`).
`id`	string		Id of the task in the event log.

Degradations¶

Entries of degradation. Every other key is a parameter of the degradation; see the degradations.

Key	Type	Default	Description
`target`	string	required	A unit id.
`kind`	string	required	A degradation of the domain library, for example `fouling`.

Family¶

The family section, used by homeostat.family().

Key	Type	Default	Description
`plants`	integer	`1`	Number of plants to draw. (≥ 1)
`histories`	integer	`1`	Histories per plant (the same plant, different noise). (≥ 1)

Output¶

The output section.

Key	Type	Default	Description
`every`	duration		Recording interval, a multiple of `dt` (default: every step).
`start`	date-time		Calendar time of t = 0; the index becomes timestamps instead of elapsed time.

Burn-in¶

The mapping form of init.

Key	Type	Default	Description
`burn_in`	duration	required	How long to run before t = 0. (> 0)