OpenBSE — Open Building Simulation Engine

This is both an experiment in a potential new building energy modeling engine, but also to test the limits of AI in this type of physics based software development. ~This line was written by a human, nothing else in this file or repo is.

Modern, open-source building energy simulation in Rust.

OpenBSE is a ground-up reimplementation of building energy simulation using validated physics (heat balance methods, psychrometrics, HVAC component performance curves) expressed in a clean, modern, composable architecture. It replaces the complexity of legacy BEM tools with:

• Clean YAML input format — no nodes, branches, branch lists, or connector lists
• Graph-based simulation engine — automatically determines execution order via topological sort
• Decoupled controls framework — sensor/actuator model (sense → compute → act)
• Full building envelope physics — CTF, convection, solar, longwave radiation, infiltration, internal gains
• Generic component contracts — any component can go on any loop if fluid types match
• Multi-format weather support — EPW and TMY3 CSV (ASHRAE Standard 140 prescribed format)

Why This Exists

EnergyPlus is the DOE's flagship building energy simulation tool. Its physics are well-validated, but its software architecture — inherited from 1970s-era BLAST and DOE-2 Fortran — creates serious usability problems: redundant HVAC topology specification, rigid system templates, simulation order baked into user input, and controls tightly coupled to specific system types.

OpenBSE preserves the validated physics while fundamentally rethinking the system topology, HVAC modeling framework, and user input paradigm. EnergyPlus math is the reference standard — every algorithm is implemented to match E+ behavior, and deviations are treated as bugs.

For AI assistants: See docs/AI_CONTEXT.md for a comprehensive project overview designed as initial context.

Quick Start

Download

Pre-built binaries are available on the Releases page. Each download includes the CLI engine, the desktop editor, and example models.

macOS users: macOS blocks unsigned applications by default. After extracting, run these commands to allow them:

xattr -d com.apple.quarantine openbse
xattr -cr openbse-editor*.dmg

Or for the editor after installing: xattr -cr /Applications/openbse-editor.app

Build from Source

git clone https://github.com/bbrannon4/OpenBSE.git
cd OpenBSE
cargo build --release

Run Tests

cargo test --workspace

300+ unit tests across 8 crates.

Run a Simulation

./target/release/openbse examples/simple_heating.yaml -w weather.epw -o results.csv

The -w flag specifies the weather file (EPW). If omitted, the engine falls back to weather_files in the YAML. The CLI flag always takes precedence.

Architecture

OpenBSE is a Rust workspace with 8 crates:

| Crate | Purpose | |-------|---------| | openbse-psychrometrics | Moist air property calculations (Hyland & Wexler) | | openbse-weather | EPW and TMY3 CSV weather file parsing | | openbse-core | Simulation graph, timestep loop, component traits | | openbse-components | HVAC component models (fan, coils, boiler, chiller, duct) | | openbse-controls | Decoupled control framework (thermostats, setpoints) | | openbse-envelope | Building envelope heat balance physics | | openbse-io | YAML parsing, CSV output, design day sizing, summary reports | | openbse-cli | Command-line interface and multi-loop control dispatcher |

No circular dependencies. Components implement traits (AirComponent, PlantComponent, EnvelopeSolver) defined in openbse-core. Rust's type system enforces physical constraints at compile time — AirPort and WaterPort are distinct types, so connecting a water pipe to an air duct won't compile.

The desktop editor (openbse-editor) is a Tauri + React app in tools/editor/ that provides a GUI for editing YAML model files with schema validation, selecting weather files, and running simulations with real-time output streaming — all without touching the command line.

Core Design Principles

1. Graph-Based Topology — Users describe components and connections. The engine builds the directed graph, creates internal nodes, and determines simulation order automatically.

2. Generic Component Contracts — Every component implements a simple trait. A boiler takes water in and sends it out hotter. A chiller takes water in and sends it out cooler. Neither knows what loop it's on.

3. Decoupled Controls — Controllers read from any sensor point in the graph and write to any actuator on any component, independent of system topology.

What's Implemented

Building Envelope

