From fc641ebb664fbdcde77d8f9b7df396ee21c57bff Mon Sep 17 00:00:00 2001 From: Gilbert Gong Date: Thu, 21 Nov 2024 22:50:35 +0700 Subject: [PATCH 1/3] add some checks, status, and get_total_profit() --- examples/battery_only.py | 3 +++ solar_and_storage/solar_and_storage.py | 27 +++++++++++++++++++++++++- 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/examples/battery_only.py b/examples/battery_only.py index c7d5479..2bf36f7 100644 --- a/examples/battery_only.py +++ b/examples/battery_only.py @@ -35,3 +35,6 @@ fig.show(rendered="browser") if HTML_OUTPUT: fig.write_html(HTML_OUTPUT) +print(result_df.attrs["message"]) +total_profit = solar_and_storage.get_total_profit() +print(f'total profit: {total_profit}') diff --git a/solar_and_storage/solar_and_storage.py b/solar_and_storage/solar_and_storage.py index a767456..3297727 100644 --- a/solar_and_storage/solar_and_storage.py +++ b/solar_and_storage/solar_and_storage.py @@ -40,6 +40,7 @@ def __init__( should be between 0 and 1. :param grid_connection_capacity: the amount of power that can be delivered to the grid """ + self.prob = None self.battery_soc_min = battery_soc_min self.battery_soc_max = battery_soc_max self.battery_capacity = battery_capacity @@ -145,6 +146,20 @@ def run_optimization(self): def get_results(self) -> pd.DataFrame: """Get optimization results (after running)""" + + # run optimization if not already run + if self.prob is None: + self.run_optimization() + # check status as we may not have found a solution + status = self.prob.status + + if status != "optimal": + # Return an empty DataFrame with metadata for non-optimal cases + result_df = pd.DataFrame() + result_df.attrs["status"] = status + result_df.attrs["message"] = message + return result_df + # run plot resutls power = np.round( self.battery_power_charge_cp_variable.value - self.power_discharge_cp_variable.value, 2 @@ -157,10 +172,20 @@ def get_results(self) -> pd.DataFrame: data = np.array([power, e_soc[:HOURS_PER_DAY], solar_power_to_grid, profit]).transpose() - return pd.DataFrame( + result_df = pd.DataFrame( data=data, columns=["power", "e_soc", "solar_power_to_grid", "profit"], ) + result_df.attrs["status"] = status + result_df.attrs["message"] = "Optimization successful" + + return result_df + + def get_total_profit(self) -> float: + results = self.get_results() + if results.attrs["status"] != "optimal": + raise ValueError(f"Cannot calculate total profit: {results.attrs['message']}") + return sum(results["profit"]) def get_fig(self) -> go.Figure: result_df = self.get_results() From 5506f0c18dddfb78fe04b5d0b7756a8c9aad3f2b Mon Sep 17 00:00:00 2001 From: Gilbert Gong Date: Fri, 22 Nov 2024 15:46:24 +0700 Subject: [PATCH 2/3] add some checks, improve graphs, modularize examples a bit --- README.md | 11 ++-- TODO.md | 5 ++ examples/battery_only.py | 27 ++++------ examples/battery_solar.py | 32 +++++------ examples/images/battery_only.png | Bin 0 -> 38263 bytes examples/images/battery_solar.png | Bin 0 -> 38450 bytes examples/solar_and_storage.png | Bin 58515 -> 0 bytes requirements.txt | 1 + solar_and_storage/example.py | 26 +++++++++ solar_and_storage/solar_and_storage.py | 50 +++++++++++++++--- tmp.md | 70 +++++++++++++++++++++++++ 11 files changed, 171 insertions(+), 51 deletions(-) create mode 100644 TODO.md create mode 100644 examples/images/battery_only.png create mode 100644 examples/images/battery_solar.png delete mode 100644 examples/solar_and_storage.png create mode 100644 solar_and_storage/example.py create mode 100644 tmp.md diff --git a/README.md b/README.md index 05fb9bc..627b148 100644 --- a/README.md +++ b/README.md @@ -19,8 +19,6 @@ pip install solar-and-storage Import the packages ```python import numpy as np -import plotly.graph_objects as go -from plotly.subplots import make_subplots from solar_and_storage.solar_and_storage import SolarAndStorage @@ -52,14 +50,15 @@ result_df = solar_and_storage.get_results() Now plot the data ```python -fig = solar_and_storage.get_fig() +fig = solar_and_storage.get_figure() fig.show(rendered="browser") ``` -![Example1](https://raw.githubusercontent.com/openclimatefix/solar-and-storage/main/examples/solar_and_storage.png) -The first plot shows the solar profile, the second shows the prices that day. The third shows the battery profile. +![Example1](examples/images/battery_solar.png) + +The first plot shows the solar profile, the second shows the prices that day. The third shows the battery profile. Finally the fourth shows profit. You can see that the battery charged from the solar site at the end of the solar maximum @@ -94,4 +93,4 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d -This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! \ No newline at end of file +This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..cb288ae --- /dev/null +++ b/TODO.md @@ -0,0 +1,5 @@ +- add tests +- refactor to use net_transfer_to_grid +- incorporate consumption + - example with 0 solar + 0 battery + - build from here diff --git a/examples/battery_only.py b/examples/battery_only.py index 2bf36f7..0e7ac1f 100644 --- a/examples/battery_only.py +++ b/examples/battery_only.py @@ -3,38 +3,29 @@ import numpy as np from solar_and_storage.solar_and_storage import SolarAndStorage +from solar_and_storage.example import prices, no_solar -HTML_OUTPUT = "examples/battery_only.html" # Change this to your desired path or leave as an empty string +HTML_OUTPUT = "" # set path or empty will skip writing HTML +PNG_OUTPUT = "examples/images/battery_only.png" # empty will skip writing PNG -hours_per_day = 24 - - -# make prices -prices = np.zeros(hours_per_day) + 30 -prices[6:19] = 40 -prices[9] = 50 -prices[12:14] = 30 -prices[16:18] = 50 -prices[17] = 60 - -# make zero solar profile -solar = np.zeros(hours_per_day) - -solar_and_storage = SolarAndStorage(prices=prices, solar_generation=list(solar)) -solar_and_storage.run_optimization() +# use example prices and no generation profile +solar_and_storage = SolarAndStorage(prices=prices, solar_generation=list(no_solar)) result_df = solar_and_storage.get_results() # data is available for direct access power = result_df["power"] e_soc = result_df["e_soc"] solar_power_to_grid = result_df["solar_power_to_grid"] +profit = result_df["profit"] # plot -fig = solar_and_storage.get_fig() +fig = solar_and_storage.get_figure() fig.show(rendered="browser") if HTML_OUTPUT: fig.write_html(HTML_OUTPUT) +if PNG_OUTPUT: + fig.write_image(PNG_OUTPUT, format="png") print(result_df.attrs["message"]) total_profit = solar_and_storage.get_total_profit() print(f'total profit: {total_profit}') diff --git a/examples/battery_solar.py b/examples/battery_solar.py index 596acad..c8ef69e 100644 --- a/examples/battery_solar.py +++ b/examples/battery_solar.py @@ -4,37 +4,29 @@ import os from solar_and_storage.solar_and_storage import SolarAndStorage +from solar_and_storage.example import prices, with_solar -HTML_OUTPUT = "examples/battery_solar.html" # Change this to your desired path or leave as an empty string +HTML_OUTPUT = "" # set path or empty will skip writing HTML +PNG_OUTPUT = "examples/images/battery_solar.png" # empty will skip writing PNG -hours_per_day = 24 - - -# make prices -prices = np.zeros(hours_per_day) + 30 -prices[6:19] = 40 -prices[9] = 50 -prices[12:14] = 30 -prices[16:18] = 50 -prices[17] = 60 - -# make solar profile -solar = np.zeros(hours_per_day) -solar[8:16] = 2.0 -solar[10:14] = 4.0 - -solar_and_storage = SolarAndStorage(prices=prices, solar_generation=list(solar)) -solar_and_storage.run_optimization() +# use example prices and solar generation profile +solar_and_storage = SolarAndStorage(prices=prices, solar_generation=list(with_solar)) result_df = solar_and_storage.get_results() # data is available for direct access power = result_df["power"] e_soc = result_df["e_soc"] solar_power_to_grid = result_df["solar_power_to_grid"] +profit = result_df["profit"] # plot -fig = solar_and_storage.get_fig() +fig = solar_and_storage.get_figure() fig.show(rendered="browser") if HTML_OUTPUT: fig.write_html(HTML_OUTPUT) +if PNG_OUTPUT: + fig.write_image(PNG_OUTPUT, format="png") +print(result_df.attrs["message"]) +total_profit = solar_and_storage.get_total_profit() +print(f'total profit: {total_profit}') diff --git a/examples/images/battery_only.png b/examples/images/battery_only.png new file mode 100644 index 0000000000000000000000000000000000000000..def405834f27f90a22025227fb3f146e36a19976 GIT binary patch literal 38263 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 literal 0 HcmV?d00001 diff --git a/examples/images/battery_solar.png b/examples/images/battery_solar.png new file mode 100644 index 0000000000000000000000000000000000000000..bd2dbd813d9783dcd3679bc72a13af97ab941150 GIT binary patch literal 38450 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Ⓢ73^Z|vM}(fwe=^kt$wq}G0IZj;We^M8w-JN+N* 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 diff --git a/requirements.txt b/requirements.txt index 80f1de7..5e5b5d7 100644 --- a/requirements.txt +++ b/requirements.txt @@ -3,3 +3,4 @@ scipy==1.8.1 cvxopt cvxpy==1.2.2 plotly +kaleido diff --git a/solar_and_storage/example.py b/solar_and_storage/example.py new file mode 100644 index 0000000..5c9e23b --- /dev/null +++ b/solar_and_storage/example.py @@ -0,0 +1,26 @@ +""" These are used in the /examples directory as well as (planned) tests """ + +import numpy as np + +# examples ues 24 hours per day +# any granularity should be supported but only 24 hours per day has been tested +hours_per_day = 24 + +prices = np.zeros(hours_per_day) + 30 +prices[6:19] = 40 +prices[9] = 50 +prices[12:14] = 30 +prices[16:18] = 50 +prices[17] = 60 + +no_solar = np.zeros(hours_per_day) + +with_solar = np.zeros(hours_per_day) +with_solar[8:16] = 2.0 +with_solar[10:14] = 4.0 + + +solar_generation = { + "no_solar": no_solar, + "with_solar": with_solar, +} diff --git a/solar_and_storage/solar_and_storage.py b/solar_and_storage/solar_and_storage.py index 3297727..1cc37a9 100644 --- a/solar_and_storage/solar_and_storage.py +++ b/solar_and_storage/solar_and_storage.py @@ -133,6 +133,13 @@ def __init__( self.constraints = constraints self.objective_function = objective_function + def get_status(self) -> str: + """Runs optimization if not already run, and returns status""" + + if self.prob is None: + self.run_optimization() + return self.prob.status + def run_optimization(self): """ Run optimization problem @@ -147,11 +154,7 @@ def run_optimization(self): def get_results(self) -> pd.DataFrame: """Get optimization results (after running)""" - # run optimization if not already run - if self.prob is None: - self.run_optimization() - # check status as we may not have found a solution - status = self.prob.status + status = self.get_status() if status != "optimal": # Return an empty DataFrame with metadata for non-optimal cases @@ -187,21 +190,54 @@ def get_total_profit(self) -> float: raise ValueError(f"Cannot calculate total profit: {results.attrs['message']}") return sum(results["profit"]) - def get_fig(self) -> go.Figure: + def get_figure(self) -> go.Figure: + """Generate figure on successful optimization""" + + status = self.get_status() + + if status != "optimal": + fig = go.Figure() + fig.update_layout( + title=f"Optimization Failed: {status.capitalize()}", + title_x=0.5, + ) + return fig + result_df = self.get_results() + total_profit = self.get_total_profit() # run plot resutls power = result_df["power"] e_soc = result_df["e_soc"] solar_power_to_grid = result_df["solar_power_to_grid"] + profit = result_df["profit"] # plot - fig = make_subplots(rows=3, cols=1, subplot_titles=["Solar profile", "Price", "SOC"]) + fig = make_subplots(rows=4, cols=1, subplot_titles=["Solar profile", "Price", "SOC", "Profit"]) fig.add_trace(go.Scatter(y=e_soc[:24], name="SOC"), row=3, col=1) fig.add_trace(go.Scatter(y=self.solar_generation, name="solar", line_shape="hv"), row=1, col=1) fig.add_trace( go.Scatter(y=solar_power_to_grid, name="solar to gird", line_shape="hv"), row=1, col=1 ) fig.add_trace(go.Scatter(y=self.prices, name="price", line_shape="hv"), row=2, col=1) + fig.add_trace(go.Scatter(y=profit, name="profit", line_shape="hv"), row=4, col=1) + + # Add title + fig.update_layout( + title="Solar and Storage Optimization Results", + title_x=0.5, + ) + + # Add total profit as an annotation below the chart + fig.update_layout( + annotations=[ + dict( + text=f"Total Profit: {total_profit:.2f}", + yref="paper", + y=-0.2, # Position below the chart + font=dict(size=14) + ) + ] + ) return fig diff --git a/tmp.md b/tmp.md new file mode 100644 index 0000000..97fac56 --- /dev/null +++ b/tmp.md @@ -0,0 +1,70 @@ +# Solar and Storage + +A Python Library to run solar and storage optimization. +This uses mixed integer linear programming and maximises revenue made by charging and discharging the battery. +The model uses variable prices and a solar generation profile. + +## Installation + +``` +pip install solar-and-storage +``` + + +## Example + +Import the packages +```python +import numpy as np + +from solar_and_storage.solar_and_storage import SolarAndStorage + +``` +Make the fake price and solar data +```python +# make prices +prices = np.zeros(24) + 30 +prices[6:19] = 40 +prices[9] = 50 +prices[12:14] = 30 +prices[16:18] = 50 +prices[17] = 60 + +# make solar profile +solar = np.zeros(24) +solar[8:16] = 2.0 +solar[10:14] = 4.0 +``` + +Then run optimization +```python +solar_and_storage = SolarAndStorage(prices=prices, solar_generation=list(solar)) +solar_and_storage.run_optimization() +result_df = solar_and_storage.get_results() +``` + + + +Now plot the data +```python +fig = solar_and_storage.get_figure() + +fig.show(rendered="browser") +``` + + +![Example1](examples/images/battery_solar.png) + +The first plot shows the solar profile, the second shows the prices that day. The third shows the battery profile. Finally the fourth shows profit. +You can see that the battery charged from the solar site at the end of the solar maximum + + + +## Thanks + +Thanks you to the follow repos for inspiration +- https://github.com/ADGEfficiency/energy-py-linear +- https://github.com/wzyfrank/battery/ +- https://github.com/greysonchung/Battery-Optimisation/ +- https://github.com/edu230991/battery-optimization/ +sdk-python-ci.yml From b3331e418876896efcbae6cbb36f4deef8aa61b6 Mon Sep 17 00:00:00 2001 From: Gilbert Gong Date: Fri, 22 Nov 2024 15:51:18 +0700 Subject: [PATCH 3/3] remove accidental tmp.md and tweak comments/whitespace in example.py --- solar_and_storage/example.py | 5 ++- tmp.md | 70 ------------------------------------ 2 files changed, 2 insertions(+), 73 deletions(-) delete mode 100644 tmp.md diff --git a/solar_and_storage/example.py b/solar_and_storage/example.py index 5c9e23b..d8e2b6a 100644 --- a/solar_and_storage/example.py +++ b/solar_and_storage/example.py @@ -2,8 +2,8 @@ import numpy as np -# examples ues 24 hours per day -# any granularity should be supported but only 24 hours per day has been tested +# examples use 24 hour day for analysis period +# any granularity should be supported but only 24 hour day has been tested hours_per_day = 24 prices = np.zeros(hours_per_day) + 30 @@ -19,7 +19,6 @@ with_solar[8:16] = 2.0 with_solar[10:14] = 4.0 - solar_generation = { "no_solar": no_solar, "with_solar": with_solar, diff --git a/tmp.md b/tmp.md deleted file mode 100644 index 97fac56..0000000 --- a/tmp.md +++ /dev/null @@ -1,70 +0,0 @@ -# Solar and Storage - -A Python Library to run solar and storage optimization. -This uses mixed integer linear programming and maximises revenue made by charging and discharging the battery. -The model uses variable prices and a solar generation profile. - -## Installation - -``` -pip install solar-and-storage -``` - - -## Example - -Import the packages -```python -import numpy as np - -from solar_and_storage.solar_and_storage import SolarAndStorage - -``` -Make the fake price and solar data -```python -# make prices -prices = np.zeros(24) + 30 -prices[6:19] = 40 -prices[9] = 50 -prices[12:14] = 30 -prices[16:18] = 50 -prices[17] = 60 - -# make solar profile -solar = np.zeros(24) -solar[8:16] = 2.0 -solar[10:14] = 4.0 -``` - -Then run optimization -```python -solar_and_storage = SolarAndStorage(prices=prices, solar_generation=list(solar)) -solar_and_storage.run_optimization() -result_df = solar_and_storage.get_results() -``` - - - -Now plot the data -```python -fig = solar_and_storage.get_figure() - -fig.show(rendered="browser") -``` - - -![Example1](examples/images/battery_solar.png) - -The first plot shows the solar profile, the second shows the prices that day. The third shows the battery profile. Finally the fourth shows profit. -You can see that the battery charged from the solar site at the end of the solar maximum - - - -## Thanks - -Thanks you to the follow repos for inspiration -- https://github.com/ADGEfficiency/energy-py-linear -- https://github.com/wzyfrank/battery/ -- https://github.com/greysonchung/Battery-Optimisation/ -- https://github.com/edu230991/battery-optimization/ -sdk-python-ci.yml