Homeostat¶

Homeostat generates process-industry time series with full ground truth. Instead of simulating physics, it composes abstract data generating processes: stochastic sources, dynamic operators, control loops, instrument models and timed events. Because the control loops are closed, a disturbance or a fault shows up where it does in a real plant: often not on the controlled variable, but on the valve.

Every run returns the data a historian would record, the true values behind it, and the ground truth: the causal graph, each signal's role, the control loops, and a log of every event.

seed: 42
duration: 1d
dt: 1s
library: process@1

units:
  - {id: TIC-101, template: temperature_loop, sp: 80}

exogenous:
  - target: TIC-101.feed_temp          # a disturbance nobody measures
    source: {kind: ou, mean: 25, std: 3, tau: 2h}

interventions:
  - {at: 6h, target: TIC-101.sp, value: 85, profile: ramp, over: 30min}
  - {at: 12h, target: TIC-101, fault: valve_stiction, magnitude: 3}

import homeostat

run = homeostat.simulate("scenario.yaml")
run.observed   # what a historian records: TT-101, TIC-101.sp, TIC-101.out, TIC-101.mode
run.truth      # the true value of every signal, including the disturbance
run.meta       # causal graph, roles, loops, event log, reproducibility

What it is for¶

• Fault detection and diagnosis. The onset, size and location of every fault are known, and a labeler says when each fault becomes visible in the data, and on which signal.
• Soft sensors and quality prediction. The true product property is available at every step, while the lab reports it every few hours, late.
• Long histories and regime changes. Production plans, maintenance, degradation and random faults generate months of history, with every change recorded.
• Many plants at once. Any value in a scenario can be a distribution; a family of plants runs as one batch.

Principles¶

• Data generating processes, not physics. A plant is a composition of small operators with exact discrete-time math. It behaves like a controlled plant without modelling the chemistry.
• Ground truth is an output. Truth, measurements, the causal graph, roles, loops and events come with every run.
• Written by people and AI assistants. A scenario is a declarative YAML file. Errors say what is wrong, where, and how to fix it.
• Reproducible. The same scenario, seed, package version and NumPy version give identical data.
• A small core with plugins. The core is pure math. Domain vocabulary (loops, ISA tags, sensors, faults) comes from libraries such as process.

Where to go next¶

• Getting started: install Homeostat and run a first scenario.
• Tutorial: build a reactor–mixer plant whose product depends on conditions nobody measures.
• Guides: plans, faults, plant families, labels and more.
• Concepts: how operators, graphs, events and randomness fit together.
• Reference: every scenario key, operator, template, fault and error code.