Templates

A template (.miravo.yaml) composes twin models into a plant topology.

Example

kind: MiravoTemplate
version: "1"
name: "Smart Factory Production Line"
description: "Discrete manufacturing line with conveyors, motor, coolant, compressed air"

namespace:
  enterprise: MiravoWorks
  site: smart-factory

areas:
  - name: production
    lines:
      - name: line-1
        twins:
          - model: belt-conveyor
            count: 2
            variation: 0.04
          - model: ac-induction-motor
            count: 1
            variation: 0.03
          - model: centrifugal-pump
            count: 1
            variation: 0.05
            parameters:
              rated_flow: 35
              rated_head: 24
  - name: utilities
    lines:
      - name: compressed-air
        twins:
          - model: air-compressor
            count: 1

settings:
  tick_interval_ms: 1000
  time_multiplier: 20

Schema Reference

Top-Level Fields

Field	Required	Description
kind	Yes	Must be MiravoTemplate
version	Yes	Schema version. Currently "1"
name	Yes	Human-readable name
description	No	Template description
namespace	Yes	UNS namespace with enterprise and site
areas	Yes	List of plant areas
settings	No	Simulation settings

Namespace

The namespace sets the top two levels of the UNS topic hierarchy:

namespace:
  enterprise: AcmeCorp
  site: detroit-plant

Produces topics like: AcmeCorp/detroit-plant/production/line-1/pump-001/pressure

Areas and Lines

Areas contain lines. Lines contain twin assignments. This maps to ISA-95 structure:

`{enterprise}/{site}/{area}/{line}/{instance}/{member}`

Twin Assignments

Each twin entry specifies:

Field	Required	Default	Description
model	Yes	—	Model name (must exist in content catalog)
count	No	1	Number of instances to spawn
variation	No	0	Random spread (0-1) applied to numeric parameters
parameters	No	—	Parameter overrides (numeric values only)

Instance IDs are auto-generated: centrifugal-pump-001, centrifugal-pump-002, etc.

Settings

Field	Default	Description
tick_interval_ms	1000	Milliseconds between ticks
time_multiplier	1	Simulation speed multiplier. 20 means 20x faster than real time.
seed	Random	RNG seed for deterministic output
overrun_threshold_multiplier	1.5	When a tick takes longer than interval * multiplier, it is flagged as an overrun

Variation

The variation field applies random spread to numeric parameters when spawning instances. With variation: 0.05, a parameter with default 1750 could range from 1662.5 to 1837.5 (plus or minus 5%).

Each instance gets a different variation from the seeded RNG, producing realistic fleet diversity.

Content Resolution

Templates reference models by name. Miravo resolves models through three layers in priority order:

1. Current directory — .twin.yaml files in the working directory
2. Local registry — ~/.miravo/registry/local/models/
3. Built-in — Shipped with Miravo via the @miravo/content package

This means you can override a built-in model by placing a file with the same name in your working directory or local registry.

Running a Template

Built-in template by name:

miravo start --template smart-factory

Local template by path:

miravo start --template ./my-plant.miravo.yaml

Validate without running:

miravo start --template smart-factory --dry-run