fixup! Implement initial storage support

Author: Peque

docs/sphinx/source/user_guide/storage.rst

@@ -115,17 +115,23 @@ The simplest way is to start with some battery specifications from a datasheet:
 .. ipython:: python
 
    parameters = {
-       "brand": "BYD",
-       "model": "HVS 5.1",
-       "width": 0.585,
-       "height": 0.712,
-       "depth": 0.298,
-       "weight": 91,
+       "brand": "Sonnen",
+       "model": "sonnenBatterie 10/5,5",
+       "width": 0.690,
+       "height": 1.840,
+       "depth": 0.270,
+       "weight": 98,
        "chemistry": "LFP",
-       "modules": 2,
-       "energy_wh": 5120,
-       "voltage": 204,
-       "max_power_w": 5100,
+       "mode": "AC",
+       "charge_efficiency": 0.96,
+       "discharge_efficiency": 0.96,
+       "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,
    }
 
 You can then use this information to build a model that can be used to run
@@ -358,6 +364,9 @@ following assumptions:
 - 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 battery can only charge from the system and discharge to the load (i.e.:
+  battery-to-grid and grid-to-battery power flow is always zero)
+
 - The grid will provide power to the system if required (i.e.: during night
   hours)
 

pvlib/battery.py

@@ -80,7 +80,7 @@ def fit_boc(model):
     datasheet.
     """
     params = {
-        "soc": 50,
+        "soc_percent": 50,
     }
     model.update(params)
     return model
@@ -117,27 +117,36 @@ def boc(model, dispatch):
         - SOC. [%]
         - TODO: other? (i.e.: Energy/capacity)
     """
-    min_soc = 10
-    max_soc = 90
+    min_soc = model.get("min_soc_percent", 10)
+    max_soc = model.get("max_soc_percent", 90)
     factor = offset_to_hours(dispatch.index.freq)
 
     states = []
-    current_energy = model["energy_wh"] * model["soc"] / 100
-    max_energy = model["energy_wh"] * max_soc / 100
-    min_energy = model["energy_wh"] * min_soc / 100
+    current_energy = model["dc_energy_wh"] * model["soc_percent"] / 100
+    max_energy = model["dc_energy_wh"] * max_soc / 100
+    min_energy = model["dc_energy_wh"] * min_soc / 100
+
+    dispatch = power.copy()
+    discharge_efficiency = model.get("discharge_efficiency", 1.0)
+    charge_efficiency = model.get("charge_efficiency", 1.0)
+    dispatch.loc[power < 0] *= discharge_efficiency
+    dispatch.loc[power > 0] /= charge_efficiency
+
     for power in dispatch:
         if power > 0:
-            power = min(power, model["max_power_w"])
+            power = min(power, model["dc_max_power_w"])
             energy = power * factor
             available = current_energy - min_energy
             energy = min(energy, available)
+            power = energy / factor * discharge_efficiency
         else:
-            power = max(power, -model["max_power_w"])
+            power = max(power, -model["dc_max_power_w"])
             energy = power * factor
             available = current_energy - max_energy
             energy = max(energy, available)
+            power = energy / factor / charge_efficiency
         current_energy -= energy
-        soc = current_energy / model["energy_wh"] * 100
+        soc = current_energy / model["dc_energy_wh"] * 100
         power = energy / factor
         states.append((power, soc))
 
@@ -169,20 +178,27 @@ def fit_sam(datasheet):
     calculates the model parameters that match the provided information from a
     datasheet.
     """
-    # TODO: validate/normalize datasheet struct
     chemistry = {
         "LFP": "LFPGraphite",
     }
     model = sam_default(chemistry[datasheet["chemistry"]])
     sam_sizing(
         model=model,
-        desired_power=datasheet["max_power_w"] / 1000,
-        desired_capacity=datasheet["energy_wh"] / 1000,
-        desired_voltage=datasheet["voltage"],
+        desired_power=datasheet["dc_max_power_w"] / 1000,
+        desired_capacity=datasheet["dc_energy_wh"] / 1000,
+        desired_voltage=datasheet["dc_nominal_voltage"],
     )
     model.ParamsCell.initial_SOC = 50
+    model.ParamsCell.minimum_SOC = datasheet.get("min_soc_percent", 10)
+    model.ParamsCell.maximum_SOC = datasheet.get("max_soc_percent", 90)
     export = model.export()
     del export["Controls"]
+    # TODO: can we use SAM's `calculate_battery_size` to assign these values
+    #       with `batt_dc_ac_efficiency` and `inverter_eff` respectively?
+    export.update({
+        "charge_efficiency": datasheet.get("charge_efficiency", 0.96),
+        "discharge_efficiency": datasheet.get("discharge_efficiency", 0.96),
+    })
     return export
 
 
@@ -220,8 +236,11 @@ def sam(model, power):
     battery = sam_new()
     battery.ParamsCell.assign(model.get("ParamsCell", {}))
     battery.ParamsPack.assign(model.get("ParamsPack", {}))
-    battery.ParamsCell.minimum_SOC = 10
-    battery.ParamsCell.maximum_SOC = 90
+    # TODO: min/max SOC should be configurable for each simulation (i.e.: we
+    #       could simulate more conservative cycles than what the battery allows
+    #       (but we probably should not allow more aggressive cycles
+    #battery.ParamsCell.minimum_SOC = 10
+    #battery.ParamsCell.maximum_SOC = 90
     battery.Controls.replace(
         {
             "control_mode": 1,
@@ -233,13 +252,19 @@ def sam(model, power):
     battery.StateCell.assign(model.get("StateCell", {}))
     battery.StatePack.assign(model.get("StatePack", {}))
 
+    battery_dispatch = power.copy()
+    battery_dispatch.loc[power < 0] *= model["discharge_efficiency"]
+    battery_dispatch.loc[power > 0] /= model["charge_efficiency"]
+
     states = []
     for p in power:
         battery.Controls.input_power = p / 1000
         battery.execute(0)
         states.append((battery.StatePack.P * 1000, battery.StatePack.SOC))
 
     results = DataFrame(states, index=power.index, columns=["Power", "SOC"])
+    results.loc[results["Power"] < 0, "Power"] /= model["charge_efficiency"]
+    results.loc[results["Power"] > 0, "Power"] *= model["discharge_efficiency"]
     export = battery.export()
     del export["Controls"]
 

pvlib/powerflow.py

@@ -116,23 +116,14 @@ def self_consumption_ac_battery_custom_dispatch(
         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)
+    final_state, results = model(battery, 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(