feat

Author: ADGEfficiency

README.md

@@ -44,10 +44,7 @@ asset = epl.Battery(
     power_mw=2,
     capacity_mwh=4,
     efficiency_pct=0.9,
-    # different electricity prices for each interval
-    # length of electricity_prices is the length of the simulation
     electricity_prices=[100.0, 50, 200, -100, 0, 200, 100, -100],
-    # a constant value for each interval
     export_electricity_prices=40,
 )
 

docs/docs/examples/renewable-battery-export.py

@@ -1,4 +1,5 @@
 """Example of a site with a renewable generator and a battery exporting to the grid."""
+
 import energypylinear as epl
 
 assets = [

docs/docs/how-to/battery-degradation.md

@@ -1,8 +1,10 @@
-Battery degradation is where battery performance reduces with time or battery use.
+Battery performance reducing is known as battery degradation. Battery degradation can occur over time or with battery use.
 
-The performance of the battery is defined by the parameters of power (MW), capacity (MWh) and efficiency (%).
+The performance of a battery is defined by the parameters of power (MW), capacity (MWh) and efficiency (%).
 
-`energypylinear` does not model battery degradation within a single simulation - degradation can be handled by splitting up the battery lifetime into multiple simulations.
+`energypylinear` does not model battery degradation within a single simulation.  Parameters like capacity or efficiency are held constant across a simulation.
+
+Degradation can be handled by splitting up the battery lifetime into multiple simulations, with different parameters used in different simulations.
 
 ## Modelling a Single Year in Monthly Chunks
 

docs/docs/how-to/renewables-and-battery.md

@@ -0,0 +1,88 @@
+# Renewable Generator, Battery and Site Limits
+
+`energypylinear` has the ability to optimize a battery located with renewable electricity generation.
+
+This guide shows how to model a site with a renewable generator and battery that can export electricity to the grid.
+
+## Basic Setup
+
+First, let's set up a site with two assets - a solar generator and battery, with a site export limit of 25 MW:
+
+<!--phmdoctest-share-names-->
+```python
+import energypylinear as epl
+
+# Create assets:
+# - 10 MW / 20 MWh battery with 90% round-trip efficiency
+# - Solar generator with a predefined generation profile (10-30 MW across 5 intervals)
+# - Generator can be curtailed down to 50% of available generation
+# - Custom name "solar" for the generator
+assets = [
+    epl.Battery(power_mw=10, capacity_mwh=20, efficiency_pct=0.9),
+    epl.RenewableGenerator(
+        electric_generation_mwh=[10, 20, 30, 20, 10],
+        electric_generation_lower_bound_pct=0.5,
+        name="solar",
+    ),
+]
+
+# Configure site:
+# - Carbon intensity values for each interval (negative values represent low carbon periods)
+# - Maximum export limit of 25 MW to the grid
+site = epl.Site(
+    assets=assets,
+    electricity_carbon_intensities=[0.5, -0.5, 0.5, 0.5, -0.5],
+    export_limit_mw=25,
+)
+
+# Optimize for carbon minimization rather than profit maximization
+simulation = site.optimize(objective="carbon")
+```
+
+## Examining the Results
+
+Let's examine the results of our optimization to see how the battery and solar plant work together under carbon optimization.
+
+<!--phmdoctest-share-names-->
+```python
+print(
+    simulation.results[
+        [
+            "site-electricity_carbon_intensities",
+            "site-export_limit_mw",
+            "site-export_power_mwh",
+            "solar-electric_generation_used_mwh",
+            "battery-electric_charge_mwh",
+            "battery-electric_discharge_mwh",
+            "battery-electric_final_charge_mwh",
+        ]
+    ]
+)
+```
+
+This gives us the following output:
+
+```
+   site-electricity_carbon_intensities  site-export_limit_mw  site-export_power_mwh  solar-electric_generation_used_mwh  battery-electric_charge_mwh  battery-electric_discharge_mwh  battery-electric_final_charge_mwh
+0                                  0.5                    25                  10.00                                10.0                        0.00                          0.00                                0.00
+1                                 -0.5                    25                  25.00                                20.0                        5.00                          0.00                                4.50
+2                                  0.5                    25                  25.00                                30.0                        0.00                          5.00                                0.00
+3                                  0.5                    25                  15.00                                20.0                        0.00                          5.00                                0.00
+4                                 -0.5                    25                  10.00                                10.0                        0.00                          0.00                                0.00
+```
+
+## Results Interpretation
+
+When optimized for carbon, we can observe the following behavior:
+
+1. During periods with negative carbon intensity (intervals 1 and 4):
+   - In interval 1: The battery charges 5 MWh while solar generates 20 MWh, maximizing export to the grid up to the 25 MW limit
+   - In interval 4: Solar generation is only 10 MWh, which is fully exported
+
+2. During periods with positive carbon intensity (intervals 0, 2, and 3):
+   - The battery discharges in intervals 2 and 3 to maximize export during high carbon periods
+   - The battery and solar work together to respect the 25 MW export limit
+
+This strategy minimizes overall carbon emissions by:
+- Maximizing export during negative carbon periods (displacing high-carbon grid generation)
+- Using the battery to shift energy between periods strategically

docs/mkdocs.yml

@@ -65,9 +65,9 @@ nav:
       - Multiple Assets: how-to/dispatch-site.md
       - Carbon: how-to/price-carbon.md
       - Forecast: how-to/dispatch-forecast.md
-      - Battery Cycles: how-to/battery-cycles.md
+      - Battery Degradation: how-to/battery-degradation.md
       - Network Charges: how-to/network-charges.md
->>>>>>> 8a21d117db6b142efd9f1d9f0dd4e87d5a7dae35
+      - Renewables, Battery and Site Limits: how-to/renewables-and-battery.md
   - Customization:
       - Constraints: how-to/custom-constraints.md
       - Objective Functions: how-to/custom-objectives.md

docs/requirements.txt

@@ -8,3 +8,4 @@ cairosvg
 mike==1.1.2
 material-plausible-plugin
 pymdown-extensions
+setuptools