Twin Models

Define one asset type in `.twin.yaml` with parameters, members, methods, lifecycle, and faults.

Define a new asset type when the built-in catalog does not match the system you need to model.

Technical details

Start with the smallest valid model

schema_version: "2"
model:
  name: my-sensor
  description: "Temperature sensor"

parameters:
  temp_center:
    type: float
    default: 22
    unit: degC

members:
  temperature:
    kind: variable
    data_type: Double
    access: read
    unit: degC
    generator:
      type: noise
      center: "$param.temp_center"
      stddev: 0.5

Save the file as my-sensor.twin.yaml.

Inspect it with miravo models inspect.

miravo models inspect ./my-sensor.twin.yaml

Author in dependency order

Define model.name and any instance-level parameters.
Declare members in the order they must be evaluated.
Add methods when external control should write members or parameters.
Add lifecycle stages and faults after the process path is correct.

Members are evaluated in declaration order. A member can reference an earlier member in the same tick. It cannot reference a later member.

Choose the right value source

Need	Use
Process truth that changes every tick	`generator`
Runtime state such as lifecycle or fault health	`binding`
Writable control surface	`readwrite` or `write` member plus `methods`
Static metadata	`property` member

Bind runtime state on purpose

fault_active:
  kind: variable
  data_type: Boolean
  access: read
  binding:
    type: fault-active

availability_state:
  kind: variable
  data_type: String
  access: read
  binding:
    type: availability-state
    member: speed_feedback
    operator: ">"
    threshold: 50

Keep observation effects after process truth

discharge_pressure:
  kind: variable
  data_type: Double
  access: read
  unit: bar
  eu_range: [0, 12]
  generator:
    type: correlated
    source: speed_feedback
    factor: 0.004
    offset: 1.5
  observation_effects:
    - type: white_noise
      strength: 0.01
    - type: drift
      tau: 1800
      sigma: 0.02

Use observation_effects only on numeric read variables. The schema rejects readwrite, write, and non-numeric targets.

Reference

Field or block	Notes
`schema_version`	Current literal is `"2"`
`model.name`	Identifier used by templates and CLI inspection
`parameters`	Supports `float`, `int`, `string`, `bool`
`members`	At least one member. Declaration order matters.
`methods`	Runtime actions use `set-members`, `set-parameters`, or `clear-faults`
`binding.type`	`threshold`, `lifecycle-stage`, `health-state`, `fault-active`, `fault-count`, `active-fault-code`, `availability-state`
`observation_effects.type`	`white_noise`, `drift`, `outlier`, `gap`, `noise_burst`