Features/schedule for flow

doc/whatsnew/v0-3-3.rst

@@ -0,0 +1,49 @@
+v0.3.3 (??, ??)
++++++++++++++++++++++++++++
+
+
+API changes
+###########
+
+* something
+
+New features
+############
+
+  * It is now possible to determine a schedule for a flow. Flow will be pushed
+    to the schedule, if possible.
+
+New components
+##############
+
+* something
+
+Documentation
+#############
+
+* something
+
+Known issues
+############
+
+* something
+
+Bug fixes
+#########
+
+* something
+
+Testing
+#######
+
+* something
+
+Other changes
+#############
+
+* something
+
+Contributors
+############
+
+* Caterina Köhl

oemof/solph/blocks.py

@@ -28,6 +28,14 @@ class Flow(SimpleBlock):
         Difference of a flow in consecutive timesteps if flow is increased
         indexed by NEGATIVE_GRADIENT_FLOWS, TIMESTEPS.
 
+    slack_pos :
+        Difference of a flow to schedule in consecutive timesteps if flow
+        has deficit to schedule. Indexed by SCHEDULE_FLOWS, TIMESTEPS.
+
+    slack_neg :
+        Excees of flow compared to schedule. Indexed by SCHEDULE_FLOWS,
+        TIMESTEPS.
+
     **The following sets are created:** (-> see basic sets at
     :class:`.Model` )
 
@@ -42,8 +50,11 @@ class Flow(SimpleBlock):
         A set of flows with the attribute :attr:`positive_gradient` being not
         None
     INTEGER_FLOWS
-        A set of flows wher the attribute :attr:`integer` is True (forces flow
+        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:**
 
@@ -71,6 +82,12 @@ 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) + slack_pos(i, o, t) - \
+            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:
@@ -80,7 +97,13 @@ class Flow(SimpleBlock):
     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:`penalty_pos` and :attr:`penalty_neg` are
+    set by the user:
+        .. math:: \sum_{(i,o)} \sum_t penalty_pos(i, o, t) \cdot \
+            slack_pos(i, o, t)  + penalty_neg(i, o, t) \cdot \
+            slack_neg(i, o, t)
     """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
@@ -120,6 +143,12 @@ 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 (
+                            len(g[2].schedule) != 0 or
+                            (len(g[2].schedule) == 0 and
+                             g[2].schedule[0] is not None))])
         # ######################### Variables  ################################
 
         self.positive_gradient = Var(self.POSITIVE_GRADIENT_FLOWS,
@@ -130,6 +159,13 @@ def _create(self, group=None):
 
         self.integer_flow = Var(self.INTEGER_FLOWS,
                                 m.TIMESTEPS, within=NonNegativeIntegers)
+
+        self.slack_pos = Var(self.SCHEDULE_FLOWS,
+                             m.TIMESTEPS, within=NonNegativeReals)
+
+        self.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:
@@ -209,6 +245,21 @@ def _integer_flow_rule(block, i, o, t):
         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.slack_pos[inp, out, ts] -
+                               self.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.
@@ -217,6 +268,7 @@ def _objective_expression(self):
 
         variable_costs = 0
         gradient_costs = 0
+        penalty_costs = 0
 
         for i, o in m.FLOWS:
             if m.flows[i, o].variable_costs[0] is not None:
@@ -236,7 +288,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:
+                    penalty_costs += (self.slack_pos[i, o, t] *
+                                      m.flows[i, o].penalty_pos[t])
+                    penalty_costs += (self.slack_neg[i, o, t] *
+                                      m.flows[i, o].penalty_neg[t])
+        return variable_costs + gradient_costs + penalty_costs
 
 
 class InvestmentFlow(SimpleBlock):

oemof/solph/network.py

@@ -117,6 +117,23 @@ 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:`penalty_pos` and :attr:`penalty_neg`.
+    penalty_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:`penalty_neg`
+    penalty_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:`penalty_pos`
 
     Notes
     -----
@@ -157,11 +174,13 @@ def __init__(self, **kwargs):
 
         scalars = ['nominal_value', 'summed_max', 'summed_min',
                    'investment', 'nonconvex', 'integer', 'fixed']
-        sequences = ['actual_value', 'variable_costs', 'min', 'max']
+        sequences = ['actual_value', 'variable_costs', 'min', 'max',
+                     'schedule', 'penalty_neg', 'penalty_pos']
         dictionaries = ['positive_gradient', 'negative_gradient']
         defaults = {'fixed': False, 'min': 0, 'max': 1, 'variable_costs': 0,
                     'positive_gradient': {'ub': None, 'costs': 0},
                     'negative_gradient': {'ub': None, 'costs': 0},
+                    'penalty_neg': 0, 'penalty_pos': 0, 'schedule': None
                     }
         keys = [k for k in kwargs if k != 'label']
 
@@ -188,6 +207,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
+            ((len(self.penalty_pos) == 0 and not self.penalty_pos[0]) or
+             (len(self.penalty_neg) == 0 and not self.penalty_neg[0]))):
+            raise ValueError("The penalty and schedule attribute need "
+                             "to be used in combination. \n Please set "
+                             "the schedule attribute of the flow.")
 
 
 class Bus(on.Bus):

tests/constraint_tests.py

@@ -341,7 +341,7 @@ def test_storage_minimum_invest(self):
                 ep_costs=145, minimum=100, maximum=200))
 
         self.compare_lp_files('storage_invest_minimum.lp')
-        
+
     def test_storage_unbalanced(self):
         """Testing a unbalanced storage (e.g. battery)."""
         bel = solph.Bus(label='electricityBus')
@@ -354,9 +354,9 @@ def test_storage_unbalanced(self):
             initial_storage_level=None,
             balanced=False,
             invest_relation_input_capacity=1,
-            invest_relation_output_capacity=1)    
+            invest_relation_output_capacity=1)
         self.compare_lp_files('storage_unbalanced.lp')
-    
+
     def test_storage_invest_unbalanced(self):
         """Testing a unbalanced storage (e.g. battery)."""
         bel = solph.Bus(label='electricityBus')
@@ -680,3 +680,21 @@ def test_dsm_module_interval(self):
             cost_dsm_down=2,
         )
         self.compare_lp_files('dsm_module_interval.lp')
+
+    def test_flow_schedule(self):
+        """Contraint 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,
+                                      penalty_pos=[0, 800, 900],
+                                      penalty_neg=999,
+                                      schedule=schedule)},
+            conversion_factors={b_th: 1}
+        )
+        self.compare_lp_files('flow_schedule.lp')

