Fluxion: AI-Accelerated Building Energy Engine

Fluxion is a next-generation Building Energy Modeling (BEM) engine. It is designed to be differentiable, quantum-ready, and exponentially faster than legacy monolithic tools by utilizing a hybrid Neuro-Symbolic architecture.

Status: Fluxion is in active development — specifically mid-milestone on v1.3 "Blind ASHRAE 140 Validation" (physics-only, no calibration factors). It is not production-ready. The strict ±15% annual-energy gate on the current develop tip reads 9 PASS / 33 KNOWN-FAIL / 0 REGRESSION on the ASHRAE 140 §7 (Class I) envelope-and-fabric cases (600/900 series, 195, 800/810, 960/970 and the free-float variants) — the only ASHRAE 140 section fluxion implements today (checker scripts/check_strict_energy_gate_regression.py, statuses in tests/reference_data/zone_balance/strict_energy_gate_baseline.json, verified 2026-10-15 at commit 6c18425e). Use it as a high-throughput research/oracle tool, not as a drop-in EnergyPlus replacement.

Why the low pass rate is the point

The low numbers are real and they are supposed to look like that — both the stored metric-level snapshot (9.8%, ASHRAE 140 §7 Class I) and the live strict gate (9 of 42 case-metrics passing; 33 documented as KNOWN-FAIL, §7 Class I). Every number the suite reports is checked against a strict ±15% annual-energy-balance gate and an honesty guard that asserts each recorded engine value sits in the ASHRAE-published band or in an explicit xfail for a documented structural gap. Fluxion has never been tuned to pass: no calibration factors, no case-type hints — fixes go into the underlying physics, and the known failures are tracked publicly in docs/KNOWN_ISSUES.md as the roadmap, not hidden. A red suite that tells the truth is the deliverable of this milestone; scripts/ashrae_140_pipeline.py reproduces the whole check in one command (see Run the validation pipeline).

🏗 Architecture

Fluxion separates the "heavy lifting" of physics (CFD/Radiation) into AI surrogates, while maintaining a rigorous First-Principles thermal network for energy conservation. The thermal network, conduction solvers, and solar/ventilation models are organized as swap-point traits (HeatConductionSolver, VentilationSchedule, ThermalModelTrait) so that physics and AI-surrogate implementations are interchangeable. See ARCHITECTURE.md and CODEBASE_MAP.md for module boundaries and the full trait contracts.

Current Validation Status

Fluxion is not yet ASHRAE 140-compliant. The current strict ±15% annual-energy gate at the develop tip is 9 PASS / 33 KNOWN-FAIL / 0 REGRESSION on the ASHRAE 140 §7 (Class I) envelope-and-fabric cases (verified 2026-10-15 at ad88bfa9; KNOWN-FAIL rows are the documented structural failures in docs/KNOWN_ISSUES.md, not hidden regressions). The metric-level table below is the live validator sweep regenerated 2026-10-15 at ad88bfa9 (round 37; supersedes the stored 2026-09-26 snapshot) — every figure below is ASHRAE 140 §7 (Class I) scope only; §6, §8, §9, §10, §11 and §12 are separate sections, tracked in docs/compliance/section_coverage.md — see docs/ASHRAE140_RESULTS.md for the full case-by-case breakdown and SCORECARD.md for the consolidated, reproducible release-readiness view.

Metric	Current	Target (release gate)	Status
Strict ±15% annual-energy gate (live, 2026-10-15 @ ad88bfa9) — ASHRAE 140 §7 (Class I)	9 PASS / 33 KNOWN-FAIL / 0 REGRESSION	0 REGRESSION sustained; KNOWN-FAIL count trending down	ℹ️ tracked
Pass rate (metric-level)	6.0% (5/84 metrics, ASHRAE 140 §7 Class I envelope cases)	≥ 60%	❌ Fail
Mean Absolute Error (MAE)	78.50% (ASHRAE 140 §7 Class I envelope cases)	≤ 50%	❌ Fail
Cases fully passing (stored snapshot) — ASHRAE 140 §7 (Class I)	0/18 (0.0%, §7 Class I envelope cases)	—	❌
Max single-case deviation — ASHRAE 140 §7 (Class I)	964.17% (§7 Class I envelope cases)	—	ℹ️

