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.
Files changed (99) hide show
  1. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/PKG-INFO +1 -1
  2. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/pyproject.toml +1 -1
  3. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/eptr2_api_schema.json +1 -1
  4. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-imbalance-costs/SKILL.md +2 -2
  5. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/plant_costs.py +27 -1
  6. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/price_and_cost.py +2 -0
  7. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/main.py +12 -0
  8. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/mcp/server.py +3 -1
  9. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/util/costs.py +289 -90
  10. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/LICENSE +0 -0
  11. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/README.md +0 -0
  12. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/docs/assets/README.md +0 -0
  13. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/examples/README.md +0 -0
  14. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/pyproject.toml +0 -0
  15. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/src/eptr2/mcp/README.md +0 -0
  16. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/tutorials/README.md +0 -0
  17. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/tutorials/pyproject.toml +0 -0
  18. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/.gitignore +0 -0
  19. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/LICENSE +0 -0
  20. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/README.md +0 -0
  21. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/docs/assets/README.md +0 -0
  22. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/examples/README.md +0 -0
  23. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/__init__.py +0 -0
  24. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/__main__.py +0 -0
  25. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/agentic/__init__.py +0 -0
  26. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/agentic/discovery.py +0 -0
  27. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/agentic/schema.py +0 -0
  28. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/agentic/skills.py +0 -0
  29. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/agentic/validation.py +0 -0
  30. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/__init__.py +0 -0
  31. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/mcp.json +0 -0
  32. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/plugin.json +0 -0
  33. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-api-discovery/SKILL.md +0 -0
  34. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-api-discovery/endpoint-categories.md +0 -0
  35. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-api-discovery/scripts/list_endpoints.py +0 -0
  36. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-consumption-data/SKILL.md +0 -0
  37. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-consumption-data/examples.md +0 -0
  38. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-convenience-wrappers/SKILL.md +0 -0
  39. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-generation-tracking/SKILL.md +0 -0
  40. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-generation-tracking/examples.md +0 -0
  41. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-imbalance-costs/examples.md +0 -0
  42. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-imbalance-costs/formulas.md +0 -0
  43. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-market-operations/SKILL.md +0 -0
  44. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-market-operations/examples.md +0 -0
  45. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-price-analysis/SKILL.md +0 -0
  46. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-price-analysis/api-reference.md +0 -0
  47. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-price-analysis/examples.md +0 -0
  48. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/__init__.py +0 -0
  49. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/ancillary.py +0 -0
  50. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/bilateral.py +0 -0
  51. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/bpm.py +0 -0
  52. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/consumption.py +0 -0
  53. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/dam.py +0 -0
  54. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/dams.py +0 -0
  55. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/general.py +0 -0
  56. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/generation.py +0 -0
  57. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/idm.py +0 -0
  58. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/imbalance.py +0 -0
  59. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/mms.py +0 -0
  60. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/ng_general.py +0 -0
  61. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/ng_sgp.py +0 -0
  62. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/ng_transmission.py +0 -0
  63. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/ng_vgp.py +0 -0
  64. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/renewables.py +0 -0
  65. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/reporting.py +0 -0
  66. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/retroactive.py +0 -0
  67. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/transmission.py +0 -0
  68. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/vep.py +0 -0
  69. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/calls/yek_g.py +0 -0
  70. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/cli.py +0 -0
  71. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/__init__.py +0 -0
  72. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/ancillary.py +0 -0
  73. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/bpm.py +0 -0
  74. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/consumption.py +0 -0
  75. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/dabi_idm.py +0 -0
  76. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/idm_log.py +0 -0
  77. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/ids.py +0 -0
  78. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/mms.py +0 -0
  79. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/org_activity.py +0 -0
  80. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/periodic_orgs.py +0 -0
  81. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/composite/production.py +0 -0
  82. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/mapping/__init__.py +0 -0
  83. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/mapping/checks.py +0 -0
  84. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/mapping/help.py +0 -0
  85. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/mapping/parameters.py +0 -0
  86. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/mapping/path.py +0 -0
  87. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/mapping/processing.py +0 -0
  88. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/mcp/README.md +0 -0
  89. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/mcp/__init__.py +0 -0
  90. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/processing/__init__.py +0 -0
  91. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/processing/postprocess/__init__.py +0 -0
  92. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/processing/postprocess/items.py +0 -0
  93. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/processing/preprocess/__init__.py +0 -0
  94. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/processing/preprocess/calls.py +0 -0
  95. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/processing/preprocess/params.py +0 -0
  96. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/util/__init__.py +0 -0
  97. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/util/certificate.py +0 -0
  98. {eptr2-1.4.1.dev0 → eptr2-1.4.1.dev1}/src/eptr2/util/evaluation.py +0 -0
  99. {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.dev0
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.dev0"
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.dev0",
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 ...",
@@ -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 calculations are based on a single plant type. Aggregators have more complex rules that are not covered here.
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("mcp-smp-imb", start_date=start_date, end_date=end_date)
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
- "wind": {"tolerance": 0.15, **rate},
51
- "solar": {"tolerance": 0.08, **rate},
52
- "unlicensed_from_transmission": {"tolerance": 0.20, **rate},
53
- "other": {"tolerance": 0.05, **rate},
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. The imbalance and KUPST formulas are unchanged.
61
- ## Source: KUPST coefficients table ("Tablo 4, KÜPST katsayıları,
62
- ## Kasım 2026'dan itibaren") supplied by the maintainer.
63
- ## TODO: cite the board decision / Resmi Gazete issue.
64
- ## Consumption unit categories of the same table start in 2027
65
- ## and are not included yet.
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", "hydro", "hes", "dam", "baraj", "river", "akarsu", "coal",
279
- "komur", "linyit", "lignite", "gas", "dogalgaz", "natural", "ngcc", "dgkc",
280
- "geothermal", "jeotermal", "jes", "biomass", "biyokutle", "biogas", "biyogaz",
281
- "fuel", "fueloil", "nuclear", "nukleer", "thermal", "termik", "import", "ithal",
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); battery
304
- (plant_w_battery if it is a generation plant with storage, battery if it is
305
- standalone storage); wind; solar; other sources.
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 (e.g. 30 or more for wind and solar, 25 or
404
- more for other sources from 2026-11-01). False for categories or periods
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
- category = normalize_kupst_category(category)
411
- cat_d = params["kupst"].get(category, params["kupst"]["other"])
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:`calculate_unit_kupst_cost_2026` instead.
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
- "use calculate_unit_kupst_cost_2026 instead",
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
- tol_val = forecast * tol
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 singular unit functions with list comprehension instead.
2637
- This function will be removed in a future version.
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 a future version. "
2644
- "Use calculate_unit_imbalance_cost with list comprehension instead.",
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 individual unit functions with list comprehension instead.
2689
- This function will be removed in a future version.
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 a future version. "
2695
- "Use calculate_unit_imbalance_cost and calculate_kupst_cost with list comprehension instead.",
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
- In further versions, please use the singular unit functions and make your own list comprehension.
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
- "In further versions, please use the singular unit functions.",
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:`get_kupst_tolerance_2026` instead.
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
- "use get_kupst_tolerance_2026 instead",
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:`calculate_imbalance_price_and_costs_2026` instead.
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
- "use calculate_imbalance_price_and_costs_2026 instead",
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
- "use calculate_unit_price_and_costs instead",
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
- In further versions, please use the singular unit functions and make your own list comprehension.
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
- "In further versions, please use the singular unit functions.",
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 list comprehension with :func:`calculate_kupsm` instead.
2905
- This function will be removed in a future version.
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
- "In further versions, please use the singular unit functions.",
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 only.
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 for consumers)
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
File without changes
File without changes