Features/schedule for flow

docs/whatsnew/v0-4-1.rst

@@ -18,4 +18,4 @@ Contributors
 ^^^^^^^^^^^^^^^^^^^^
 
 * Uwe Krien
-* Patrik Schönfeldt
+* Patrik Schönfeldt

docs/whatsnew/v0-4-2.rst

@@ -11,7 +11,8 @@ API changes
 New features
 ^^^^^^^^^^^^^^^^^^^^
 
-* something
+* It is now possible to determine a schedule for a flow. Flow will be pushed
+  to the schedule, if possible.
 
 New components/constraints
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -46,4 +47,4 @@ Other changes
 Contributors
 ^^^^^^^^^^^^^^^^^^^^
 
-* something
+* Caterina Köhl

src/oemof/solph/blocks.py

@@ -39,7 +39,16 @@ class Flow(SimpleBlock):
         Difference of a flow in consecutive timesteps if flow is increased
         indexed by NEGATIVE_GRADIENT_FLOWS, TIMESTEPS.
 
-    **The following sets are created:** (-> see basic sets at :class:`.Model` )
+    schedule_slack_pos :
+        Difference of a flow to schedule in consecutive timesteps if flow
+        has deficit to schedule. Indexed by SCHEDULE_FLOWS, TIMESTEPS.
+
+    schedule_slack_neg :
+        Excees of flow compared to schedule. Indexed by SCHEDULE_FLOWS,
+        TIMESTEPS.
+
+    **The following sets are created:** (-> see basic sets at
+    :class:`.Model` )
 
     SUMMED_MAX_FLOWS
         A set of flows with the attribute :attr:`summed_max` being not None.
@@ -54,6 +63,9 @@ class Flow(SimpleBlock):
     INTEGER_FLOWS
         A set of flows where the attribute :attr:`integer` is True (forces flow
         to only take integer values)
+    SCHEDULE_FLOWS
+        A set of flows with :attr:`schedule` not None (forces flow to follow
+        schedule)
 
     **The following constraints are build:**
 
@@ -84,16 +96,28 @@ class Flow(SimpleBlock):
           \forall (i, o) \in \textrm{POSITIVE\_GRADIENT\_FLOWS}, \\
           \forall t \in \textrm{TIMESTEPS}.
 
+    Schedule constraint :attr:`om.Flow.positive_gradient_constr[i, o]`:
+        .. math:: flow(i, o, t) + schedule_slack_pos(i, o, t) - \
+            schedule_slack_neg(i, o, t) = schedule(i, o, t) \\
+            \forall (i, o) \in \textrm{SCHEDULE\_FLOWS}, \\
+            \forall t \in \textrm{TIMESTEPS}.
+
     **The following parts of the objective function are created:**
 
     If :attr:`variable_costs` are set by the user:
-      .. math::
+        .. math::
           \sum_{(i,o)} \sum_t flow(i, o, t) \cdot variable\_costs(i, o, t)
 
     The expression can be accessed by :attr:`om.Flow.variable_costs` and
     their value after optimization by :meth:`om.Flow.variable_costs()` .
 
