Metadata-Version: 2.4
Name: better-lbnl-os
Version: 0.1.0
Summary: Open-source building energy analytics library extracted from BETTER (Building Efficiency Targeting Tool for Energy Retrofits)
Project-URL: Homepage, https://github.com/LBNL-ETA/better-lbnl-os
Project-URL: Documentation, https://better-lbnl-os.readthedocs.io
Project-URL: Repository, https://github.com/LBNL-ETA/better-lbnl-os
Project-URL: Issues, https://github.com/LBNL-ETA/better-lbnl-os/issues
Project-URL: Changelog, https://github.com/LBNL-ETA/better-lbnl-os/blob/main/CHANGELOG.md
Author-email: Han Li <hanli@lbl.gov>
Maintainer-email: Han Li <hanli@lbl.gov>
License: Building Efficiency Targeting Tool for Energy Retrofits (BETTER), Copyright (c) 2018, 
        The Regents of the University of California, through Lawrence Berkeley National 
        Laboratory, and Johnson Controls, Inc. (collectively the “Licensors”) subject to
        receipt of any required approvals from the U.S. Dept. of Energy.  All rights reserved.
         
        If you have questions about your rights to use or distribute this software,
        please contact Berkeley Lab’s Intellectual Property Office at IPO@lbl.gov
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        (1) Redistributions of source code must retain the above copyright notice,
        this list of conditions and the following disclaimer.
         
        (2) Redistributions in binary form must reproduce the above copyright notice,
        this list of conditions and the following disclaimer in the documentation
        and/or other materials provided with the distribution.
         
        (3) Neither the name of the University of California, Lawrence Berkeley
        National Laboratory, U.S. Dept. of Energy, Johnson Controls, Inc., nor the
        names of its contributors may be used to endorse or promote products derived
        from this software without specific prior written permission.
        
        (4) Use of the software, in source or binary form is permitted for both
        commercial and non-commercial purposes, provided however that no right or
        license to any of Licensors’ related patents or other intellectual property
        rights extends to any uses or applications not in full compliance with this
        open source license.
         
        (5) In the event you create any bug fixes, patches, upgrades, updates,
        improvements, modifications, derivative works or enhancements to the source
        code or binary code of the software (“Enhancements”) you hereby grant the
        Licensors each, a paid-up, non-exclusive, irrevocable, worldwide license in
        the Enhancements to reproduce, prepare derivative works, distribute copies to
        the public, perform publicly and display publicly, and to permit others to do
        so.  Programming dynamically linked to the software shall not be deemed
        derivative works or Enhancements of the software, nor subject to the foregoing 
        license.   
        
         
        THIS SOFTWARE IS PROVIDED BY THE LICENSOR AND CONTRIBUTORS “AS IS” AND ANY
        EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
        WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-
        INFRINGEMENT ARE DISCLAIMED. IN NO EVENT SHALL THE LICENSORS OR CONTRIBUTORS
        BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
        SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
        INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
        CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
        ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
        POSSIBILITY OF SUCH DAMAGE.
        
        NOTICE.  This Software was developed under funding from the U.S. Department of 
        Energy and the U.S. Government consequently retains certain rights. As such, 
        the U.S. Government has been granted for itself and others acting on its 
        behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to 
        reproduce, distribute copies to the public, prepare derivative works, and perform 
        publicly and display publicly, and to permit other to do so. 
