fixup! Implement initial storage support

Author: Peque

docs/sphinx/source/user_guide/storage.rst

@@ -253,6 +253,81 @@ Power flow
 
 With pvlib you can simulate power flow for different scenarios and use cases.
 
+In order to start playing with these use cases, you can start off by creating a
+model chain containing the results of the PV generation for a particular
+location and configuration:
+
+.. ipython:: python
+
+   from pvlib.iotools import get_pvgis_tmy
+   from pvlib.location import Location
+   from pvlib.modelchain import ModelChain
+   from pvlib.pvsystem import Array
+   from pvlib.pvsystem import FixedMount
+   from pvlib.pvsystem import PVSystem
+   from pvlib.pvsystem import retrieve_sam
+   from pvlib.temperature import TEMPERATURE_MODEL_PARAMETERS as tmodel
+
+   def run_model_chain():
+       name = 'Madrid'
+       latitude = 40.31672645215922
+       longitude = -3.674695061062714
+       altitude = 603
+       timezone = 'Europe/Madrid'
+       module = retrieve_sam('SandiaMod')['Canadian_Solar_CS5P_220M___2009_']
+       inverter = retrieve_sam('cecinverter')['Powercom__SLK_1500__240V_']
+       weather = get_pvgis_tmy(latitude, longitude, map_variables=True)[0]
+       weather.index = date_range(
+           start="2021-01-01 00:00:00",
+           end="2022-01-01 00:00:00",
+           closed="left",
+           freq="H",
+       )
+       weather.index.name = "Timestamp"
+       location = Location(
+           latitude,
+           longitude,
+           name=name,
+           altitude=altitude,
+           tz=timezone,
+       )
+       mount = FixedMount(surface_tilt=latitude, surface_azimuth=180)
+       temperature_model_parameters = tmodel['sapm']['open_rack_glass_glass']
+       array = Array(
+           mount=mount,
+           module_parameters=module,
+           modules_per_string=16,
+           strings=1,
+           temperature_model_parameters=temperature_model_parameters,
+       )
+       system = PVSystem(arrays=[array], inverter_parameters=inverter)
+       mc = ModelChain(system, location)
+       mc.run_model(weather)
+       return mc
+
+   mc = run_model_chain()
+
+
+And a syntethic load profile for the experiment:
+
+.. ipython:: python
+
+   from numpy import nan
+   from numpy.random import uniform
+
+   def create_synthetic_load_profile(index):
+       load = Series(data=nan, index=index)
+       load[load.index.hour == 0] = 600
+       load[load.index.hour == 4] = 400
+       load[load.index.hour == 13] = 1100
+       load[load.index.hour == 17] = 800
+       load[load.index.hour == 21] = 1300
+       load *= uniform(low=0.6, high=1.4, size=len(load))
+       return load.interpolate(method="spline", order=2)
+
+   load = create_synthetic_load_profile(mc.results.ac.index)
+
+
 Self consumption
 ****************
 
@@ -279,38 +354,14 @@ The self-consumption use case is defined with the following assumptions:
 - The grid will provide power to the system if required (i.e.: during night
   hours)
 
-To simulate a system like this, you first need to start with the well-known PV
-system generation and load profiles:
-
-.. ipython:: python
-
-   import pkgutil
-   from io import BytesIO
-
-   from pandas import Series
-   from pandas import read_csv
-   from pandas import to_datetime
-
-
-   def read_file(fname):
-       df = read_csv(BytesIO(pkgutil.get_data("pvlib", fname)))
-       df.columns = ["Timestamp", "Power"]
-       df["Timestamp"] = to_datetime(df["Timestamp"], format="%Y-%m-%dT%H:%M:%S%z", utc=True)
-       s = df.set_index("Timestamp")["Power"]
-       s = s.asfreq("H")
-       return s.tz_convert("Europe/Madrid")
-
-   generation = read_file("data/generated.csv")
-   load = read_file("data/consumed.csv")
-
-
-You can use these profiles to solve the energy/power flow for the
+You can use the system and load profiles to solve the energy/power flow for the
 self-consumption use case:
 
 .. ipython:: python
 
    from pvlib.powerflow import self_consumption
 
+   generation = mc.results.ac
    self_consumption_flow = self_consumption(generation, load)
    self_consumption_flow.head()
 
@@ -321,12 +372,7 @@ from grid to load/system:
 .. ipython:: python
 
    @savefig power_flow_self_consumption_load.png
-   self_consumption_flow.groupby(self_consumption_flow.index.hour).mean()[["System to load", "Grid to load"]].plot.bar(stacked=True, xlabel="Hour", ylabel="Power (W)", title="Average power flow to load")
-   @suppress
-   plt.close()
-
-   @savefig power_flow_self_consumption_system.png
-   self_consumption_flow.groupby(self_consumption_flow.index.hour).mean()[["System to load", "System to grid"]].plot.bar(stacked=True, xlabel="Hour", ylabel="Power (W)", title="Average system power flow")
+   self_consumption_flow.groupby(self_consumption_flow.index.hour).mean()[["System to load", "Grid to load", "System to grid"]].plot.bar(stacked=True, xlabel="Hour", ylabel="Power (W)", title="Average power flow")
    @suppress
    plt.close()
 
@@ -412,28 +458,110 @@ load/battery/grid, from battery to load and from grid to load/system:
 .. ipython:: python
 
    @savefig flow_self_consumption_ac_battery_load.png
