topotherm.postprocessing
========================

.. py:module:: topotherm.postprocessing

.. autoapi-nested-parse::

   Postprocessing of the results from the optimization. This includes the
   calculation of the diameter and mass flow of the pipes, and the elimination of
   unused pipes and nodes.

   Functions
   ---------
   - ``calc_diam_and_velocity`` : Calculate pipe diameter and velocity depending
     on the mass flow and pipe power.
   - ``sts`` : Postprocessing for the single time step model.
   - ``to_networkx_graph`` : Export the postprocessed, optimal district as a
     NetworkX graph.
   - ``mts`` : Postprocessing for the multiple time step model.



Functions
---------

.. autoapisummary::

   topotherm.postprocessing.diameter_and_velocity
   topotherm.postprocessing.calculate_hydraulics
   topotherm.postprocessing.sts
   topotherm.postprocessing.mts
   topotherm.postprocessing.to_networkx_graph
   topotherm.postprocessing.to_dataframe


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

.. py:function:: diameter_and_velocity(v, mass_lin, settings)

   Equations for calculating the diameter and velocity of a pipe based on
   mass flow and power of the pipes

   :param v: Tuple containing the velocity and diameter (``(velocity, diameter)``).
   :type v: tuple of float
   :param mass_lin: Mass flow of the pipe (kg/s).
   :type mass_lin: float
   :param settings: Settings object containing water and piping parameters.
   :type settings: Settings

   :returns: Tuple containing:

             - ``velocity`` : float
                 Calculated velocity of the pipe (m/s).
             - ``diameter`` : float
                 Calculated diameter of the pipe (m).
   :rtype: tuple of float


.. py:function:: calculate_hydraulics(power, settings)

   Calculate mass flow, diameter, and velocity for each pipe given the
   installed thermal power and the supply/return temperatures from ``settings``.

   :param power: Installed thermal power for each pipe.
   :type power: np.ndarray
   :param settings: Settings object containing temperature setpoints and water properties.
   :type settings: Settings

   :returns: Tuple containing:

             - ``mass_flow`` : np.ndarray
                 Mass flow for each pipe (kg/s).
             - ``diameter`` : np.ndarray
                 Pipe diameter (m).
             - ``velocity`` : np.ndarray
                 Flow velocity (m/s).
   :rtype: tuple of np.ndarray


.. py:function:: sts(model, matrices, settings)

   Postprocessing for the single time step model. This includes the
   calculation of the diameter and velocity of the pipes and the elimination
   of unused pipes and nodes.

   :param model: Solved Pyomo model.
   :type model: pyo.ConcreteModel
   :param matrices: Dictionary containing the matrices.
   :type matrices: dict
   :param settings: Settings for the optimization.
   :type settings: tt.settings.Settings

   :returns: Optimal variables and postprocessed data.
   :rtype: dict


.. py:function:: mts(model, matrices, settings)

   Postprocessing for the multiple time step model. This includes the
   calculation of the diameter and velocity of the pipes and the elimination
   of unused pipes and nodes.

   :param model: Solved Pyomo model.
   :type model: pyo.ConcreteModel
   :param matrices: Dictionary containing the matrices.
   :type matrices: dict
   :param settings: Settings for the optimization.
   :type settings: tt.settings.Settings

   :returns: Optimal variables and postprocessed data.
   :rtype: dict


.. py:function:: to_networkx_graph(matrices)

   Convert incidence matrices to a directed NetworkX graph.
   Includes the nodes and edges of the district, their length, and, if
   available, installed diameter, and power.

   :param matrices: Dictionary containing the incidence matrices as output by ``topotherm.postprocessing.sts`` or as input to the model.
   :type matrices: dict

   :returns: NetworkX directed graph.
   :rtype: nx.DiGraph


.. py:function:: to_dataframe(matrices_optimal, matrices_init)

   Export the postprocessed, optimal district as pandas DataFrames.
   Includes the nodes and edges of the district, their length, installed
   diameter, and power.

   :param matrices_optimal: Solved and cleaned matrices as output by
                            ``topotherm.postprocessing.sts``.
   :type matrices_optimal: dict
   :param matrices_init: Original matrices as output by ``topotherm.fileio.load``.
   :type matrices_init: dict

   :returns: * **nodes** (*pd.DataFrame*) -- DataFrame of nodes.
             * **edges** (*pd.DataFrame*) -- DataFrame of edges.