TyMill/SmartBuildSim: SmartBuildSim v1.0.0 — Initial Public Release

SmartBuildSim is an open, production-grade synthetic-twin framework for smart-building AI. It generates BIM-consistent, deterministic sensor streams and provides ready-to-run pipelines for forecasting, anomaly detection, clustering, and a compact RL thermostat controller. The release ships with a typed CLI (Typer), YAML configs, tested workflows, and full documentation.

Highlights

• Deterministic synthetic data generator
  • BIM-validated building layouts (site → building → floor → room → sensors)
  • Configurable duration, sampling, trend/seasonality/noise
  • Event injection: HVAC failure, window-open, meter bias
  • Optional noise/missingness/drift flags
• AI-ready modules
  • Forecasting: scikit-learn pipeline (StandardScaler + LinearRegression), RMSE reporting
  • Anomaly detection: IsolationForest + z-score baseline, per-timestamp scores/labels
  • Clustering: KMeans daily/zone profiles with simple quality scores
  • Reinforcement learning: tabular Q-learning for discrete thermostat actions (hold/cool/heat)
• CLI & configs
  • Typer-based CLI, YAML configs with dotted overrides
  • Reproducible seeds; artifacts saved as CSV/Parquet, .joblib, .npy, .png
• Quality & docs
  • Python 3.10 / 3.11 / 3.12 (CI green)
  • Unit tests (pytest), type hints (pydantic models), docs (MkDocs)

Quickstart (CLI)

# generate synthetic telemetry
smartbuildsim data generate --config examples/config_generate.yaml --outdir out/office

# forecasting (RMSE)
smartbuildsim model forecast --config examples/config_forecast.yaml --outdir out/office

# anomaly detection (IF + z-score)
smartbuildsim model anomalies --config examples/config_anomaly.yaml --outdir out/office

# clustering of daily/zone profiles
smartbuildsim cluster run --config examples/config_cluster.yaml --outdir out/office

# thermostat RL (tabular Q-learning)
smartbuildsim rl train --config examples/config_rl.yaml --outdir out/office

Installation

• From source (recommended for this release):

pip install smartbuildsim

System Requirements

• Python 3.10–3.12
• Key deps: pandas, numpy, scikit-learn, pydantic, typer, matplotlib, pyyaml, joblib

Reproducibility

• All examples use fixed seeds and YAML configs in examples/
• CI runs tests on 3.10/3.11/3.12
• Artifacts (CSV/Parquet, models, plots) written under out/…

What's New in v1.0.0

• First public, fully documented release
• Deterministic generator + event injector
• Forecasting, Anomaly, Clustering, RL modules with CLI wrappers
• Reference configs & scripts in examples/
• Documentation site and passing CI across supported Python versions

License

MIT © Tymoteusz Miller

Related Identifiers

• Software repository: https://github.com/TyMill/SmartBuildSim
• Documentation: https://tymill.github.io/SmartBuildSim/

(PL) Krótkie streszczenie do Zenodo

Pierwsze publiczne wydanie SmartBuildSim — biblioteki "synthetic twin" dla inteligentnych budynków. Generator tworzy deterministyczne strumienie czujników zgodne z BIM i umożliwia wtrysk zdarzeń (awarie HVAC, otwarte okno, bias licznika). Dostępne są gotowe pipeline'y AI: prognozowanie (scikit-learn, RMSE), wykrywanie anomalii (IsolationForest, z-score), klasteryzacja (KMeans) i prosty sterownik RL (Q-learning). Biblioteka ma CLI (Typer), konfiguracje YAML, testy i dokumentację.