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.

🏗 Architecture

Fluxion separates the "heavy lifting" of physics (CFD/Radiation) into AI surrogates, while maintaining a rigorous First-Principles thermal network for energy conservation.

ASHRAE 140 Validation

Fluxion is validated against ASHRAE Standard 140-2023 (8 of 18 cases currently implemented). This ensures the accuracy of our differentiable physics engine against industry-standard benchmarks.

Note: Full 18/18 validation is in progress. See GitHub Issue #103 for implementation status.

Key features validated:

• Shading: Overhangs and vertical fins.
• Multi-Zone: Inter-zone heat transfer through common walls.
• Scheduling: Thermostat setbacks and timed ventilation.
• Free-Floating: Natural thermal response without HVAC.

See ASHRAE 140 Validation for details.

🚀 Features

• Throughput: Evaluates 10,000+ configurations/sec via BatchOracle and rayon threading.
• Speed: <100ms annual simulations via AI approximation.
• Hybrid Physics: Hard constraints (Energy Balance) + Soft constraints (Neural Surrogates).
• Interoperability: Native Python SDK via pyo3.

🛠 Installation

Rust Core

cargo build --release

Python Bindings

pip install maturin
maturin develop

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'

🌳 Contributing & Branching

Development Workflow:

• Development: Use the develop branch for active feature development and testing
• Pull Requests: Create PRs against the develop branch
• Releases: Merge from develop to main for official releases

See CONTRIBUTING.md for detailed guidelines.

🧪 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 must be trained on synthetic data generated by the analytical model.

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 generates synthetic data using the analytical physics model (or loads it from a file) and trains a PyTorch neural network.

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

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 can be integrated into the Rust SurrogateManager for inference. This is a future enhancement; currently, the SurrogateManager uses placeholder values.

🧩 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_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 oracle example to see actual results:

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 calibrate the physics engine; then EUI can be converted and reported in kWh/m²/year as described in the docs.