+    If :attr:`schedule`, :attr:`schedule_cost_pos` and
+    :attr:`schedule_cost_neg` are set by the user:
+        .. math:: \sum_{(i,o)} \sum_t schedule_cost_pos(i, o, t) \cdot \
+            schedule_slack_pos(i, o, t)  + schedule_cost_neg(i, o, t) \cdot \
+            schedule_slack_neg(i, o, t)
     """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
@@ -133,6 +157,13 @@ def _create(self, group=None):
         self.INTEGER_FLOWS = Set(
             initialize=[(g[0], g[1]) for g in group
                         if g[2].integer])
+
+        self.SCHEDULE_FLOWS = Set(initialize=[
+            (g[0], g[1]) for g in group if (
+                g[2].schedule[0] is not None or
+                any([g[2].schedule[i] is not None for i in range(
+                    0, len(g[2].schedule))]))])
+
         # ######################### Variables  ################################
 
         self.positive_gradient = Var(self.POSITIVE_GRADIENT_FLOWS,
@@ -143,6 +174,13 @@ def _create(self, group=None):
 
         self.integer_flow = Var(self.INTEGER_FLOWS,
                                 m.TIMESTEPS, within=NonNegativeIntegers)
+
+        self.schedule_slack_pos = Var(self.SCHEDULE_FLOWS,
+                                      m.TIMESTEPS, within=NonNegativeReals)
+
+        self.schedule_slack_neg = Var(self.SCHEDULE_FLOWS,
+                                      m.TIMESTEPS, within=NonNegativeReals)
+
         # set upper bound of gradient variable
         for i, o, f in group:
             if m.flows[i, o].positive_gradient['ub'][0] is not None:
@@ -222,6 +260,21 @@ def _integer_flow_rule(block, ii, oi, ti):
         self.integer_flow_constr = Constraint(self.INTEGER_FLOWS, m.TIMESTEPS,
                                               rule=_integer_flow_rule)
 
+        def _schedule_rule(model):
+            for inp, out in self.SCHEDULE_FLOWS:
+                for ts in m.TIMESTEPS:
+                    if m.flows[inp, out].schedule[ts] is not None:
+                        lhs = (m.flow[inp, out, ts] +
+                               self.schedule_slack_pos[inp, out, ts] -
+                               self.schedule_slack_neg[inp, out, ts])
+                        rhs = m.flows[inp, out].schedule[ts]
+                        self.schedule_constr.add((inp, out, ts),
+                                                 lhs == rhs)
+        self.schedule_constr = Constraint(
+            self.SCHEDULE_FLOWS, m.TIMESTEPS, noruleinit=True)
+        self.schedule_build = BuildAction(
+            rule=_schedule_rule)
+
     def _objective_expression(self):
         r""" Objective expression for all standard flows with fixed costs
         and variable costs.
@@ -230,6 +283,7 @@ def _objective_expression(self):
 
         variable_costs = 0
         gradient_costs = 0
+        schedule_costs = 0
 
         for i, o in m.FLOWS:
             if m.flows[i, o].variable_costs[0] is not None:
@@ -250,7 +304,16 @@ def _objective_expression(self):
                                        m.flows[i, o].negative_gradient[
                                            'costs'])
 
-        return variable_costs + gradient_costs
+            schedule = m.flows[i, o].schedule
+            if (len(schedule) > 1 or
+                (len(schedule) == 0 and
+                 schedule[0] is not None)):
+                for t in m.TIMESTEPS:
+                    schedule_costs += (self.schedule_slack_pos[i, o, t] *
+                                       m.flows[i, o].schedule_cost_pos[t])
+                    schedule_costs += (self.schedule_slack_neg[i, o, t] *
+                                       m.flows[i, o].schedule_cost_neg[t])
+        return variable_costs + gradient_costs + schedule_costs
 
 
 class InvestmentFlow(SimpleBlock):

src/oemof/solph/network.py

@@ -123,6 +123,24 @@ class Flow(on.Edge):
         :class:`Flow <oemof.solph.blocks.Flow>`.
         Note: at the moment this does not work if the investment attribute is
         set .
+    schedule : numeric (sequence or scalar)
+        Schedule for the flow. Flow has to follow the schedule, otherwise a
+        penalty term will be activated. If array-like, values can be None
+        for flexible, non-fixed flow during the certain timestep.  Used in
+        combination with :attr:`schedule_cost_pos` and
+        :attr:`schedule_cost_neg`.
+    schedule_cost_pos : numeric (sequence or scalar)
+        A penalty parameter of the penalty term which describes the costs
+        associated with one unit of deficit of the flow compared to the
+        schedule. If this is set the costs will be added to the objective
+        expression of the optimization problem. Used in combination with the
+        :attr:`schedule` and :attr:`schedule_cost_neg`
+    schedule_cost_neg: numeric (sequence or scalar)
+        A penalty parameter of the penalty term which describes the costs
+        associated with one unit of the exceeded flow when flow exceeds the
+        schedule. If this is set the costs will be added to the objective
+        expression of the optimization problem. Used in combination with
+        the :attr:`schedule` and :attr:`schedule_cost_pos`
 
     Notes
     -----
@@ -162,11 +180,13 @@ def __init__(self, **kwargs):
 
         scalars = ['nominal_value', 'summed_max', 'summed_min',
                    'investment', 'nonconvex', 'integer']
