Remove flag to include battery charge & discharge binary variables (#45)

* feat: remove flag to include battery charge / discharge binary variables

* test: fix up changed battery dispatch behaviour

* test: make hypothesis tests quiet

* test: increase timeout on hypothesis testing

* test: increase hypothesis examples

* test: fix battery charge test by clipping battery values to zero

* test: test battery check helper

* test: separate out distance between import export price tests

* test: test updates, documentation & refactors based on self review

* test: fix test name

* refactor: move optimizer config into asset.optimize

* docs: changelog updates

* test: increase timeout for hypothesis testing

* test: add timeout onto hypothesis tests in battery

* docs: fix readme line numbers in mkdocs index

Author: ADGEfficiency

README.md

@@ -42,7 +42,8 @@ asset = epl.Battery(
     power_mw=2,
     capacity_mwh=4,
     efficiency_pct=0.9,
-  electricity_prices=[100.0, 50, 200, -100, 0, 200, 100, -100]
+  electricity_prices=[100.0, 50, 200, -100, 0, 200, 100, -100],
+  export_electricity_prices=40
 )
 
 simulation = asset.optimize()

docs/docs/changelog.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## [1.1.0](https://github.com/ADGEfficiency/energy-py-linear/releases/tag/v1.1.0)
+
+### Export Electricity Prices
+
+Assets can now accept export electricity prices - these are an optional time series that can either be a constant value or interval data:
+
+```python
+asset = epl.Battery(
+    electricity_prices=[100.0, 50, 200, -100, 0, 200, 100, -100],
+    export_electricity_prices=40
+)
+```
+
+These export electricity prices are used to calculate the value of electricity exported from site.
+
+### Optimizer Config
+
+The `.optimize()` method of assets now accepts an `epl.OptimizerConfig` object, which allows configuration of the CBC optimizer used by Pulp:
+
+```python
+asset.optimize(
+    optimizer_config=epl.OptimizerConfig(timeout=60, relative_tolerance=0.05)
+)
+```
+
+### Bugs
+
+Fixed a bug on the `allow_infeasible` flag in `epl.Site.optimize`.
+
+Fixed a bug on the `export_limit_mw` in `epl.Site.__init__`.
+
+#### Netting Off Battery Charge and Discharge
+
+`energypylinear` has the ability to constrain battery charge or discharge into a single interval, using binary variables that are linked to the charge and discharge energy.
+
+By default these were turned off, because it slows down the optimization. The effect on the site electricity balance was zero, as the charge and discharge energy were netted off in the balance.
+
+However, as the battery losses are a percentage of battery charge, this led to situations where when electricity prices were negative, the optimizer would be incentivized to have a large simultaneous charge and discharge.  This would also lead to the situation where the losses calculations were correct as a percentage of battery charge, but not of battery net charge.
+
+The solution is to remove the flag that allowed toggling of these binary variables on and off - this now means that the battery model always runs with binary variables limiting only one of charge or discharge to occur in a single interval.
+
+
 ## [1.0.0](https://github.com/ADGEfficiency/energy-py-linear/releases/tag/v1.0.0)
 
 ### Add Renewable Generator Asset

docs/docs/how-to/dispatch-forecast.md

@@ -28,7 +28,7 @@ print(f"{perfect_foresight=}")
 ```
 
 ```
-perfect_foresight=<Accounts profit=1057.78 emissions=0.0822>
+perfect_foresight=<Accounts profit=1037.78 emissions=0.0622>
 ```
 
 ## Optimize to a Forecast
@@ -65,7 +65,7 @@ print(f"{variance=}")
 ```
 
 ```
-variance=<Account profit=1197.78 emissions=0.0022>
+variance=<Account profit=1177.78 emissions=-0.0178>
 ```
 
 ## Full Example

docs/docs/how-to/price-carbon.md

@@ -62,7 +62,7 @@ print(f"{price_account=}")
 ```
 
 ```
-price_account=<Accounts profit=1057.78 emissions=-1.6558>
+price_account=<Accounts profit=1037.78 emissions=-1.6578>
 ```
 
 ## Calculate Variance Between Accounts
@@ -75,6 +75,6 @@ print(f"{-variance.cost / variance.emissions:.2f} $/tC")
 ```
 
 ```
-variance=<Account profit=923.33 emissions=0.6176>
-1495.14 $/tC
+variance=<Account profit=903.33 emissions=0.6156>
+1467.51 $/tC
 ```

docs/docs/index.md

@@ -1,3 +1,3 @@
 # energy-py-linear
 
-{!../../README.md!lines=11-93}
+{!../../README.md!lines=11-94}

docs/docs/static/battery-fast.png

@@ -37,7 +37,7 @@ Now let's change the prices and see how the dispatch changes:
 import energypylinear as epl
 
 asset = epl.Battery(
-    electricity_prices=[200, -50, -50, 200, 200],
+    electricity_prices=[200, -50, -50, 200, 220],
 )
 simulation = asset.optimize(verbose=False)
 print(simulation.results[["site-electricity_prices", "site-electricity_balance_mwh"]])
@@ -48,8 +48,8 @@ print(simulation.results[["site-electricity_prices", "site-electricity_balance_m
 0                      200                           0.0
 1                      -50                           2.0
 2                      -50                           2.0
-3                      200                          -2.0
-4                      200                          -1.6
+3                      200                          -1.6
+4                      220                          -2.0
 ```
 
 As expected, the battery continues to charge during low electricity price intervals, and discharge when electricity prices are high.

docs/docs/static/battery.png

@@ -29,63 +29,57 @@ def test_battery_performance() -> None:
     num_trials = 15
 
     run_times = collections.defaultdict(list)
-    for flag in [True, False]:
-        for idx_length in idx_lengths:
-            trial_times = collections.defaultdict(list)
-
-            for n_trial in range(num_trials):
-                print(f"idx_length: {idx_length} trial {n_trial}")
-                st = time.perf_counter()
-
-                ds = {"electricity_prices": np.random.uniform(-1000, 1000, idx_length)}
-                asset = epl.Battery(
-                    power_mw=2,
-                    capacity_mwh=4,
-                    efficiency_pct=0.9,
-                    electricity_prices=ds["electricity_prices"],
-                )
-
-                asset.optimize(
-                    verbose=False,
-                    flags=Flags(
-                        allow_evs_discharge=True,
-                        fail_on_spill_asset_use=True,
-                        allow_infeasible=False,
-                        include_charge_discharge_binary_variables=flag,
-                    ),
-                )
-
-                trial_times["time"].append(time.perf_counter() - st)
-
-            run_times["time"].append(
-                {
-                    "mean": statistics.mean(trial_times["time"]),
-                    "std": statistics.stdev(trial_times["time"]),
-                    "flag": flag,
-                    "idx_length": idx_length,
-                }
+    for idx_length in idx_lengths:
+        trial_times = collections.defaultdict(list)
+
+        for n_trial in range(num_trials):
+            print(f"idx_length: {idx_length} trial {n_trial}")
+            st = time.perf_counter()
+
+            ds = {"electricity_prices": np.random.uniform(-1000, 1000, idx_length)}
+            asset = epl.Battery(
+                power_mw=2,
+                capacity_mwh=4,
+                efficiency_pct=0.9,
+                electricity_prices=ds["electricity_prices"],
             )
-            print(run_times["time"])
+
+            asset.optimize(
+                verbose=False,
+                flags=Flags(
+                    allow_evs_discharge=True,
+                    fail_on_spill_asset_use=True,
+                    allow_infeasible=False,
+                ),
+            )
+
+            trial_times["time"].append(time.perf_counter() - st)
+
+        run_times["time"].append(
+            {
+                "mean": statistics.mean(trial_times["time"]),
+                "std": statistics.stdev(trial_times["time"]),
+                "idx_length": idx_length,
+            }
+        )
+        print(run_times["time"])
 
     fig, axes = plt.subplots(nrows=1, sharex=True)
     print("[red]final run times:[/]")
     print(run_times)
-    for flag in [True, False]:
 
-        subset: list = [p for p in run_times["time"] if p["flag"] == flag]
-        axes.plot(
-            [p["idx_length"] for p in subset],
-            [p["mean"] for p in subset],
-            marker="o",
-            label=f"include_charge_discharge_binary_variables={flag}",
-        )
-        axes.set_title(asset.__repr__())
-        axes.set_ylabel("Run Time (seconds)")
-        axes.legend()
-        axes.grid(True)
-        plt.xlabel("Index Length")
-        plt.tight_layout()
-        fig.savefig("./docs/docs/static/battery-performance.png")
+    axes.plot(
+        [p["idx_length"] for p in run_times["time"]],
+        [p["mean"] for p in run_times["time"]],
+        marker="o",
+    )
+    axes.set_title(asset.__repr__())
+    axes.set_ylabel("Run Time (seconds)")
+    axes.legend()
+    axes.grid(True)
+    plt.xlabel("Index Length")
+    plt.tight_layout()
+    fig.savefig("./docs/docs/static/battery-performance.png")
 
 
 def test_evs_performance() -> None:

docs/docs/validation/battery.md

@@ -72,20 +72,19 @@ def constrain_only_charge_or_discharge(
     difference to calculate net charge.
     """
     assert isinstance(battery, BatteryOneInterval)
-    if flags.include_charge_discharge_binary_variables:
-        optimizer.constrain_max(
-            battery.electric_charge_mwh,
-            battery.electric_charge_binary,
-            battery.cfg.capacity_mwh,
-        )
-        optimizer.constrain_max(
-            battery.electric_discharge_mwh,
-            battery.electric_discharge_binary,
-            battery.cfg.capacity_mwh,
-        )
-        optimizer.constrain(
-            battery.electric_charge_binary + battery.electric_discharge_binary <= 1
-        )
+    optimizer.constrain_max(
+        battery.electric_charge_mwh,
+        battery.electric_charge_binary,
+        battery.cfg.capacity_mwh,
+    )
+    optimizer.constrain_max(
+        battery.electric_discharge_mwh,
+        battery.electric_discharge_binary,
+        battery.cfg.capacity_mwh,
+    )
+    optimizer.constrain(
+        battery.electric_charge_binary + battery.electric_discharge_binary <= 1
+    )
 
 
 def constrain_battery_electricity_balance(
@@ -167,7 +166,6 @@ def __init__(
         initial_charge_mwh: float = 0.0,
         final_charge_mwh: float | None = None,
         freq_mins: int = defaults.freq_mins,
-        optimizer_config: "epl.OptimizerConfig" = epl.optimizer.OptimizerConfig(),
     ):
         """Initializes the asset."""
 
@@ -193,7 +191,6 @@ def __init__(
                 export_electricity_prices=export_electricity_prices,
                 electricity_carbon_intensities=electricity_carbon_intensities,
                 freq_mins=self.cfg.freq_mins,
-                optimizer_config=optimizer_config,
             )
 
     def __repr__(self) -> str:
@@ -216,14 +213,10 @@ def one_interval(
             ),
             electric_charge_binary=optimizer.binary(
                 f"{self.cfg.name}-electric_charge_binary-{i}"
-            )
-            if flags.include_charge_discharge_binary_variables
-            else 0,
+            ),
             electric_discharge_binary=optimizer.binary(
                 f"{self.cfg.name}-electric_discharge_binary-{i}"
-            )
-            if flags.include_charge_discharge_binary_variables
-            else 0,
+            ),
             electric_loss_mwh=optimizer.continuous(
                 f"{self.cfg.name}-electric_loss_mwh-{i}"
             ),
@@ -283,13 +276,15 @@ def optimize(
         objective: str = "price",
         verbose: bool = True,
         flags: Flags = Flags(),
+        optimizer_config: "epl.OptimizerConfig" = epl.optimizer.OptimizerConfig(),
     ) -> "epl.SimulationResult":
         """Optimize the asset.
 
         Args:
             objective: the optimization objective - either "price" or "carbon".
             flags: boolean flags to change simulation and results behaviour.
             verbose: level of printing.
+            optimizer_config: configuration options for the optimizer.
 
         Returns:
             epl.results.SimulationResult
@@ -298,6 +293,7 @@ def optimize(
             objective=objective,
             flags=flags,
             verbose=verbose,
+            optimizer_config=optimizer_config,
         )
 
     def plot(self, results: "epl.SimulationResult", path: pathlib.Path | str) -> None: