Lifecycle & Faults

Lifecycle stages and faults model long-term degradation and failure modes.

Lifecycle Stages

Assets progress through lifecycle stages based on operating hours. Each stage applies effects to member values, simulating real-world wear.

lifecycle:
  stages:
    - name: healthy
      duration_hours: [4000, 7000]
      effects: {}
    - name: degraded
      duration_hours: [1000, 2000]
      effects:
        vibration_baseline: { multiplier: 1.4 }
        bearing_temperature: { offset: 8 }
    - name: critical
      duration_hours: [300, 700]
      effects:
        vibration_baseline: { multiplier: 2.0 }
        bearing_temperature: { offset: 18 }
        flow_rate: { multiplier: 0.85 }

How It Works

1. Each instance starts in the first stage with randomized operating hours
2. The engine tracks operating hours based on simulation time
3. When hours exceed the stage duration, the asset transitions to the next stage
4. Stage durations are randomized within the [min, max] range per instance

Stage Effects

Effects modify generator output values using: value * multiplier + offset

Field	Default	Description
multiplier	1.0	Multiplicative scaling
offset	0	Additive shift

Effects apply to any numeric member referenced by name.

Surfacing Lifecycle State

Use a binding to expose the current stage as a member:

lifecycle_stage:
  kind: variable
  data_type: String
  access: read
  binding:
    type: lifecycle-stage

Faults

Faults model specific failure modes with triggers, effects, and durations.

faults:
  - name: cavitation
    trigger:
      condition: "discharge_pressure < 2.5"
      probability: 0.01
    effects:
      vibration_radial: { spike: 1.8, duration_ticks: 180 }
      flow_rate: { multiplier: 0.75, duration_ticks: 180 }
      motor_current: { offset: 3, duration_ticks: 180 }

  - name: bearing_wear
    trigger:
      lifecycle_stage: degraded
      probability: 0.004
    effects:
      vibration_axial: { multiplier: 1.4, duration_ticks: 600 }
      bearing_temperature: { offset: 6, duration_ticks: 600 }

Trigger Types

Field	Description
lifecycle_stage	Only evaluate when the asset is in this stage
condition	Expression like "pressure < 2.5" evaluated against member values
probability	Per-tick probability of firing (0 to 1)

Triggers can combine lifecycle_stage with probability — the fault only rolls the dice when the asset is in the specified stage.

Effect Types

Effects are applied in order: spike, then multiplier, then offset.

Field	Description
spike	Multiplicative spike (e.g., 1.8 means 1.8x the current value)
multiplier	Ongoing multiplicative scaling
offset	Additive shift
duration_ticks	How long the effect lasts before auto-clearing

String-valued effects short-circuit — they replace the member value directly.

Injecting Faults at Runtime

Trigger faults manually through the CLI or admin API:

Via the CLI:

miravo inject pump-001 cavitation

Via the admin API:

curl -s http://127.0.0.1:8080/commands \
  -H 'content-type: application/json' \
  -d '{"type":"triggerFault","instanceId":"pump-001","fault":"cavitation"}'

Clear a fault:

curl -s http://127.0.0.1:8080/commands \
  -H 'content-type: application/json' \
  -d '{"type":"clearFault","instanceId":"pump-001","fault":"cavitation"}'

Fault State Bindings

Expose fault state as members:

fault_active:
  kind: variable
  data_type: Boolean
  access: read
  binding:
    type: fault-active          # true when any fault is active

fault_count:
  kind: variable
  data_type: UInt16
  access: read
  binding:
    type: fault-count           # Number of active faults

active_fault_code:
  kind: variable
  data_type: String
  access: read
  binding:
    type: active-fault-code     # Name of the active fault
    fallback: none

health_state:
  kind: variable
  data_type: String
  access: read
  binding:
    type: health-state          # Combines lifecycle + fault state