tests/lp_files/flow_schedule.lp

@@ -0,0 +1,79 @@
+\* Source Pyomo model name=Model *\
+
+min
+objective:
++999 Flow_slack_neg(boiler_penalty_bus_th_penalty_0)
++999 Flow_slack_neg(boiler_penalty_bus_th_penalty_1)
++999 Flow_slack_neg(boiler_penalty_bus_th_penalty_2)
++800 Flow_slack_pos(boiler_penalty_bus_th_penalty_1)
++900 Flow_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_slack_neg(boiler_penalty_bus_th_penalty_1)
++1 Flow_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_slack_neg(boiler_penalty_bus_th_penalty_2)
++1 Flow_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_slack_pos(boiler_penalty_bus_th_penalty_1) <= +inf
+   0 <= Flow_slack_pos(boiler_penalty_bus_th_penalty_2) <= +inf
+   0 <= Flow_slack_neg(boiler_penalty_bus_th_penalty_0) <= +inf
+   0 <= Flow_slack_neg(boiler_penalty_bus_th_penalty_1) <= +inf
+   0 <= Flow_slack_neg(boiler_penalty_bus_th_penalty_2) <= +inf
+end

tests/test_processing.py

@@ -99,6 +99,8 @@ def test_flows_with_none_exclusion(self):
                     'positive_gradient_costs': 0,
                     'variable_costs': 0,
                     'label': str(b_el2.outputs[demand].label),
+                    'penalty_pos': 0,
+                    'penalty_neg': 0,
                 }
             ).sort_index()
         )
@@ -132,6 +134,9 @@ def test_flows_without_none_exclusion(self):
             'flow': None,
             'values': None,
             'label': str(b_el2.outputs[demand].label),
+            'penalty_pos': 0,
+            'penalty_neg': 0,
+            'schedule': None,
         }
         assert_series_equal(
             param_results[(b_el2, demand)]['scalars'].sort_index(),
@@ -141,7 +146,7 @@ def test_flows_without_none_exclusion(self):
             'actual_value': self.demand_values,
         }
         default_sequences = [
-            'actual_value'
+            'actual_value',
         ]
         for attr in default_sequences:
             if attr not in sequences_attributes: