ebm 0.99.3__tar.gz

ebm-0.99.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Norges vassdrags- og energidirektorat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ebm-0.99.3/MANIFEST.in

@@ -0,0 +1,2 @@
+include ebm/data/*.csv
+recursive-include ebm *.py

ebm-0.99.3/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: ebm
+Version: 0.99.3
+Summary: A project for energy usage modeling
+Author-email: Lars Petrusson <lfep@nve.no>, Ketil Nordstad <kenord@nve.no>
+Project-URL: Homepage, https://www.nve.no/
+Project-URL: Documentation, https://nve.github.io/ebm-docs
+Project-URL: Repository, https://github.com/NVE/ebm
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: loguru
+Requires-Dist: numpy
+Requires-Dist: openpyxl
+Requires-Dist: pandas
+Requires-Dist: python-dotenv
+Requires-Dist: rich
+Requires-Dist: pandera
+Requires-Dist: XlsxWriter
+Requires-Dist: pywin32; platform_system == "Windows"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: build
+Requires-Dist: build; extra == "build"
+Provides-Extra: dev
+Requires-Dist: ebm[test]; extra == "dev"
+Requires-Dist: ebm[build]; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: ruff-lsp; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
+Requires-Dist: numpydoc; extra == "docs"
+Requires-Dist: sphinx-tabs; extra == "docs"
+Provides-Extra: tqdm
+Requires-Dist: tqdm; extra == "tqdm"
+Requires-Dist: XlsxWriter; extra == "tqdm"
+Dynamic: license-file
+
+#  Introduction 
+
+EBM is a model used by the Norwegian Water Resources and Energy Directorates (NVE) to forecast energy use in the 
+building stock. EBM is an open-source model developed and managed by NVE. The model allows the user to analyze how 
+demographic trends and policy instruments impact the yearly energy use on a national and regional level. Energy use is 
+estimated by a bottom- up approach, based on the building stock floor area, energy need and distribution of heating 
+systems. The mathematical model is implemented in Python, with input and output files in excel or csv.
+
+
+![ebm-in-windows-terminal.png](docs/source/_static/getting_started/ebm-in-windows-terminal.png)
+
+
+# Getting Started
+
+## More information
+
+
+ - [Full documentation found here](https://nve.github.io/ebm-docs/index.html)
+   - [Model description](https://nve.github.io/ebm-docs/model_description/index.html)
+   - [Limitations](https://nve.github.io/ebm-docs/limitations.html)
+   - [Getting started](https://nve.github.io/ebm-docs/user_guide/getting_started.html)
+   - [Troubleshooting](https://nve.github.io/ebm-docs/user_guide/troubleshooting.html)
+
+
+## 1. Installation process
+
+Please refer to [getting started](https://nve.github.io/ebm-docs/user_guide/getting_started.html) for information on 
+how ti install EBM as a user. 
+
+Open a terminal application and navigate to wherever you want to do work. 
+
+### Make a python virtual environment (optional)
+
+While optional, it is always recommended to install and run python modules in a discrete virtual environment. To create a 
+new python virtual environment (venv) type the following in a terminal.
+
+ `python -m venv venv`
+
+## Activate virtual environment
+To use your venv you need to activate it
+### Using powershell
+(Your command prompt starts with PS) 
+`\venv\Scripts\active.ps1`
+
+### Using cmd
+(Your command prompt starts with C:\ where C is any letter from A-Z)
+`\venv\Scripts\active.bat`
+
+### GNU/Linux and macOS
+
+`source venv/bin/active`
+
+More information on [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/)
+
+
+## Install EBM
+
+There are two options. **Install from PyPI** (Python package index) or install **clone the github repository**.
+
+### Install from PyPI
+
+`python -m pip install ebm`
+
+You can now run the model as a module `python -m ebm` or as a program `ebm`
+
+Please refer to [getting started](https://nve.github.io/ebm-docs/user_guide/getting_started.html) for more information on how the model works.
+
+
+### Clone the github repository
+
+`git clone https://github.com/NVE/ebm`
+
+`cd ebm`
+
+Make sure your current working directory is the EBM root. 
+
+```
+python -m pip install -e .
+
+```
+
+The command will install install all dependencies and ebm as an editable module.
+
+    
+    
+## 2. Software dependencies
+  - pandas
+  - loguru
+  - openpyxl
+  - pandera
+   
+  Dependecies will be automatically installed when you install the package as described under Installation process.
+  See also [requirements.txt](requirements.txt)
+
+## 3. Run the model
+
+There are multiple ways to run the program. Listed bellow is running as a standalone program and running as a module. If 
+running as a program fails due to security restriction, you might be able to use the module approach instead. 
+
+See also [Running as code](#running-as-code)
+
+
+### Running as a module
+
+```cmd
+python3 -m ebm
+```
+
+By default, the results will be written to the subdirectory `output`
+
+For more information use `--help`
+
+`python -m ebm --help`
+
+```shell
+usage: ebm [-h] [--version] [--debug] [--categories [CATEGORIES ...]] [--input [INPUT]] [--force] [--open]
+           [--csv-delimiter CSV_DELIMITER] [--create-input] [--horizontal-years]
+           [{area-forecast,energy-requirements,heating-systems,energy-use}] [output_file]
+
+Calculate EBM energy use 1.2.15
+
+positional arguments:
+  {area-forecast,energy-requirements,heating-systems,energy-use}
+
+                        The calculation step you want to run. The steps are sequential. Any prerequisite to the chosen step will run
+                            automatically.
+  output_file           The location of the file you want to be written. default: output\ebm_output.xlsx
+                            If the file already exists the program will terminate without overwriting.
+                            Use "-" to output to the console instead
+
+options:
+  -h, --help            show this help message and exit
+  --version, -v         show program's version number and exit
+  --debug               Run in debug mode. (Extra information written to stdout)
+  --categories [CATEGORIES ...], --building-categories [CATEGORIES ...], -c [CATEGORIES ...]
+
+                        One or more of the following building categories:
+                            house, apartment_block, kindergarten, school, university, office, retail, hotel, hospital, nursing_home, culture, sports, storage_repairs.
+                            The default is to use all categories.
+  --input [INPUT], --input-directory [INPUT], -i [INPUT]
+                        path to the directory with input files
+  --force, -f           Write to <filename> even if it already exists
+  --open, -o            Open output file(s) automatically when finished writing. (Usually Excel)
+  --csv-delimiter CSV_DELIMITER, --delimiter CSV_DELIMITER, -e CSV_DELIMITER
+                        A single character to be used for separating columns when writing csv. Default: "," Special characters like ; should be quoted ";"
+  --create-input
+                        Create input directory containing all required files in the current working directory
+  --horizontal-years, --horizontal, --horisontal
+                        Show years horizontal (left to right)
+```
+
+
+### Running as code
+```python
+
+from ebm.temp_calc import calculate_energy_use_wide
+from ebm.model.file_handler import FileHandler
+
+fh = FileHandler()
+fh.create_missing_input_files()
+
+df = calculate_energy_use_wide(ebm_input=fh.input_directory)
+print(df)
+
+```
+
+## License
+This project is licensed under the MIT License. You are free to use, modify, and distribute the software with proper attribution.
+
+## Contributing
+We welcome contributions! Please refer to the Contributing Guide (CONTRIBUTING.md) for details on how to get started.
+
+## Documentation
+Full documentation is available at the EBM User Guide: https://nve.github.io/ebm/
+
+
+

ebm-0.99.3/README.md

@@ -0,0 +1,177 @@
+#  Introduction 
+
+EBM is a model used by the Norwegian Water Resources and Energy Directorates (NVE) to forecast energy use in the 
+building stock. EBM is an open-source model developed and managed by NVE. The model allows the user to analyze how 
+demographic trends and policy instruments impact the yearly energy use on a national and regional level. Energy use is 
+estimated by a bottom- up approach, based on the building stock floor area, energy need and distribution of heating 
+systems. The mathematical model is implemented in Python, with input and output files in excel or csv.
+
+
+![ebm-in-windows-terminal.png](docs/source/_static/getting_started/ebm-in-windows-terminal.png)
+
+
+# Getting Started
+
+## More information
+
+
+ - [Full documentation found here](https://nve.github.io/ebm-docs/index.html)
+   - [Model description](https://nve.github.io/ebm-docs/model_description/index.html)
+   - [Limitations](https://nve.github.io/ebm-docs/limitations.html)
+   - [Getting started](https://nve.github.io/ebm-docs/user_guide/getting_started.html)
+   - [Troubleshooting](https://nve.github.io/ebm-docs/user_guide/troubleshooting.html)
+
+
+## 1. Installation process
+
+Please refer to [getting started](https://nve.github.io/ebm-docs/user_guide/getting_started.html) for information on 
+how ti install EBM as a user. 
+
+Open a terminal application and navigate to wherever you want to do work. 
+
+### Make a python virtual environment (optional)
+
+While optional, it is always recommended to install and run python modules in a discrete virtual environment. To create a 
+new python virtual environment (venv) type the following in a terminal.
+
+ `python -m venv venv`
+
+## Activate virtual environment
+To use your venv you need to activate it
+### Using powershell
+(Your command prompt starts with PS) 
+`\venv\Scripts\active.ps1`
+
+### Using cmd
+(Your command prompt starts with C:\ where C is any letter from A-Z)
+`\venv\Scripts\active.bat`
+
+### GNU/Linux and macOS
+
+`source venv/bin/active`
+
+More information on [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/)
+
+
+## Install EBM
+
+There are two options. **Install from PyPI** (Python package index) or install **clone the github repository**.
+
+### Install from PyPI
+
+`python -m pip install ebm`
+
+You can now run the model as a module `python -m ebm` or as a program `ebm`
+
+Please refer to [getting started](https://nve.github.io/ebm-docs/user_guide/getting_started.html) for more information on how the model works.
+
+
+### Clone the github repository
+
+`git clone https://github.com/NVE/ebm`
+
+`cd ebm`
+
+Make sure your current working directory is the EBM root. 
+
+```
+python -m pip install -e .
+
+```
+
+The command will install install all dependencies and ebm as an editable module.
+
+    
+    
+## 2. Software dependencies
+  - pandas
+  - loguru
+  - openpyxl
+  - pandera
+   
+  Dependecies will be automatically installed when you install the package as described under Installation process.
+  See also [requirements.txt](requirements.txt)
+
+## 3. Run the model
+
+There are multiple ways to run the program. Listed bellow is running as a standalone program and running as a module. If 
+running as a program fails due to security restriction, you might be able to use the module approach instead. 
+
+See also [Running as code](#running-as-code)
+
+
+### Running as a module
+
+```cmd
+python3 -m ebm
+```
+
+By default, the results will be written to the subdirectory `output`
+
+For more information use `--help`
+
+`python -m ebm --help`
+
+```shell
+usage: ebm [-h] [--version] [--debug] [--categories [CATEGORIES ...]] [--input [INPUT]] [--force] [--open]
+           [--csv-delimiter CSV_DELIMITER] [--create-input] [--horizontal-years]
+           [{area-forecast,energy-requirements,heating-systems,energy-use}] [output_file]
+
+Calculate EBM energy use 1.2.15
+
+positional arguments:
+  {area-forecast,energy-requirements,heating-systems,energy-use}
+
+                        The calculation step you want to run. The steps are sequential. Any prerequisite to the chosen step will run
+                            automatically.
+  output_file           The location of the file you want to be written. default: output\ebm_output.xlsx
+                            If the file already exists the program will terminate without overwriting.
+                            Use "-" to output to the console instead
+
+options:
+  -h, --help            show this help message and exit
+  --version, -v         show program's version number and exit
+  --debug               Run in debug mode. (Extra information written to stdout)
+  --categories [CATEGORIES ...], --building-categories [CATEGORIES ...], -c [CATEGORIES ...]
+
+                        One or more of the following building categories:
+                            house, apartment_block, kindergarten, school, university, office, retail, hotel, hospital, nursing_home, culture, sports, storage_repairs.
+                            The default is to use all categories.
+  --input [INPUT], --input-directory [INPUT], -i [INPUT]
+                        path to the directory with input files
+  --force, -f           Write to <filename> even if it already exists
+  --open, -o            Open output file(s) automatically when finished writing. (Usually Excel)
+  --csv-delimiter CSV_DELIMITER, --delimiter CSV_DELIMITER, -e CSV_DELIMITER
+                        A single character to be used for separating columns when writing csv. Default: "," Special characters like ; should be quoted ";"
+  --create-input
+                        Create input directory containing all required files in the current working directory
+  --horizontal-years, --horizontal, --horisontal
+                        Show years horizontal (left to right)
+```
+
+
+### Running as code
+```python
+
+from ebm.temp_calc import calculate_energy_use_wide
+from ebm.model.file_handler import FileHandler
+
+fh = FileHandler()
+fh.create_missing_input_files()
+
+df = calculate_energy_use_wide(ebm_input=fh.input_directory)
+print(df)
+
+```
+
+## License
+This project is licensed under the MIT License. You are free to use, modify, and distribute the software with proper attribution.
+
+## Contributing
+We welcome contributions! Please refer to the Contributing Guide (CONTRIBUTING.md) for details on how to get started.
+
+## Documentation
+Full documentation is available at the EBM User Guide: https://nve.github.io/ebm/
+
+
+

ebm-0.99.3/ebm/__main__.py

@@ -0,0 +1,152 @@
+"""EBM start from where when running as a script or module"""
+import os
+import pathlib
+import sys
+
+import pandas as pd
+from loguru import logger
+
+from ebm.cmd import prepare_main
+from ebm.cmd.helpers import configure_json_log, configure_loglevel, load_environment_from_dotenv
+from ebm.cmd.initialize import create_output_directory, init
+from ebm.cmd.migrate import migrate_directories
+from ebm.cmd.pipeline import export_energy_model_reports
+from ebm.cmd.result_handler import EbmDefaultHandler, append_result, transform_model_to_horizontal
+from ebm.cmd.run_calculation import validate_years
+from ebm.model.building_category import BuildingCategory
+from ebm.model.database_manager import DatabaseManager
+from ebm.model.enums import ReturnCode
+from ebm.model.file_handler import FileHandler
+
+df = None
+
+
+def main() -> tuple[ReturnCode, pd.DataFrame | None]:
+    """
+    Execute the EBM module as a script.
+
+    This function serves as the entry point for the script. It handles argument parsing,
+    initializes necessary components, and orchestrates the main workflow of the script.
+
+    Returns
+    -------
+    exit code : tuple[ReturnCode, pd.DataFrame]
+        zero when the program exits gracefully
+
+    """
+    load_environment_from_dotenv()
+    configure_loglevel(log_format=os.environ.get('LOG_FORMAT', '{level.icon} <level>{message}</level>'))
+    configure_json_log()
+
+    logger.debug(f'Starting {sys.executable} {__file__}')
+
+    program_name = 'ebm'
+    default_path = pathlib.Path('output/ebm_output.xlsx')
+
+    arguments = prepare_main.make_arguments(program_name, default_path)
+
+    # Make local variable from arguments for clarity
+    building_categories = [BuildingCategory.from_string(b_c) for b_c in arguments.categories]
+    if not building_categories:
+        building_categories = list(BuildingCategory)
+
+    # `;` Will normally be interpreted as line end when typed in a shell. If the
+    # delimiter is empty make the assumption that the user used ;. An empty delimiter is not valid anyway.
+    csv_delimiter = arguments.csv_delimiter if arguments.csv_delimiter else ';'
+
+    # Make sure everything is working as expected
+    model_years = validate_years(start_year=arguments.start_year, end_year=arguments.end_year)
+
+    input_directory = arguments.input
+    logger.info(f'Using data from "{input_directory}"')
+    database_manager = DatabaseManager(file_handler=FileHandler(directory=input_directory))
+
+    # Create input directory if requested
+    if arguments.create_input:
+        if init(database_manager.file_handler):
+            logger.success('Finished creating input files in {input_directory}',
+                           input_directory=database_manager.file_handler.input_directory)
+            return ReturnCode.OK, None
+        # Exit with 0 for success. The assumption is that the user would like to review the input before proceeding.
+        return ReturnCode.MISSING_INPUT_FILES, None
+    if arguments.migrate:
+        migrate_directories([database_manager.file_handler.input_directory])
+        logger.success('Finished migration')
+        return ReturnCode.OK, None
+
+    missing_input_error = f"""
+Use `<program name> --create-input --input={input_directory}` to create an input directory with the default input files
+""".strip().replace('\n',  ' ')
+
+    # Make sure all required files exists
+    try:
+        missing_files = database_manager.file_handler.check_for_missing_files()
+        if missing_files:
+            print(missing_input_error, file=sys.stderr)
+            return ReturnCode.MISSING_INPUT_FILES, None
+    except FileNotFoundError as file_not_found:
+        if str(file_not_found).startswith('Input Directory Not Found'):
+            logger.error(f'Input Directory "{input_directory}" Not Found')
+            print(missing_input_error, file=sys.stderr)
+            return ReturnCode.FILE_NOT_ACCESSIBLE, None
+
+    database_manager.file_handler.validate_input_files()
+
+    output_file = arguments.output_file
+    create_output_directory(filename=output_file)
+
+    output_file_return_code = prepare_main.check_output_file_status(output_file, arguments.force, default_path,
+                                                                    program_name)
+    if output_file_return_code!= ReturnCode.OK:
+        return output_file_return_code, None
+
+    step_choice = arguments.step
+
+    convert_result_to_horizontal: bool = arguments.horizontal_years
+
+    default_handler = EbmDefaultHandler()
+
+    model = None
+
+    files_to_open = [output_file]
+
+    if step_choice == 'energy-use':
+        output_directory = output_file if output_file.is_dir() else output_file.parent
+        files_to_open = export_energy_model_reports(model_years, database_manager, output_directory)
+    else:
+        model = default_handler.extract_model(model_years, building_categories, database_manager, step_choice)
+
+        if convert_result_to_horizontal and (step_choice in ['area-forecast', 'energy-requirements']) and output_file.suffix=='.xlsx':
+            sheet_name_prefix = 'area' if step_choice == 'area-forecast' else 'energy'
+            logger.debug(f'Transform heating {step_choice}')
+
+            df = transform_model_to_horizontal(model.reset_index())
+            append_result(output_file, df, f'{sheet_name_prefix} condition')
+
+            model = model.reset_index()
+            # Demolition should not be summed any further
+            model = model[model.building_condition!='demolition']
+            model['building_condition'] = 'all'
+            df = transform_model_to_horizontal(model)
+            append_result(output_file, df, f'{sheet_name_prefix} TEK')
+
+            model['building_code'] = 'all'
+            df = transform_model_to_horizontal(model)
+            append_result(output_file, df, f'{sheet_name_prefix} category')
+            logger.success('Wrote {filename}', filename=output_file)
+        else:
+            default_handler.write_tqdm_result(output_file, model, csv_delimiter)
+
+    for file_to_open in files_to_open:
+        if arguments.open or os.environ.get('EBM_ALWAYS_OPEN', 'FALSE').upper() == 'TRUE':
+            logger.info(f'Open {file_to_open}')
+            os.startfile(file_to_open, 'open')
+        else:
+            logger.debug(f'Finished {file_to_open}')
+
+    return ReturnCode.OK, model
+
+
+if __name__ == '__main__':
+    exit_code, result = main()
+    df = result

ebm-0.99.3/ebm/__version__.py

@@ -0,0 +1 @@
+version = "0.99.3"

ebm-0.99.3/ebm/cmd/calibrate.py

@@ -0,0 +1,83 @@
+import pathlib
+
+from loguru import logger
+import pandas as pd
+
+from dotenv import load_dotenv
+
+from ebm.model.bema import map_sort_order
+
+from ebm.model.calibrate_heating_systems import extract_area_forecast, extract_energy_requirements, \
+    extract_heating_systems
+from ebm.model.data_classes import YearRange
+from ebm.services.files import make_unique_path
+
+CALIBRATION_YEAR = 2023
+
+model_period = YearRange(2020, 2050)
+start_year = model_period.start
+end_year = model_period.end
+
+
+def run_calibration(database_manager,
+                    calibration_year,
+                    area_forecast: pd.DataFrame = None,
+                    write_to_output = False):
+    """
+
+    Parameters
+    ----------
+    database_manager : ebm.model.database_manager.DatabaseManager
+
+    Returns
+    -------
+    pandas.core.frame.DataFrame
+    """
+    load_dotenv(pathlib.Path('.env'))
+
+    input_directory = database_manager.file_handler.input_directory
+
+    logger.info(f'Using input directory "{input_directory}"')
+    logger.info('Extract area forecast')
+    area_forecast = extract_area_forecast(database_manager) if area_forecast is None else area_forecast
+    if write_to_output:
+        write_dataframe(area_forecast[area_forecast.year == calibration_year], 'area_forecast')
+
+    logger.info('Extract energy requirements')
+    energy_requirements = extract_energy_requirements(area_forecast, database_manager)
+    if write_to_output:
+        en_req = energy_requirements.xs(2023, level='year').reset_index().sort_values(
+            by='building_category', key=lambda x: x.map(map_sort_order))
+        write_dataframe(en_req, 'energy_requirements')
+        grouped = en_req[['building_category', 'm2', 'kwh_m2', 'energy_requirement']].groupby(
+            by=['building_category'], as_index=False).agg({'m2': 'first', 'kwh_m2': 'first', 'energy_requirement': 'sum'})
+        grouped = grouped.sort_values(by='building_category', key=lambda x: x.map(map_sort_order))
+        write_dataframe(grouped, 'energy_requirements_sum', sheet_name='sum')
+
+    logger.info('Extract heating systems')
+    heating_systems = extract_heating_systems(energy_requirements, database_manager)
+    if write_to_output:
+        write_dataframe(heating_systems.xs(2023, level='year'), 'heating_systems')
+
+
+    return heating_systems
+
+
+def write_dataframe(df, name='dataframe', sheet_name='Sheet1'):
+    output_directory = pathlib.Path('output')
+    if output_directory.is_dir():
+        logger.debug(f'Writing {name} to file')
+        output_file = output_directory / f'{name}.xlsx'
+        output_file = make_unique_path(output_file)
+        df.to_excel(output_file, merge_cells=False, sheet_name=sheet_name)
+        logger.info(f'Wrote {name} to {output_file} ! {sheet_name if sheet_name!="Sheet1" else ""}')
+    else:
+        logger.warning(f'Cannot write to {output_directory}. Directory does not exists')
+
+
+def main():
+    raise NotImplementedError('Running calibrate as a script is not supported')
+
+
+if __name__ == '__main__':
+    main()