openBES 0.1.0__tar.gz

openbes-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: openBES
+Version: 0.1.0
+Summary: Python implementation of the Open Building Energy Simulation (OpenBES) tool.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pandas
+Requires-Dist: pvlib
+Requires-Dist: numba
+Provides-Extra: dev
+Requires-Dist: line_profiler; extra == "dev"
+
+# OpenBES-py
+
+[![Unittest](https://github.com/OxfordRSE/OpenBES-py/actions/workflows/unittest.yml/badge.svg)](https://github.com/OxfordRSE/OpenBES-py/actions/workflows/unittest.yml)
+[![ASHRAE 140 Suite](https://github.com/OxfordRSE/OpenBES-py/actions/workflows/test_cases.yml/badge.svg)](https://github.com/OxfordRSE/OpenBES-py/actions/workflows/test_cases.yml)
+[![.github/workflows/package_test.yml](https://github.com/OxfordRSE/OpenBES-py/actions/workflows/package_test.yml/badge.svg)](https://github.com/OxfordRSE/OpenBES-py/actions/workflows/package_test.yml)
+
+OpenBES-py is an open-source building energy simulation tool written in Python. It is designed to provide transparent, reproducible, and extensible energy modeling for buildings, supporting research, education, and practical analysis.
+
+## Features
+
+- **Modular simulation engine**: Each energy category is implemented as a separate module for clarity and extensibility.
+- **Comprehensive test suite**: All core modules are covered by unit and integration tests.
+- **Standardized test cases**: Planned integration with ASHRAE Standard 140 test cases (see `cases_ashrae_std140_...` directory).
+- **Modern dependency management**: Uses [UV](https://github.com/astral-sh/uv) for fast, reliable Python environment setup (`uv.lock` included).
+
+## Current Status
+
+The Python code reproduces the Excel spreadsheet simulation results for the Holywell House specification to at least 6 decimal places.
+
+The next step is to validate the Python code against ASHRAE Standard 140 test cases.
+
+## Installation
+
+1. Install [UV](https://github.com/astral-sh/uv) if you do not have it: `pip install uv`
+
+2. Set up a virtual environment (recommended): `uv venv`
+
+3. Install dependencies: `uv sync`
+
+4. Run tests to verify installation: `uv run python -m unittest discover -s tests`
+
+## License
+
+The license for this project is under consideration. 
+
+## Credits
+
+We use Pandas for data manipulation and NumPy for numerical calculations.
+
+We use PVLib.iotools for reading EPW (energy plus weather) files.
+
+    Jensen, A., Anderson, K., Holmgren, W., Mikofski, M., Hansen, C., Boeman, L., Loonen, R. “pvlib iotools — Open-source Python functions for seamless access to solar irradiance data.” Solar Energy, 266, 112092, (2023). DOI: 10.1016/j.solener.2023.112092.
+

openbes-0.1.0/README.md

@@ -0,0 +1,43 @@
+# OpenBES-py
+
+[![Unittest](https://github.com/OxfordRSE/OpenBES-py/actions/workflows/unittest.yml/badge.svg)](https://github.com/OxfordRSE/OpenBES-py/actions/workflows/unittest.yml)
+[![ASHRAE 140 Suite](https://github.com/OxfordRSE/OpenBES-py/actions/workflows/test_cases.yml/badge.svg)](https://github.com/OxfordRSE/OpenBES-py/actions/workflows/test_cases.yml)
+[![.github/workflows/package_test.yml](https://github.com/OxfordRSE/OpenBES-py/actions/workflows/package_test.yml/badge.svg)](https://github.com/OxfordRSE/OpenBES-py/actions/workflows/package_test.yml)
+
+OpenBES-py is an open-source building energy simulation tool written in Python. It is designed to provide transparent, reproducible, and extensible energy modeling for buildings, supporting research, education, and practical analysis.
+
+## Features
+
+- **Modular simulation engine**: Each energy category is implemented as a separate module for clarity and extensibility.
+- **Comprehensive test suite**: All core modules are covered by unit and integration tests.
+- **Standardized test cases**: Planned integration with ASHRAE Standard 140 test cases (see `cases_ashrae_std140_...` directory).
+- **Modern dependency management**: Uses [UV](https://github.com/astral-sh/uv) for fast, reliable Python environment setup (`uv.lock` included).
+
+## Current Status
+
+The Python code reproduces the Excel spreadsheet simulation results for the Holywell House specification to at least 6 decimal places.
+
+The next step is to validate the Python code against ASHRAE Standard 140 test cases.
+
+## Installation
+
+1. Install [UV](https://github.com/astral-sh/uv) if you do not have it: `pip install uv`
+
+2. Set up a virtual environment (recommended): `uv venv`
+
+3. Install dependencies: `uv sync`
+
+4. Run tests to verify installation: `uv run python -m unittest discover -s tests`
+
+## License
+
+The license for this project is under consideration. 
+
+## Credits
+
+We use Pandas for data manipulation and NumPy for numerical calculations.
+
+We use PVLib.iotools for reading EPW (energy plus weather) files.
+
+    Jensen, A., Anderson, K., Holmgren, W., Mikofski, M., Hansen, C., Boeman, L., Loonen, R. “pvlib iotools — Open-source Python functions for seamless access to solar irradiance data.” Solar Energy, 266, 112092, (2023). DOI: 10.1016/j.solener.2023.112092.
+

openbes-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "openBES"
+version = "0.1.0"
+description = "Python implementation of the Open Building Energy Simulation (OpenBES) tool."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "pandas",
+    "pvlib",
+    "numba",
+]
+
+[project.optional-dependencies]
+dev = [
+    "line_profiler",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["openbes*"]
+
+[build-system]
+requires = ["setuptools>=61", "wheel", "build"]
+build-backend = "setuptools.build_meta"

openbes-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

openbes-0.1.0/src/openBES.egg-info/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: openBES
+Version: 0.1.0
+Summary: Python implementation of the Open Building Energy Simulation (OpenBES) tool.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pandas
+Requires-Dist: pvlib
+Requires-Dist: numba
+Provides-Extra: dev
+Requires-Dist: line_profiler; extra == "dev"
+
+# OpenBES-py
+
+[![Unittest](https://github.com/OxfordRSE/OpenBES-py/actions/workflows/unittest.yml/badge.svg)](https://github.com/OxfordRSE/OpenBES-py/actions/workflows/unittest.yml)
+[![ASHRAE 140 Suite](https://github.com/OxfordRSE/OpenBES-py/actions/workflows/test_cases.yml/badge.svg)](https://github.com/OxfordRSE/OpenBES-py/actions/workflows/test_cases.yml)
+[![.github/workflows/package_test.yml](https://github.com/OxfordRSE/OpenBES-py/actions/workflows/package_test.yml/badge.svg)](https://github.com/OxfordRSE/OpenBES-py/actions/workflows/package_test.yml)
+
+OpenBES-py is an open-source building energy simulation tool written in Python. It is designed to provide transparent, reproducible, and extensible energy modeling for buildings, supporting research, education, and practical analysis.
+
+## Features
+
+- **Modular simulation engine**: Each energy category is implemented as a separate module for clarity and extensibility.
+- **Comprehensive test suite**: All core modules are covered by unit and integration tests.
+- **Standardized test cases**: Planned integration with ASHRAE Standard 140 test cases (see `cases_ashrae_std140_...` directory).
+- **Modern dependency management**: Uses [UV](https://github.com/astral-sh/uv) for fast, reliable Python environment setup (`uv.lock` included).
+
+## Current Status
+
+The Python code reproduces the Excel spreadsheet simulation results for the Holywell House specification to at least 6 decimal places.
+
+The next step is to validate the Python code against ASHRAE Standard 140 test cases.
+
+## Installation
+
+1. Install [UV](https://github.com/astral-sh/uv) if you do not have it: `pip install uv`
+
+2. Set up a virtual environment (recommended): `uv venv`
+
+3. Install dependencies: `uv sync`
+
+4. Run tests to verify installation: `uv run python -m unittest discover -s tests`
+
+## License
+
+The license for this project is under consideration. 
+
+## Credits
+
+We use Pandas for data manipulation and NumPy for numerical calculations.
+
+We use PVLib.iotools for reading EPW (energy plus weather) files.
+
+    Jensen, A., Anderson, K., Holmgren, W., Mikofski, M., Hansen, C., Boeman, L., Loonen, R. “pvlib iotools — Open-source Python functions for seamless access to solar irradiance data.” Solar Energy, 266, 112092, (2023). DOI: 10.1016/j.solener.2023.112092.
+

openbes-0.1.0/src/openBES.egg-info/SOURCES.txt

@@ -0,0 +1,23 @@
+README.md
+pyproject.toml
+src/openBES.egg-info/PKG-INFO
+src/openBES.egg-info/SOURCES.txt
+src/openBES.egg-info/dependency_links.txt
+src/openBES.egg-info/requires.txt
+src/openBES.egg-info/top_level.txt
+src/openbes/__init__.py
+src/openbes/simulations/__init__.py
+src/openbes/simulations/base.py
+src/openbes/simulations/building_energy.py
+src/openbes/simulations/climate.py
+src/openbes/simulations/cooling.py
+src/openbes/simulations/geometry.py
+src/openbes/simulations/heating.py
+src/openbes/simulations/hot_water.py
+src/openbes/simulations/lighting.py
+src/openbes/simulations/occupancy.py
+src/openbes/simulations/solar_irradiation.py
+src/openbes/simulations/ventilation.py
+src/openbes/types/__init__.py
+src/openbes/types/dataclasses.py
+src/openbes/types/enums.py

openbes-0.1.0/src/openBES.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openbes-0.1.0/src/openBES.egg-info/requires.txt

@@ -0,0 +1,6 @@
+pandas
+pvlib
+numba
+
+[dev]
+line_profiler

openbes-0.1.0/src/openBES.egg-info/top_level.txt

@@ -0,0 +1 @@
+openbes

openbes-0.1.0/src/openbes/__init__.py

@@ -0,0 +1,2 @@
+from .simulations.building_energy import BuildingEnergySimulation
+from .types import OpenBESSpecification

openbes-0.1.0/src/openbes/simulations/base.py

@@ -0,0 +1,91 @@
+from pandas import DataFrame
+
+from ..types import OpenBESSpecification, ENERGY_SOURCES
+
+
+def month_for_day(day_number_in_year: int) -> int:
+    """Calculate the month for a given day number in the year.
+    Args:
+        day_number_in_year (int): The day number in the year (1-365).
+    Returns:
+        int: The corresponding month (1-12).
+    """
+    if day_number_in_year <= 31:
+        return 1
+    elif day_number_in_year <= 59:
+        return 2
+    elif day_number_in_year <= 90:
+        return 3
+    elif day_number_in_year <= 120:
+        return 4
+    elif day_number_in_year <= 151:
+        return 5
+    elif day_number_in_year <= 181:
+        return 6
+    elif day_number_in_year <= 212:
+        return 7
+    elif day_number_in_year <= 243:
+        return 8
+    elif day_number_in_year <= 273:
+        return 9
+    elif day_number_in_year <= 304:
+        return 10
+    elif day_number_in_year <= 334:
+        return 11
+    else:
+        return 12
+
+
+# Blank DataFrame of each hour with month info, indexed by day of the year
+HOURS_DF = DataFrame([
+    {
+        'month': month_for_day(d),
+        'day': d,
+        'hour': h,
+        'is_daytime': 8 <= h <= 22
+    } for d in range(1, 366) for h in range(1, 25)
+]).set_index(['month', 'day', 'hour'])
+
+
+class HourlySimulation:
+    """
+    Base class for hourly simulations.
+
+    Each instance is initialized with an OpenBESSpecification and contains an _hours property
+    that holds a DataFrame representing each hour of the year.
+
+    Properties will typically add columns to the _hours DataFrame as needed for various calculations,
+    and usually return that DataFrame or specific columns from it.
+    """
+
+    spec: OpenBESSpecification
+    _hours: DataFrame
+
+    def __init__(self, spec: OpenBESSpecification):
+        self.spec = spec
+        self._hours = HOURS_DF.copy()
+
+
+class EnergyUseSimulation(HourlySimulation):
+    """
+    Base class for hourly energy use simulations.
+
+    Child classes should override the energy_use property to return a DataFrame representing
+    the energy use in kW for each hour of the year, with a column for each of the ENERGY_SOURCES.
+
+    The _energy_use property is initialized as a DataFrame of NaNs with the same index as _hours
+    and columns for each ENERGY_SOURCES. self.energy_use should populate this DataFrame appropriately.
+    """
+    def __init__(self, spec: OpenBESSpecification):
+        super().__init__(spec)
+        self._energy_use = DataFrame(index=self._hours.index, columns=list(ENERGY_SOURCES)).astype(float)
+
+    @property
+    def energy_use(self) -> DataFrame:
+        """DataFrame of energy use in kW for each hour of the year, with a column for each ENERGY_SOURCES.
+        """
+        raise NotImplementedError("Child classes must implement the energy_use property.")
+
+    @property
+    def annual_energy_use(self) -> DataFrame:
+        return self.energy_use.sum().sum()

openbes-0.1.0/src/openbes/simulations/building_energy.py

@@ -0,0 +1,102 @@
+import logging
+from typing import Dict
+
+from pandas import DataFrame
+
+from .base import EnergyUseSimulation
+from .climate import ClimateSimulation
+from .cooling import CoolingSimulation
+from .geometry import BuildingGeometry
+from .heating import HeatingSimulation
+from .hot_water import HotWaterSimulation
+from .lighting import LightingSimulation
+from .occupancy import OccupationSimulation
+from .ventilation import VentilationSimulation
+from ..types import (
+    OpenBESSpecification,
+    ENERGY_USE_CATEGORIES,
+    ENERGY_SOURCES,
+)
+
+logger = logging.getLogger(__name__)
+
+class BuildingEnergySimulation(EnergyUseSimulation):
+    """
+    A building energy simulation takes a building specification and model parameters and produces a report
+    on the energy use of the building.
+    """
+
+    def __init__(
+            self,
+            spec: OpenBESSpecification,
+            hot_water: HotWaterSimulation = None,
+            geometry: BuildingGeometry = None,
+            occupancy: OccupationSimulation = None,
+            lighting: LightingSimulation = None,
+            ventilation: VentilationSimulation = None,
+            climate: ClimateSimulation = None,
+            cooling: CoolingSimulation = None,
+            heating: HeatingSimulation = None,
+    ):
+        super().__init__(spec)
+        self._standby_energy_use = self._energy_use.copy()
+        self._standby_energy_use[ENERGY_SOURCES.Electricity] = (spec.building_standby_load * 12) / len(self._energy_use)
+        self._other_energy_use = self._energy_use.copy()
+        self._other_energy_use[ENERGY_SOURCES.Electricity] = (spec.other_electricity_usage * 12) / len(self._energy_use)
+        self._other_energy_use[ENERGY_SOURCES.Natural_gas] = (spec.other_gas_usage * 12) / len(self._energy_use)
+        self.hot_water = hot_water or HotWaterSimulation(self.spec)
+        self.geometry = geometry or BuildingGeometry(self.spec)
+        self.occupancy = occupancy or OccupationSimulation(self.spec, geometry=self.geometry)
+        self.lighting = lighting or LightingSimulation(self.spec, occupancy=self.occupancy)
+        self.ventilation = ventilation or VentilationSimulation(
+            self.spec,
+            occupancy=self.occupancy,
+            geometry=self.geometry
+        )
+        self.climate = climate or ClimateSimulation(
+            spec,
+            geometry=self.geometry,
+            occupancy=self.occupancy,
+            lighting=self.lighting,
+            ventilation=self.ventilation,
+        )
+        self.cooling = cooling or CoolingSimulation(
+            spec,
+            geometry=self.geometry,
+            occupancy=self.occupancy,
+            lighting=self.lighting,
+            ventilation=self.ventilation,
+            climate=self.climate,
+        )
+        self.heating = heating or HeatingSimulation(
+            spec,
+            geometry=self.geometry,
+            occupancy=self.occupancy,
+            lighting=self.lighting,
+            ventilation=self.ventilation,
+            climate=self.climate,
+        )
+
+    @property
+    def energy_use_by_category(self) -> Dict[ENERGY_USE_CATEGORIES, DataFrame]:
+        """Heating energy use in kWh for each hour of the year for each ENERGY_SOURCE for each ENERGY_USE_CATEGORY.
+        """
+        return {
+                ENERGY_USE_CATEGORIES.Others: self._other_energy_use,
+                ENERGY_USE_CATEGORIES.Building_standby: self._standby_energy_use,
+                ENERGY_USE_CATEGORIES.Lighting: self.lighting.energy_use,
+                ENERGY_USE_CATEGORIES.Hot_water: self.hot_water.energy_use,
+                ENERGY_USE_CATEGORIES.Ventilation: self.ventilation.energy_use,
+                ENERGY_USE_CATEGORIES.Cooling: self.cooling.energy_use,
+                ENERGY_USE_CATEGORIES.Heating: self.heating.energy_use,
+            }
+
+    @property
+    def energy_use(self) -> DataFrame:
+        """Total energy use in kWh for each hour of the year for each ENERGY_SOURCE.
+        """
+        if self._energy_use.isna().any().any():
+            self._energy_use.fillna(0, inplace=True)
+            for category_use in self.energy_use_by_category.values():
+                self._energy_use = self._energy_use.add(category_use, fill_value=0.0)
+        return self._energy_use