A safety-constrained physical-AI controller for autonomous building operations. Uses EnergyPlus simulation with PyEnergyPlus API, local LLM (Ollama/Qwen) or deterministic fallback for bounded planning, and hard safety validation before schedule override injection.

Building HVAC control typically relies on fixed schedules or reactive thermostats. Optimus is a safety-constrained physical-AI controller that observes live EnergyPlus simulation state, plans bounded supervisory actions via local LLM or deterministic fallback, validates safety constraints, and injects approved schedule overrides — all with full auditability.

The Problem

Traditional building control:

Fixed schedules — no adaptation to weather, occupancy, or demand
Reactive thermostats — no predictive capability
No auditability — operators can't see why decisions were made
Safety gaps — no hard constraints on comfort or equipment limits

Optimus addresses this with a closed-loop physical-AI system evaluated entirely in EnergyPlus simulation.

Architecture

IDF/EPW Upload
      ↓
Runtime Preparation (reporting enrichment, RunPeriod normalization)
      ↓
EnergyPlus Baseline Run
      ↓
Interface Discovery (thermostats, cooling schedules, People, ITE)
      ↓
Peak-Window Calibration (95th percentile of baseline peak)
      ↓
Live PyEnergyPlus Callback Loop
      ↓
┌─────────────────────────────────────┐
│  Bounded Planner                    │
│  • Local Ollama/Qwen                │
│  • Deterministic fallback           │
│  • Compact structured context       │
└─────────────────────────────────────┘
      ↓
┌─────────────────────────────────────┐
│  Hard Safety Validator              │
│  • PMV + zone temp (comfort)        │
│  • ITE inlet temp (data center)     │
│  • One-hour bound + auto-restore    │
└─────────────────────────────────────┘
      ↓
Schedule Override Injection → EnergyPlus
      ↓
EnergyPlus SQL → KPI Comparison Report
JSONL Audit Trail → Full Traceability

Key Components

1. EnergyPlus Integration

PyEnergyPlus API for live callback access to facility demand, temperatures, occupancy, weather
Interface Discovery (idf_profile.py): identifies zone thermostats, cooling/heating schedule actuators, People objects, ITE equipment
Baseline Run: isolated copy with enriched reporting, captures total energy, peak demand, recurring peak hours
Unsupported Models: baseline-only with clear explanation when no safe actuator exists

2. Bounded Planning

Local LLM (Ollama/Qwen) or deterministic fallback — no external API dependency
Compact Context: weather forecast, occupancy forecast, current demand, allowed modes, prior outcomes
Structured Output: must echo numeric context exactly; validator rejects ungrounded/malformed plans
Rate Limited: max 7 pre-alert plans per simulation; timeout → deterministic fallback

3. Hard Safety Validation

Model Type	Safety Signal	Allowed Action	Never Changed
Comfort Building	Occupied-zone PMV + temperature	+0.5°C cooling setpoint, 1 hour	HVAC topology, loads, non-thermostat schedules
Data Center	ITE inlet temperature	+0.5°C cooling setpoint, 1 hour (with inlet headroom)	CPU, server-fan, UPS, workload schedules

One-hour bound: native schedules auto-restored after 1 hour or immediately on safety breach
PMV/ITE guards: override reset to native scheduling on safety violation

4. Auditability & Reporting

Every job under jobs/<job-id>/:

baseline/summary.json — EnergyPlus SQL baseline KPIs
ai/comparison.json — baseline/AI energy, peak, comfort, agent metrics
ai/live_metrics.jsonl — timestamped telemetry
ai/six_hour_plan_log.jsonl — candidate plans, validation reasons, outcomes
ai/agent_decisions.jsonl — actual supervisory overrides only
ai/opportunity_report.md/.json — peak, cooling, rejection analysis

Deployment

docker compose up --build

Opens Streamlit at http://localhost:8501. Docker installs EnergyPlus 26.1.0. Ollama optional (host) for LLM planning; deterministic fallback keeps loop operational without it.

Results

Frozen v1 Controller validated as robust, auditable closed loop.

Metric	Result
Savings	Model-dependent: some models have measurable cooling opportunity; others correctly classified as no-opportunity or safety-gated
Safety	Zero comfort/ITE violations in validated runs
Auditability	100% actions traceable to validation reason
Fallback	Deterministic planner operates when LLM unavailable

Key Insight: Optimus reports measured results and rejection reasons rather than manufacturing improvements.

Engineering Lessons

Physical-AI needs hard boundaries — ML optimization without safety constraints is insufficient for physical systems
Deterministic fallback is a feature — enables evaluation, CI/CD, and offline operation without external dependencies
EnergyPlus SQL + JSONL = full traceability — building operators need to see why each action was taken or rejected
Bounded overrides prevent runaway control — one-hour limit with auto-restoration is essential for operator trust
Interface discovery determines capability — unsupported models run baseline-only with clear explanation, not fake actuation

What This Is Not

❌ Production building automation system — evaluated in EnergyPlus simulation only
❌ Autonomous without qualification — prototype with defined safety boundaries
❌ Guaranteed energy savings — savings are model-dependent; correctly reports no-opportunity cases
❌ Parameter server / distributed training — this is a simulation control loop, not distributed ML

Related Project

This blog post accompanies the Optimus: Autonomous EnergyPlus Building Controller project case study.

View Project Case Study →

Resources

GitHub: https://github.com/ShreyanshShakya/Optimus
System Architecture: docs/system_architecture.md
Evaluation Methodology: docs/baseline_methodology.md
Safety Metrics: docs/comfort_metric_method.md
Planning Contract: docs/six_hour_planning.md
Frozen v1 Release: docs/release_v1_frozen.md