topotherm.simultaneity
======================

.. py:module:: topotherm.simultaneity

.. autoapi-nested-parse::

   Calculate the simultaneity factor of a given graph of the optimal district heating network.



Functions
---------

.. autoapisummary::

   topotherm.simultaneity.calculate
   topotherm.simultaneity.compute_laplacian
   topotherm.simultaneity.resolve_loops
   topotherm.simultaneity.resolve_multi_connections
   topotherm.simultaneity.get_n_end_consumers
   topotherm.simultaneity.calculate_simultaneity_factor
   topotherm.simultaneity.update_data


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

.. py:function:: calculate(graph)

   Calculate the simultaneity factor of a given graph of the optimal district
   heating network.

   Args:
       graph: A NetworkX graph object representing the network.

   Returns:
        nx.DiGraph: A graph containing the simultaneity factors of the graph
        in the attribute 'simultaneity'.


.. py:function:: compute_laplacian(graph)

   Compute the Laplacian matrix of a given graph.

   Args:
       graph: A NetworkX graph object of the solved network connections.

   Returns:
       pd.DataFrame: A pandas DataFrame representing the Laplacian matrix.


.. py:function:: resolve_loops(graph, laplace)

   Resolve loops in the graph and update the Laplacian matrix accordingly.

   Args:
       graph: A NetworkX graph object.
       laplace: The Laplacian matrix of the graph.

   Returns:
       A tuple containing the updated graph and Laplacian matrix.


.. py:function:: resolve_multi_connections(G_copy, laplace)

   Resolves multiple incoming connections for nodes in a directed graph by propagating 'connections' attributes
   and updating the Laplacian matrix accordingly.

   Parameters:
   G_copy: A copy of the directed graph from the previous step.
   laplace: The Laplacian matrix to be updated.

   Returns:
   laplace: Updated Laplacian matrix with modified diagonal elements.


.. py:function:: get_n_end_consumers(graph, laplace)

   Identify and mark end consumers in the graph based on the Laplacian matrix.

   Args:
       graph: A NetworkX graph object.
       laplace: The Laplacian matrix of the graph.

   Returns:
       The graph with 'n_consumers' attributes added to nodes.


.. py:function:: calculate_simultaneity_factor(graph)

   Calculate the simultaneity factor for edges in the graph.

   Args:
       graph: A NetworkX graph object with number of end consumers marked as
       n_consumers attributes.

   Returns:
       nx.DiGraph: A graph that has edge names and values for the
       simultaneity factor


.. py:function:: update_data(df_nodes, df_edges, network)

   Update the edge and node data with simultaneity attributes.

   Args:
       node_data: A DataFrame containing edge data.
       edge_data: A DataFrame containing node data.
       network_simultaneity: A NetworkX graph object with simultaneity factors,
       needs to contain power, simultaneity attributes

   Returns:
       tuple[pd.DataFrame, pd.DataFrame]: Updated edge and node data DataFrames.