better-lbnl-os 0.1.1

Open-source building energy analytics library from BETTER (Building Efficiency Targeting Tool for Energy Retrofits)

BETTER-LBNL-OS

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

Using uv (recommended)

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

• Project Inquiries: [e-mail]
• Technical Lead: Han Li ([e-mail])
• Principal Investigator: Carolyn Szum ([e-mail])

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.

Related Projects

• BETTER Web Application: Full web-based building analysis platform
• BuildingSync: Standard schema for building data exchange
• SEED Platform: Standard Energy Efficiency Data Platform