• Materials & Constructions — multi-layer opaque walls, U-factor windows with E+ SimpleGlazingSystem angular model (LBNL-2804E), simple constructions, F-factor ground floors
• Vertex Geometry — 3D polygon vertices with automatic area, azimuth, tilt, volume calculation
• CTF — full Seem (1987) state-space conduction transfer functions matching EnergyPlus, with NoMass layer support and lumped RC fallback
• Exterior Convection — DOE-2 (MoWiTT) algorithm with roughness correction
• Interior Convection — ASHRAE/Walton natural convection correlations
• Solar — position (Spencer 1971), Hay-Davies anisotropic sky model (circumsolar + isotropic), angular SHGC transmission (28-bin mapping per LBNL-2804E), FullExterior and FullInteriorAndExterior distribution with beam/diffuse split and VMULT redistribution
• External Shading — overhangs and fins with geometric beam shadow calculation (Sutherland-Hodgman polygon clipping), diffuse sky view factor reduction, 8x8 grid sampling for multi-caster union, Suncast-style solar precompute with disk-cached .solar files
• Sky Longwave Radiation — Berdahl-Martin sky emissivity model with cloud cover correction
• Interior Longwave Radiation — MRT-based surface radiation exchange
• Infiltration — EnergyPlus design flow rate model with wind dependence, ASHRAE combined infiltration model, multizone pressure network solver (Newton-Raphson with auto-generated cracks, Swami & Chandra Cp, stack effect)
• Internal Gains — people, lights, equipment with radiant/convective/lost fraction split
• Zone Air Balance — 3rd-order backward difference predictor-corrector (matching E+ ZoneTempPredictorCorrector)
• Ideal Loads — nonproportional thermostat for ASHRAE 140 validation
• Ground Temperature — monthly table or Kusuda-Achenbach model from weather data
• Thermostat Schedules — time-of-day heating/cooling setpoint variation
• Conditional Night Ventilation — schedule-driven with temperature conditions
• Free-Float Mode — no-HVAC simulation for temperature drift analysis

HVAC Components

• Fan — constant volume, VAV with power curve, on/off cycling
• Heating Coil — electric resistance, hot water, gas burner (with efficiency)
• Cooling Coil — DX single-speed with COP, performance curves (Cap-fT, EIR-fT, PLF-fPLR), outdoor temp derating
• Heat Pump Coil — air-source heat pump heating with defrost and performance curves
• Duct — NTU conduction model with leakage fraction and ambient zone coupling
• Boiler — efficiency curves, part-load ratio limits
• Chiller — electric chiller with COP and condenser modeling
• Cooling Tower — single/two/variable-speed with effectiveness-NTU model, polynomial fan power curve, approach temperature limits
• Heat Recovery — sensible effectiveness heat exchanger (air-side enthalpy wheel / plate HX)
• Heat Exchanger — water-to-water plate-and-frame HX for inter-loop connections (effectiveness-NTU, always-on or economizer mode)
• Pump — constant/variable speed with power curves, headered staging, heat-to-fluid modeling

Controls

• PSZ-AC — ASHRAE 90.1 modulating economizer, on/off and proportional cycling, gas furnace with fixed heating DAT
• DOAS — 100% outdoor air, fixed supply setpoints, always-on pre-conditioning
• FCU — per-zone recirculating fan coil, proportional fan speed modulation
• VAV — ASHRAE Guideline 36 dual-maximum, SAT reset (13-18°C), modulating economizer, preheat frost protection
• Design Day Autosizing — two-stage ASHRAE-compliant sizing (zone peak + system coincident), configurable oversize factors

Simulation

• Graph-based execution order (topological sort)
• Sub-hourly timesteps (1, 2, 4, 6, 10, 12, 15, 20, 30, 60 per hour)
• Multi-weather-file support (EPW and TMY3 CSV), CLI -w flag overrides YAML
• Configurable CSV output with flexible variable selection, including 16 energy end-use variables
• Summary reports in three formats: text, HTML (with styled tables and ASHRAE compliance), and structured CSV
• Monthly energy end-use breakdown (all 14 categories), per-zone peak loads summary (TRACE-style)
• Holiday schedule support
• Multi-loop coupled envelope + HVAC simulation (DOAS + FCU additive mixing)
• Plant loop topological ordering (inter-loop HX and condenser dependencies)
• Primary/secondary/tertiary plant loop support via HX inter-connections

Validation

ASHRAE Standard 140-2023

Test cases are in 140_tests/. 28 cases from Section 7 (Building Thermal Envelope) plus Case CE100 (Cooling Equipment) have been implemented. Current status: 63 of 63 metrics pass (100%) against the standard's prescribed acceptance ranges.

DOE Prototype Comparison (EnergyPlus)

DOE prototype building models are being validated against EnergyPlus using the simplified IDFs in prototype_tests/. Current status for the Single-Family house (CZ5B Boulder):

| End Use | EnergyPlus | OpenBSE | Diff | |---------|-----------|---------|------| | Heating (Gas) | 6,689 kWh | 9,907 kWh | +48% |