The four metric-level rows above are regenerated (generated 2026-10-15 from a live fluxion validate sweep at ad88bfa9, promoted into validation/performance_history.latest.json); the strict-gate row above them is the live regression gate. All of these figures are ASHRAE 140 §7 (Class I) scope — envelope and fabric load tests only. The metric-level regression vs the 2026-09-26 snapshot (9.8% → 6.0% pass, 45.27% → 78.50% MAE, §7 Class I) reflects the round-26+ fidelity-first engine changes measured against the un-tuned validator reference bands — see the round-37 loop notes; no validator band or engine constant was adjusted to move these figures.

Run the validation pipeline

One command runs the whole ASHRAE 140-2023 check end to end — provenance verification, the strict ±15% annual-energy gate, the honesty guard, and the engine benchmark against the stored baseline — with energy-balance results surfaced first:

python3 scripts/ashrae_140_pipeline.py                 # full run (~10 min: builds and runs the engine)
python3 scripts/ashrae_140_pipeline.py --skip-engine   # provenance + honesty guard only, no Rust toolchain
python3 scripts/ashrae_140_pipeline.py --output report.json

The script orchestrates the repo's existing checks; it never tunes outputs to pass — a regression is a failure, and a known structural failure is reported as exactly that (exit 0 pass, 1 validation failure, 2 a stage could not run). Sample verdict output (real run, --skip-engine skips the engine stage):

ASHRAE 140-2023 validation pipeline — 2026-10-06T13:35:04+00:00
========================================================================
[  PASS  ] energy-balance: strict ±15% annual-energy gate (vs recorded baseline)
           PASS: strict ±15% gate holds. Documented structural cooling gaps (Cases 600/900/950/960/970 per docs/KNOWN_ISSUES.md §LIMIT-05 / §LIMIT-14 / §LIMIT-17 / §LIMIT-23 / §LIMIT-24) are tracked (not silently ignored); no regression detected.
[  PASS  ] energy-balance: Python honesty guard (recorded values vs ASHRAE bands)
           25 passed, 10 xfailed in 0.63s
[  PASS  ] provenance: suite files match ASHRAE publisher hashes
           14/14 verified against publisher hashes; 0 mismatched, 0 absent, 0 unverified
[SKIPPED ] engine: ASHRAE 140 case series vs stored benchmark baseline
========================================================================

v1.3 Milestone — Blind ASHRAE 140 Validation (Physics Only)

The current milestone removes all post-simulation correction factors and case-type hints, then fixes the underlying physics so the engine passes against true ASHRAE 140 reference values (not "calibrated for 5R1C" ranges). The milestone is structured in five phases:

