Skip to content

Network Lines Data

NetworkLineFlowsData dataclass

Wrapper for bidirectional flow data of network transmission lines.

The four frames hold the flows of the lines in both directions, before and after losses. They have one column per line and the same index.

Flow direction conventions:

  • sent_up: Flow that enters the line at node_from (towards node_to)
  • received_up: Flow that leaves the line at node_to after losses (coming from node_from)
  • sent_down: Flow that enters the line at node_to (towards node_from)
  • received_down: Flow that leaves the line at node_from after losses (coming from node_to)

The distinction between 'sent' and 'received' allows for modeling transmission losses, where received_flow = sent_flow * (1 - loss_rate).

Parameters:

Name Type Description Default
sent_up DataFrame

DataFrame with the flow that enters at node_from

required
received_up DataFrame

DataFrame with the flow received at node_to after losses

required
sent_down DataFrame

DataFrame with the flow that enters at node_to

required
received_down DataFrame

DataFrame with the flow received at node_from after losses

required

Raises:

Type Description
ValueError

If indices or columns of the four DataFrames don't match

Source code in src/mesqual/energy_data_handling/network_lines_data.py
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
@dataclass(eq=False)
class NetworkLineFlowsData:
    """Wrapper for bidirectional flow data of network transmission lines.

    The four frames hold the flows of the lines in both directions, before and
    after losses. They have one column per line and the same index.

    Flow direction conventions:

    - sent_up: Flow that enters the line at node_from (towards node_to)
    - received_up: Flow that leaves the line at node_to after losses (coming from node_from)
    - sent_down: Flow that enters the line at node_to (towards node_from)
    - received_down: Flow that leaves the line at node_from after losses (coming from node_to)

    The distinction between 'sent' and 'received' allows for modeling transmission
    losses, where received_flow = sent_flow * (1 - loss_rate).

    Args:
        sent_up: DataFrame with the flow that enters at node_from
        received_up: DataFrame with the flow received at node_to after losses
        sent_down: DataFrame with the flow that enters at node_to
        received_down: DataFrame with the flow received at node_from after losses

    Raises:
        ValueError: If indices or columns of the four DataFrames don't match
    """

    sent_up: pd.DataFrame
    received_up: pd.DataFrame
    sent_down: pd.DataFrame
    received_down: pd.DataFrame

    def __post_init__(self):
        """Validate that all DataFrames have matching indices and columns.

        Raises:
            ValueError: If any DataFrame has mismatched indices or columns.
        """
        others = {
            'received_up': self.received_up,
            'sent_down': self.sent_down,
            'received_down': self.received_down,
        }
        for name, df in others.items():
            if not self.sent_up.index.equals(df.index):
                raise ValueError(f'Index mismatch: sent_up vs {name}')
            if not self.sent_up.columns.equals(df.columns):
                raise ValueError(f'Columns mismatch: sent_up vs {name}')

    @classmethod
    def from_net_flow_without_losses(cls, net_flow: pd.DataFrame) -> 'NetworkLineFlowsData':
        """Create NetworkLineFlowsData from net line flow data assuming no transmission losses.

        Converts net flow data (where positive values indicate flow in up direction
        and negative values indicate flow in down direction) into the bidirectional
        flow representation used by this class.

        Args:
            net_flow: DataFrame with net flow values. Positive = up direction,
                negative = down direction

        Returns:
            NetworkLineFlowsData instance with flows split into up/down directions

        Examples:
            >>> flows = NetworkLineFlowsData.from_net_flow_without_losses(pd.DataFrame({'L1': [100.0, -50.0]}))
            >>> flows.sent_up['L1'].tolist(), flows.sent_down['L1'].tolist()
            ([100.0, 0.0], [-0.0, 50.0])
        """
        positive_flow = net_flow.clip(lower=0)
        negative_flow = -net_flow.clip(upper=0)

        return cls(
            sent_up=positive_flow, received_up=positive_flow, sent_down=negative_flow, received_down=negative_flow
        )

    @classmethod
    def from_nodal_net_injection(
        cls, node_a_net_injection: pd.DataFrame, node_b_net_injection: pd.DataFrame
    ) -> 'NetworkLineFlowsData':
        """Create NetworkLineFlowsData from nodal net-injection data.

        Converts nodal net-injection data (where positive values indicate flow from node towards line (injection)
        and negative values indicate flow from line towards node (ejection)) into the bidirectional
        flow representation used by this class. Automatically computes losses.
        Node_A refers to the topological "node_from" and
        Node_B to the topological "node_to" in the definition of the lines.

        Args:
            node_a_net_injection: DataFrame with net injection at Node_A.
                positive = injection, negative = ejection
            node_b_net_injection: DataFrame with net injection at Node_B.
                positive = injection, negative = ejection

        Returns:
            NetworkLineFlowsData instance with flows split into up/down directions

        Examples:
            >>> flows = NetworkLineFlowsData.from_nodal_net_injection(
            ...     pd.DataFrame({'L1': [100.0, -49.0]}), pd.DataFrame({'L1': [-98.0, 50.0]})
            ... )
            >>> flows.sent_up['L1'].tolist(), flows.received_up['L1'].tolist()  # 2 MW losses in the first step
            ([100.0, 0.0], [98.0, -0.0])
        """

        return cls(
            sent_up=node_a_net_injection.clip(0),
            received_up=-1 * node_b_net_injection.clip(None, 0),
            sent_down=node_b_net_injection.clip(0),
            received_down=-1 * node_a_net_injection.clip(None, 0),
        )

    @classmethod
    def from_up_and_down_flow_without_losses(
        cls, flow_up: pd.DataFrame, flow_down: pd.DataFrame
    ) -> 'NetworkLineFlowsData':
        """Create NetworkLineFlowsData from separate up and down flow data without losses.

        This constructor assumes that there are no transmission losses, so sent and
        received flows are identical in each direction.

        Args:
            flow_up: DataFrame with flow data in up direction (node_from -> node_to)
            flow_down: DataFrame with flow data in down direction (node_to -> node_from)

        Returns:
            NetworkLineFlowsData instance where sent and received flows are equal

        Examples:
            >>> flows = NetworkLineFlowsData.from_up_and_down_flow_without_losses(
            ...     pd.DataFrame({'L1': [100.0, 80.0]}), pd.DataFrame({'L1': [50.0, 60.0]})
            ... )
            >>> flows.received_down['L1'].tolist()
            [50.0, 60.0]
        """
        return cls(sent_up=flow_up, received_up=flow_up, sent_down=flow_down, received_down=flow_down)

