| Name | epnlink JSON |
| Version |
0.0.7
JSON |
| download |
| home_page | None |
| Summary | Python interface to EnergyPLAN - Advanced energy system analysis computer model |
| upload_time | 2024-11-05 15:12:37 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
energyplan
parse
energy
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# epnlink
Python interface to [EnergyPLAN - Advanced energy system analysis computer model](https://www.energyplan.eu).
## Description
This project provides python input-output parsers for the EnergyPLAN energy system modelling software, with data managed using `pandas` dataframes. It includes a descriptive `key:value` map of the GUI fields. It is intended for simulation automation using [command line calls](https://www.energyplan.eu/training/faqs/#eleven), and is confirmed to work correctly with EnergyPLAN 16.2. running under WINE.
## Functionality
- Map GUI fields to configuration `key:value` pairs
- Read and write EnergyPLAN simulation input files
- Read and parse EnergyPLAN ascii output files
## Installation
Install from pypi with `pip install epnlink`
## Usage
Please refer to the docstrings in the code for detailed usage. While this library can be used to fully specify simulations, the recommended workflow is to build base simulations using the GUI and leverage this library for sensitivity testing or optimisation.
**Quick-start example:**
```python
import epnlink as ep
# Create a template file
df_tmp = ep.utilities.get_ep_template()
# Initialise the template to zeros
df_tmp = ep.utilities.initialise_settings(df_tmp)
# Or, read an existing file that was saved by EnergyPLAN
fpath_raw = "/home/EnergyPLAN/input.txt"
df = ep.utilities.load_settings_file(fpath_raw, raw=True)
# Modify the capacity of renewable generation technology 1
df.loc['input_RES1_capacity', 'value'] = 42
# Save the modified file
fpath_mod = "/home/EnergyPLAN/input-mod.txt"
df_out = df.dropna(subset='value')
ep.utilities.save_settings_file(df, fpath_mod)
# Readback the modified file as a demonstration - notice that raw=False
df_mod = ep.utilities.load_settings_file(fpath_mod, raw=False)
# < RUN A SIMULATION VIA CLI - e.g., subprocess.run() >
# "energyPLAN.exe -i input-mod.txt -ascii results.ascii"
# Parse the simulation results to dict of dataframes
fpath_results = "/home/EnergyPLAN/results.ascii"
results = ep.results.read_ascii_file(fpath_results)
# Examine annual fuel balance dataframe
df_fb = results['annual_fuel_balance']
```
### Working with EnergyPLAN input .txt files
EnergyPLAN input files are in `.txt` format. If the files are produced directly from EnergyPLAN, they will be encoded as `cp1252`. If they have been saved by this library they will use `utf-8` encoding. EnergyPLAN can work with either format, but it defaults to `cp1252`.
#### Creating input files
Create a template input file with `df = ep.utilities.get_ep_template()` and initialise it with `df = ep.utilities.initialise_settings(df)`. The template contains the descriptive mapping between GUI fields and parameter `key:value` pairs.
#### Reading input files
Load an existing EnergyPLAN input file with `ep.utilities.load_settings_file(fpath, raw=True)`. If the file has been produced by this library, set `raw=False`. *If in doubt - try each setting!*
#### Writing input files
Save an input file for EnergyPLAN with `ep.utilities.save_settings_file(df, fpath)`, where `df` contains the EnergyPLAN settings, and `fpath` is the absolute or relative path to save the file.
### Working with EnergyPLAN output .ascii files
This library parses the `.ascii` files that EnergyPLAN outputs when called from the command line interface. When used from the GUI, EnergyPLAN can also output files to the screen as tabulated plaintext or to the clipboard for pasting into spreadsheet software - these workflows are not supported by `epnlink`.
#### Parsing .ascii results
Parse the results into a dict of dataframes with `ep.results.read_ascii_file(fpath)` containing:
| Results key | Contents |
| --------------------------------- | -------------------------------------------------------------- |
| annual_costs | Costs - total, variable, and components |
| annual_emissions | Emissions - SO2, PM2.5, NOx, CH4, N2O |
| annual_emissions_co2 | CO2 emissions |
| annual_fuel_balance | Fuel balance across applications |
| annual_fuel_consumption | Fuel consumption – total and households |
| annual_investment_costs | Investment costs – Total, Annual, and Fixed O&M |
| annual_share_of_res | Share of renewable energy – PES, Electricity, Total production |
| application_annual_avg_max_min_mw | Application demand - Average, Max, and Min |
| application_annual_total_twh | Application demand – Total TWh |
| application_hourlies_mw | Application hourly demand |
| application_monthly_avg_mw | Application monthly averages |
| calculation_time | Simulation calculation time (invalid) |
| sim_parameters | Copy of the simulation input settings |
# Citation
If you find this library useful in your work, we would appreciate it if you cite the following paper:
**C. Cameron, A. Foley, H. Lund, and S. McLoone, *‘A soft-linking method for responsive modelling of decarbonisation scenario costs’*, International Journal of Sustainable Energy Planning and Management, 2024, [https://doi.org/10.54337/ijsepm.8234](https://doi.org/10.54337/ijsepm.8234)**
Bibtex:
```bibtex
@article{cameron_2024,
title = {A soft-linking method for responsive modelling of decarbonisation scenario costs},
doi = {10.54337/ijsepm.8234},
author = {Cameron, Ché and Foley, Aoife and Lund, Henrik and McLoone, Seán},
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "epnlink",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "energyplan, parse, energy",
"author": null,
"author_email": "Ch\u00e9 Cameron <research@checameron.com>",
"download_url": "https://files.pythonhosted.org/packages/6c/cc/8071f96c8435d6db0cb9ec8b4341aa75ca59b6507e1f3c0ed55eb421e767/epnlink-0.0.7.tar.gz",
"platform": null,
"description": "# epnlink\nPython interface to [EnergyPLAN - Advanced energy system analysis computer model](https://www.energyplan.eu).\n\n## Description\nThis project provides python input-output parsers for the EnergyPLAN energy system modelling software, with data managed using `pandas` dataframes. It includes a descriptive `key:value` map of the GUI fields. It is intended for simulation automation using [command line calls](https://www.energyplan.eu/training/faqs/#eleven), and is confirmed to work correctly with EnergyPLAN 16.2. running under WINE.\n\n## Functionality\n- Map GUI fields to configuration `key:value` pairs\n- Read and write EnergyPLAN simulation input files\n- Read and parse EnergyPLAN ascii output files\n\n## Installation\nInstall from pypi with `pip install epnlink`\n\n## Usage\nPlease refer to the docstrings in the code for detailed usage. While this library can be used to fully specify simulations, the recommended workflow is to build base simulations using the GUI and leverage this library for sensitivity testing or optimisation.\n\n**Quick-start example:**\n\n```python\nimport epnlink as ep\n\n# Create a template file\ndf_tmp = ep.utilities.get_ep_template()\n\n# Initialise the template to zeros\ndf_tmp = ep.utilities.initialise_settings(df_tmp)\n\n# Or, read an existing file that was saved by EnergyPLAN\nfpath_raw = \"/home/EnergyPLAN/input.txt\"\ndf = ep.utilities.load_settings_file(fpath_raw, raw=True)\n\n# Modify the capacity of renewable generation technology 1\ndf.loc['input_RES1_capacity', 'value'] = 42\n\n# Save the modified file\nfpath_mod = \"/home/EnergyPLAN/input-mod.txt\"\ndf_out = df.dropna(subset='value')\nep.utilities.save_settings_file(df, fpath_mod)\n\n# Readback the modified file as a demonstration - notice that raw=False\ndf_mod = ep.utilities.load_settings_file(fpath_mod, raw=False)\n\n# < RUN A SIMULATION VIA CLI - e.g., subprocess.run() >\n# \"energyPLAN.exe -i input-mod.txt -ascii results.ascii\"\n\n# Parse the simulation results to dict of dataframes\nfpath_results = \"/home/EnergyPLAN/results.ascii\"\nresults = ep.results.read_ascii_file(fpath_results)\n\n# Examine annual fuel balance dataframe\ndf_fb = results['annual_fuel_balance']\n```\n\n### Working with EnergyPLAN input .txt files\nEnergyPLAN input files are in `.txt` format. If the files are produced directly from EnergyPLAN, they will be encoded as `cp1252`. If they have been saved by this library they will use `utf-8` encoding. EnergyPLAN can work with either format, but it defaults to `cp1252`.\n\n#### Creating input files\nCreate a template input file with `df = ep.utilities.get_ep_template()` and initialise it with `df = ep.utilities.initialise_settings(df)`. The template contains the descriptive mapping between GUI fields and parameter `key:value` pairs.\n\n#### Reading input files\nLoad an existing EnergyPLAN input file with `ep.utilities.load_settings_file(fpath, raw=True)`. If the file has been produced by this library, set `raw=False`. *If in doubt - try each setting!*\n\n#### Writing input files\nSave an input file for EnergyPLAN with `ep.utilities.save_settings_file(df, fpath)`, where `df` contains the EnergyPLAN settings, and `fpath` is the absolute or relative path to save the file.\n\n### Working with EnergyPLAN output .ascii files\nThis library parses the `.ascii` files that EnergyPLAN outputs when called from the command line interface. When used from the GUI, EnergyPLAN can also output files to the screen as tabulated plaintext or to the clipboard for pasting into spreadsheet software - these workflows are not supported by `epnlink`.\n\n#### Parsing .ascii results\nParse the results into a dict of dataframes with `ep.results.read_ascii_file(fpath)` containing:\n\n| Results key | Contents |\n| --------------------------------- | -------------------------------------------------------------- |\n| annual_costs | Costs - total, variable, and components |\n| annual_emissions | Emissions - SO2, PM2.5, NOx, CH4, N2O |\n| annual_emissions_co2 | CO2 emissions |\n| annual_fuel_balance | Fuel balance across applications |\n| annual_fuel_consumption | Fuel consumption \u2013 total and households |\n| annual_investment_costs | Investment costs \u2013 Total, Annual, and Fixed O&M |\n| annual_share_of_res | Share of renewable energy \u2013 PES, Electricity, Total production |\n| application_annual_avg_max_min_mw | Application demand - Average, Max, and Min |\n| application_annual_total_twh | Application demand \u2013 Total TWh |\n| application_hourlies_mw | Application hourly demand |\n| application_monthly_avg_mw | Application monthly averages |\n| calculation_time | Simulation calculation time (invalid) |\n| sim_parameters | Copy of the simulation input settings |\n\n# Citation\nIf you find this library useful in your work, we would appreciate it if you cite the following paper:\n\n**C. Cameron, A. Foley, H. Lund, and S. McLoone, *\u2018A soft-linking method for responsive modelling of decarbonisation scenario costs\u2019*, International Journal of Sustainable Energy Planning and Management, 2024, [https://doi.org/10.54337/ijsepm.8234](https://doi.org/10.54337/ijsepm.8234)**\n\nBibtex:\n```bibtex\n@article{cameron_2024,\n\ttitle = {A soft-linking method for responsive modelling of decarbonisation scenario costs},\n\tdoi = {10.54337/ijsepm.8234},\n\tauthor = {Cameron, Ch\u00e9 and Foley, Aoife and Lund, Henrik and McLoone, Se\u00e1n},\n}\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Python interface to EnergyPLAN - Advanced energy system analysis computer model",
"version": "0.0.7",
"project_urls": {
"Homepage": "https://github.com/Atinoda/epnlink"
},
"split_keywords": [
"energyplan",
" parse",
" energy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b395dcbb4dba9571b36b29a9c079200544c39e39ec16408fb705b36036450663",
"md5": "31fe54cc58beb49491e0d01d52a1d0ea",
"sha256": "fa9a75afe96f59dc4be985166ec582ef878d0187fb63ac797a56277f56deb503"
},
"downloads": -1,
"filename": "epnlink-0.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "31fe54cc58beb49491e0d01d52a1d0ea",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 42984,
"upload_time": "2024-11-05T15:12:35",
"upload_time_iso_8601": "2024-11-05T15:12:35.357247Z",
"url": "https://files.pythonhosted.org/packages/b3/95/dcbb4dba9571b36b29a9c079200544c39e39ec16408fb705b36036450663/epnlink-0.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6ccc8071f96c8435d6db0cb9ec8b4341aa75ca59b6507e1f3c0ed55eb421e767",
"md5": "38cff98a442cdae251bb4dc332a781f4",
"sha256": "241d0947cc8a9cf2b2de07a4a73366636444e04a167595878d723bc331b4b12f"
},
"downloads": -1,
"filename": "epnlink-0.0.7.tar.gz",
"has_sig": false,
"md5_digest": "38cff98a442cdae251bb4dc332a781f4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 45070,
"upload_time": "2024-11-05T15:12:37",
"upload_time_iso_8601": "2024-11-05T15:12:37.586903Z",
"url": "https://files.pythonhosted.org/packages/6c/cc/8071f96c8435d6db0cb9ec8b4341aa75ca59b6507e1f3c0ed55eb421e767/epnlink-0.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-05 15:12:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Atinoda",
"github_project": "epnlink",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "epnlink"
}
