DRAF CHEAT SHEET

May 10, 2023 · View on GitHub

Common work flow

# import draf and its pre-defined component templates:
import draf
from draf.components import *

# create a case study:
cs = draf.CaseStudy("my_case_study", year=2019, country="DE", freq="60min",
                    coords=(49.01, 8.39), consider_invest=True)

# define a modeling horizon (default: whole year, here: 2 days):
cs.set_time_horizon(start="Apr-01 00:00", steps=24 * 2)

# create and parametrize a reference scenario:
sc = cs.add_REF_scen("REF", components=[BES, Main, EG, eDem, PV])
sc.update_params(E_BES_CAPx_=100)

# create a second scenario based on "REF" and update a parameter:
sc_new = cs.add_scen("new_scen", based_on="REF")
sc_new.update_params(E_BES_CAPx_=500)

# solve all scenarios:
cs.optimize()

# save the case study (including all scenarios and data) to your hard disk:
cs.save()

cs = draf.open_latest_casestudy("my_case_study")

# get an overview of the results:
cs.plot()

Interactive analysis

cs.scens - show scenarios
sc.dims - show dimensions
sc.params - show parameter entities
sc.vars - show variable entities
sc.res - show result entities

On a case study

cs.scens.REF - access a specific scenario
cs.plot() - access essential plots and tables
cs.plot.describe_interact() - description of all entities
cs.optimize(solver_params=dict(MIPGap=0)) - set a MIPGap

On a scenario

sc.params.c_EG_RTP_T - access a specific parameter entity
sc.res.P_EG_buy_T - access a specific results entity
sc.plot.describe() - description of all entities of this scenario

On an entity

cs.dated(my_entity_T) - add a date-time index to a time series
my_entity_T.plot() - plot an entity with pd.Series.plot

Paths

draf.paths.DATA_DIR - draf data directory
draf.paths.RESULTS_DIR - draf results directory
draf.paths.CACHE_DIR - draf cache directory
elmada.paths.CACHE_DIR - elmada cache directory

Elmada

import elmada
elmada.get_prices(method="hist_EP") - get historic day-ahead market prices from ENTSO-E
elmada.get_emissions(method="XEF_EP") - get historic grid-mix emission factors

Building own components

from draf import Collectors, Dimensions, Params, Results, Scenario, Vars
from gurobipy import GRB, Model, quicksum
from draf.prep import DataBase as db

# short version
class MyShortComponent:
    def param_func(self, sc): ...
    def model_func(self, sc, m, d, p, v, c): ...

# advanced version 
class MyAdvancedComponent(Component):
    """Description of your own component"""

    def dim_func(self, sc: Scenario):
        sc.dim("F", ["ng", "bio"], doc="Types of fuel")

    def param_func(self, sc: Scenario):
        sc.collector("F_fuel_F", doc="Fuel power", unit="kWh")
        sc.param(from_db=db.c_Fuel_F)
        sc.var("C_Fuel_ceTax_", doc="Total carbon tax on fuel", unit="k€/a")

    def model_func(self, sc: Scenario, m: Model, d: Dimensions, p: Params, v: Vars, c: Collectors):
        m.addConstr(v.C_Fuel_ == p.k__dT_ * v.F_fuel_F.prod(p.c_Fuel_F) * conv("€", "k€", 1e-3))
        c.CE_TOT_["Fuel"] = v.CE_Fuel_
        c.P_EL_source_T["PV"] = lambda t: v.P_PV_FI_T[t] + v.P_PV_OC_T[t]

param_func

sc.collector("P_EL_source_T", doc="...", unit="kW_el") - add a collector
sc.var("C_TOT_", doc="Total costs", unit="k€/a", lb=-GRB.INFINITY) - define a variable that can be negative
sc.var("P_PV_FI_T", doc="Feed-in", unit="kW_el") - define a variable with time dimension
sc.param("c_PV_inv_", data=200, doc="Investment costs", unit="€/kW_p", src="my_data_source")
sc.param(from_db=db.c_Fuel_F) - use data from the draf database
prepper functions (default parameter name is the function name):
- sc.prep.c_EG_T() - real-time-prices-tariffs
- sc.prep.ce_EG_T() - dynamic carbon emission factors
- sc.prep.P_eDem_T(profile="G1", annual_energy=5e6) - electricity demand with 5 GWh/a
- sc.prep.dQ_hDem_T(annual_energy=2e6, target_temp=22.0, threshold_temp=15.0) - heating demand with 2 GWh/a using weather data
- sc.prep.P_PV_profile_T() - photovoltaic profile
- sc.prep.c_EG_addon_(AbLa_surcharge=0.00003, Concession_fee=0.0011, ...) - electricity price components other than wholesale prices
- sc.prep.T__amb_T() - ambient air temperature from nearest weather station

model_func

General
- d.T - time index (special dimension)
- p.k__dT_ - time step (special parameter)
- p.k__PartYearComp_ - weighting factor to compensate part year analysis (special parameter)
GurobiPy Syntax, e.g.:
- from gurobipy import GRB, Model, quicksum - import GurobiPy objects
- m.setObjective((...), GRB.MINIMIZE) - set objective
- m.addConstr((v.your == p.constraint * v.goes + p.here), "constr_1") - add one constraint
- m.addConstrs((v.your_T[t] == p.constraint_T[t] * v.goes_ + p.here_T[t] for t in d.T), "constr_2") - add a set of constraints
Pyomo Syntax, e.g.:
- import pyomo.environ as pyo - import Pyomo
- pyo.Objective(expr=(...), sense=pyo.minimize) - set objective
- m.constr_1 = pyo.Constraint(expr=(v.your == p.constraint * v.goes + p.here)) - add one constraint
- m.constr_1 = pyo.Constraint(d.T, rule=lambda t: v.your_T[t] == p.constraint_T[t] * v.goes_ + p.here_T[t]) - add a set of constraints

Helper functions

draf.helper.address2coords("Moltkestraße 30, Karlsruhe") - converts an address to geo coordinates
draf.helper.play_beep_sound() - play a beep sound (is used in the cs.optimize() routine)
draf.helper.read(...) - draf default read function
draf.helper.write(...) - draf default write function
pd.read_csv(...) - read an external csv file

Naming conventions

Naming conventions for entities

In general, entity names should adhere to the following structure: <Etype>_<Component>_<OptionalDescription>_<DIMENSIONS>

Examples:	entity 1	entity 2
Entity name	`P_EG_buy_T`	`c_PV_inv_`
Etype	`P`	`c`
Component	`EG`	`PV`
Description	`buy`	`inv`
Dimension	`T`	`-`

For typical symbols, see draf/conventions.py.

Naming conventions for Python objects

short	long
`cs`	CaseStudy object
`sc`, `scen`	Scenario object
`m`, `mdl`	Model
`d`, `dims`	Dimension container object
`p`, `params`	Parameters container object
`v`, `vars`	Variables container object
`r`, `res`	Results container object
`ent`	Entity: a variable or parameter
`doc`	Documentation / description string
`constr`	Constraint
`meta`	Meta data
`df`	Pandas `DataFrame`
`ser`	Pandas `Series`
`fp`	file path
`gp`	`gurobipy` - the Gurobi Python Interface

Versioning of draf

Bump version (replace <part> with major, minor, or patch):

bump2version --dry-run --verbose <part>
bump2version <part>
git push origin <tag_name>