-        sequences = ['fix', 'variable_costs', 'min', 'max']
+        sequences = ['fix', 'variable_costs', 'min', 'max',
+                     'schedule', 'schedule_cost_neg', 'schedule_cost_pos']
         dictionaries = ['positive_gradient', 'negative_gradient']
         defaults = {'variable_costs': 0,
                     'positive_gradient': {'ub': None, 'costs': 0},
-                    'negative_gradient': {'ub': None, 'costs': 0}}
+                    'negative_gradient': {'ub': None, 'costs': 0}
+                    }
         keys = [k for k in kwargs if k != 'label']
 
         if 'fixed_costs' in keys:
@@ -218,6 +238,13 @@ def __init__(self, **kwargs):
         if self.investment and self.nonconvex:
             raise ValueError("Investment flows cannot be combined with " +
                              "nonconvex flows!")
+        if (len(self.schedule) != 0 and
+            (self.schedule_cost_neg[0] is None or
+             self.schedule_cost_pos[0] is None)):
+            raise ValueError("The schedule attribute and the associated costs "
+                             "need to be used in combination. \n Please set "
+                             "the `schedule_cost_neg` and `schedule_cost_pos` "
+                             "attributes of the flow.")
 
 
 class Bus(on.Bus):

tests/constraint_tests.py

@@ -803,6 +803,23 @@ def test_dsm_module_interval(self):
         )
         self.compare_lp_files('dsm_module_interval.lp')
 