__post_init__

__post_init__()

Validate that all DataFrames have matching indices and columns.

Raises:

Type Description
ValueError

If any DataFrame has mismatched indices or columns.

Source code in src/mesqual/energy_data_handling/network_lines_data.py
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
def __post_init__(self):
    """Validate that all DataFrames have matching indices and columns.

    Raises:
        ValueError: If any DataFrame has mismatched indices or columns.
    """
    others = {
        'received_up': self.received_up,
        'sent_down': self.sent_down,
        'received_down': self.received_down,
    }
    for name, df in others.items():
        if not self.sent_up.index.equals(df.index):
            raise ValueError(f'Index mismatch: sent_up vs {name}')
        if not self.sent_up.columns.equals(df.columns):
            raise ValueError(f'Columns mismatch: sent_up vs {name}')

from_net_flow_without_losses classmethod

from_net_flow_without_losses(net_flow: DataFrame) -> NetworkLineFlowsData

Create NetworkLineFlowsData from net line flow data assuming no transmission losses.

Converts net flow data (where positive values indicate flow in up direction and negative values indicate flow in down direction) into the bidirectional flow representation used by this class.

Parameters:

Name Type Description Default
net_flow DataFrame

DataFrame with net flow values. Positive = up direction, negative = down direction

required

Returns:

Type Description
NetworkLineFlowsData

NetworkLineFlowsData instance with flows split into up/down directions

Examples:

>>> flows = NetworkLineFlowsData.from_net_flow_without_losses(pd.DataFrame({'L1': [100.0, -50.0]}))
>>> flows.sent_up['L1'].tolist(), flows.sent_down['L1'].tolist()
([100.0, 0.0], [-0.0, 50.0])
Source code in src/mesqual/energy_data_handling/network_lines_data.py
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
@classmethod
def from_net_flow_without_losses(cls, net_flow: pd.DataFrame) -> 'NetworkLineFlowsData':
    """Create NetworkLineFlowsData from net line flow data assuming no transmission losses.

    Converts net flow data (where positive values indicate flow in up direction
    and negative values indicate flow in down direction) into the bidirectional
    flow representation used by this class.

    Args:
        net_flow: DataFrame with net flow values. Positive = up direction,
            negative = down direction

    Returns:
        NetworkLineFlowsData instance with flows split into up/down directions

    Examples:
        >>> flows = NetworkLineFlowsData.from_net_flow_without_losses(pd.DataFrame({'L1': [100.0, -50.0]}))
        >>> flows.sent_up['L1'].tolist(), flows.sent_down['L1'].tolist()
        ([100.0, 0.0], [-0.0, 50.0])
    """
    positive_flow = net_flow.clip(lower=0)
    negative_flow = -net_flow.clip(upper=0)

    return cls(
        sent_up=positive_flow, received_up=positive_flow, sent_down=negative_flow, received_down=negative_flow
    )

from_nodal_net_injection classmethod

from_nodal_net_injection(node_a_net_injection: DataFrame, node_b_net_injection: DataFrame) -> NetworkLineFlowsData

