docs: add device_scheduler page

documentation/concepts/device_scheduler.rst

@@ -0,0 +1,151 @@
+:orphan:
+
+.. _device_scheduler:
+
+Device Scheduler
+===========
+
+Introduction
+--------------
+This generic device scheduler is able to handle an EMS with multiple devices, with various types of constraints on the EMS level and on the device level,
+and with multiple market commitments on the EMS level.
+
+A typical example is a house with many devices. The commitments are assumed to be with regard to the flow of energy to the device (positive for consumption, negative for production). In practice, this generic scheduler is used in the **StorageScheduler** to schedule a storage device.
+
+The solver minimises the costs of deviating from the commitments.
+
+
+
+Notation
+---------
+
+================================ ================================================ ==============================================================================================================  
+Symbol                              Variable in the Code                           Description
+================================ ================================================ ==============================================================================================================  
+:math:`\Delta_{up}(c,j)`              commitment_upwards_deviation                       Upwards deviation from the power commitment of the EMS.
+:math:`\Delta_{down}(c,j)`            commitment_downwards_deviation                     Downward deviation from the power commitment of the EMS.
+:math:`\Delta Stock(d,j)`                           n/a                                  Change of stock of device :math:`d` in the :math:`j` time period.
+:math:`Price_{up}(c,j)`               up_price                                           Price of incurring a upwards deviations in commitment :math:`c` in the :math:`j` time period.
+:math:`Price_{down}(c,j)`             down_price                                         Price of incurring a downward deviations in commitment :math:`c` in the :math:`j` time period.
+:math:`\eta_{up}(d,j)`                device_derivative_up_efficiency                    Upwards conversion efficiency.
+:math:`\eta_{down}(d,j)`              device_derivative_down_efficiency                  Downward conversion efficiency.
+:math:`Stock_{min}(d,j)`              device_min                                         Minium quantity for the Stock of device :math:`d` at time :math:`j`.
+:math:`Stock_{max}(d,j)`              device_max                                         Maximum quantity for the Stock of device :math:`d` at time :math:`j`.
+:math:`\epsilon(d,j)`                 efficiencies                                       Stock energy losses.
+:math:`P_{up}(d,j)`                   device_power_up                                    Upwards power of device :math:`d` at time :math:`j`.
+:math:`P_{down}(d,j)`                 device_power_down                                  Downward power of device :math:`d` at time :math:`j`.
+:math:`P_{max}(d,j)`                  device_derivative_max                              Maximum flow of device :math:`d` at time  :math:`j`.
+:math:`P_{min}(d,j)`                  device_derivative_min                              Minium flow of device :math:`d` at time  :math:`j`.
+:math:`P^{ems}_{min}(j)`              ems_derivative_min                                 Minium flow of the EMS at time  :math:`j`.
+:math:`P^{ems}_{max}(j)`              ems_derivative_max                                 Maximum flow of the EMS :math:`d` at time  :math:`j`.
+:math:`P^{ems}(j)`                    ems_power                                          Aggregated power of all the devices at time :math:`j`.
+:math:`Commitment(c,j)`               commitment_quantity                                Commitments made by the EMS.
+================================ ================================================ ==============================================================================================================  
+
+Cost Function
+--------------
+
+The cost function quantifies the total cost of upwards and downwards deviations from the different commitments.
+
+.. math:: 
+    :name: cost_function
+
+    \min [\sum_{c,j} \Delta _{up}(c,j) \cdot Price_{up}(c,j) +  \Delta_{down}(c,j) \cdot Price_{down}(c,j)]
+
+
+State Dynamics
+---------------
+
+To simplify the description of the model, the auxiliary variable :math:`\Delta Stock(d,j)` is introduced in the documentation. It represents the
+change of :math:`Stock(d,j)`, taking into account conversion efficiencies but not considering the storage losses.
+
+.. math::
+  :name: stock
+
+    \Delta Stock(d,j) = \frac{P_{down}(d,j)}{\eta_{down}(d,j) } + P_{up}(d,j)  \cdot \eta_{up}(d,j)
+
+
+
+.. math:: 
+  :name: device_bounds
+
+    Stock_{min}(d,j)  \leq Stock(d,j) - Stock(d,-1)\leq Stock_{max}(d,j) 
+
+
+Perfect Efficiency
+^^^^^^^^^^^^^^^^^^^
+
+.. math:: 
+  :name: efficiency_e1
+
+    Stock(d, j) = Stock(d, j-1) + \Delta Stock(d,j)
+
+Left Efficiency
+^^^^^^^^^^^^^^^^^
+First apply the stock change, then apply the losses (i.e. the stock changes on the left side of the time interval in which the losses apply)
+
+
+.. math:: 
+  :name: efficiency_left
+
+    Stock(d, j)  = (Stock(d, j-1) + \Delta Stock(d,j)) \cdot \epsilon(d,j)
+
+
+Right Efficiency
+^^^^^^^^^^^^^^^^^
+First apply the losses, then apply the stock change (i.e. the stock changes on the right side of the time interval in which the losses apply)
+
+.. math:: 
+  :name: efficiency_right
+
+    Stock(d, j)  = Stock(d, j-1) \cdot \epsilon(d,j) + \Delta Stock(d,j)
+
+Linear Efficiency
+^^^^^^^^^^^^^^^^^
+Assume the change happens at a constant rate, leading to a linear stock change, and exponential decay, within the current interval
+
+.. math:: 
+  :name: efficiency_linear
+
+    Stock(d, j)  = Stock(d, j-1) \cdot \epsilon(d,j) + \Delta Stock(d,j) \cdot \frac{\epsilon(d,j) - 1}{log(\epsilon(d,j))}
+
+Constraints
+--------------
+
+Device bounds
+^^^^^^^^^^^^^
+
+.. math:: 
+  :name: device_derivative_bounds
+
+    P_{min}(d,j) \leq P_{up}(d,j) + P_{down}(d,j)\leq P_{max}(d,j)
+
+.. math:: 
+  :name: device_down_derivative_bounds
+
+    min(P_{min}(d,j),0) \leq P_{down}(d,j)\leq 0
+
+
+.. math:: 
+  :name: device_up_derivative_bounds
+
+    0 \leq P_{up}(d,j)\leq max(P_{max}(d,j),0)
+
+
+.. math:: 
+  :name: ems_derivative_bounds
+
+    P^{ems}_{min}(j) \leq \sum_d P^{ems}(d,j) \leq P^{ems}_{max}(j)
+
+EMS Power
+^^^^^^^^^^
+
+.. math:: 
+    :name: ems_flow_commitment_equalities
+
+    \sum_d P^{ems}(d,j) = \sum_c Commitment(c,j) + \Delta {up}(c,j) + \Delta {down}(c,j)
+
+.. math:: 
+    :name: device_derivative_equalities
+
+    P^{ems}(d,j) = P_{up}(d,j) + P_{down}(d,j)

documentation/index.rst

@@ -173,6 +173,7 @@ The platform operator of FlexMeasures can be an Aggregator.
     concepts/inbuilt-smart-functionality
     concepts/algorithms
     concepts/security_auth
+    concepts/device_scheduler
 
 
 .. toctree::