BETTER-LBNL-OS

December 23, 2025 · View on GitHub

CI codecov PyPI version Python Versions License Documentation Status

Open-source Python library for building energy analytics, serving as the analytical engine underlying the Building Efficiency Targeting Tool for Energy Retrofits (BETTER) web application. BETTER is a software toolkit that enables building operators to quickly, easily identify the most cost-saving energy efficiency measures in buildings and portfolios. BETTER is made possible by support from the U.S. Department of Energy (DOE) Building Technologies Office (BTO).

Features

  • Change-point Model Fitting: Automated fitting of 1-, 3-, 5-parameter (1P/3P/5P) change-point models for building energy analysis
  • Building Benchmarking: Statistical comparison of building energy performance against peer groups
  • Energy Savings Estimation: Weather-normalized energy savings calculations with uncertainty quantification
  • Energy Efficiency Measure Recommendations: Rule-based recommendations for energy efficiency improvements
  • Portfolio Analytics: Aggregate analysis across multiple buildings

Installation

Using pip

pip install better-lbnl-os

uv add better-lbnl-os

Development Installation

git clone https://github.com/LBNL-ETA/better-lbnl-os.git
cd better-lbnl-os
uv venv
uv pip install -e ".[dev]"

Quick Start

from better_lbnl_os import fit_changepoint_model
import numpy as np

# Prepare temperature and energy data (showing heating and cooling patterns)
temperatures = np.array([30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85])  # °F
energy_use = np.array([150, 140, 125, 110, 95, 85, 80, 80, 85, 95, 110, 125])  # kBtu/day

# Fit change-point model
model_result = fit_changepoint_model(temperatures, energy_use)

# Check model quality
if model_result.is_valid():
    print(f"Model Type: {model_result.model_type}")  # 5P (heating and cooling)
    print(f"R-squared: {model_result.r_squared:.3f}")  # 0.995
    print(f"Baseload: {model_result.baseload:.1f}")  # 80.0

Documentation

Full documentation is available at https://better-lbnl-os.readthedocs.io

Key Concepts

  • Domain Models: Rich objects that encapsulate both data and business logic
  • Pure Functions: Mathematical algorithms implemented as side-effect-free functions
  • Service Layer: Orchestration of complex workflows
  • Adapter Pattern: Clean separation for framework integration

Examples

See the examples/ directory for:

  • benchmarking_demo.py - Building benchmarking demonstration
  • notebooks/explore.ipynb - Interactive exploration notebook
  • weather/ - Weather data integration examples

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Install development dependencies (uv pip install -e ".[dev]")
  4. Make your changes
  5. Run tests (pytest)
  6. Run linting (ruff check . && black . && mypy src)
  7. Commit your changes (git commit -m 'Add amazing feature')
  8. Push to the branch (git push origin feature/amazing-feature)
  9. Open a Pull Request

Testing

Run the test suite:

# Run all tests
pytest

# Run with coverage
pytest --cov=better_lbnl_os --cov-report=html

# Run specific test categories
pytest -m "not slow"  # Skip slow tests
pytest tests/unit/    # Only unit tests

License

This project is licensed under a modified Berkeley Software Distribution (BSD) license with additional U.S. DOE government clauses - see the LICENSE and COPYRIGHT files for details.

Citation

If you use BETTER-LBNL-OS in your research, please cite:

@software{better_lbnl_os,
  author = {Li, Han},
  title = {BETTER-LBNL-OS: Open-Source Building Energy Analytics Library},
  year = {2025},
  publisher = {Lawrence Berkeley National Laboratory},
  url = {https://github.com/LBNL-ETA/better-lbnl-os}
}

Contact

Acknowledgments

This work was supported by the U.S. DOE BTO. BETTER is part of the U.S. DOE Building Data Tools portfolio.

  • U.S. DOE Program Manager: Billierae Engelman
  • Cooperative Research and Development Agreement (CRADA) Partner: Johnson Controls, Inc.