topotherm.multiple_timestep
===========================

.. py:module:: topotherm.multiple_timestep

.. autoapi-nested-parse::

   This module contains the optimization models for the multiple-timestep
   district heating network design.

   The module contains the following functions:
       * annuity: Calculate the annuity factor
       * model: Create the optimization model for the multiple time steps operation



Functions
---------

.. autoapisummary::

   topotherm.multiple_timestep.annuity
   topotherm.multiple_timestep.model


Module Contents
---------------

.. py:function:: annuity(c_i, n)

   Calculate the annuity factor.

   :param c_i: Interest rate (as a decimal, e.g. ``0.05`` for 5%).
   :type c_i: float
   :param n: Number of years.
   :type n: float

   :returns: Annuity factor.
   :rtype: float

   .. rubric:: Examples

   Calculate the annuity factor for a 5% interest rate over 10 years:

   >>> annuity(0.05, 10)
   0.129504...

   With a higher interest rate (10%) and the same duration:

   >>> annuity(0.10, 10)
   0.162745...


.. py:function:: model(matrices, sets, regression_inst, regression_losses, economics, optimization_mode)

   Create the optimization model for the thermo-hydraulic system with
   multiple time step operation.

   :param matrices: Matrices of the district heating network with keys
                    ``a_i``, ``a_p``, ``a_c``, ``l_i``, ``position``, ``q_c``.
   :type matrices: dict
   :param sets: Sets for the optimization, obtained from ``matrices``.
   :type sets: dict
   :param regression_inst: Regression coefficients for the thermal capacity.
   :type regression_inst: dict
   :param regression_losses: Regression coefficients for the heat losses.
   :type regression_losses: dict
   :param economics: Economic parameters of the system.
   :type economics: topotherm.settings.Economics
   :param optimization_mode: Optimization mode, either ``'economic'`` for economic optimization
                             or ``'forced'`` for forced operation.
   :type optimization_mode: str

   :returns: Multiple time-step optimization model.
   :rtype: pyo.ConcreteModel