eptr2 1.4.1.dev0__tar.gz → 1.4.1.dev1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/PKG-INFO +1 -1
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/pyproject.toml +1 -1
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/eptr2_api_schema.json +1 -1
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-imbalance-costs/SKILL.md +2 -2
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/plant_costs.py +27 -1
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/price_and_cost.py +2 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/main.py +12 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/mcp/server.py +3 -1
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/util/costs.py +289 -90
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/LICENSE +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/README.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/docs/assets/README.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/examples/README.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/pyproject.toml +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/src/eptr2/mcp/README.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/tutorials/README.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/tutorials/pyproject.toml +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.gitignore +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/LICENSE +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/README.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/docs/assets/README.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/examples/README.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/__init__.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/__main__.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/agentic/__init__.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/agentic/discovery.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/agentic/schema.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/agentic/skills.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/agentic/validation.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/__init__.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/mcp.json +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/plugin.json +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-api-discovery/SKILL.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-api-discovery/endpoint-categories.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-api-discovery/scripts/list_endpoints.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-consumption-data/SKILL.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-consumption-data/examples.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-convenience-wrappers/SKILL.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-generation-tracking/SKILL.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-generation-tracking/examples.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-imbalance-costs/examples.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-imbalance-costs/formulas.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-market-operations/SKILL.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-market-operations/examples.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-price-analysis/SKILL.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-price-analysis/api-reference.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-price-analysis/examples.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/__init__.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/ancillary.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/bilateral.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/bpm.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/consumption.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/dam.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/dams.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/general.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/generation.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/idm.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/imbalance.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/mms.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/ng_general.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/ng_sgp.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/ng_transmission.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/ng_vgp.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/renewables.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/reporting.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/retroactive.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/transmission.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/vep.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/yek_g.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/cli.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/__init__.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/ancillary.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/bpm.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/consumption.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/dabi_idm.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/idm_log.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/ids.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/mms.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/org_activity.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/periodic_orgs.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/production.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/mapping/__init__.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/mapping/checks.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/mapping/help.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/mapping/parameters.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/mapping/path.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/mapping/processing.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/mcp/README.md +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/mcp/__init__.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/processing/__init__.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/processing/postprocess/__init__.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/processing/postprocess/items.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/processing/preprocess/__init__.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/processing/preprocess/calls.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/processing/preprocess/params.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/util/__init__.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/util/certificate.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/util/evaluation.py +0 -0
- {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/util/time.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: eptr2
|
|
3
|
-
Version: 1.4.1.
|
|
3
|
+
Version: 1.4.1.dev1
|
|
4
4
|
Summary: EPIAS Transparency Platform v2.0 Python client by Robokami / Tideseed
|
|
5
5
|
Project-URL: Homepage, https://github.com/Tideseed/eptr2
|
|
6
6
|
Project-URL: Documentation, https://tideseed.github.io/eptr2/
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "eptr2"
|
|
3
|
-
version = "1.4.1.
|
|
3
|
+
version = "1.4.1.dev1"
|
|
4
4
|
description = "EPIAS Transparency Platform v2.0 Python client by Robokami / Tideseed"
|
|
5
5
|
authors = [{ name = "Tideseed", email = "info@tideseed.com" }]
|
|
6
6
|
license = { text = "Apache License 2.0" }
|
|
@@ -4785,7 +4785,7 @@
|
|
|
4785
4785
|
"url": "https://seffaflik.epias.com.tr/electricity/electricity-transmission/zero-balance-adjustment/monthly-zero-balance-adjustment"
|
|
4786
4786
|
}
|
|
4787
4787
|
},
|
|
4788
|
-
"eptr2_version": "1.4.1.
|
|
4788
|
+
"eptr2_version": "1.4.1.dev1",
|
|
4789
4789
|
"schema_format_version": "2.0",
|
|
4790
4790
|
"usage": {
|
|
4791
4791
|
"cli": "eptr2 call <key> --start-date ... --end-date ...",
|
{eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-imbalance-costs/SKILL.md
RENAMED
|
@@ -5,7 +5,7 @@ description: Calculate Turkish electricity imbalance and KÜPST deviation costs
|
|
|
5
5
|
|
|
6
6
|
# Imbalance and KÜPST costs
|
|
7
7
|
|
|
8
|
-
Use contract-aware utilities for historical analysis. The library distinguishes regulation periods (`pre_2026`, `26_01` from 2026-01-01, `26_02` from 2026-11-01); do not apply a timeless 3% margin or one tolerance to a range crossing a rule boundary. Functions called without a contract use the newest parameters (`regulation_period="current"`); pass a contract or a period label to reproduce a specific period.
|
|
8
|
+
Use contract-aware utilities for historical analysis. The library distinguishes regulation periods (`pre_2026`, `26_01` from 2026-01-01, `26_02` from 2026-11-01, `27_01` from 2027-01-01); do not apply a timeless 3% margin or one tolerance to a range crossing a rule boundary. Functions called without a contract use the newest parameters (`regulation_period="current"`); pass a contract or a period label to reproduce a specific period.
|
|
9
9
|
|
|
10
10
|
```python
|
|
11
11
|
from eptr2.util.costs import calculate_unit_price_and_costs_by_contract
|
|
@@ -17,7 +17,7 @@ costs = calculate_unit_price_and_costs_by_contract(
|
|
|
17
17
|
print(costs)
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
For ranges or plant data, prefer the main functions: they resolve floor/ceiling, V, B, margins and KÜPST tolerance and multiplier (by category) for each hour, and fetch MCP, SMP and `systemStatus` when `prices` is not given. Where EPİAŞ's published imbalance prices are available (fetched rows, or `positiveImbalance` / `negativeImbalance` in `prices`) they are used, and `imb_price_source` says `published`; otherwise the prices are calculated. Hours without SMP (the rest of the current day, future hours) are skipped with a warning; pass `prices` with an SMP scenario to price them. KÜPST unit cost is always calculated. Pass `include_calculated=True` to also get the calculated prices for a check against the published ones.
|
|
20
|
+
For ranges or plant data, prefer the main functions: they resolve floor/ceiling, V, B, margins and KÜPST tolerance and multiplier (by category) for each hour, and fetch MCP, SMP and `systemStatus` when `prices` is not given. Where EPİAŞ's published imbalance prices are available (fetched rows, or `positiveImbalance` / `negativeImbalance` in `prices`) they are used, and `imb_price_source` says `published`; otherwise the prices are calculated. Hours without SMP (the rest of the current day, future hours) are skipped with a warning; pass `prices` with an SMP scenario to price them. KÜPST unit cost is always calculated. Storage categories differ: a plant with storage ("depolamalı üretim tesisi") is `plant_w_battery` (tolerance 0.05, multiplier 0.10), standalone storage is `battery`, and a plant with an integrated storage unit ("bütünleşik depolama ünitesi") uses its main source's tolerance, so pass its main source (e.g. `"Rüzgar"`); names like "RES+BESS" resolve to `plant_w_battery`. Hydro, geothermal and biomass are `other_renewable` (tolerance and multiplier of other sources, maintenance multiplier from 30 fault entries like wind and solar; other sources from 25). From 2027-01-01 consumption units pay KÜPST too: pass `is_producer=False` with category `consumption_art17` (tolerance 0.75) or `consumption_other` (0.30); before 2027 consumers have no KÜPST. Pass `include_calculated=True` to also get the calculated prices for a check against the published ones.
|
|
21
21
|
|
|
22
22
|
```python
|
|
23
23
|
from eptr2.util.costs import calculate_imbalance_costs
|
|
@@ -189,7 +189,7 @@ def calculate_portfolio_costs(
|
|
|
189
189
|
For a given portfolio (e.g. an aggregator) of power plants, this function calculates the overall imbalance and kupst costs based on provided production data. There are some caveats to consider.
|
|
190
190
|
|
|
191
191
|
+ This function is suitable for only production/generation portfolios (not consumption). If your portfolio includes consumption units, results will be inaccurate.
|
|
192
|
-
+ KUPST
|
|
192
|
+
+ KUPST tolerance and multiplier follow each plant's 'source' column of id_df (see normalize_kupst_category). Aggregator rules (communities as a balancing unit, capacity-weighted tolerance under Article 4 of EPDK Decisions 14029 and 14907) are not covered here.
|
|
193
193
|
+ Your portfolio does not have to be an aggregator but calculations resemble those of an aggregator. You can use this function to estimate costs for potential aggregators.
|
|
194
194
|
"""
|
|
195
195
|
#####
|
|
@@ -287,6 +287,7 @@ def calculate_portfolio_costs(
|
|
|
287
287
|
else:
|
|
288
288
|
sub_df["actual"] = sub_df["total_rt"]
|
|
289
289
|
|
|
290
|
+
sub_df["kupst_source"] = row.get("source", "other")
|
|
290
291
|
sub_df["da_forecast"] = sub_df["toplam_kgup_v1"]
|
|
291
292
|
sub_df["forecast"] = sub_df[f"toplam_{forecast_source}"]
|
|
292
293
|
## Negative means underproduction, negative imbalance
|
|
@@ -333,6 +334,7 @@ def calculate_portfolio_costs(
|
|
|
333
334
|
"contract",
|
|
334
335
|
"plant_name",
|
|
335
336
|
"uevcb_id",
|
|
337
|
+
"kupst_source",
|
|
336
338
|
"da_forecast",
|
|
337
339
|
"forecast",
|
|
338
340
|
"actual",
|
|
@@ -399,6 +401,8 @@ def calculate_portfolio_costs(
|
|
|
399
401
|
cost_df[
|
|
400
402
|
[
|
|
401
403
|
"contract",
|
|
404
|
+
"mcp",
|
|
405
|
+
"smp",
|
|
402
406
|
"sd_sign",
|
|
403
407
|
"unit_pos_imb_cost",
|
|
404
408
|
"unit_neg_imb_cost",
|
|
@@ -409,6 +413,28 @@ def calculate_portfolio_costs(
|
|
|
409
413
|
how="left",
|
|
410
414
|
)
|
|
411
415
|
|
|
416
|
+
## The KUPST multiplier depends on each plant's category (e.g. 0.10 for a
|
|
417
|
+
## plant with storage, 0.02 for transmission-connected unlicensed), so the
|
|
418
|
+
## unit cost of the price data (category 'other') is recalculated per plant.
|
|
419
|
+
## Pre-2026 contracts keep it.
|
|
420
|
+
def _plant_unit_kupst_cost(row):
|
|
421
|
+
kupst_d = get_kupst_params_by_contract(
|
|
422
|
+
None if use_latest_regulation else row["contract"],
|
|
423
|
+
category=row["kupst_source"],
|
|
424
|
+
)
|
|
425
|
+
if kupst_d is None or pd.isna(row["mcp"]) or pd.isna(row["smp"]):
|
|
426
|
+
return row["unit_kupst_cost"]
|
|
427
|
+
return calculate_unit_kupst_cost(
|
|
428
|
+
mcp=row["mcp"],
|
|
429
|
+
smp=row["smp"],
|
|
430
|
+
kupst_multiplier=kupst_d["multiplier"],
|
|
431
|
+
kupst_floor_price=kupst_d["floor_price"],
|
|
432
|
+
)
|
|
433
|
+
|
|
434
|
+
plan_realized_w_costs_df["unit_kupst_cost"] = plan_realized_w_costs_df.apply(
|
|
435
|
+
_plant_unit_kupst_cost, axis=1
|
|
436
|
+
)
|
|
437
|
+
|
|
412
438
|
# plan_realized_w_costs_df["kupsm_da"] = plan_realized_w_costs_df.apply(
|
|
413
439
|
# lambda row: calculate_kupsm(
|
|
414
440
|
# actual=row["actual"],
|
|
@@ -54,11 +54,13 @@ def get_hourly_price_and_cost_data(
|
|
|
54
54
|
if verbose:
|
|
55
55
|
logger.info("Getting MCP, SMP and imbalance price data...")
|
|
56
56
|
|
|
57
|
+
## One row per hour: EPİAŞ returned every hour of 2026-11-01 twice
|
|
57
58
|
price_df = eptr.call(
|
|
58
59
|
"mcp-smp-imb",
|
|
59
60
|
start_date=start_date,
|
|
60
61
|
end_date=end_date,
|
|
61
62
|
request_kwargs={"timeout": timeout},
|
|
63
|
+
drop_duplicates=True,
|
|
62
64
|
**retry_kwargs,
|
|
63
65
|
)
|
|
64
66
|
|
|
@@ -373,6 +373,8 @@ class EPTR2:
|
|
|
373
373
|
def call(self, key: str, **kwargs):
|
|
374
374
|
"""
|
|
375
375
|
Main call function for the API. This function is used to process parameters and make calls to EPIAS Transparency API.
|
|
376
|
+
|
|
377
|
+
drop_duplicates=True drops rows that are identical in every column from the DataFrame (postprocessed results only), e.g. EPİAŞ's mcp-smp-imb returned every hour of 2026-11-01 twice. Default False: the data is returned as EPİAŞ sends it.
|
|
376
378
|
"""
|
|
377
379
|
|
|
378
380
|
self.check_renew_tgt(**kwargs)
|
|
@@ -532,6 +534,15 @@ class EPTR2:
|
|
|
532
534
|
from eptr2.mapping.processing import get_postprocess_function
|
|
533
535
|
|
|
534
536
|
df = get_postprocess_function(key)(res, key=key)
|
|
537
|
+
if kwargs.get("drop_duplicates", False) and hasattr(df, "drop_duplicates"):
|
|
538
|
+
n_rows = len(df)
|
|
539
|
+
df = df.drop_duplicates().reset_index(drop=True)
|
|
540
|
+
if len(df) < n_rows:
|
|
541
|
+
logger.warning(
|
|
542
|
+
"%s: dropped %d duplicate row(s) returned by EPİAŞ.",
|
|
543
|
+
key,
|
|
544
|
+
n_rows - len(df),
|
|
545
|
+
)
|
|
535
546
|
return df
|
|
536
547
|
|
|
537
548
|
return res
|
|
@@ -613,6 +624,7 @@ RESERVED_CALL_OPTIONS = frozenset(
|
|
|
613
624
|
"connect_timeout",
|
|
614
625
|
"credentials_file_path",
|
|
615
626
|
"custom_aliases",
|
|
627
|
+
"drop_duplicates",
|
|
616
628
|
"force_renew_tgt",
|
|
617
629
|
"get_raw_response",
|
|
618
630
|
"is_test",
|
|
@@ -203,7 +203,9 @@ if MCP_AVAILABLE:
|
|
|
203
203
|
def get_imbalance_price(start_date: str, end_date: str) -> str:
|
|
204
204
|
"""Get electricity imbalance prices (positive and negative)."""
|
|
205
205
|
client = _get_eptr_client()
|
|
206
|
-
result = client.call(
|
|
206
|
+
result = client.call(
|
|
207
|
+
"mcp-smp-imb", start_date=start_date, end_date=end_date, drop_duplicates=True
|
|
208
|
+
)
|
|
207
209
|
return _format_result(result)
|
|
208
210
|
|
|
209
211
|
@mcp.tool()
|
|
@@ -44,25 +44,118 @@ def get_time_regulation_params_map():
|
|
|
44
44
|
|
|
45
45
|
## Categories without a 'multiplier_maintenance' have no maintenance
|
|
46
46
|
## multiplier; the plain multiplier applies even with the penalty flag.
|
|
47
|
+
## EPDK Decision 14029 (11/12/2025, RG 29/12/2025 No. 33122), in force
|
|
48
|
+
## 2026-01-01: multipliers in Article 2, tolerances in Article 3.
|
|
47
49
|
def _kupst_2026_01():
|
|
48
|
-
rate = {"multiplier": 0.05, "multiplier_maintenance": 0.08}
|
|
49
50
|
return {
|
|
50
|
-
|
|
51
|
-
"
|
|
52
|
-
|
|
53
|
-
|
|
51
|
+
## Rüzgar (renewable: maintenance multiplier from 30 fault entries)
|
|
52
|
+
"wind": {
|
|
53
|
+
"tolerance": 0.15,
|
|
54
|
+
"multiplier": 0.05,
|
|
55
|
+
"multiplier_maintenance": 0.08,
|
|
56
|
+
"maintenance_fault_threshold": 30,
|
|
57
|
+
},
|
|
58
|
+
## Güneş
|
|
59
|
+
"solar": {
|
|
60
|
+
"tolerance": 0.08,
|
|
61
|
+
"multiplier": 0.05,
|
|
62
|
+
"multiplier_maintenance": 0.08,
|
|
63
|
+
"maintenance_fault_threshold": 30,
|
|
64
|
+
},
|
|
65
|
+
## Depolamalı elektrik üretim tesisleri
|
|
66
|
+
"plant_w_battery": {"tolerance": 0.05, "multiplier": 0.10},
|
|
67
|
+
## Diğer kaynaklar
|
|
68
|
+
"other": {
|
|
69
|
+
"tolerance": 0.05,
|
|
70
|
+
"multiplier": 0.05,
|
|
71
|
+
"multiplier_maintenance": 0.08,
|
|
72
|
+
"maintenance_fault_threshold": 25,
|
|
73
|
+
},
|
|
74
|
+
## Other renewables (hydro, geothermal, biomass, ...): tolerance of
|
|
75
|
+
## "Diğer kaynaklar", fault threshold of "Yenilenebilir enerji kaynakları"
|
|
76
|
+
"other_renewable": {
|
|
77
|
+
"tolerance": 0.05,
|
|
78
|
+
"multiplier": 0.05,
|
|
79
|
+
"multiplier_maintenance": 0.08,
|
|
80
|
+
"maintenance_fault_threshold": 30,
|
|
81
|
+
},
|
|
82
|
+
## İletim sisteminden bağlı lisanssız santraller, santral bazında
|
|
83
|
+
"unlicensed_from_transmission": {"tolerance": 0.20, "multiplier": 0.02},
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
## EPDK Decision 14907 (24/09/2026, RG 19/10/2026 No. 33405), in force from
|
|
87
|
+
## the billing period after publication (2026-11-01). Article 2 and 3.
|
|
88
|
+
def _kupst_2026_02():
|
|
89
|
+
return {
|
|
90
|
+
## Rüzgar
|
|
91
|
+
"wind": {
|
|
92
|
+
"tolerance": 0.15,
|
|
93
|
+
"multiplier": 0.05,
|
|
94
|
+
"multiplier_maintenance": 0.08,
|
|
95
|
+
"maintenance_fault_threshold": 30,
|
|
96
|
+
},
|
|
97
|
+
## Güneş
|
|
98
|
+
"solar": {
|
|
99
|
+
"tolerance": 0.08,
|
|
100
|
+
"multiplier": 0.05,
|
|
101
|
+
"multiplier_maintenance": 0.08,
|
|
102
|
+
"maintenance_fault_threshold": 30,
|
|
103
|
+
},
|
|
104
|
+
## Depolamalı elektrik üretim tesisi
|
|
105
|
+
"plant_w_battery": {"tolerance": 0.05, "multiplier": 0.10},
|
|
106
|
+
## Diğer kaynaklar
|
|
107
|
+
"other": {
|
|
108
|
+
"tolerance": 0.05,
|
|
109
|
+
"multiplier": 0.05,
|
|
110
|
+
"multiplier_maintenance": 0.08,
|
|
111
|
+
"maintenance_fault_threshold": 25,
|
|
112
|
+
},
|
|
113
|
+
## Other renewables, as in _kupst_2026_01
|
|
114
|
+
"other_renewable": {
|
|
115
|
+
"tolerance": 0.05,
|
|
116
|
+
"multiplier": 0.05,
|
|
117
|
+
"multiplier_maintenance": 0.08,
|
|
118
|
+
"maintenance_fault_threshold": 30,
|
|
119
|
+
},
|
|
120
|
+
## İletime bağlı lisanssız, santral bazında
|
|
121
|
+
"unlicensed_from_transmission": {"tolerance": 0.20, "multiplier": 0.02},
|
|
122
|
+
## Dağıtıma bağlı lisanssız, katılımcı bazında
|
|
123
|
+
"unlicensed_from_distribution": {"tolerance": 0.25, "multiplier": 0.01},
|
|
124
|
+
## Müstakil depolama
|
|
125
|
+
"battery": {"tolerance": 0.20, "multiplier": 0.02},
|
|
54
126
|
}
|
|
55
127
|
|
|
56
128
|
map_l = [
|
|
129
|
+
{
|
|
130
|
+
## Consumption settlement units get KUPST from 2027-01-01
|
|
131
|
+
## (Decision 14907, Provisional Article 1): n = 0.01 (Article 2 e),
|
|
132
|
+
## tolerance 0.75 for withdrawal units under DUY Article 17(2)
|
|
133
|
+
## (a)-(ç) and 0.30 for other consumption (Article 3 g, ğ).
|
|
134
|
+
## Production values are unchanged from 26_02.
|
|
135
|
+
"date": "2027-01-01",
|
|
136
|
+
"period": "27_01",
|
|
137
|
+
"V": 100,
|
|
138
|
+
"B": 100,
|
|
139
|
+
"low_margin": 0.03,
|
|
140
|
+
"high_margin": 0.06,
|
|
141
|
+
"ceil_margin": 0.05,
|
|
142
|
+
"dsg_tolerance": 0.05,
|
|
143
|
+
"kupst_floor_price": 750.0,
|
|
144
|
+
"kupst": {
|
|
145
|
+
**_kupst_2026_02(),
|
|
146
|
+
"consumption_art17": {"tolerance": 0.75, "multiplier": 0.01},
|
|
147
|
+
"consumption_other": {"tolerance": 0.30, "multiplier": 0.01},
|
|
148
|
+
},
|
|
149
|
+
},
|
|
57
150
|
{
|
|
58
151
|
## V lowered from 150 to 100 and KUPST multipliers and tolerances
|
|
59
152
|
## set per category, effective from the first delivery hour of
|
|
60
|
-
## 2026-11-01
|
|
61
|
-
##
|
|
62
|
-
##
|
|
63
|
-
##
|
|
64
|
-
## Consumption unit categories of
|
|
65
|
-
##
|
|
153
|
+
## 2026-11-01 (the billing period after publication).
|
|
154
|
+
## Sources: EPDK Decision 14907 (KÜPSM/KÜPST coefficients, replaces
|
|
155
|
+
## 14029) and Decision 14911 (V = 100 TL/MWh), both 24/09/2026,
|
|
156
|
+
## RG 19/10/2026 No. 33405.
|
|
157
|
+
## Consumption unit categories of 14907 start on 2027-01-01
|
|
158
|
+
## (Provisional Article 1): see the 27_01 row.
|
|
66
159
|
"date": "2026-11-01",
|
|
67
160
|
"period": "26_02",
|
|
68
161
|
"V": 100,
|
|
@@ -72,37 +165,7 @@ def get_time_regulation_params_map():
|
|
|
72
165
|
"ceil_margin": 0.05,
|
|
73
166
|
"dsg_tolerance": 0.05,
|
|
74
167
|
"kupst_floor_price": 750.0,
|
|
75
|
-
"kupst":
|
|
76
|
-
## Rüzgar
|
|
77
|
-
"wind": {
|
|
78
|
-
"tolerance": 0.15,
|
|
79
|
-
"multiplier": 0.05,
|
|
80
|
-
"multiplier_maintenance": 0.08,
|
|
81
|
-
"maintenance_fault_threshold": 30,
|
|
82
|
-
},
|
|
83
|
-
## Güneş
|
|
84
|
-
"solar": {
|
|
85
|
-
"tolerance": 0.08,
|
|
86
|
-
"multiplier": 0.05,
|
|
87
|
-
"multiplier_maintenance": 0.08,
|
|
88
|
-
"maintenance_fault_threshold": 30,
|
|
89
|
-
},
|
|
90
|
-
## Depolamalı üretim tesisi
|
|
91
|
-
"plant_w_battery": {"tolerance": 0.05, "multiplier": 0.10},
|
|
92
|
-
## Diğer kaynaklar
|
|
93
|
-
"other": {
|
|
94
|
-
"tolerance": 0.05,
|
|
95
|
-
"multiplier": 0.05,
|
|
96
|
-
"multiplier_maintenance": 0.08,
|
|
97
|
-
"maintenance_fault_threshold": 25,
|
|
98
|
-
},
|
|
99
|
-
## İletime bağlı lisanssız, santral bazında
|
|
100
|
-
"unlicensed_from_transmission": {"tolerance": 0.20, "multiplier": 0.02},
|
|
101
|
-
## Dağıtıma bağlı lisanssız, katılımcı bazında
|
|
102
|
-
"unlicensed_from_distribution": {"tolerance": 0.25, "multiplier": 0.01},
|
|
103
|
-
## Müstakil depolama
|
|
104
|
-
"battery": {"tolerance": 0.20, "multiplier": 0.02},
|
|
105
|
-
},
|
|
168
|
+
"kupst": _kupst_2026_02(),
|
|
106
169
|
},
|
|
107
170
|
{
|
|
108
171
|
"date": "2026-01-01",
|
|
@@ -238,11 +301,18 @@ KUPST_CATEGORIES = (
|
|
|
238
301
|
"solar",
|
|
239
302
|
"plant_w_battery",
|
|
240
303
|
"other",
|
|
304
|
+
"other_renewable",
|
|
241
305
|
"unlicensed_from_transmission",
|
|
242
306
|
"unlicensed_from_distribution",
|
|
243
307
|
"battery",
|
|
308
|
+
"consumption_art17",
|
|
309
|
+
"consumption_other",
|
|
244
310
|
)
|
|
245
311
|
|
|
312
|
+
## Consumption settlement unit categories: KUPST applies to them only where the
|
|
313
|
+
## regulation row defines them (from 2027-01-01).
|
|
314
|
+
KUPST_CONSUMPTION_CATEGORIES = ("consumption_art17", "consumption_other")
|
|
315
|
+
|
|
246
316
|
## Exact names (after normalization) that map to a category
|
|
247
317
|
KUPST_CATEGORY_ALIASES = {
|
|
248
318
|
"sun": "solar",
|
|
@@ -253,6 +323,10 @@ KUPST_CATEGORY_ALIASES = {
|
|
|
253
323
|
"default": "other",
|
|
254
324
|
"diger": "other",
|
|
255
325
|
"diger_kaynaklar": "other",
|
|
326
|
+
"renewable": "other_renewable",
|
|
327
|
+
"yenilenebilir": "other_renewable",
|
|
328
|
+
"consumption": "consumption_other",
|
|
329
|
+
"tuketim": "consumption_other",
|
|
256
330
|
## Earlier names
|
|
257
331
|
"storage_plant": "plant_w_battery",
|
|
258
332
|
"unlicensed_transmission": "unlicensed_from_transmission",
|
|
@@ -274,11 +348,21 @@ _KUPST_PLANT_W_BATTERY_KEYS = (
|
|
|
274
348
|
_KUPST_BATTERY_ONLY_KEYS = ("mustakil", "standalone", "stand", "alone", "only")
|
|
275
349
|
_KUPST_WIND_KEYS = ("wind", "ruzgar", "res", "wpp", "onshore", "offshore")
|
|
276
350
|
_KUPST_SOLAR_KEYS = ("solar", "sun", "gunes", "ges", "pv", "photovoltaic", "fotovoltaik", "spp")
|
|
351
|
+
## Renewables other than wind and solar (Law 5346 Art. 3: hidrolik, jeotermal,
|
|
352
|
+
## biyokütle, biyogaz incl. landfill gas, dalga, akıntı, gel-git)
|
|
353
|
+
_KUPST_OTHER_RENEWABLE_KEYS = (
|
|
354
|
+
"hydro", "hydroelectric", "hes", "hidrolik", "hidroelektrik", "dam", "baraj",
|
|
355
|
+
"barajli", "river", "akarsu", "kanal", "run", "geothermal", "jeotermal", "jes",
|
|
356
|
+
"biomass", "biyokutle", "biogas", "biyogaz", "landfill", "cop", "wave", "dalga",
|
|
357
|
+
"tidal", "gelgit", "renewable", "yenilenebilir",
|
|
358
|
+
)
|
|
277
359
|
_KUPST_OTHER_KEYS = (
|
|
278
|
-
"other", "diger", "
|
|
279
|
-
"
|
|
280
|
-
"
|
|
281
|
-
|
|
360
|
+
"other", "diger", "coal", "komur", "linyit", "lignite", "gas", "dogalgaz",
|
|
361
|
+
"natural", "ngcc", "dgkc", "fuel", "fueloil", "nuclear", "nukleer", "thermal",
|
|
362
|
+
"termik", "import", "ithal",
|
|
363
|
+
)
|
|
364
|
+
_KUPST_CONSUMPTION_KEYS = (
|
|
365
|
+
"consumption", "consumer", "tuketim", "tuketici", "cekis", "withdrawal", "load",
|
|
282
366
|
)
|
|
283
367
|
_TR_FOLD = str.maketrans("ıİşŞğĞüÜöÖçÇâÂîÎûÛ", "iissgguuooccaaiiuu")
|
|
284
368
|
|
|
@@ -300,9 +384,25 @@ def normalize_kupst_category(name: str | None, strict: bool = False) -> str:
|
|
|
300
384
|
'Dağıtıma bağlı lisanssız', 'unlicensed', 'HES', 'doğalgaz' all resolve.
|
|
301
385
|
|
|
302
386
|
Rules, in order: an exact category name or alias; unlicensed (distribution
|
|
303
|
-
if a distribution keyword is present, transmission otherwise);
|
|
304
|
-
(
|
|
305
|
-
|
|
387
|
+
if a distribution keyword is present, transmission otherwise); consumption
|
|
388
|
+
(consumption_art17 with '17' in the name, consumption_other otherwise);
|
|
389
|
+
battery (plant_w_battery if it is a generation plant with storage, battery
|
|
390
|
+
if it is standalone storage); wind; solar; other renewables (hydro,
|
|
391
|
+
geothermal, biomass, ...); other sources.
|
|
392
|
+
|
|
393
|
+
other_renewable exists because EPDK Decisions 14029 and 14907 set the
|
|
394
|
+
maintenance fault threshold for renewable sources (30) and other sources
|
|
395
|
+
(25), while hydro, geothermal and biomass share the tolerance of other
|
|
396
|
+
sources. Renewable follows Law 5346 Art. 3.
|
|
397
|
+
|
|
398
|
+
Storage cases differ in the EPDK decisions (14029 and 14907): a plant with
|
|
399
|
+
storage ("depolamalı elektrik üretim tesisi") is plant_w_battery
|
|
400
|
+
(tolerance 0.05, multiplier 0.10); standalone storage ("müstakil
|
|
401
|
+
depolama") is battery (its own row from 2026-11-01, 'other' before); a
|
|
402
|
+
generation plant with an integrated storage unit ("bütünleşik depolama
|
|
403
|
+
ünitesi") uses its main source's tolerance (Article 3(3)), so pass the
|
|
404
|
+
main source (e.g. 'wind') for it. Names such as 'RES+BESS' cannot tell the
|
|
405
|
+
last two apart and resolve to plant_w_battery.
|
|
306
406
|
|
|
307
407
|
Args:
|
|
308
408
|
name: Source or category name. None gives 'other'.
|
|
@@ -331,6 +431,10 @@ def normalize_kupst_category(name: str | None, strict: bool = False) -> str:
|
|
|
331
431
|
if has(_KUPST_DISTRIBUTION_KEYS):
|
|
332
432
|
return "unlicensed_from_distribution"
|
|
333
433
|
return "unlicensed_from_transmission"
|
|
434
|
+
if has(_KUPST_CONSUMPTION_KEYS):
|
|
435
|
+
if "17" in tokens or any(t.endswith("17") for t in tokens):
|
|
436
|
+
return "consumption_art17"
|
|
437
|
+
return "consumption_other"
|
|
334
438
|
if has(_KUPST_BATTERY_KEYS):
|
|
335
439
|
if has(_KUPST_BATTERY_ONLY_KEYS):
|
|
336
440
|
return "battery"
|
|
@@ -341,6 +445,8 @@ def normalize_kupst_category(name: str | None, strict: bool = False) -> str:
|
|
|
341
445
|
return "wind"
|
|
342
446
|
if has(_KUPST_SOLAR_KEYS):
|
|
343
447
|
return "solar"
|
|
448
|
+
if has(_KUPST_OTHER_RENEWABLE_KEYS):
|
|
449
|
+
return "other_renewable"
|
|
344
450
|
if has(_KUPST_OTHER_KEYS) or not strict:
|
|
345
451
|
return "other"
|
|
346
452
|
|
|
@@ -379,9 +485,17 @@ def get_kupst_params_by_contract(
|
|
|
379
485
|
return None
|
|
380
486
|
|
|
381
487
|
category = normalize_kupst_category(category)
|
|
488
|
+
cat_d = _kupst_category_params(params, category)
|
|
489
|
+
if cat_d is None:
|
|
490
|
+
## Consumption before the regulation covers it: no KUPST
|
|
491
|
+
return {
|
|
492
|
+
"category": category,
|
|
493
|
+
"tolerance": None,
|
|
494
|
+
"multiplier": 0.0,
|
|
495
|
+
"floor_price": params["kupst_floor_price"],
|
|
496
|
+
}
|
|
382
497
|
if category not in params["kupst"]:
|
|
383
498
|
category = "other"
|
|
384
|
-
cat_d = params["kupst"][category]
|
|
385
499
|
|
|
386
500
|
multiplier = cat_d["multiplier"]
|
|
387
501
|
if include_maintenance_penalty:
|
|
@@ -395,20 +509,49 @@ def get_kupst_params_by_contract(
|
|
|
395
509
|
}
|
|
396
510
|
|
|
397
511
|
|
|
512
|
+
def _kupst_category_params(params: dict, category: str) -> dict | None:
|
|
513
|
+
"""Parameters of a normalized category in a regulation row: 'other' for
|
|
514
|
+
production categories the row does not list, None for consumption
|
|
515
|
+
categories before KUPST applies to them."""
|
|
516
|
+
if category in params["kupst"]:
|
|
517
|
+
return params["kupst"][category]
|
|
518
|
+
if category in KUPST_CONSUMPTION_CATEGORIES:
|
|
519
|
+
return None
|
|
520
|
+
return params["kupst"]["other"]
|
|
521
|
+
|
|
522
|
+
|
|
523
|
+
def kupst_applies(contract: str | None, category: str | None, is_producer: bool = True) -> bool:
|
|
524
|
+
"""
|
|
525
|
+
Whether KUPST applies to a unit: always for production units; for
|
|
526
|
+
consumption units only from 2027-01-01 (EPDK Decision 14907, Provisional
|
|
527
|
+
Article 1), with a consumption category ('consumption_art17' or
|
|
528
|
+
'consumption_other').
|
|
529
|
+
"""
|
|
530
|
+
if is_producer:
|
|
531
|
+
return True
|
|
532
|
+
params = contract_to_regulation_params(contract)
|
|
533
|
+
if params is None:
|
|
534
|
+
return False
|
|
535
|
+
return normalize_kupst_category(category) in params["kupst"].keys() & set(
|
|
536
|
+
KUPST_CONSUMPTION_CATEGORIES
|
|
537
|
+
)
|
|
538
|
+
|
|
539
|
+
|
|
398
540
|
def is_kupst_maintenance_penalty_applicable(
|
|
399
541
|
contract: str | None, category: str | None, monthly_fault_entries: int
|
|
400
542
|
) -> bool:
|
|
401
543
|
"""
|
|
402
544
|
Whether the KUPST maintenance multiplier applies, given the number of fault
|
|
403
|
-
entries of the plant in the month (
|
|
404
|
-
more for other sources from 2026-
|
|
405
|
-
without a defined threshold.
|
|
545
|
+
entries of the plant in the month (30 or more for renewable sources: wind,
|
|
546
|
+
solar, other_renewable; 25 or more for other sources; from 2026-01-01).
|
|
547
|
+
False for categories or periods without a defined threshold.
|
|
406
548
|
"""
|
|
407
549
|
params = contract_to_regulation_params(contract)
|
|
408
550
|
if params is None:
|
|
409
551
|
return False
|
|
410
|
-
|
|
411
|
-
cat_d
|
|
552
|
+
cat_d = _kupst_category_params(params, normalize_kupst_category(category))
|
|
553
|
+
if cat_d is None:
|
|
554
|
+
return False
|
|
412
555
|
threshold = cat_d.get("maintenance_fault_threshold")
|
|
413
556
|
return threshold is not None and monthly_fault_entries >= threshold
|
|
414
557
|
|
|
@@ -851,11 +994,12 @@ def temp_calculate_draft_unit_kupst_cost(
|
|
|
851
994
|
):
|
|
852
995
|
"""
|
|
853
996
|
.. deprecated:: 1.3.2
|
|
854
|
-
Use :func:`
|
|
997
|
+
Use :func:`calculate_unit_kupst_cost_by_contract` instead.
|
|
998
|
+
This function will be removed in eptr2 1.5.0.
|
|
855
999
|
"""
|
|
856
1000
|
warnings.warn(
|
|
857
|
-
"temp_calculate_draft_unit_kupst_cost is deprecated
|
|
858
|
-
"
|
|
1001
|
+
"temp_calculate_draft_unit_kupst_cost is deprecated and will be removed in eptr2 1.5.0. "
|
|
1002
|
+
"Use calculate_unit_kupst_cost_by_contract instead.",
|
|
859
1003
|
DeprecationWarning,
|
|
860
1004
|
stacklevel=2,
|
|
861
1005
|
)
|
|
@@ -920,8 +1064,13 @@ def calculate_unit_kupst_cost_pre_2026(
|
|
|
920
1064
|
def calculate_kupsm(actual: float, forecast: float, tol: float):
|
|
921
1065
|
"""
|
|
922
1066
|
Calculate the KÜPSM (Kesinleşmiş Üretim Planından Sapma Miktarı) given actual and forecast values and tolerance.
|
|
1067
|
+
|
|
1068
|
+
The tolerance amount is tol * |forecast|, so consumption plans entered as
|
|
1069
|
+
negative quantities work too. tol None (KUPST does not apply) gives 0.
|
|
923
1070
|
"""
|
|
924
|
-
|
|
1071
|
+
if tol is None:
|
|
1072
|
+
return 0.0
|
|
1073
|
+
tol_val = abs(forecast) * tol
|
|
925
1074
|
kupsm = max(0, abs(forecast - actual) - tol_val)
|
|
926
1075
|
return kupsm
|
|
927
1076
|
|
|
@@ -1155,7 +1304,7 @@ def calculate_kupst_cost(
|
|
|
1155
1304
|
if return_detail:
|
|
1156
1305
|
detail_d = {
|
|
1157
1306
|
"kupst_tol_perc": tol,
|
|
1158
|
-
"kupsm_tol": tol,
|
|
1307
|
+
"kupsm_tol": abs(forecast) * tol,
|
|
1159
1308
|
"kupsm": kupsm,
|
|
1160
1309
|
"unit_kupst_cost": unit_kupst,
|
|
1161
1310
|
"kupst_cost": kupst_cost,
|
|
@@ -2633,15 +2782,15 @@ def calculate_imbalance_cost_list(
|
|
|
2633
2782
|
):
|
|
2634
2783
|
"""
|
|
2635
2784
|
.. deprecated:: 1.3.3
|
|
2636
|
-
Use
|
|
2637
|
-
This function will be removed in
|
|
2785
|
+
Use :func:`calculate_imbalance_costs` (or :func:`calculate_unit_imbalance_cost` per hour) instead.
|
|
2786
|
+
This function will be removed in eptr2 1.5.0.
|
|
2638
2787
|
|
|
2639
2788
|
Calculates imbalance costs for a given forecast and actual values.
|
|
2640
2789
|
Imbalance dampening reduces imbalance costs by the given rate (<1). It is used to emulate balance responsible party (DSG) effect.
|
|
2641
2790
|
"""
|
|
2642
2791
|
warnings.warn(
|
|
2643
|
-
"calculate_imbalance_cost_list is deprecated and will be removed in
|
|
2644
|
-
"Use calculate_unit_imbalance_cost
|
|
2792
|
+
"calculate_imbalance_cost_list is deprecated and will be removed in eptr2 1.5.0. "
|
|
2793
|
+
"Use calculate_imbalance_costs (or calculate_unit_imbalance_cost per hour) instead.",
|
|
2645
2794
|
DeprecationWarning,
|
|
2646
2795
|
stacklevel=2,
|
|
2647
2796
|
)
|
|
@@ -2685,14 +2834,14 @@ def calculate_diff_costs_list(
|
|
|
2685
2834
|
):
|
|
2686
2835
|
"""
|
|
2687
2836
|
.. deprecated:: 1.3.3
|
|
2688
|
-
Use
|
|
2689
|
-
This function will be removed in
|
|
2837
|
+
Use :func:`calculate_imbalance_costs` instead.
|
|
2838
|
+
This function will be removed in eptr2 1.5.0.
|
|
2690
2839
|
|
|
2691
2840
|
Wrapper function to calculate all costs related to the difference between actual and forecasted values.
|
|
2692
2841
|
"""
|
|
2693
2842
|
warnings.warn(
|
|
2694
|
-
"calculate_diff_costs_list is deprecated and will be removed in
|
|
2695
|
-
"Use
|
|
2843
|
+
"calculate_diff_costs_list is deprecated and will be removed in eptr2 1.5.0. "
|
|
2844
|
+
"Use calculate_imbalance_costs instead.",
|
|
2696
2845
|
DeprecationWarning,
|
|
2697
2846
|
stacklevel=2,
|
|
2698
2847
|
)
|
|
@@ -2737,13 +2886,14 @@ def calculate_diff_costs_list(
|
|
|
2737
2886
|
def calculate_imbalance_cost_values_list_pre_2026(mcp: list, smp: list):
|
|
2738
2887
|
"""
|
|
2739
2888
|
.. deprecated:: 1.3.3
|
|
2740
|
-
|
|
2889
|
+
Use :func:`calculate_unit_imbalance_cost` per hour (or :func:`calculate_imbalance_prices`) instead.
|
|
2890
|
+
This function will be removed in eptr2 1.5.0.
|
|
2741
2891
|
|
|
2742
2892
|
Calculates imbalance costs relative to day-ahead prices (MCP) for positive and negative imbalances
|
|
2743
2893
|
"""
|
|
2744
2894
|
warnings.warn(
|
|
2745
|
-
"calculate_imbalance_cost_values_list_pre_2026 is deprecated
|
|
2746
|
-
"
|
|
2895
|
+
"calculate_imbalance_cost_values_list_pre_2026 is deprecated and will be removed in eptr2 1.5.0. "
|
|
2896
|
+
"Use calculate_unit_imbalance_cost per hour instead.",
|
|
2747
2897
|
DeprecationWarning,
|
|
2748
2898
|
stacklevel=2,
|
|
2749
2899
|
)
|
|
@@ -2763,11 +2913,12 @@ def calculate_imbalance_cost_values_list_pre_2026(mcp: list, smp: list):
|
|
|
2763
2913
|
def temp_get_draft_kupst_tolerance(source: str):
|
|
2764
2914
|
"""
|
|
2765
2915
|
.. deprecated:: 1.3.2
|
|
2766
|
-
Use :func:`
|
|
2916
|
+
Use :func:`get_kupst_tolerance_by_contract` instead.
|
|
2917
|
+
This function will be removed in eptr2 1.5.0.
|
|
2767
2918
|
"""
|
|
2768
2919
|
warnings.warn(
|
|
2769
|
-
"temp_get_draft_kupst_tolerance is deprecated
|
|
2770
|
-
"
|
|
2920
|
+
"temp_get_draft_kupst_tolerance is deprecated and will be removed in eptr2 1.5.0. "
|
|
2921
|
+
"Use get_kupst_tolerance_by_contract instead.",
|
|
2771
2922
|
DeprecationWarning,
|
|
2772
2923
|
stacklevel=2,
|
|
2773
2924
|
)
|
|
@@ -2788,11 +2939,12 @@ def temp_calculate_imbalance_price_and_costs_new(
|
|
|
2788
2939
|
):
|
|
2789
2940
|
"""
|
|
2790
2941
|
.. deprecated:: 1.3.2
|
|
2791
|
-
Use :func:`
|
|
2942
|
+
Use :func:`calculate_unit_price_and_costs` instead.
|
|
2943
|
+
This function will be removed in eptr2 1.5.0.
|
|
2792
2944
|
"""
|
|
2793
2945
|
warnings.warn(
|
|
2794
|
-
"temp_calculate_imbalance_price_and_costs_new is deprecated
|
|
2795
|
-
"
|
|
2946
|
+
"temp_calculate_imbalance_price_and_costs_new is deprecated and will be removed in eptr2 1.5.0. "
|
|
2947
|
+
"Use calculate_unit_price_and_costs instead.",
|
|
2796
2948
|
DeprecationWarning,
|
|
2797
2949
|
stacklevel=2,
|
|
2798
2950
|
)
|
|
@@ -2825,6 +2977,7 @@ def calculate_imbalance_price_and_costs_2026(
|
|
|
2825
2977
|
"""
|
|
2826
2978
|
.. deprecated:: 1.3.3
|
|
2827
2979
|
Use :func:`calculate_unit_price_and_costs` instead.
|
|
2980
|
+
This function will be removed in eptr2 1.5.0.
|
|
2828
2981
|
|
|
2829
2982
|
Function to calculate imbalance prices based on new regulation (2026)
|
|
2830
2983
|
|
|
@@ -2840,8 +2993,8 @@ def calculate_imbalance_price_and_costs_2026(
|
|
|
2840
2993
|
regulation: Direction of system regulation ("up", "down", "balanced") when mcp == smp
|
|
2841
2994
|
"""
|
|
2842
2995
|
warnings.warn(
|
|
2843
|
-
"calculate_imbalance_price_and_costs_2026 is deprecated
|
|
2844
|
-
"
|
|
2996
|
+
"calculate_imbalance_price_and_costs_2026 is deprecated and will be removed in eptr2 1.5.0. "
|
|
2997
|
+
"Use calculate_unit_price_and_costs instead.",
|
|
2845
2998
|
DeprecationWarning,
|
|
2846
2999
|
stacklevel=2,
|
|
2847
3000
|
)
|
|
@@ -2869,13 +3022,14 @@ def calculate_imbalance_price_and_costs_2026(
|
|
|
2869
3022
|
def calculate_imbalance_prices_list_pre_2026(mcp: list, smp: list):
|
|
2870
3023
|
"""
|
|
2871
3024
|
.. deprecated:: 1.3.3
|
|
2872
|
-
|
|
3025
|
+
Use :func:`calculate_unit_imbalance_cost` per hour (or :func:`calculate_imbalance_prices`) instead.
|
|
3026
|
+
This function will be removed in eptr2 1.5.0.
|
|
2873
3027
|
|
|
2874
3028
|
Calculates imbalance prices for positive and negative imbalances
|
|
2875
3029
|
"""
|
|
2876
3030
|
warnings.warn(
|
|
2877
|
-
"calculate_imbalance_prices_list_pre_2026 is deprecated
|
|
2878
|
-
"
|
|
3031
|
+
"calculate_imbalance_prices_list_pre_2026 is deprecated and will be removed in eptr2 1.5.0. "
|
|
3032
|
+
"Use calculate_imbalance_prices instead.",
|
|
2879
3033
|
DeprecationWarning,
|
|
2880
3034
|
stacklevel=2,
|
|
2881
3035
|
)
|
|
@@ -2901,8 +3055,8 @@ def calculate_kupst_cost_list(
|
|
|
2901
3055
|
):
|
|
2902
3056
|
"""
|
|
2903
3057
|
.. deprecated:: 1.3.3
|
|
2904
|
-
Use
|
|
2905
|
-
This function will be removed in
|
|
3058
|
+
Use :func:`calculate_imbalance_costs` (or :func:`calculate_kupst_cost` per hour) instead.
|
|
3059
|
+
This function will be removed in eptr2 1.5.0.
|
|
2906
3060
|
|
|
2907
3061
|
Calculate KUPST (Production Plan Deviation Cost) for multiple periods.
|
|
2908
3062
|
|
|
@@ -2967,8 +3121,8 @@ def calculate_kupst_cost_list(
|
|
|
2967
3121
|
"""
|
|
2968
3122
|
|
|
2969
3123
|
warnings.warn(
|
|
2970
|
-
"calculate_kupst_cost_list is deprecated
|
|
2971
|
-
"
|
|
3124
|
+
"calculate_kupst_cost_list is deprecated and will be removed in eptr2 1.5.0. "
|
|
3125
|
+
"Use calculate_imbalance_costs (or calculate_kupst_cost per hour) instead.",
|
|
2972
3126
|
DeprecationWarning,
|
|
2973
3127
|
stacklevel=2,
|
|
2974
3128
|
)
|
|
@@ -3082,6 +3236,27 @@ def _row_contract(row: dict) -> str:
|
|
|
3082
3236
|
raise ValueError("Each row needs a 'date' or 'contract'")
|
|
3083
3237
|
|
|
3084
3238
|
|
|
3239
|
+
def _dedupe_price_rows(rows: list[dict]) -> list[dict]:
|
|
3240
|
+
"""One row per hour. EPİAŞ's mcp-smp-imb returned every hour of 2026-11-01
|
|
3241
|
+
twice (identical rows), so identical rows of the same hour are kept once.
|
|
3242
|
+
Rows of the same hour with different prices raise ValueError, since it is
|
|
3243
|
+
unknown which one is right."""
|
|
3244
|
+
seen = {}
|
|
3245
|
+
result = []
|
|
3246
|
+
for row in rows:
|
|
3247
|
+
contract = _row_contract(row)
|
|
3248
|
+
values = tuple(_get_field(row, field) for field in _PRICE_FIELD_NAMES)
|
|
3249
|
+
if contract in seen:
|
|
3250
|
+
if seen[contract] != values:
|
|
3251
|
+
raise ValueError(
|
|
3252
|
+
f"Conflicting price rows for {contract}: {seen[contract]} and {values}"
|
|
3253
|
+
)
|
|
3254
|
+
continue
|
|
3255
|
+
seen[contract] = values
|
|
3256
|
+
result.append(row)
|
|
3257
|
+
return result
|
|
3258
|
+
|
|
3259
|
+
|
|
3085
3260
|
def _maybe_df(rows: list[dict], return_df: bool):
|
|
3086
3261
|
if not return_df:
|
|
3087
3262
|
return rows
|
|
@@ -3102,6 +3277,7 @@ def _fetch_mcp_smp_imb(start_contract: str, end_contract: str, eptr=None, **kwar
|
|
|
3102
3277
|
"mcp-smp-imb",
|
|
3103
3278
|
start_date=_contract_to_date_str(start_contract),
|
|
3104
3279
|
end_date=_contract_to_date_str(end_contract),
|
|
3280
|
+
drop_duplicates=True,
|
|
3105
3281
|
)
|
|
3106
3282
|
rows = _to_records(res)
|
|
3107
3283
|
if len(rows) == 0:
|
|
@@ -3224,6 +3400,7 @@ def calculate_imbalance_prices(
|
|
|
3224
3400
|
rows = _fetch_mcp_smp_imb(start_contract, end_contract, eptr=eptr, **kwargs)
|
|
3225
3401
|
else:
|
|
3226
3402
|
rows = _to_records(prices)
|
|
3403
|
+
rows = _dedupe_price_rows(rows)
|
|
3227
3404
|
|
|
3228
3405
|
overrides = {
|
|
3229
3406
|
k: kwargs[k]
|
|
@@ -3367,6 +3544,16 @@ def calculate_imbalance_costs(
|
|
|
3367
3544
|
calculated ones otherwise (see imb_price_source). KUPST tolerance and multiplier follow each row's
|
|
3368
3545
|
category and date.
|
|
3369
3546
|
|
|
3547
|
+
``forecast`` is the plan the costs are measured against, so the choice of
|
|
3548
|
+
plan sets the question being answered:
|
|
3549
|
+
|
|
3550
|
+
- KUDÜP approximates the settled values. Settlement measures KÜPSM against
|
|
3551
|
+
BUDÜP = KUDÜP + YAL - YAT + SRDM + SFHM (EPDK Decisions 14029 and 14907,
|
|
3552
|
+
Article 1). Plant-level YAL/YAT are not available from the
|
|
3553
|
+
Transparency Platform, so they are taken as 0 and BUDÜP = KUDÜP.
|
|
3554
|
+
- KGÜP v1 (the day-ahead plan) answers "what if the day-ahead plan had not
|
|
3555
|
+
changed": the costs had the plant not updated its plan intraday.
|
|
3556
|
+
|
|
3370
3557
|
Args:
|
|
3371
3558
|
data: Hourly quantities as a DataFrame or list of dicts with 'date' (or
|
|
3372
3559
|
'contract'), 'actual' and 'forecast' in MWh. Optional per row
|
|
@@ -3379,7 +3566,10 @@ def calculate_imbalance_costs(
|
|
|
3379
3566
|
(e.g. 'wind', 'Rüzgar', 'GES', 'Müstakil depolama'), see
|
|
3380
3567
|
normalize_kupst_category.
|
|
3381
3568
|
is_producer: Production (True) or consumption (False) unit. KUPST
|
|
3382
|
-
applies to producers
|
|
3569
|
+
applies to producers, and to consumption units from 2027-01-01
|
|
3570
|
+
when their category is 'consumption_art17' (withdrawal units of
|
|
3571
|
+
DUY Art. 17(2) (a)-(ç), tolerance 0.75) or 'consumption_other'
|
|
3572
|
+
(0.30), see kupst_applies.
|
|
3383
3573
|
prices: Hourly prices passed to calculate_imbalance_prices. Fetched
|
|
3384
3574
|
from EPİAŞ if None.
|
|
3385
3575
|
eptr: EPTR2 client for fetching.
|
|
@@ -3391,13 +3581,22 @@ def calculate_imbalance_costs(
|
|
|
3391
3581
|
One row per input row with the input columns and contract, category,
|
|
3392
3582
|
is_producer, mcp, smp, system_direction, pos_imb_price, neg_imb_price,
|
|
3393
3583
|
imb_price_source, imb_qty (positive surplus, negative deficit), unit_imb_cost, imb_cost,
|
|
3394
|
-
kupst_tolerance, kupsm, unit_kupst_cost, kupst_cost (0
|
|
3395
|
-
and total_cost, in TL.
|
|
3584
|
+
kupst_tolerance, kupsm, unit_kupst_cost, kupst_cost (0 where KUPST
|
|
3585
|
+
does not apply) and total_cost, in TL.
|
|
3396
3586
|
|
|
3397
3587
|
Notes:
|
|
3398
3588
|
Imbalance is the raw deviation of the unit; balancing group (DSG)
|
|
3399
3589
|
tolerance and netting are not applied.
|
|
3400
3590
|
|
|
3591
|
+
Rules of the KÜPST decisions (14029, 14907) that are not modelled:
|
|
3592
|
+
from 2026-11-01 the deviation is |(UEVM - UEÇM) - BUDÜP|, i.e. net of
|
|
3593
|
+
the unit's withdrawals, so pass net quantities for units that both
|
|
3594
|
+
inject and withdraw; unlicensed plants are assessed on generation only
|
|
3595
|
+
(14907 Art. 1(3)); distribution-connected unlicensed plants are
|
|
3596
|
+
assessed per participant, so pass the participant's aggregate; and
|
|
3597
|
+
14907 does not apply to the transmission-connected plants of Art.
|
|
3598
|
+
5(1)(ç), (d), (e) of the unlicensed generation regulation (14907 Art. 5).
|
|
3599
|
+
|
|
3401
3600
|
Examples:
|
|
3402
3601
|
>>> calculate_imbalance_costs(
|
|
3403
3602
|
... actual=80, forecast=100, date="2026-11-01T10:00:00+03:00",
|
|
@@ -3447,7 +3646,7 @@ def calculate_imbalance_costs(
|
|
|
3447
3646
|
imb_cost = round(abs(imb_qty) * unit_imb_cost, 2)
|
|
3448
3647
|
|
|
3449
3648
|
kupst = {"kupst_tolerance": None, "kupsm": 0.0, "unit_kupst_cost": None, "kupst_cost": 0.0}
|
|
3450
|
-
if row_is_producer:
|
|
3649
|
+
if kupst_applies(contract, row_category, row_is_producer):
|
|
3451
3650
|
kupst_d = _kupst_params_for_row(
|
|
3452
3651
|
contract,
|
|
3453
3652
|
row_category,
|
|
File without changes
|
|
File without changes
|
{eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/docs/assets/README.md
RENAMED
|
File without changes
|
{eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/examples/README.md
RENAMED
|
File without changes
|
{eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/pyproject.toml
RENAMED
|
File without changes
|
|
File without changes
|
{eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/tutorials/README.md
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-consumption-data/SKILL.md
RENAMED
|
File without changes
|
{eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-consumption-data/examples.md
RENAMED
|
File without changes
|
{eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-convenience-wrappers/SKILL.md
RENAMED
|
File without changes
|
{eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-generation-tracking/SKILL.md
RENAMED
|
File without changes
|
{eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-generation-tracking/examples.md
RENAMED
|
File without changes
|
{eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-imbalance-costs/examples.md
RENAMED
|
File without changes
|
{eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-imbalance-costs/formulas.md
RENAMED
|
File without changes
|
{eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-market-operations/SKILL.md
RENAMED
|
File without changes
|
{eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-market-operations/examples.md
RENAMED
|
File without changes
|
|
File without changes
|
{eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-price-analysis/api-reference.md
RENAMED
|
File without changes
|
{eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-price-analysis/examples.md
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|