• Phase A — Baseline Stripping: Catalog and remove all correction infrastructure; measure the true physics-only baseline. Phase A8 completed 2026-09-07 (Issue #3291 / PR #3482) — shipped the ZoneSolverKind::Gauge selector as the unconditional default. Superseded by ADR-0017 (Issue #3978): the default thermal selector is now cfg-dependent and explicit in every build — ZoneSolverKind::Gauge with --features gauge-solver, explicit legacy FiveROneC (HighMass specs still auto-promote to 9R4C) in default builds; the silent fall-through was removed, and an explicit Gauge selector in a default build panics loudly at construction (canonical wording: Cargo.toml:208-225; src/sim/thermal_selector.rs). The unconditional-default flip is gated on the teacher validation suite (#3986).
• Phase B — Physics Fixes: Solar distribution (ISO 13790), thermal-mass time constant, and free-floating temperature fixes. The GaugeSolver structural rework is the unblocker for the aggressive-baseline cohort tracked by Issue #3072 / ADR-0007; full peak accuracy runs through the equation-based DAE teacher path via the gauge arm — the β-soak gate (#3286) remains the nightly authority on that arm, the gauge-solver cfg-gate removal is tracked in #3290, and per ADR-0017 the unconditional-default flip is gated on the teacher validation suite (#3986, superseding the §LIMIT-21 closure plan).
• Phase C — Benchmark Correction: Replace calibrated ranges with true EnergyPlus/ESP-r/TRNSYS reference values.
• Phase D — Blind Validation Pass: Run the full blind suite targeting ≥80% pass (ASHRAE 140 §7 Class I scope).
• Phase E — Sustained Validation: CI gate + regression tracking to hold the pass rate as the codebase evolves.

Historical phase planning documents (.planning/, including the ASHRAE 140 blind validation plan) were archived to the archive/v1-experimental-sprawl branch.

Known Limitations

These are documented structural failures (also listed in release_gates.yaml → validation.individual.known_failures and AGENTS.md). Per RULES.md, the fix path is the underlying physics — no parameter tuning to make tests pass.

• Baseline 600-series (low-mass): All 6 cases FAIL. Simplified envelope model over-predicts peak loads (e.g. peak heating ~4.36 kW vs 2.80–3.80 kW reference band).
• High-mass 900-series: All 6 cases FAIL. Heating is over-predicted by ~200% due to a 5R1C/CTF thermal-mass limitation (e.g. Case 900 annual heating 5,130 kWh vs 1,170–2,040 kWh reference band, per docs/KNOWN_ISSUES.md §LIMIT-05 UPDATE #2453).
• Overall accuracy: 45.27% MAE (ASHRAE 140 §7 Class I scope), driven by the high-mass annual-energy deviation above.
• Peak load accuracy: High-mass peak loads UNDER-estimated post-#1280 (Case 900 0.86 kW vs 2.10–3.50 kW reference band; full peak accuracy gated on the DAE teacher validation suite (#3986), which per ADR-0017 holds flip authority on the cfg-dependent default selector (superseding the §LIMIT-21 closure plan, Issue #3297).

For the historical v0.8.0 snapshot (Peak Load & Free-Float Validation narrative), see docs/archive/ASHRAE140_RESULTS_v0.8.0.md (archived; superseded by the current blind-validation figures above).

🚀 Features

• Throughput: ~900 configs/sec throughput in release mode via BatchOracle and rayon threading (≥150 configs/sec CI gate; see SCORECARD.md).
• Speed: <100ms annual simulations via AI approximation (design target).
• Hybrid Physics: Hard constraints (Energy Balance) + Soft constraints (Neural Surrogates) at swap-point traits.
• Interoperability: Native Python SDK via pyo3, Node.js bindings via napi-rs, and WebAssembly bindings via wasm-pack for browser/CAD/BIM integration. See docs/bindings.md for the top-level surface overview; per-surface detail lives in docs/NAPI_BINDINGS.md, fluxion-wasm/README.md, and fluxion-wasm/WASM_STATUS.md.
• Cross-Platform: Supports macOS (x64 + ARM), Linux, and Windows.

Feature Flags (default = none)

Most functionality is behind cargo feature flags; default builds skip the ONNX runtime. Notable flags:

• Physics solvers: gauge-solver (production GaugeSolver zone-solver gate, Phase A8, #3291 / #3482 — with --features gauge-solver on, the dispatcher's gauge arm is unconditional and panics on missing gauge backend; pending §LIMIT-21 / β-soak #3286; see docs/FEATURES.md §gauge-solver), debug-physics (gates eprintln! in physics hot loops).
• AI / surrog: ort (alias onnx, ONNX inference), cuda (GPU inference; auto-downgrades to CPU if unavailable).
• Acausal HVAC / fluid: fluid (enables fluxion-fluid acausal HVAC/fluid port traits).
• Advanced co-simulation: fluxion-cfd (FFD/CFD airflow), fluxion-city (urban radiation), grid (thermal→electrical coupling via fluxion-grid, #4005), dwave (D-Wave quantum annealing SAPI).
• Telemetry / concurrency: kafka (rdkafka telemetry), loom (concurrency fuzzing; needs ~32 GB).
• Bindings / interop: python-bindings, python-extension (maturin wheel build, #2532), napi-bindings, multi-zone, wiring-tracing, ashrae_140_v2021, dhat (heap profiling).

See docs/FEATURES.md for the complete, authoritative cargo feature list and build commands; AGENTS.md §Toolchain, Security, and Generated Artifacts covers env vars and security tooling.

🛠 Installation

Rust Core

cargo build --release

Python Bindings

pip install maturin
maturin develop

Node.js Bindings

cd npm
npm install
npm run build

The Node.js bindings provide high-performance native access to Fluxion with full TypeScript support. See npm/README.md for detailed documentation.

Development Setup (recommended)

Follow these steps on macOS / zsh to create an isolated Python environment, install developer tools, enable pre-commit hooks, and build the Python bindings. This project requires Python 3.10+ (see pyproject.toml).

# 1) Create & activate a venv
python3 -m venv .venv
source .venv/bin/activate

# 2) Upgrade pip
python -m pip install --upgrade pip

# 3) Install development dependencies (linters, test tools, build helpers)
pip install -r requirements-dev.txt

# 4) Install and enable pre-commit hooks
pip install pre-commit
pre-commit install                # normal hooks
pre-commit install --hook-type commit-msg -f  # commit-msg hook (force replace existing hooks if needed)

# 5) Run hooks once across the repo (optional but recommended)
pre-commit run --all-files

# 6) Build & install Python bindings for local development
maturin develop

Optional minimal install

If you only need maturin for quick builds or one-off development (and don't want to install all dev tools), install it separately:

python -m pip install 'maturin>=1.0,<2.0'

Low-memory builds (Linux)

Cargo builds pick up memory-safe defaults from .cargo/config.toml: a linker wrapper that prefers mold, then lld, and falls back to the system cc driver when neither is installed, plus split-debuginfo = "unpacked" on dev/test builds so DWARF data never streams through the linker. Constrain parallelism on RAM-constrained machines with cargo build -j <n> or [build] jobs in ~/.cargo/config.toml — see docs/DEVELOPMENT.md for details.

Repo-root pointers

A few repo-root files are agent/maintainer-facing rather than reviewer-facing:

Path	What it is
RULES.md	Repo rules for agents and maintainers (incl. the no-parameter-tuning rule)
SCORECARD.md	Consolidated release-readiness scorecard
agent-orchestrator.yaml, bernstein.yaml, delta_config.yaml	Agent-orchestration config consumed by local automation
test_results/	Scratch output from local test runs (not authoritative; CI artifacts are)

🌳 Contributing & Branching

Development Workflow:

• Development: Use the develop branch for active feature development and testing.
• Pull Requests: Create PRs against the develop branch (PR body must include Closes #N / Fixes #N).
• Releases: Merge from develop to main via a release PR (--no-ff). No direct pushes to develop or main.

See CONTRIBUTING.md (short form) and CONTRIBUTING.md (long form) for detailed guidelines.

🚀 Release Process

Follow these steps to prepare and publish a new version of Fluxion.

Note on validation gating: ASHRAE 140 validation is not currently a release-passing check — the strict ±15% annual-energy gate applies only to the §7 (Class I) envelope-and-fabric cases that are not documented structural failures (see Current Validation Status); the other 140 sections are not implemented and are tracked in docs/compliance/section_coverage.md. Baseline Case 600 and high-mass Case 900 are excluded as known structural failures; do not treat "Case 900 annual energy within reference ranges" as a pre-release verification step — it is a known FAIL (5,130 kWh vs the 1,170–2,040 kWh band, per docs/KNOWN_ISSUES.md §LIMIT-05 UPDATE #2453) being addressed by the v1.3 milestone.

1. Version Bump

Update the version number in both configuration files:

• Rust: Cargo.toml ([package] version = "X.Y.Z")
• Python: pyproject.toml ([project] version = "X.Y.Z")

2. Validation & Quality Check

Ensure all physics and integration tests pass before proceeding:

# Run the full workspace suite (canonical — bare `cargo test` runs the ROOT crate only:
# `default-members = ["."]` silently skips ~4,400 sibling-crate tests while reporting green)
cargo test --workspace --exclude fluxion-tauri --no-fail-fast

# List the ASHRAE 140 validation binaries (the suite spans multiple `--test` binaries)
ls tests/ashrae_140*.rs

# Run one ASHRAE 140 binary with visible output; repeat per binary as needed
cargo test --test all_tests ashrae_140_validation:: -- --nocapture

Check the current pass rate and known failures in docs/ASHRAE140_RESULTS.md and SCORECARD.md — both report ASHRAE 140 §7 (Class I) scope only. The suite is not purely informational: the strict ±15% annual-energy regression gate is enforced in CI (.github/workflows/physics-pr.yml, job: "ASHRAE 140 Strict Energy Gate (Issue #1333)"; Issues #2506 / #3572), excluding the documented structural failures noted above. Required branch-protection checks are listed in release_gates.yaml → ci.required_checks.

3. Package Verification

Verify the crate size and structure for crates.io:

# Check package size (must be < 10MB)
# Ensure large directories like refdata/ and assets/ are excluded in Cargo.toml
cargo publish --dry-run --allow-dirty

Successful output should show: Packaged X files, ~3.1MiB (632.9KiB compressed).

4. Build Python Wheels

Build the cross-platform Python wheels:

maturin build --release

Wheels will be generated in target/wheels/.

5. Publication

Publish to package registries (requires owner tokens):

# Publish to crates.io
cargo publish

# Publish to PyPI
twine upload target/wheels/*

6. GitHub Release

Create a new tag and release on GitHub:

gh release create vX.Y.Z --notes-file CHANGELOG.md

🧪 Usage

Quantum/ML Oracle (High Throughput)

Used for Genetic Algorithms, D-Wave Quantum Annealers, or Bayesian Optimization.

import fluxion
import numpy as np

# Initialize the Oracle
oracle = fluxion.BatchOracle()

# Generate a population of 10,000 design candidates
# Column 0: Window U-Value (0.5 to 3.0)
# Column 1: HVAC Setpoint (19.0 to 24.0)
population = np.random.rand(10000, 2).tolist()

# Evaluate all 10,000 in parallel (Rust handles the threading)
results = oracle.evaluate_population(population, use_surrogates=True)

print(f"Best Performance: {min(results)}")

🤖 Training AI Surrogates

Fluxion uses AI surrogates to accelerate expensive physics calculations. These surrogates are trained on physics-extracted training data from the data/training/ directory.

Training Instructions

1. Install development dependencies:

   pip install -r requirements-dev.txt

2. Train a surrogate model:

   python tools/train_surrogate.py --num-samples 50000 --epochs 100

   This script extracts training data from physics simulations (or loads pre-extracted samples from data/training/) and trains a PyTorch neural network.

3. Output: Trained models are saved to the models/ directory in ONNX format (e.g., models/surrogate.onnx).

   Production training source: Pre-extracted physics samples live in data/training/. The training script loads from this directory (see data/training/README.md for the extraction pipeline).

Configuration Options

Key arguments (see python tools/train_surrogate.py --help for full list):

• --num-samples: Number of training samples (default: 10000)
• --epochs: Training epochs (default: 100)
• --hidden-dims: Hidden layer sizes (e.g., 128 64)
• --output-dir: Directory for saving results

Integration

Once trained, the ONNX model is wired to the Rust SurrogateManager for inference (Issue #1285). The SurrogateManager::load_onnx() method loads the model and runs real ONNX inference at swap points.

🧩 Examples

A set of small, self-contained examples are included in the examples/ folder to help new users get started quickly:

• examples/run_model.py: Creates a Model, runs a 1-year simulation with and without surrogates, and prints results.
• examples/run_ashrae_check.py: Recommended first run. Runs the ASHRAE 140-2023 validation pipeline in fast mode (provenance verify + strict ±15% energy gate + honesty guard) in ~5 seconds, no Rust toolchain needed. A real ASHRAE comparison against the published reference bands (recorded suite values, not a fresh engine run; the full ~10 min end-to-end run is python3 scripts/ashrae_140_pipeline.py).
• examples/run_oracle.py: Creates a BatchOracle, generates a small random population (20 candidates) and evaluates it using surrogates.
• examples/quick_start.sh: A helper script that installs maturin (if necessary), builds the Python bindings locally, and runs the oracle example.

Quick start (minimal):

1. Create and activate a Python virtual environment (optional but recommended):

python3 -m venv .venv
source .venv/bin/activate

2. Build & install Python bindings for local development:

pip install --upgrade pip
pip install maturin
maturin develop

3. Run the ASHRAE 140 check to see real validation results (recommended first run, ~5 seconds):

python examples/run_ashrae_check.py

Or run the oracle example (requires maturin develop first; shows the throughput API with deterministic mock loads):

python examples/run_oracle.py

Or use the helper script which runs the same steps (macOS / zsh):

bash examples/quick_start.sh

If you encounter an import error when running the examples, ensure maturin develop completed successfully and your Python interpreter matches the one used to build the bindings.

Sample Output

Running the small oracle example may produce output similar to the following:

Creating BatchOracle...
Evaluating population of 20 candidates (surrogates ON)...
Elapsed: 0.006s
Best candidate index: 12, EUI: 268850.3790
Sample results:
  #0: U=1.034, setpoint=19.44 -> EUI=678227.4306
  #1: U=2.733, setpoint=23.86 -> EUI=1699972.7457
  #2: U=2.229, setpoint=19.07 -> EUI=1192690.7518
  #3: U=1.413, setpoint=21.23 -> EUI=1107914.1676
  #4: U=2.733, setpoint=19.44 -> EUI=1312456.1032

Interpreting Results

• U: Window thermal transmittance (U-value) in W/m²K — lower values indicate better insulating windows. Example range used by the examples: 0.5 (high-performing glazing) to 3.0 (poor glazing).

• setpoint: HVAC setpoint temperature in degrees Celsius (°C). Typical design range in examples: 19.0 to 24.0.

• EUI: Energy metric printed by the examples. In this repository the physics engine is intentionally simplified for clarity and testing: the ThermalModel::solve_timesteps routine accumulates a raw, per-hour, per-zone energy-like value (sum of absolute temperature departure from setpoint across all zones and hours). Because of that, numeric EUI values printed by the toy examples are very large — they are a raw cumulative metric, not a calibrated kWh/m²/year. Use these values for relative comparison (lower = better), not as validated physical EUI numbers.

  • If you need a quick normalization for human-scale comparison, divide the reported EUI by the number of zones and number of timesteps (e.g., num_zones * 8760) to get an average hourly temperature-gap metric. Converting this to physical energy (kWh/m²) requires thermal capacity and area scaling which are not part of the current toy model.

• Elapsed: Wall-clock time to evaluate the population. The BatchOracle is designed for high-throughput evaluation (many candidates in parallel); elapsed time will depend on population size and whether surrogates are enabled.

• Best candidate index: Index of the candidate with the lowest (best) EUI in the evaluated population and its corresponding EUI value.

Notes:

• The included SurrogateManager currently returns deterministic mock loads when no neural model is loaded, so results are deterministic given the same random seed and are intended for API validation and performance testing rather than production accuracy.
• For validation or publication-quality results, implement a trained surrogate (ONNX) and complete the v1.3 blind-validation milestone; then EUI can be converted and reported in kWh/m²/year as described in the docs.