Refine Site API, Upgrade Pydantic (#41)

* fix: update site api to use freq_mins the same as assets

* chore: bump version to 1.0.0

* chore: enable python 3.12

* test: add missing site docs tests

* docs: fix docs tests

* build: update poetry lock check

* test: update to python 3.11

* test: add more evs tests

* test: more site testing

* build: upgrade pydantic, numpy versions, make check, test, static,
develop poetry groups optional

* build: pydantic version upgrade

* test: add pytest and hypothesis ignore stubs to mypy

* test: add _pytest to mypy ignores

* test: make mypy happy with _pytest

Author: ADGEfficiency

.github/workflows/test.yml

@@ -13,13 +13,13 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v4
         with:
-          python-version: 3.10.6
+          python-version: 3.11.5
       - run: make test QUIET=
   check:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v4
         with:
-          python-version: 3.10.6
+          python-version: 3.11.5
       - run: make check QUIET=

Makefile

@@ -13,7 +13,7 @@ QUIET := -q
 
 setup-pip-poetry:
 	pip install --upgrade pip $(QUIET)
-	pip install poetry -c ./constraints.txt $(QUIET)
+	pip install poetry==1.6.1 $(QUIET)
 
 setup: setup-pip-poetry
 	poetry install --with main $(QUIET)
@@ -58,6 +58,7 @@ create-test-docs: setup-test clean-test-docs
 	python -m phmdoctest ./docs/docs/validation/renewable-generator.md --outfile tests/phmdoctest/test_validate_renewable_generator.py
 	python -m phmdoctest ./docs/docs/how-to/dispatch-forecast.md --outfile tests/phmdoctest/test_forecast.py
 	python -m phmdoctest ./docs/docs/how-to/price-carbon.md --outfile tests/phmdoctest/test_carbon.py
+	python -m phmdoctest ./docs/docs/how-to/dispatch-site.md --outfile tests/phmdoctest/test_dispatch_site.py
 	python -m phmdoctest ./docs/docs/assets/chp.md --outfile tests/phmdoctest/test_optimize_chp.py
 	python -m phmdoctest ./docs/docs/assets/battery.md --outfile tests/phmdoctest/test_optimize_battery.py
 	python -m phmdoctest ./docs/docs/assets/evs.md --outfile tests/phmdoctest/test_optimize_evs.py
@@ -92,7 +93,7 @@ lint: setup-check
 	ruff check . --ignore E501 --extend-exclude=__init__.py,poc
 	isort --check **/*.py --profile black
 	black --check **/*.py
-	poetry lock --check
+	poetry check
 
 
 #  ----- FORMATTING -----

constraints.txt

@@ -22,7 +22,7 @@ asset = epl.Battery(
     power_mw=1,
     capacity_mwh=3,
     efficiency_pct=0.9,
-    electricity_carbon_intensities = [0.1, 0.2, 0.1, 0.15, 0.01, 0.7, 0.5, 0.01],
+    electricity_carbon_intensities=[0.1, 0.2, 0.1, 0.15, 0.01, 0.7, 0.5, 0.01],
     freq_mins=60,
     initial_charge_mwh=0,
     final_charge_mwh=0,
@@ -40,6 +40,7 @@ assert all(
         "site-low_temperature_load_mwh",
         "site-low_temperature_generation_mwh",
         "site-gas_prices",
+        "site-electric_load_mwh",
         "spill-electric_generation_mwh",
         "spill-electric_load_mwh",
         "spill-high_temperature_generation_mwh",

docs/docs/assets/battery.md

@@ -48,6 +48,7 @@ assert all(
         "site-low_temperature_load_mwh",
         "site-low_temperature_generation_mwh",
         "site-gas_prices",
+        "site-electric_load_mwh",
         "spill-electric_generation_mwh",
         "spill-electric_load_mwh",
         "spill-high_temperature_generation_mwh",

docs/docs/assets/chp.md

@@ -43,6 +43,7 @@ assert all(
         "site-low_temperature_load_mwh",
         "site-low_temperature_generation_mwh",
         "site-gas_prices",
+        "site-electric_load_mwh",
         "spill-electric_generation_mwh",
         "spill-electric_load_mwh",
         "spill-high_temperature_generation_mwh",

docs/docs/assets/evs.md

@@ -45,6 +45,7 @@ assert all(
         "site-low_temperature_load_mwh",
         "site-low_temperature_generation_mwh",
         "site-gas_prices",
+        "site-electric_load_mwh",
         "spill-electric_generation_mwh",
         "spill-electric_load_mwh",
         "spill-high_temperature_generation_mwh",

docs/docs/assets/heat-pump.md

@@ -26,6 +26,7 @@ assert all(
         "site-low_temperature_load_mwh",
         "site-low_temperature_generation_mwh",
         "site-gas_prices",
+        "site-electric_load_mwh",
         "wind-electric_generation_mwh",
         "total-electric_generation_mwh",
         "total-electric_load_mwh",

docs/docs/assets/renewable-generator.md

@@ -6,28 +6,32 @@ Multiple assets can be optimized using a single `epl.Site`, which accepts a list
 
 Below we give some examples of typical configurations of energy assets.
 
-## Battery & CHP Generator
+## Battery & CHP
 
-We can use a site to optimize an electric battery alongside a gas fired generator:
+We can use a site to optimize an electric battery alongside a gas fired CHP:
 
 ```python
 import energypylinear as epl
 
-site = epl.Site(assets=[
-  epl.Battery(power_mw=2.0, capacity_mwh=4.0),
-  epl.Generator(
-    electric_power_max_mw=100,
-    electric_power_min_mw=30,
-    electric_efficiency_pct=0.4
-  )
-])
-
-simulation = site.optimize(
-  electricity_prices=[100.0, 50, 200, -100, 0, 200, 100, -100],
-  freq_mins=60,
-  initial_charge_mwh=1,
-  final_charge_mwh=3
+site = epl.Site(
+    assets=[
+        epl.Battery(
+            power_mw=2.0,
+            capacity_mwh=4.0,
+            initial_charge_mwh=1,
+            final_charge_mwh=3
+        ),
+        epl.CHP(
+            electric_power_max_mw=100,
+            electric_power_min_mw=30,
+            electric_efficiency_pct=0.4,
+        ),
+    ],
+    electricity_prices=[100.0, 50, 200, -100, 0, 200, 100, -100],
+    freq_mins=60,
 )
+
+simulation = site.optimize()
 ```
 
 ## Fast & Slow Battery
@@ -37,17 +41,27 @@ We can use a site to optimize a fast and slow battery alongside each other:
 ```python
 import energypylinear as epl
 
-site = epl.Site(assets=[
-  epl.Battery(power_mw=4.0, capacity_mwh=1.0),
-  epl.Battery(power_mw=2.0, capacity_mwh=4.0),
-])
-
-simulation = site.optimize(
-  electricity_prices=[100.0, 50, 200, -100, 0, 200, 100, -100],
-  freq_mins=60,
-  initial_charge_mwh=1,
-  final_charge_mwh=3
+site = epl.Site(
+    assets=[
+        epl.Battery(
+            power_mw=4.0,
+            capacity_mwh=1.0,
+            initial_charge_mwh=1,
+            final_charge_mwh=1
+        ),
+        epl.Battery(
+            power_mw=2.0,
+            capacity_mwh=4.0,
+            initial_charge_mwh=4.0,
+            final_charge_mwh=0.0,
+            name="battery-2",
+        ),
+    ],
+    electricity_prices=[100.0, 50, 200, -100, 0, 200, 100, -100],
+    freq_mins=60,
 )
+
+simulation = site.optimize()
 ```
 
 ## Battery & EV Chargers
@@ -57,22 +71,29 @@ We can use a site to optimize a battery that sits alongside EV chargers:
 ```python
 import energypylinear as epl
 
-site = epl.Site(assets=[
-  epl.Battery(power_mw=2.0, capacity_mwh=4.0),
-  epl.EVs(charger_mws=[100, 100], charger_turndown=0.1)
-])
-
-simulation = site.optimize(
-  electricity_prices=[100.0, 50, 200, -100, 0, 200, 100, -100],
-  freq_mins=60,
-  initial_charge_mwh=1,
-  final_charge_mwh=3,
-  charge_events=[
-      [1, 0, 0, 0, 0, 0, 0, 0],
-      [0, 1, 1, 1, 0, 0, 0, 0],
-      [0, 0, 0, 1, 1, 0, 0, 0],
-      [0, 1, 0, 0, 0, 0, 0, 0],
+site = epl.Site(
+    assets=[
+        epl.Battery(
+            power_mw=2.0,
+            capacity_mwh=4.0,
+            initial_charge_mwh=1,
+            final_charge_mwh=3,
+        ),
+        epl.EVs(
+            chargers_power_mw=[100, 100],
+            charger_turndown=0.1,
+            charge_events=[
+                [1, 0, 0, 0, 0, 0, 0, 0],
+                [0, 1, 1, 1, 0, 0, 0, 0],
+                [0, 0, 0, 1, 1, 0, 0, 0],
+                [0, 1, 0, 0, 0, 0, 0, 0],
+            ],
+            charge_events_capacity_mwh=[50, 100, 30, 40],
+        ),
     ],
-  charge_event_mwh=[50, 100, 30, 40]
+    electricity_prices=[100.0, 50, 200, -100, 0, 200, 100, -100],
+    freq_mins=60,
 )
+
+simulation = site.optimize()
 ```