Sensor Stream Simulator

A reproducible generator for synthetic cooling-loop sensor measurements. The data is intended for software testing and engineering education; it is not collected from physical equipment.

Why I built it

I built this project while preparing to study mechanical engineering at Case Western Reserve University. I wanted to understand how physical relationships, random variation, anomalies, file formats, and automated tests fit together in an engineering software project.

Features

• Eight modes: normal operation, gradual temperature increase, restricted flow, pressure-drop increase, sensor drift, random missing measurements, pump failure, and leak event
• Configurable sample count, interval, random seed, and ISO 8601 start time
• CSV and JSON output
• Scenario and ground-truth anomaly labels in every row
• A clearly named synthetic_heat_load_w model input in every output row
• Coupled flow, pump, resistance, pressure-loss, and temperature relationships
• Fixed default start time and seeded randomness for full reproducibility
• Committed example datasets and a matplotlib plotting script

Technical approach

The simulator uses Python's standard random.Random class with a local seeded generator. Each scenario first sets pump speed, relative hydraulic resistance, synthetic heat load, and any downstream delivery loss. The generator then calculates flow, pressure drop, and outlet temperature in that order. This keeps the reported pump, flow, and pressure values tied to one simplified model.

The core relationships are:

flow = 0.39 kg/s × (pump speed / 60%) × downstream delivery fraction
       / sqrt(relative resistance) × (1 + seeded flow noise)

pressure drop = 35 kPa × relative resistance × (flow / 0.39 kg/s)²

temperature rise = synthetic_heat_load_w / (flow × 4180 J/(kg·K))

Relative resistance is 1.0 in normal operation. Restricted-flow and pressure-drop-increase scenarios raise it; their synthetic pump controller also raises pump speed. Pump failure reduces commanded pump speed and the imposed heat load. The leak scenario reduces the fraction of flow delivered past the modeled leak location and lowers inlet pressure.

synthetic_heat_load_w is an imposed ground-truth value created by the model. It is not measured electrical power, a calibrated sensor reading, or evidence from real cooling equipment. The relationships above are intentionally simplified and are not a pump curve, hydraulic solver, or complete physical model.

Installation

Python 3.11 or newer is required.

python -m venv .venv

Activate on Windows:

.venv\Scripts\Activate.ps1

Or activate on macOS/Linux:

source .venv/bin/activate

Install the project and development tools:

python -m pip install -e ".[dev]"

Usage

python -m sensor_stream_simulator generate \
  --scenario restricted-flow \
  --samples 500 \
  --interval-seconds 5 \
  --seed 42 \
  --output data/restricted_flow.csv

Use a .json output filename for JSON. Run python -m sensor_stream_simulator generate --help for every option and scenario.

Example output

Generated 500 synthetic samples for 'restricted-flow' at .../restricted_flow.csv

Every output row contains:

timestamp, inlet_temperature_c, outlet_temperature_c, flow_rate_kg_s,
synthetic_heat_load_w, inlet_pressure_kpa, outlet_pressure_kpa,
relative_humidity_percent, pump_speed_percent, leak_detected, scenario,
is_anomaly, anomaly_type

Committed datasets:

• data/normal.csv
• data/restricted_flow.csv
• data/pump_failure.csv
• data/leak_event.json

Plot the restricted-flow dataset, including its imposed synthetic heat load:

python examples/plot_session.py

Testing

python -m pytest
python -m ruff check .
python -m ruff format --check .

The tests cover all eight scenarios, rounded heat-balance consistency, expected scenario trends, timestamps, file output, invalid inputs, CLI behavior, and exact reproducibility for equal seeds.

Assumptions

• Water has a constant approximate specific heat of 4180 J/(kg·K).
• The exported heat load is synthetic ground truth imposed by the generator.
• Flow scales with pump speed and inverse square-root relative resistance, with small seeded noise.
• Pressure loss follows a simplified relative-resistance-times-flow-squared relationship.
• Scenario transitions are intentionally smooth enough to inspect in a chart.

Limitations

• All values are synthetic and have not been measured on physical equipment.
• The model omits control-loop dynamics, fluid-property variation, pipe geometry, sensor calibration curves, pump curves, and detailed pump performance.
• Relative resistance and downstream delivery fraction are illustrative scenario controls, not identified parameters from real equipment.
• The sensor-drift scenario deliberately biases reported outlet temperature, so its measured temperature rise no longer closes the underlying heat balance.
• Ground-truth labels are known because the generator creates the anomalies; they do not represent the output of a detection algorithm.
• The ranges are plausible examples, not specifications for a real system.

What I learned

This project helped me practice reproducible simulation, linking variables with simple physical relationships, modeling different failure modes, designing file formats, and testing both numerical behavior and command-line workflows.

Possible future work

• Read scenario parameters from a small configuration file
• Add correlated noise and configurable sensor accuracy
• Model recovery periods after transient events
• Add streaming output that yields samples in real time

How the repositories connect

This simulator produces synthetic files that can be opened by cooling-loop-dashboard. The dashboard uses calculations from thermal-calculator. The simulator remains independent and does not require either project.

License

MIT