fixup! Implement initial storage support

Author: Peque

docs/sphinx/source/user_guide/storage.rst

@@ -74,9 +74,7 @@ account the following conventions:
 
 - Positive values represent power provided by the storage system (i.e.:
   discharging), hence negative values represent power into the storage system
-  (i.e.: charging) NOTE: should we use values representing the energy instead?
-  sounds more intuitive to me but if NREL chose to use power instead there may
-  be a good reason
+  (i.e.: charging)
 
 .. note:: The left-labelling of the bins can be in conflict with energy meter
    series data provided by the electricity retailer companies, where the
@@ -307,24 +305,22 @@ self-consumption use case:
 
    from pvlib.powerflow import self_consumption
 
-   power_flow = self_consumption(generation, load)
-   power_flow.head()
+   self_consumption_flow = self_consumption(generation, load)
+   self_consumption_flow.head()
 
 
 The function will return the power flow series from system to load/grid and
 from grid to load/system:
 
 .. ipython:: python
 
-   from pvlib.powerflow import self_consumption
-
    @savefig power_flow_self_consumption_load.png
-   power_flow.groupby(power_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")
+   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
-   power_flow.groupby(power_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", "System to grid"]].plot.bar(stacked=True, xlabel="Hour", ylabel="Power (W)", title="Average system power flow")
    @suppress
    plt.close()
 
@@ -350,34 +346,58 @@ following assumptions:
 - The load is provided with power from the system, when possible
 
 - When the system is unable to provide sufficient power to the load, the
-  battery will try to fill the load requirements
+  battery may try to fill the load requirements, if the dispatching activates
+  the discharge
 
 - When both the system and the battery are unable to provide sufficient power
   to the load, the grid will fill the load requirements
 
-- When the system produces more power than the required by the load, it will be
-  fed to the battery
+- When the system produces more power than the required by the load, it may be
+  fed to the battery, if the dispatching activates the charge
 
-- When the excess power cannot be fed into the battery, it will be fed into the
-  grid
+- When the excess power from the system (after feeding the load) is not fed
+  into the battery, it will be fed into the grid
 
 - The grid will provide power to the system if required (i.e.: during night
   hours)
 
-For this use case, you need to provide, appart from the well-known generation
-and load profiles, the battery parameters and battery model simulation
-function:
+For this use case, you need to start with the self-consumption power flow
+solution:
+
+.. ipython:: python
+
+   from pvlib.powerflow import self_consumption
+
+   self_consumption_flow = self_consumption(generation, load)
+   self_consumption_flow.head()
+
+
+Then you need to provide a dispatch series, which could easily be defined so
+that the battery always charges from the excess energy by the system and always
+discharges when the load requires energy from the grid:
+
+.. ipython:: python
+
+   dispatch = self_consumption_flow["Grid to load"] - self_consumption_flow["System to grid"]
+
+
+.. note:: Note how the positive values represent power provided by the storage
+   system (i.e.: discharging) while negative values represent power into the
+   storage system (i.e.: charging)
+
+
+The last step is to use the self-consumption power flow solution and the
+dispatch series to solve the new power flow scenario:
 
 .. ipython:: python
 
-   from pvlib.powerflow import self_consumption_ac_battery
+   from pvlib.powerflow import self_consumption_ac_battery_custom_dispatch
 
    battery = fit_sam(parameters)
-   state, flow = self_consumption_ac_battery(generation, load, battery, sam)
-   flow.head()
+   state, flow = self_consumption_ac_battery_custom_dispatch(self_consumption_flow, dispatch, battery, sam)
 
 
-The function will return the power flow series from system to
+The new power flow results now include the flow series from system to
 load/battery/grid, from battery to load and from grid to load/system:
 
 .. ipython:: python
@@ -393,16 +413,28 @@ load/battery/grid, from battery to load and from grid to load/system:
    plt.close()
 
 
-The returned ``state`` represents the state of the battery after running the
-simulation. You can use this state to call
-:py:func:`~pvlib.flow.self_consumption_ac_battery`.
-
-
 .. note:: The :py:func:`~pvlib.flow.self_consumption_ac_battery` function
    allows you to define the AC-DC losses, if you would rather avoid the default
    values.
 
 
+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:
+
+.. ipython:: python
+
+   dispatch = self_consumption_flow["Grid to load"] - self_consumption_flow["System to grid"]
+   dispatch.loc[dispatch.index.hour < 8] = 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
+   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()
+
+
 Energy flow
 -----------
 

pvlib/powerflow.py

@@ -85,3 +85,57 @@ def self_consumption_ac_battery(
         axis=1, skipna=False
     )
     return final_state, df
+
+
+def self_consumption_ac_battery_custom_dispatch(
+    df, dispatch, battery, model, ac_dc_loss=4, dc_ac_loss=4
+):
+    """
+    Calculate the power flow for a self-consumption use case with an
+    AC-connected battery and a custom dispatch series. It assumes the system is
+    connected to the grid.
+
+    Parameters
+    ----------
+    df : DataFrame
+        The self-consumption power flow solution. [W]
+    dispatch : Series
+        The battery model to use.
+    battery : dict
+        The battery parameters.
+    model : str
+        The battery model to use.
+    ac_dc_loss : float
+        The fixed loss when converting AC to DC (i.e.: charging). [%]
+    dc_ac_loss : float
+        The fixed loss when converting DC to AC (i.e.: discharging). [%]
+
+    Returns
+    -------
+    DataFrame
+        The resulting power flow provided by the system, the grid and the
+        battery into the system, grid, battery and load. [W]
+    """
+    # TODO: should we move this to the battery model? (i.e.: the dispatch
+    #       series adjustment and the conversion losses
+    ac_dc_efficiency = 1 - ac_dc_loss / 100
+    dc_ac_efficiency = 1 - dc_ac_loss / 100
+    dc_dispatch = dispatch.copy()
+    dc_dispatch.loc[dispatch < 0] *= dc_ac_efficiency
+    dc_dispatch.loc[dispatch > 0] /= ac_dc_efficiency
+    final_state, results = model(battery, dc_dispatch)
+    df = df.copy()
+    df["System to battery"] = -results["Power"]
+    df["System to battery"].loc[df["System to battery"] < 0] = 0.0
+    df["System to battery"] /= ac_dc_efficiency
+    df["System to battery"] = df[["System to battery", "System to grid"]].min(axis=1)
+    df["System to grid"] -= df["System to battery"]
+    df["Battery to load"] = results["Power"]
+    df["Battery to load"].loc[df["Battery to load"] < 0] = 0.0
+    df["Battery to load"] *= dc_ac_efficiency
+    df["Battery to load"] = df[["Battery to load", "Grid to load"]].min(axis=1)
+    df["Grid to load"] -= df["Battery to load"]
+    df["Grid"] = df[["Grid to system", "Grid to load"]].sum(
+        axis=1, skipna=False
+    )
+    return final_state, df

setup.py

@@ -53,13 +53,13 @@
                  'requests-mock', 'pytest-timeout', 'pytest-rerunfailures',
                  'pytest-remotedata']
 EXTRAS_REQUIRE = {
-    'optional': ['cython', 'ephem', 'netcdf4', 'nrel-pysam >= 3.0', 'numba',
+    'optional': ['cython', 'ephem', 'netcdf4', 'nrel-pysam >= 3.0.1', 'numba',
                  'pvfactors', 'siphon', 'statsmodels',
                  'cftime >= 1.1.1'],
     'doc': ['ipython', 'matplotlib', 'sphinx == 3.1.2',
             'pydata-sphinx-theme', 'sphinx-gallery', 'docutils == 0.15.2',
             'pillow', 'netcdf4', 'siphon',
-            'sphinx-toggleprompt >= 0.0.5', 'nrel-pysam >= 3.0'],
+            'sphinx-toggleprompt >= 0.0.5', 'nrel-pysam >= 3.0.1'],
     'test': TESTS_REQUIRE
 }
 EXTRAS_REQUIRE['all'] = sorted(set(sum(EXTRAS_REQUIRE.values(), [])))