+    def test_flow_schedule(self):
+        """Constraint test of scheduled flows."""
+        b_gas = solph.Bus(label='bus_gas')
+        b_th = solph.Bus(label='bus_th_penalty')
+
+        schedule = [None, 300, 50]
+        solph.Transformer(
+            label="boiler_penalty",
+            inputs={b_gas: solph.Flow()},
+            outputs={b_th: solph.Flow(nominal_value=200, variable_costs=0,
+                                      schedule_cost_pos=[0, 800, 900],
+                                      schedule_cost_neg=999,
+                                      schedule=schedule)},
+            conversion_factors={b_th: 1}
+        )
+        self.compare_lp_files('flow_schedule.lp')
+
     def test_nonconvex_investment_storage_without_offset(self):
         """All invest variables are coupled. The invest variables of the Flows
         will be created during the initialisation of the storage e.g. battery

tests/lp_files/flow_schedule.lp

@@ -0,0 +1,79 @@
+\* Source Pyomo model name=Model *\
+
+min
+objective:
++999 Flow_schedule_slack_neg(boiler_penalty_bus_th_penalty_0)
++999 Flow_schedule_slack_neg(boiler_penalty_bus_th_penalty_1)
++999 Flow_schedule_slack_neg(boiler_penalty_bus_th_penalty_2)
++800 Flow_schedule_slack_pos(boiler_penalty_bus_th_penalty_1)
++900 Flow_schedule_slack_pos(boiler_penalty_bus_th_penalty_2)
+
+s.t.
+
+c_e_Bus_balance(bus_gas_0)_:
++1 flow(bus_gas_boiler_penalty_0)
+= 0
+
+c_e_Bus_balance(bus_gas_1)_:
++1 flow(bus_gas_boiler_penalty_1)
+= 0
+
+c_e_Bus_balance(bus_gas_2)_:
++1 flow(bus_gas_boiler_penalty_2)
+= 0
+
+c_e_Bus_balance(bus_th_penalty_0)_:
++1 flow(boiler_penalty_bus_th_penalty_0)
+= 0
+
+c_e_Bus_balance(bus_th_penalty_1)_:
++1 flow(boiler_penalty_bus_th_penalty_1)
+= 0
+
+c_e_Bus_balance(bus_th_penalty_2)_:
++1 flow(boiler_penalty_bus_th_penalty_2)
+= 0
+
+c_e_Transformer_relation(boiler_penalty_bus_gas_bus_th_penalty_0)_:
+-1 flow(boiler_penalty_bus_th_penalty_0)
++1 flow(bus_gas_boiler_penalty_0)
+= 0
+
+c_e_Transformer_relation(boiler_penalty_bus_gas_bus_th_penalty_1)_:
+-1 flow(boiler_penalty_bus_th_penalty_1)
++1 flow(bus_gas_boiler_penalty_1)
+= 0
+
+c_e_Transformer_relation(boiler_penalty_bus_gas_bus_th_penalty_2)_:
+-1 flow(boiler_penalty_bus_th_penalty_2)
++1 flow(bus_gas_boiler_penalty_2)
+= 0
+
+c_e_Flow_schedule_constr(boiler_penalty_bus_th_penalty_1)_:
+-1 Flow_schedule_slack_neg(boiler_penalty_bus_th_penalty_1)
++1 Flow_schedule_slack_pos(boiler_penalty_bus_th_penalty_1)
++1 flow(boiler_penalty_bus_th_penalty_1)
+= 300
+
+c_e_Flow_schedule_constr(boiler_penalty_bus_th_penalty_2)_:
+-1 Flow_schedule_slack_neg(boiler_penalty_bus_th_penalty_2)
++1 Flow_schedule_slack_pos(boiler_penalty_bus_th_penalty_2)
++1 flow(boiler_penalty_bus_th_penalty_2)
+= 50
+
+c_e_ONE_VAR_CONSTANT:
+ONE_VAR_CONSTANT = 1.0
+
+bounds
+   0 <= flow(boiler_penalty_bus_th_penalty_0) <= 200
+   0 <= flow(boiler_penalty_bus_th_penalty_1) <= 200
+   0 <= flow(boiler_penalty_bus_th_penalty_2) <= 200
+   0 <= flow(bus_gas_boiler_penalty_0) <= +inf
+   0 <= flow(bus_gas_boiler_penalty_1) <= +inf
+   0 <= flow(bus_gas_boiler_penalty_2) <= +inf
+   0 <= Flow_schedule_slack_pos(boiler_penalty_bus_th_penalty_1) <= +inf
+   0 <= Flow_schedule_slack_pos(boiler_penalty_bus_th_penalty_2) <= +inf
+   0 <= Flow_schedule_slack_neg(boiler_penalty_bus_th_penalty_0) <= +inf
+   0 <= Flow_schedule_slack_neg(boiler_penalty_bus_th_penalty_1) <= +inf
+   0 <= Flow_schedule_slack_neg(boiler_penalty_bus_th_penalty_2) <= +inf
+end

tests/test_processing.py

@@ -137,6 +137,9 @@ def test_flows_without_none_exclusion(self):
             'flow': None,
             'values': None,
             'label': str(b_el2.outputs[demand].label),
+            'schedule_cost_pos': None,
+            'schedule_cost_neg': None,
+            'schedule': None,
         }
         assert_series_equal(
             param_results[(b_el2, demand)]['scalars'].sort_index(),

tests/test_solph_network_classes.py

@@ -98,3 +98,34 @@ def test_warning_fixed_still_used():
         solph.Flow(fixed=True)
         assert len(w) != 0
         assert msg == str(w[-1].message)
+
+
+def test_missing_schedule_costs_values():
+    """
+    If schedule attribute is used and negative and positive schedule costs
+    are missing, an error will be raised.
+    """
+    msg = ("The schedule attribute and the associated costs "
+           "need to be used in combination. \n Please set "
+           "the `schedule_cost_neg` and `schedule_cost_pos` "
+           "attributes of the flow.")
+    with pytest.raises(ValueError, match=msg):
+        solph.Flow(schedule=[54, 74, 90])
+
+
+def test_missing_schedule_neg_cost_value():
+    msg = ("The schedule attribute and the associated costs "
+           "need to be used in combination. \n Please set "
+           "the `schedule_cost_neg` and `schedule_cost_pos` "
+           "attributes of the flow.")
+    with pytest.raises(ValueError, match=msg):
+        solph.Flow(schedule=[54, 74, 90], schedule_cost_pos=1000)
+
+
+def test_missing_schedule_pos_cost_value():
+    msg = ("The schedule attribute and the associated costs "
+           "need to be used in combination. \n Please set "
+           "the `schedule_cost_neg` and `schedule_cost_pos` "
+           "attributes of the flow.")
+    with pytest.raises(ValueError, match=msg):
+        solph.Flow(schedule=[54, 74, 90], schedule_cost_neg=1000)