Clean up and improve models

Author: flma0001

README.md

@@ -10,7 +10,7 @@ draf is a Python library for analyzing price-based demand response. It is develo
 
 # Quick start
 
-```bash
+```sh
 git clone https://github.com/DrafProject/draf
 cd draf
 
@@ -32,7 +32,7 @@ pytest
 
 A `CaseStudy` object can contain several `Scenario` instances e.g.:
 
-``` None
+```none
 CaseStudy
  ⤷ Year, Country, timely resolution (freq)
  ⤷ Plots (scenario comparision, pareto analysis)
@@ -45,6 +45,8 @@ CaseStudy
 # Some features
 
 - Intuitive handling of complex data structures.
+- Fast model formulation with gurobipy.
+- Open-source model formulation with pyomo.
 - Uses the power of gurobi, the fastest MILP solver available and its community for model formulation and solving.
 - Easy and automatic scenario generation and sensitivity analyses.
 - Naming conventions for parameters and variables.
@@ -55,7 +57,7 @@ CaseStudy
 - Modules for peak-load analysis.
 - Economic assessment uses historic day-ahead market prices.
 - Convenient plotting and presentation functions.
-- Automatic unit conversion, great descriptions and documentation.
+- Automatic unit conversion, descriptions and documentation.
 - Uses Python's modern type annotations.
 - Whole case studies and individual scenarios can be saved including all results.
 
@@ -73,44 +75,40 @@ Raw-data  parquet-files  pd.Series
 
 You can make your own model...
 
-``` Python
+```py
+from gurobipy import GRB, Model, quicksum
+
 import draf
-import gurobipy as gp
 
 cs = draf.CaseStudy(name="foo", year=2019, freq="60min", country="DE")
+cs.set_time_horizon(start="Jan-02 00", steps=24 * 2)
 
 sc = cs.add_REF_scen()
-sc.add_dim("T", infer=True)
-sc.prep.add_c_GRID_RTP_T()
-sc.prep.add_E_dem_T(profile="G3", annual_energy=5e5)
-sc.add_var("C_", unit="€/a", lb=-gp.GRB.INFINITY)
+sc.dim("T", infer=True)
+sc.var("C_", unit="€/a", lb=-GRB.INFINITY)
+sc.prep.c_GRID_RTP_T()
+sc.prep.E_dem_T(profile="G3", annual_energy=5e5)
 
-def model_func(d, p, v, m):  # (d)imensions, (p)arameters, (v)ariables, (m)odel
-     m.setObjective(v.C_, gp.GRB.MINIMIZE)
-     m.addConstr(v.C_ == gp.quicksum(p.E_dem_T[t] * p.c_GRID_RTP_T[t] for t in d.T))
+def model_func(m: Model, d: draf.Dimensions, p: draf.Params, v: draf.Vars):
+     m.setObjective(v.C_, GRB.MINIMIZE)
+     m.addConstr(v.C_ == quicksum(p.E_dem_T[t] * p.c_GRID_RTP_T[t] for t in d.T))
 
-cs.set_model(model_func).optimize().save()
+cs.set_model(mod.model_func).optimize().save()
 ```
 
 ... or use an existing one.
 
-``` Python
+```py
 import draf
-import draf.models.PV_BES as mod
+from draf.models.gp import pv_bes as mod
 
 cs = draf.CaseStudy(name="ShowCase", year=2017, freq="60min", country="DE")
-
-cs.add_REF_scen(doc="no BES").set_params(mod.params_func).update_params(
-     P_PV_CAPx_=100, c_GRID_peak_=50
-)
-
-cs.add_scens(
-    scen_vars=[("c_GRID_T", "t", ["c_GRID_RTP_T", "c_GRID_TOU_T"]), ("E_BES_CAPx_", "b", [1000])],
-    nParetoPoints=4,
-)
-
-cs.improve_pareto_and_set_model(mod.model_func).optimize(mod.postprocess_func).save()
-
+sc = cs.add_REF_scen(doc="no BES").set_params(mod.params_func)
+sc.update_params(P_PV_CAPx_=100, c_GRID_peak_=50)
+cs.add_scens(scen_vars=[("c_GRID_T", "t", ["c_GRID_RTP_T", "c_GRID_TOU_T"]),
+                        ("E_BES_CAPx_", "b", [1000])],
+             nParetoPoints=3)
+cs.set_model(mod.model_func).optimize(postprocess_func=mod.postprocess_func).save()
 ```
 
 # Common Abbreviations