-   flow.groupby(flow.index.hour).mean()[["System to load", "Battery to load", "Grid to load"]].plot.bar(stacked=True, legend=True, xlabel="Hour", ylabel="Power (W)", title="Average power flow to load")
+   flow.groupby(flow.index.hour).mean()[["System to load", "Battery to load", "Grid to load", "System to battery", "System to grid"]].plot.bar(stacked=True, legend=True, xlabel="Hour", ylabel="Power (W)", title="Average power flow")
    @suppress
    plt.close()
 
-   @savefig flow_self_consumption_ac_battery_system.png
-   flow.groupby(flow.index.hour).mean()[["System to load", "System to battery", "System to grid"]].plot.bar(stacked=True, legend=True, xlabel="Hour", ylabel="Power (W)", title="Average system power flow")
+
+Self consumption with DC-connected battery
+******************************************
+
+The self-consumption with DC-connected battery is a completely different use
+case. As opposed to the AC-connected battery use case, you cannot just take
+into account the system's AC ouput and the load. Instead, you need to note that
+the battery is connected to a single inverter, and the inverter imposes some
+restrictions on how the power can flow from PV and from the battery.
+
+Hence, for this use case, you need to consider the PV power output (DC
+generation) and the inverter model as well in order to be able to calculate the
+inverter's output power (AC).
+
+The restrictions are as follow:
+
+- PV and battery are DC-connected to the same single inverter
+
+- Battery can only charge from PV
+
+- The PV generation (DC) is well-known
+
+- A custom dispatch series must be defined, but there is no guarantee that it
+  will be followed
+
+  - The battery cannot charge with higher power than PV can provide
+
+  - The battery cannot discharge with higher power if the inverter cannot
+    handle the total power provided by PV and the battery
+
+  - The battery will be charged to avoid clipping AC power
+
+For this use case, you can start with the same self-consumption power flow
+solution and dispatch series as in the AC battery use case:
+
+.. ipython:: python
+
+   self_consumption_flow = self_consumption(generation, load)
+   dispatch = self_consumption_flow["Grid to load"] - self_consumption_flow["System to grid"]
+
+
+TODO:
+
+.. ipython:: python
+
+   from pvlib.powerflow import multi_dc_battery
+
+   battery_datasheet = {
+       "chemistry": "LFP",
+       "mode": "DC",
+       "charge_efficiency": 0.98,
+       "discharge_efficiency": 0.98,
+       "min_soc_percent": 5,
+       "max_soc_percent": 95,
+       "dc_modules": 1,
+       "dc_modules_in_series": 1,
+       "dc_energy_wh": 5500,
+       "dc_nominal_voltage": 102.4,
+       "dc_max_power_w": 3400,
+   }
+   results = multi_dc_battery(
+       v_dc=[mc.results.dc["v_mp"]],
+       p_dc=[mc.results.dc["p_mp"]],
+       inverter=mc.system.inverter_parameters,
+       battery_dispatch=dispatch,
+       battery_parameters=fit_sam(battery_datasheet),
+       battery_model=sam,
+   )
+   dc_battery_flow = self_consumption(results["AC power"], load)
+   dc_battery_flow["PV to load"] = dc_battery_flow["System to load"] * (1 - results["Battery factor"])
+   dc_battery_flow["Battery to load"] = dc_battery_flow["System to load"] * results["Battery factor"]
+   @savefig flow_self_consumption_dc_battery_load.png
+   dc_battery_flow.groupby(dc_battery_flow.index.hour).mean()[["PV to load", "Battery to load", "Grid to load", "System to grid"]].plot.bar(stacked=True, legend=True, xlabel="Hour", ylabel="Power (W)", title="Average power flow")
    @suppress
    plt.close()
 
 
-While the self-consumption with AC-connected battery use case imposes many
-restrictions to the power flow, it still allows some flexibility to decide when
-to allow charging and discharging. If you wanted to simulate a use case where
-discharging should be avoided from 00:00 to 08:00, you could do that by simply:
+Dispatching strategies
+**********************
+
+While the self-consumption-with-battery use case imposes many restrictions to
+the power flow, it still allows some flexibility to decide when to charge and
+discharge the battery.
+
+An example of a different dispatching strategy is to set a well-defined
+schedule that determines when the energy should flow into or out of the
+battery. This is a common use case when you want to tie the battery flow to the
+grid energy rates (i.e.: avoid discharging when the energy rates are low).
+
+For example, if you wanted to simulate an AC-connected battery in a system
+where discharging should be avoided between 21:00 and 00:00, you could do that
+by simply:
 
 .. ipython:: python
 
    dispatch = self_consumption_flow["Grid to load"] - self_consumption_flow["System to grid"]
-   dispatch.loc[dispatch.index.hour < 8] = 0
+   dispatch.loc[dispatch.index.hour >= 21] = 0
    state, flow = self_consumption_ac_battery_custom_dispatch(self_consumption_flow, dispatch, battery, sam)
 
-   @savefig flow_self_consumption_ac_battery_load_custom_dispatch_restricted.png
+   @savefig flow_self_consumption_ac_battery_restricted_dispatch_load.png
    flow.groupby(flow.index.hour).mean()[["System to load", "Battery to load", "Grid to load"]].plot.bar(stacked=True, legend=True, xlabel="Hour", ylabel="Power (W)", title="Average power flow to load")
    @suppress
    plt.close()