License-File: LICENSE
Keywords: BETTER,LBNL,benchmarking,building energy,change-point model,energy analytics,energy efficiency
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: geocoder>=1.38.1
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: requests>=2.28.0
Requires-Dist: scipy>=1.7.0
Provides-Extra: all
Requires-Dist: black>=23.0.0; extra == 'all'
Requires-Dist: ipykernel>=6.0.0; extra == 'all'
Requires-Dist: ipywidgets>=8.0.0; extra == 'all'
Requires-Dist: isort>=5.12.0; extra == 'all'
Requires-Dist: jupyter>=1.0.0; extra == 'all'
Requires-Dist: matplotlib>=3.5.0; extra == 'all'
Requires-Dist: mypy>=1.0.0; extra == 'all'
Requires-Dist: nbsphinx>=0.9.0; extra == 'all'
Requires-Dist: notebook>=6.4.0; extra == 'all'
Requires-Dist: plotly>=5.0.0; extra == 'all'
Requires-Dist: pre-commit>=3.0.0; extra == 'all'
Requires-Dist: pytest-cov>=4.0.0; extra == 'all'
Requires-Dist: pytest-mock>=3.10.0; extra == 'all'
Requires-Dist: pytest>=7.0.0; extra == 'all'
Requires-Dist: ruff>=0.1.0; extra == 'all'
Requires-Dist: sphinx-autodoc-typehints>=1.23.0; extra == 'all'
Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == 'all'
Requires-Dist: sphinx>=6.0.0; extra == 'all'
Requires-Dist: types-requests>=2.28.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: ipykernel>=6.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: matplotlib>=3.5.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: nbsphinx>=0.9.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: sphinx-autodoc-typehints>=1.23.0; extra == 'dev'
Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == 'dev'
Requires-Dist: sphinx>=6.0.0; extra == 'dev'
Requires-Dist: types-requests>=2.28.0; extra == 'dev'
Provides-Extra: examples
Requires-Dist: ipywidgets>=8.0.0; extra == 'examples'
Requires-Dist: jupyter>=1.0.0; extra == 'examples'
Requires-Dist: notebook>=6.4.0; extra == 'examples'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5.0; extra == 'viz'
Requires-Dist: plotly>=5.0.0; extra == 'viz'
Description-Content-Type: text/markdown

# BETTER-LBNL

[![CI](https://github.com/LBNL-ETA/better-lbnl-os/actions/workflows/ci.yml/badge.svg)](https://github.com/LBNL-ETA/better-lbnl-os/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/LBNL-ETA/better-lbnl-os/branch/main/graph/badge.svg)](https://codecov.io/gh/LBNL-ETA/better-lbnl-os)
[![PyPI version](https://badge.fury.io/py/better-lbnl-os.svg)](https://badge.fury.io/py/better-lbnl-os)
[![Python Versions](https://img.shields.io/pypi/pyversions/better-lbnl-os.svg)](https://pypi.org/project/better-lbnl-os/)
[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
[![Documentation Status](https://readthedocs.org/projects/better-lbnl-os/badge/?version=latest)](https://better-lbnl-os.readthedocs.io/en/latest/?badge=latest)

Open-source Python library for building energy analytics, serving as the analytical engine underlying the [BETTER web application](https://better.lbl.gov) (Building Efficiency Targeting Tool for Energy Retrofits).

## Features

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

## Installation

### Using pip

```bash
pip install better-lbnl-os
```

### Using uv (recommended)

```bash
uv add better-lbnl-os
```

### Development Installation

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

## Quick Start

```python
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](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](CONTRIBUTING.md) 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:

```bash
# 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 BSD license with additional DOE government clauses - see the [LICENSE](LICENSE) and [COPYRIGHT](COPYRIGHT) files for details.

## Citation

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

```bibtex
@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

- **Author**: Han Li (hanli@lbl.gov)
- **Project Manager**: Carolyn Szum (cszum@lbl.gov)
- **Organization**: Lawrence Berkeley National Laboratory

## Acknowledgments

This work was supported by the U.S. Department of Energy's Building Technologies Office. BETTER is part of the [DOE Building Data Tools](https://buildingdata.energy.gov/) ecosystem.

- **DOE Program Manager**: Billierae Engelman
- **Cooperative Research and Development Agreement (CRADA) Partner**: Johnson Controls, Inc. (benchmarking methodology and LEAN Energy Analysis)

## Related Projects

- [BETTER Web Application](https://better.lbl.gov): The full web-based building analysis platform
- [BuildingSync](https://buildingsync.net): Schema for building data exchange
- [SEED Platform](https://seed-platform.org): Standard Energy Efficiency Data Platform