@@ -139,6 +137,15 @@ cs.improve_pareto_and_set_model(mod.model_func).optimize(mod.postprocess_func).s
 
 This piece of software is in a very early stage. Use at your own risk.
 
+# Dokumentation
+
+## Conventions
+
+### Naming conventions
+
+All parameters and variable names 
+
+'E_GRID_buy_T'
 
 # License
 

draf/__init__.py

@@ -4,11 +4,9 @@
 
 __author__ = "Markus Fleschutz | [email protected]"
 __copyright__ = "Copyright (C) 2021 Markus Fleschutz"
-from draf import helper as hp
-from draf import models, prep, tools
+from draf import helper, models, prep, tools
 from draf.core.case_study import CaseStudy, open_casestudy, open_latest_casestudy
 from draf.core.entity_stores import Dimensions, Params, Results, Vars
 from draf.core.scenario import Scenario
-from draf.paths import BASE
 
 from ._version import __version__

draf/core/params_prepping.py

@@ -25,21 +25,21 @@ def __getstate__(self):
         """For serialization with pickle."""
         return None
 
-    def add_n_comp_(self, name="n_comp_"):
+    def n_comp_(self, name="n_comp_"):
         """Add cost weighting factor to compensate part year analysis."""
         sc = self.sc
-        return self.sc.add_par(
+        return self.sc.param(
             name=name,
             unit="",
             doc="Weighting factor to compensate part year analysis",
             data=len(sc.dtindex) / len(sc.dtindex_custom),
         )
 
     @hp.copy_doc(get_emissions, start="Args:")
-    def add_ce_GRID_T(self, name="ce_GRID_T", method="XEF_PP", **kwargs):
+    def ce_GRID_T(self, name="ce_GRID_T", method="XEF_PP", **kwargs):
         """Add dynamic carbon emission factors."""
         sc = self.sc
-        return self.sc.add_par(
+        return self.sc.param(
             name=name,
             unit="kgCO2eq/kWh_el",
             doc=f"{method} for {sc.year}, {sc.freq}, {sc.country}",
@@ -51,10 +51,10 @@ def add_ce_GRID_T(self, name="ce_GRID_T", method="XEF_PP", **kwargs):
             ),
         )
 
-    def add_c_GRID_RTP_T(self, name="c_GRID_RTP_T", method="hist_EP", **kwargs):
+    def c_GRID_RTP_T(self, name="c_GRID_RTP_T", method="hist_EP", **kwargs):
         """Add Real-time-prices-tariffs."""
         sc = self.sc
-        return self.sc.add_par(
+        return self.sc.param(
             name=name,
             unit="€/kWh_el",
             doc=f"Day-ahead-market-prices {sc.year}, {sc.freq}, {sc.country}",
@@ -64,10 +64,10 @@ def add_c_GRID_RTP_T(self, name="c_GRID_RTP_T", method="hist_EP", **kwargs):
             ),
         )
 
-    def add_c_GRID_PP_T(self, name="c_GRID_PP_T", method="PP"):
+    def c_GRID_PP_T(self, name="c_GRID_PP_T", method="PP"):
         """Add marginal costs from PP-method. Only for Germany."""
         sc = self.sc
-        return self.sc.add_par(
+        return self.sc.param(
             name=name,
             unit="€/kWh_el",
             doc=f"Marginal Costs {sc.year}, {sc.freq}, {sc.country}",
@@ -76,10 +76,10 @@ def add_c_GRID_PP_T(self, name="c_GRID_PP_T", method="PP"):
             ],
         )
 
-    def add_c_GRID_PWL_T(self, name="c_GRID_PWL_T", method="PWL", **kwargs):
+    def c_GRID_PWL_T(self, name="c_GRID_PWL_T", method="PWL", **kwargs):
         """Add marginal costs from PWL-method."""
         sc = self.sc
-        return self.sc.add_par(
+        return self.sc.param(
             name=name,
             unit="€/kWh_el",
             doc=f"Marginal Costs {sc.year}, {sc.freq}, {sc.country}",
@@ -88,7 +88,7 @@ def add_c_GRID_PWL_T(self, name="c_GRID_PWL_T", method="PWL", **kwargs):
             ),
         )
 
-    def add_c_GRID_TOU_T(
+    def c_GRID_TOU_T(
         self, name: str = "c_GRID_TOU_T", prices: Optional[List[float]] = None, prov: str = "BW"
     ):
         """A Time-of-Use tariff with two prices.
@@ -124,14 +124,14 @@ def add_c_GRID_TOU_T(
                 _lt = min(prices)
                 _ht = max(prices)
 
-        return self.sc.add_par(
+        return self.sc.param(
             name=name,
             unit="€/kWh_el",
             doc=f"Time-Of-Use-tariff with the prices {_lt:.3f}€ and {_ht:.3f}€",
             data=_lt * _y_lt + _ht * _y_ht,
         )
 
-    def add_c_GRID_FLAT_T(
+    def c_GRID_FLAT_T(
         self, price: Optional[float] = None, name="c_GRID_FLAT_T", doc_addon: str = ""
     ):
         if price is None:
@@ -144,15 +144,15 @@ def add_c_GRID_FLAT_T(
                 )
 
         unit = "€/kWh_el"
-        return self.sc.add_par(
+        return self.sc.param(
             name=name,
             unit=unit,
             doc=f"Flat-electricity tariff ({price:.4f} {unit}). {doc_addon}",
             fill=price,
         )
 
     @hp.copy_doc(prep.get_el_SLP)
-    def add_E_dem_T(
+    def E_dem_T(
         self,
         name="E_dem_T",
         profile="G1",
@@ -164,7 +164,7 @@ def add_E_dem_T(
         """Add an electricity demand"""
         sc = self.sc
 
-        return self.sc.add_par(
+        return self.sc.param(
             name=name,
             unit="kWh_el",
             doc=f"Electricity demand from standard load profile {profile}",
@@ -183,7 +183,7 @@ def add_E_dem_T(
         )
 
     @hp.copy_doc(prep.get_thermal_demand)
-    def add_H_dem_T(
+    def H_dem_T(
         self,
         name="H_dem_T",
         annual_energy: float = 1.0,
@@ -196,7 +196,7 @@ def add_H_dem_T(
 
         ser_amb_temp = prep.get_ambient_temp(year=sc.year, freq=sc.freq, location=location)
 
-        return self.sc.add_par(
+        return self.sc.param(
             name=name,
             unit="kWh_th",
             doc=f"Heat demand derived from ambient temperatur in {location}",
@@ -210,17 +210,17 @@ def add_H_dem_T(
             ),
         )
 
-    def add_E_PV_profile_T(self, name="E_PV_profile_T"):
+    def E_PV_profile_T(self, name="E_PV_profile_T"):
         """Add a photovoltaic profile."""
         sc = self.sc
-        return self.sc.add_par(
+        return self.sc.param(
             name=name,
             unit="kW_el/kW_peak",
             doc=f"Produced PV-power for 1 kW_peak",
             data=sc.trim_to_datetimeindex(prep.get_PV_profile()),
         )
 
-    def add_c_GRID_addon_T(
+    def c_GRID_addon_T(
         self,
         name="c_GRID_addon_T",
         AbLa_surcharge=0.00006,
@@ -251,7 +251,7 @@ def add_c_GRID_addon_T(
             Sales,
         ]
 
-        return self.sc.add_par(
+        return self.sc.param(
             name=name,
             unit="€/kWh_el",
             doc="Add-on electricity price component",

draf/core/scenario.py

@@ -194,7 +194,7 @@ def set_params(self, params_builder_func: Callable) -> Scenario:
         except RuntimeError as e:
             logger.error(e)
 
-        self.add_par(
+        self.param(
             "timelog_params_",
             self._cs._get_time_diff(),
             doc="Time for building the params",
@@ -223,7 +223,7 @@ def set_model(
 
         self._cs._set_time_trace()
         self._activate_vars()
-        self.add_par(
+        self.param(
             "timelog_vars_",
             self._cs._get_time_diff(),
             doc="Time for building the variables",
@@ -241,7 +241,7 @@ def set_model(
 
         model_builder_func(m=self.mdl, d=self.dims, p=params, v=self.vars)
 
-        self.add_par(
+        self.param(
             "timelog_model_",
             self._cs._get_time_diff(),
             doc="Time for building the model",
@@ -367,7 +367,7 @@ def _optimize_gurobipy(
         self.mdl.setParam("LogToConsole", int(logToConsole), verbose=False)
         self.mdl.setParam("OutputFlag", int(outputFlag), verbose=False)
         self.mdl.optimize()
-        self.add_par(
+        self.param(
             "timelog_solve_",
             self._cs._get_time_diff(),
             doc="Time for solving the model",
@@ -416,7 +416,7 @@ def _optimize_pyomo(
 
         results = solver.solve(self.mdl, tee=logToConsole, load_solutions=False, logfile=logfile)
 
-        self.add_par(
+        self.param(
             "timelog_solve_",
             self._cs._get_time_diff(),
             doc="Time for solving the model",
@@ -530,7 +530,7 @@ def get_coords(self, dims: str) -> List:
         """Returns a list of coordinates for the given dimensions."""
         return [getattr(self.dims, dim) for dim in list(dims)]
 
-    def add_var(
+    def var(
         self,
         name: str,
         doc: str = "",
@@ -597,7 +597,7 @@ def get_meta(self, ent_name: str, meta_type: str) -> str:
 
     def update_params(self, **kwargs) -> Scenario:
         """Update multiple existing parameters.
-        e.g. sc.update_params(E_GRID_dem_T=2000, c_GRID_addon_T=0, c_el_peak_=0)
+        e.g. sc.update_params(E_GRID_dem_T=2000, c_GRID_addon_T=0, c_GRID_peak_=0)
         """
         for ent_name, data in kwargs.items():
 
@@ -611,9 +611,9 @@ def update_params(self, **kwargs) -> Scenario:
                 raise RuntimeError(f"The parameter {ent_name} you want to update does not exist.")
 
             if self.fits_convention(ent_name, data):
-                self.add_par(ent_name, data=data, update=True)
+                self.param(ent_name, data=data, update=True)
             else:
-                self.add_par(ent_name, fill=data, update=True)
+                self.param(ent_name, fill=data, update=True)
 
         return self
 
@@ -626,7 +626,7 @@ def fits_convention(self, ent_name: str, data: Union[int, float, pd.Series]) ->
         elif isinstance(data, pd.Series):
             return data.index.nlevels == len(dims)
 
-    def add_par(
+    def param(
         self,
         name: Optional[str] = None,
         data: Optional[Union[int, float, list, np.ndarray, pd.Series]] = None,
@@ -657,7 +657,7 @@ def add_par(
         if from_db is not None:
             if name is not None:
                 from_db.name = name
-            return self.add_par(**from_db.__dict__)
+            return self.param(**from_db.__dict__)
 
         dims = self._get_dims(name)
 
@@ -692,7 +692,7 @@ def add_par(
         self.params._changed_since_last_dic_export = True
         return data
 
-    def add_dim(
+    def dim(
         self,
         name: str,
         data: Union[List, np.ndarray] = None,