Create NetworkLineFlowsData from nodal net-injection data.

Converts nodal net-injection data (where positive values indicate flow from node towards line (injection) and negative values indicate flow from line towards node (ejection)) into the bidirectional flow representation used by this class. Automatically computes losses. Node_A refers to the topological "node_from" and Node_B to the topological "node_to" in the definition of the lines.

Parameters:

Name Type Description Default
node_a_net_injection DataFrame

DataFrame with net injection at Node_A. positive = injection, negative = ejection

required
node_b_net_injection DataFrame

DataFrame with net injection at Node_B. positive = injection, negative = ejection

required

Returns:

Type Description
NetworkLineFlowsData

NetworkLineFlowsData instance with flows split into up/down directions

Examples:

>>> flows = NetworkLineFlowsData.from_nodal_net_injection(
...     pd.DataFrame({'L1': [100.0, -49.0]}), pd.DataFrame({'L1': [-98.0, 50.0]})
... )
>>> flows.sent_up['L1'].tolist(), flows.received_up['L1'].tolist()  # 2 MW losses in the first step
([100.0, 0.0], [98.0, -0.0])
Source code in src/mesqual/energy_data_handling/network_lines_data.py
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
@classmethod
def from_nodal_net_injection(
    cls, node_a_net_injection: pd.DataFrame, node_b_net_injection: pd.DataFrame
) -> 'NetworkLineFlowsData':
    """Create NetworkLineFlowsData from nodal net-injection data.

    Converts nodal net-injection data (where positive values indicate flow from node towards line (injection)
    and negative values indicate flow from line towards node (ejection)) into the bidirectional
    flow representation used by this class. Automatically computes losses.
    Node_A refers to the topological "node_from" and
    Node_B to the topological "node_to" in the definition of the lines.

    Args:
        node_a_net_injection: DataFrame with net injection at Node_A.
            positive = injection, negative = ejection
        node_b_net_injection: DataFrame with net injection at Node_B.
            positive = injection, negative = ejection

    Returns:
        NetworkLineFlowsData instance with flows split into up/down directions

    Examples:
        >>> flows = NetworkLineFlowsData.from_nodal_net_injection(
        ...     pd.DataFrame({'L1': [100.0, -49.0]}), pd.DataFrame({'L1': [-98.0, 50.0]})
        ... )
        >>> flows.sent_up['L1'].tolist(), flows.received_up['L1'].tolist()  # 2 MW losses in the first step
        ([100.0, 0.0], [98.0, -0.0])
    """

    return cls(
        sent_up=node_a_net_injection.clip(0),
        received_up=-1 * node_b_net_injection.clip(None, 0),
        sent_down=node_b_net_injection.clip(0),
        received_down=-1 * node_a_net_injection.clip(None, 0),
    )

from_up_and_down_flow_without_losses classmethod

from_up_and_down_flow_without_losses(flow_up: DataFrame, flow_down: DataFrame) -> NetworkLineFlowsData

Create NetworkLineFlowsData from separate up and down flow data without losses.

This constructor assumes that there are no transmission losses, so sent and received flows are identical in each direction.

Parameters:

Name Type Description Default
flow_up DataFrame

DataFrame with flow data in up direction (node_from -> node_to)

required
flow_down DataFrame

DataFrame with flow data in down direction (node_to -> node_from)

required

Returns:

Type Description
NetworkLineFlowsData

NetworkLineFlowsData instance where sent and received flows are equal

Examples:

>>> flows = NetworkLineFlowsData.from_up_and_down_flow_without_losses(
...     pd.DataFrame({'L1': [100.0, 80.0]}), pd.DataFrame({'L1': [50.0, 60.0]})
... )
>>> flows.received_down['L1'].tolist()
[50.0, 60.0]
Source code in src/mesqual/energy_data_handling/network_lines_data.py
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
@classmethod
def from_up_and_down_flow_without_losses(
    cls, flow_up: pd.DataFrame, flow_down: pd.DataFrame
) -> 'NetworkLineFlowsData':
    """Create NetworkLineFlowsData from separate up and down flow data without losses.

    This constructor assumes that there are no transmission losses, so sent and
    received flows are identical in each direction.

    Args:
        flow_up: DataFrame with flow data in up direction (node_from -> node_to)
        flow_down: DataFrame with flow data in down direction (node_to -> node_from)

    Returns:
        NetworkLineFlowsData instance where sent and received flows are equal

    Examples:
        >>> flows = NetworkLineFlowsData.from_up_and_down_flow_without_losses(
        ...     pd.DataFrame({'L1': [100.0, 80.0]}), pd.DataFrame({'L1': [50.0, 60.0]})
        ... )
        >>> flows.received_down['L1'].tolist()
        [50.0, 60.0]
    """
    return cls(sent_up=flow_up, received_up=flow_up, sent_down=flow_down, received_down=flow_down)