Congestion Rent Calculator¶
CongestionRentCalculator
dataclass
¶
Calculates congestion rents for electricity transmission lines.
Congestion rent is the value that a line captures from the price difference between its two nodes: flow times price spread times the length of the time step.
The calculator handles flows in both directions (up and down). It uses separate sent and received quantities, so transmission losses reduce the rent.
Formulas:
- Congestion rent (up) = granularity × (received_up × price_to - sent_up × price_from)
- Congestion rent (down) = granularity × (received_down × price_from - sent_down × price_to)
- Total congestion rent = congestion_rent_up + congestion_rent_down
Input shapes
All six inputs are Series for one line, or all are DataFrames
with one column per line. The frames have the same columns. All
inputs have the same index. A Series result keeps the name of
the inputs when all inputs have the same name.
Granularity
granularity_hrs is the length of each time step in hours. A
Series has the index of the inputs and applies along the rows,
so each line of a frame gets the same step length per row. A
number applies to all rows. The values of an explicit
granularity_hrs are not checked.
Without granularity_hrs, a DatetimeIndex gives the step length
per day from TimeSeriesGranularityAnalyzer in strict mode. Days
may have different step lengths, for example a day of 60 min steps
and a day of 15 min steps. Mixed step lengths or a missing row
within a day raise GranularityError. An index that is not a
DatetimeIndex gives 1 hour and logs a warning.
A day is the calendar date in the timezone of the index. A caller
that knows the MTU grid passes granularity_hrs. This applies
also to an index in UTC or in naive local time where the MTU
length changes or DST changes: the calendar dates of such an index
do not match the delivery days.
Attributes:
| Name | Type | Description |
|---|---|---|
sent_up |
Series | DataFrame
|
Power sent in up direction at node_from (MW). |
received_up |
Series | DataFrame
|
Power received in up direction at node_to, after losses (MW). |
sent_down |
Series | DataFrame
|
Power sent in down direction at node_to (MW). |
received_down |
Series | DataFrame
|
Power received in down direction at node_from, after losses (MW). |
price_node_from |
Series | DataFrame
|
Price at node_from (€/MWh). |
price_node_to |
Series | DataFrame
|
Price at node_to (€/MWh). |
granularity_hrs |
Series | float | None
|
Step length in hours. Detected from the index if None. |
Raises:
| Type | Description |
|---|---|
TypeError
|
The inputs mix |
ValueError
|
The indices, the columns of the frames, or the index of
a |
GranularityError
|
Auto-detection finds duplicate timestamps, mixed
step lengths within a day, or a day with one row. The message
asks to pass |
Examples:
>>> index = pd.date_range('2024-01-01', periods=2, freq='h')
>>> calculator = CongestionRentCalculator(
... sent_up=pd.Series([100.0, 150.0], index=index),
... received_up=pd.Series([95.0, 142.0], index=index), # 5% losses
... sent_down=pd.Series([0.0, 0.0], index=index),
... received_down=pd.Series([0.0, 0.0], index=index),
... price_node_from=pd.Series([45.0, 50.0], index=index),
... price_node_to=pd.Series([65.0, 70.0], index=index),
... )
>>> calculator.calculate().tolist() # EUR per hour
[1675.0, 2440.0]
Source code in src/mesqual/energy_data_handling/variable_utils/congestion_rent.py
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 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 | |
congestion_rent_up
property
¶
congestion_rent_up: Series | DataFrame
Congestion rent of the flows in up direction (€).
Returns:
| Type | Description |
|---|---|
Series | DataFrame
|
Series, or DataFrame with one column per line. |
congestion_rent_down
property
¶
congestion_rent_down: Series | DataFrame
Congestion rent of the flows in down direction (€).
Returns:
| Type | Description |
|---|---|
Series | DataFrame
|
Series, or DataFrame with one column per line. |
congestion_rent_total
property
¶
congestion_rent_total: Series | DataFrame
Total congestion rent, the sum of up and down direction (€).
Returns:
| Type | Description |
|---|---|
Series | DataFrame
|
Series, or DataFrame with one column per line. |
__post_init__
¶
__post_init__()
Validate the inputs and set the granularity.
Source code in src/mesqual/energy_data_handling/variable_utils/congestion_rent.py
99 100 101 102 103 104 105 106 107 108 109 110 111 | |
calculate
¶
calculate() -> Series | DataFrame
Calculate the total congestion rent (same as congestion_rent_total).
Returns:
| Type | Description |
|---|---|
Series | DataFrame
|
Series, or DataFrame with one column per line, in €. |
Source code in src/mesqual/energy_data_handling/variable_utils/congestion_rent.py
168 169 170 171 172 173 174 | |
from_node_prices
classmethod
¶
from_node_prices(flows: NetworkLineFlowsData, line_model: DataFrame, node_prices: DataFrame, granularity_hrs: Series | float | None = None, node_from_col: str = 'node_from', node_to_col: str = 'node_to') -> CongestionRentCalculator
Build the calculator for all lines from node prices and the line model.
Maps the node prices to the two ends of each line with the columns
node_from_col and node_to_col of the line model. The result has
one column per line in flows.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
flows
|
NetworkLineFlowsData
|
Flows of the lines, one column per line. |
required |
line_model
|
DataFrame
|
Line table indexed by line, with the columns
|
required |
node_prices
|
DataFrame
|
Prices (€/MWh), one column per node, with the index of the flows. |
required |
granularity_hrs
|
Series | float | None
|
Step length in hours. Detected from the index if None. |
None
|
node_from_col
|
str
|
Column of the line model with the node at the start of each line. |
'node_from'
|
node_to_col
|
str
|
Column of the line model with the node at the end of each line. |
'node_to'
|
Returns:
| Type | Description |
|---|---|
CongestionRentCalculator
|
Calculator with one column per line. |
Raises:
| Type | Description |
|---|---|
KeyError
|
A line of |
Examples:
>>> from mesqual.energy_data_handling.network_lines_data import NetworkLineFlowsData
>>> flows = NetworkLineFlowsData.from_net_flow_without_losses(dataset.fetch('Line.Results.flow_sent_net'))
>>> calculator = CongestionRentCalculator.from_node_prices(
... flows, dataset.fetch('Line.Model'), dataset.fetch('Node.Results.price')
... )
>>> calculator.calculate().columns.tolist()
['L1', 'L2', 'L3', 'L4', 'L5']
Source code in src/mesqual/energy_data_handling/variable_utils/congestion_rent.py
176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 | |
from_net_flow_without_losses
classmethod
¶
from_net_flow_without_losses(net_flow: Series | DataFrame, price_node_from: Series | DataFrame, price_node_to: Series | DataFrame, granularity_hrs: Series | float | None = None) -> Series | DataFrame
Calculate congestion rent from net flow data, without losses.
Splits the net flow into up and down direction. Sent equals received in each direction.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
net_flow
|
Series | DataFrame
|
Net flow (MW). Positive is up direction, negative is down direction. |
required |
price_node_from
|
Series | DataFrame
|
Price at node_from (€/MWh). |
required |
price_node_to
|
Series | DataFrame
|
Price at node_to (€/MWh). |
required |
granularity_hrs
|
Series | float | None
|
Step length in hours. Detected from the index if None. |
None
|
Returns:
| Type | Description |
|---|---|
Series | DataFrame
|
Total congestion rent in €, with the shape of |
Examples:
>>> index = pd.date_range('2024-01-01', periods=2, freq='h')
>>> net_flow = pd.Series([100.0, -50.0], index=index)
>>> price_from, price_to = pd.Series([40.0, 40.0], index=index), pd.Series([50.0, 30.0], index=index)
>>> CongestionRentCalculator.from_net_flow_without_losses(net_flow, price_from, price_to).tolist()
[1000.0, 500.0]
Source code in src/mesqual/energy_data_handling/variable_utils/congestion_rent.py
228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 | |
from_up_and_down_flow_without_losses
classmethod
¶
from_up_and_down_flow_without_losses(flow_up: Series | DataFrame, flow_down: Series | DataFrame, price_node_from: Series | DataFrame, price_node_to: Series | DataFrame, granularity_hrs: Series | float | None = None) -> Series | DataFrame
Calculate congestion rent from up and down flows, without losses.
Sent equals received in each direction.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
flow_up
|
Series | DataFrame
|
Flow in up direction (MW, non-negative). |
required |
flow_down
|
Series | DataFrame
|
Flow in down direction (MW, non-negative). |
required |
price_node_from
|
Series | DataFrame
|
Price at node_from (€/MWh). |
required |
price_node_to
|
Series | DataFrame
|
Price at node_to (€/MWh). |
required |
granularity_hrs
|
Series | float | None
|
Step length in hours. Detected from the index if None. |
None
|
Returns:
| Type | Description |
|---|---|
Series | DataFrame
|
Total congestion rent in €, with the shape of |
Examples:
>>> index = pd.date_range('2024-01-01', periods=2, freq='h')
>>> flow_up, flow_down = pd.Series([100.0, 0.0], index=index), pd.Series([0.0, 50.0], index=index)
>>> price_from, price_to = pd.Series([40.0, 40.0], index=index), pd.Series([50.0, 30.0], index=index)
>>> CongestionRentCalculator.from_up_and_down_flow_without_losses(flow_up, flow_down, price_from, price_to).tolist()
[1000.0, 500.0]
Source code in src/mesqual/energy_data_handling/variable_utils/congestion_rent.py
269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 | |