# Homeostat

> Homeostat generates process-industry time series with full ground truth from abstract data generating processes. A plant and its timeline are described in a declarative YAML scenario; a run returns the historian view, the true values behind it and the ground truth (causal graph, roles, loops, event log).

Rules for writing scenarios:

- Every signal has one writer. Change a regulated variable through its setpoint (`<loop>.sp`) and a controller output through manual mode (`<loop>.mode: MAN` and `<loop>.man_out`).
- Durations are seconds or strings such as `30s`, `10min`, `2h`, `1d`. `duration` must be a multiple of `dt`.
- Instrument noise is a percentage of the measurement span, so set spans around the expected values.
- Units connect through ports: `exogenous: [{target: <unit>.<port>, from: <signal>}]`.
- Errors carry a code, a location and a fix; read the fix and change the config accordingly.

## Documentation

- [Your first scenario](https://homeostat.kausalflow.com/docs/getting-started/first-scenario/): a flow loop, a disturbance, and running it
- [Reading a run](https://homeostat.kausalflow.com/docs/getting-started/reading-a-run/): truth, measured, observed and meta
- [Scenario files](https://homeostat.kausalflow.com/docs/guides/scenario-files/): units, wiring, custom operators, measurements, initial state
- [Changes and faults](https://homeostat.kausalflow.com/docs/guides/changes-and-faults/): interventions, faults, profiles and lanes
- [Plans](https://homeostat.kausalflow.com/docs/guides/plans/): regimes, production transitions, degradation, maintenance
- [Self-running plans](https://homeostat.kausalflow.com/docs/guides/self-running-plans/): generated production, maintenance and faults
- [Plant families](https://homeostat.kausalflow.com/docs/guides/plant-families/): distributions and families of plants
- [Labels](https://homeostat.kausalflow.com/docs/guides/labels/): fault visibility, settle times, feasibility, material lineage
- [Tutorial: a reactor-mixer plant](https://homeostat.kausalflow.com/docs/tutorials/reactor-mixer-plant/)

## Reference

- [Scenario schema](https://homeostat.kausalflow.com/docs/reference/scenario/): every key of a scenario file
- [JSON Schema](https://homeostat.kausalflow.com/docs/reference/scenario.schema.json): the same schema, machine-readable
- [Operators](https://homeostat.kausalflow.com/docs/reference/operators/): core operators, their equations and parameters
- [Process library](https://homeostat.kausalflow.com/docs/reference/process-library/): templates, ports, sensor presets, faults, degradations, tasks
- [Error codes](https://homeostat.kausalflow.com/docs/reference/errors/)
- [Python API](https://homeostat.kausalflow.com/docs/reference/api/)

## Vocabulary of the `process` library (version 1)

- Templates: `flow_loop`, `level_loop`, `temperature_loop`, `mixer`, `heat_exchanger`, `reactor`, `cstr`
- Sensor presets: `thermocouple`, `magnetic_flowmeter`, `radar_level`, `online_analyzer`, `lab`
- Faults: `valve_stiction`, `valve_stuck`, `sensor_bias`, `sensor_drift`, `sensor_noise`, `fouling`
- Degradations: `fouling`, `sensor_drift`, `valve_wear`, `catalyst_decay`
- Maintenance tasks: `clean`, `replace_catalyst`, `calibrate`, `replace_sensor`, `replace_valve`, `stop`, `remove_sensor`, `install_sensor`
- Core operators: `sum`, `product`, `weighted_mean`, `log_linear`, `first_order`, `fopdt`, `integrator`, `variable_delay`, `saturation`, `stiction`, `pid`, `lag`, `bias`, `white_noise`, `clip`, `quantize`, `delay`, `gate`, `sample_hold`, `constant`, `clock`, `schedule`, `ou`, `ar`

## Optional

- [Concepts](https://homeostat.kausalflow.com/docs/concepts/): operators, graphs and roles, the step, events, randomness, outputs