flextool 4.1.0__tar.gz → 4.1.1__tar.gz

{flextool-4.1.0 → flextool-4.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flextool
-Version: 4.1.0
+Version: 4.1.1
 Summary: IRENA FlexTool is an energy and power systems model for understanding the role of variable power generation in future energy systems.
 Author: IRENA FlexTool contributors
 License: © International Renewable Energy Agency 2018-2022

flextool-4.1.1/flextool/engine_polars/_constants.py

@@ -0,0 +1,16 @@
+"""Shared numeric constants for the polars engine.
+
+FlexTool timelines use arbitrary indices (not datetime), so "a year" has
+no calendar definition the engine can read off the timestamps.
+``HOURS_PER_YEAR`` is the single canonical hours->years unit used for
+*every* period-share / annualisation conversion in the engine
+(``period_share_of_year``, ``timeline_duration_in_years``, the
+``scale_to_annual_flow`` denominator, peak annualisation, ...).  Keeping
+it in one place means the serve/report/cost annualisations stay mutually
+consistent, and a future per-period override only has to replace one
+symbol rather than ~two dozen scattered literals.
+"""
+from __future__ import annotations
+
+# Hours in a reference year (365 * 24).  See module docstring.
+HOURS_PER_YEAR = 8760.0

{flextool-4.1.0 → flextool-4.1.1}/flextool/engine_polars/_derived_params.py

@@ -54,6 +54,7 @@ from ._axis_enums import (
     rename_to_axis,
     schema_dtype,
 )
+from ._constants import HOURS_PER_YEAR
 from ._emit_provider_io import _provider_key
 from ._solve_state import CommissioningLagError, LineageFilterError
 from ._param_shapes import (
@@ -826,7 +827,7 @@ def p_period_share_from_source(
     sd = step_dur.frame
     out = (sd.lazy()
               .group_by("d")
-              .agg((pl.col("value").cast(pl.Float64).sum() / 8760.0)
+              .agg((pl.col("value").cast(pl.Float64).sum() / HOURS_PER_YEAR)
                    .alias("value"))
               .sort("d")
               .collect())
@@ -10228,7 +10229,7 @@ def p_f_d_k_from_source(
     out_lf = (out_lf
                 .with_columns(pl.col("sum_step").fill_null(0.0))
                 .with_columns(value=(pl.col("cum") + pl.col("sum_step"))
-                                       / (pl.col("share") * 8760.0))
+                                       / (pl.col("share") * HOURS_PER_YEAR))
                 .select("d", "value"))
     out = out_lf.collect()
     if out.height == 0:

{flextool-4.1.0 → flextool-4.1.1}/flextool/engine_polars/_emit_inflow_scaling.py

@@ -56,6 +56,7 @@ from pathlib import Path
 
 import polars as pl
 
+from flextool.engine_polars._constants import HOURS_PER_YEAR
 from flextool.engine_polars._emit_provider_io import (
     _emit,
     _provider_key,
@@ -289,6 +290,14 @@ def _compute_inflow_scaling_frames(
         solve_data_dir / "p_timeline_duration_in_years.csv",
         provider=provider,
     )
+    # Full-timeline annualised inflow energy per node — the
+    # timeset-independent ``scale_to_annual_flow`` denominator.  Emitted
+    # by ``create_averaged_timeseries`` only for coarsened
+    # (``new_stepduration``) solves; absent → legacy per-solve formula.
+    ftf = _read_keyed_float(
+        solve_data_dir / "node_full_timeline_flow.csv",
+        provider=provider,
+    )
 
     # Representative weight w[(d, t)] = p_timestep_weight[d, t] (the param
     # the cost objective already uses).  Sourced from the per-solve
@@ -420,12 +429,20 @@ def _compute_inflow_scaling_frames(
     # ── period_flow_annual_multiplier ─────────────────────────────────
     # value = complete_period_share_of_year[d] / period_share_of_annual_flow[n, d].
     # Domain: (n, d) where scale_to_annual_flow AND pdNode annual_flow.
+    # When a full-timeline energy exists for the node (coarsened solve),
+    # use the timeset-independent denominator
+    # value = annual_flow[n, d] / abs(full_timeline_flow[n]) instead.
     rows_pfam: list[tuple[str, str, float]] = []
     for n in nodes:
         if not _has_method(n, "scale_to_annual_flow"):
             continue
+        ft = ftf.get(n, 0.0)
         for d in period_in_use:
-            if pdNode.get((n, "annual_flow", d), 0.0) == 0.0:
+            af = pdNode.get((n, "annual_flow", d), 0.0)
+            if af == 0.0:
+                continue
+            if ft != 0.0:
+                rows_pfam.append((n, d, af / abs(ft)))
                 continue
             denom = psaf.get((n, d), 0.0)
             if denom == 0.0:
@@ -549,7 +566,7 @@ def _compute_inflow_scaling_frames(
     # ── new_peak_inflow_sum, new_old_multiplier/slope/section ─────────
     # Same domain as rows_nps; values derived from peak / npop / npopis.
     npis_dict = {
-        (n, d): pdNode.get((n, "peak_inflow", d), 0.0) * 8760.0
+        (n, d): pdNode.get((n, "peak_inflow", d), 0.0) * HOURS_PER_YEAR
         for n, d, _ in rows_nps
     }
     rows_npis = [(n, d, npis_dict.get((n, d), 0.0)) for n, d, _ in rows_nps]
@@ -696,6 +713,13 @@ def _compute_inflow_scaling_frames_vectorized(
         solve_data_dir / "p_timeline_duration_in_years.csv",
         provider=provider,
     )
+    # Full-timeline annualised inflow energy per node — the
+    # timeset-independent ``scale_to_annual_flow`` denominator (see the
+    # legacy oracle for the full rationale).  Absent → legacy formula.
+    ftf = _read_keyed_float(
+        solve_data_dir / "node_full_timeline_flow.csv",
+        provider=provider,
+    )
 
     # Representative weight w[(d, t)] = p_timestep_weight[d, t] (see the
     # legacy reader block for the full rationale).  DEFAULT 1.0 for any
@@ -1032,19 +1056,33 @@ def _compute_inflow_scaling_frames_vectorized(
         {"period": list(cpsoy.keys()), "v_cpsoy": list(cpsoy.values())},
         schema={"period": pl.Utf8, "v_cpsoy": pl.Float64},
     )
+    # Full-timeline energy lookup: when present (coarsened solve) its
+    # branch overrides the legacy cpsoy/psaf denominator with the
+    # timeset-independent ``af / abs(full_timeline_flow)``.
+    ftf_lk = pl.DataFrame(
+        {"node": list(ftf.keys()), "v_ftf": list(ftf.values())},
+        schema={"node": pl.Utf8, "v_ftf": pl.Float64},
+    )
     pfam_df = (
         annual_flow_only_eo
         .join(period_po, how="cross")
         # (a) af==0/miss → DROP.
         .join(af_lk, on=["node", "period"], how="left")
         .filter(pl.col("v_af").fill_null(0.0) != 0.0)
-        # (b) psaf miss OR exact-0 → DROP.
         .join(psaf_lk, on=["node", "period"], how="left")
-        .filter(pl.col("v_psaf").fill_null(0.0) != 0.0)
         # (c) cpsoy numerator → survive-with-0.
         .join(cpsoy_lk, on="period", how="left")
+        .join(ftf_lk, on="node", how="left")
+        # (b) Full-timeline branch (v_ftf != 0) survives regardless of
+        # psaf; legacy branch keeps the psaf miss-OR-exact-0 → DROP gate.
+        .filter(
+            (pl.col("v_ftf").fill_null(0.0) != 0.0)
+            | (pl.col("v_psaf").fill_null(0.0) != 0.0))
         .with_columns(
-            (pl.col("v_cpsoy").fill_null(0.0) / pl.col("v_psaf"))
+            pl.when(pl.col("v_ftf").fill_null(0.0) != 0.0)
+            .then(pl.col("v_af") / pl.col("v_ftf").abs())
+            .otherwise(
+                pl.col("v_cpsoy").fill_null(0.0) / pl.col("v_psaf"))
             .alias("value_f"),
         )
     )
@@ -1169,7 +1207,7 @@ def _compute_inflow_scaling_frames_vectorized(
         )
         .with_columns(
             # npis = peak * 8760.0 (constraint 3).
-            (pl.col("v_peak") * 8760.0).alias("v_npis"),
+            (pl.col("v_peak") * HOURS_PER_YEAR).alias("v_npis"),
             # npop = 0.0 if old_peak == 0.0 else peak / old_peak.  FILL,
             # not drop (constraint 1); exact ``== 0.0`` guard (constraint 4).
             pl.when(pl.col("old_peak") == 0.0)

{flextool-4.1.0 → flextool-4.1.1}/flextool/engine_polars/_emit_period_calc.py

@@ -45,6 +45,7 @@ from pathlib import Path
 
 import polars as pl
 
+from flextool.engine_polars._constants import HOURS_PER_YEAR
 from flextool.engine_polars._emit_provider_io import _emit
 
 
@@ -241,7 +242,8 @@ def emit_period_calculated_params(
     for (d2, _t), v in complete_step_duration.items():
         sum_complete_by_d2[d2] = sum_complete_by_d2.get(d2, 0.0) + v
 
-    p_tdy = [(tl, sum_timeline_dur.get(tl, 0.0) / 8760.0) for tl in timelines]
+    p_tdy = [(tl, sum_timeline_dur.get(tl, 0.0) / HOURS_PER_YEAR)
+             for tl in timelines]
     _emit_keyed(provider, "solve_data/p_timeline_duration_in_years.csv",
                 ("timeline", "value"), p_tdy)
 
@@ -251,7 +253,7 @@ def emit_period_calculated_params(
     _emit_keyed(provider, "solve_data/hours_in_period.csv",
                 ("period", "value"), hours_in_period)
 
-    period_share = [(d, h / 8760.0) for d, h in hours_in_period]
+    period_share = [(d, h / HOURS_PER_YEAR) for d, h in hours_in_period]
     _emit_keyed(provider, "solve_data/period_share_of_year.csv",
                 ("period", "value"), period_share)
 
@@ -274,7 +276,7 @@ def emit_period_calculated_params(
     _emit_keyed(provider, "solve_data/complete_hours_in_period.csv",
                 ("period", "value"), complete_hours)
 
-    complete_share = [(d, h / 8760.0) for d, h in complete_hours]
+    complete_share = [(d, h / HOURS_PER_YEAR) for d, h in complete_hours]
     _emit_keyed(provider, "solve_data/complete_period_share_of_year_calc.csv",
                 ("period", "value"), complete_share)
 
@@ -399,7 +401,7 @@ def emit_period_calculated_params(
     f_d_k_rows: list[tuple[str, float]] = []
     for d in period_in_use:
         num = p_ladder_cum.get(d, 0.0) + sum_step_dur_by_period.get(d, 0.0)
-        denom = complete_share_lookup.get(d, 0.0) * 8760.0
+        denom = complete_share_lookup.get(d, 0.0) * HOURS_PER_YEAR
         f_d_k_rows.append((d, num / denom))
     _emit_keyed(provider, "solve_data/f_d_k.csv",
                 ("period", "value"), f_d_k_rows)

{flextool-4.1.0 → flextool-4.1.1}/flextool/engine_polars/_native_run_model.py

@@ -991,8 +991,10 @@ def native_run_model(state, solver) -> int:
             # sub-solve Provider too — this iter's readers must find
             # them without waiting for the next seed pass.
             for _key, _frame in cascade_input_provider.items():
-                if _key.startswith("solve_data/pt_") or _key.startswith(
-                    "solve_data/pbt_",
+                if (
+                    _key.startswith("solve_data/pt_")
+                    or _key.startswith("solve_data/pbt_")
+                    or _key.endswith("node_full_timeline_flow")
                 ):
                     sub_solve_provider.put(_key, _frame)
         previous_complete_solve = complete_solve[solve]

{flextool-4.1.0 → flextool-4.1.1}/flextool/engine_polars/_per_solve_sets.py

@@ -49,6 +49,7 @@ from typing import TYPE_CHECKING
 import polars as pl
 
 from ._axis_enums import alias_to_axis
+from ._constants import HOURS_PER_YEAR
 
 if TYPE_CHECKING:
     from flextool.engine_polars._input_source import InputSource
@@ -304,7 +305,7 @@ def derive_per_solve_aggregates(
     # ── p_timeline_duration_in_years[timeline] ───────────────────────
     # = sum_t step_duration[timeline, t] / 8760
     p_tdy = (tl_lf.group_by("timeline")
-                   .agg((pl.col("step_duration").sum() / 8760.0)
+                   .agg((pl.col("step_duration").sum() / HOURS_PER_YEAR)
                         .alias("value"))
                    .sort("timeline")
                    .collect())
@@ -321,7 +322,8 @@ def derive_per_solve_aggregates(
     # PerSolveAggregates dataclass already exposes the per-(d, d) frame
     # which downstream branch-aware helpers can fold themselves.
     cpsoy = (expanded_lf
-               .group_by("d").agg((pl.col("step_duration").sum() / 8760.0)
+               .group_by("d").agg((pl.col("step_duration").sum()
+                                    / HOURS_PER_YEAR)
                                   .alias("value"))
                .sort("d")
                .collect())

{flextool-4.1.0 → flextool-4.1.1}/flextool/engine_polars/_timeline.py

@@ -50,6 +50,7 @@ from typing import TYPE_CHECKING, Any
 import polars as pl
 import spinedb_api as api
 
+from flextool.engine_polars._constants import HOURS_PER_YEAR
 from flextool.engine_polars._solve_config import (
     DictMode,
     get_single_entities,
@@ -828,6 +829,76 @@ class TimelineConfig:
                 _build_frame_with_headers(headers, out_rows),
             )
 
+        # ── Full-timeline inflow energy (timeset-independent scaling) ──
+        # ``scale_to_annual_flow`` normalises each node's inflow to its
+        # ``annual_flow`` using the ORIGINAL unmodified timeline
+        # (pre-``new_stepduration``).  A shared timeset makes
+        # ``create_timeline_from_timestep_duration`` accumulate every
+        # solve's periods into a single coarsened timeline; summing over
+        # that leaks later solves' inflow into this solve's scaling.
+        # Instead sum the raw inflow over the WHOLE original timeline and
+        # annualise it with its ``timeline_duration_in_years`` (= total
+        # hours / HOURS_PER_YEAR), exactly as the sibling
+        # ``scale_in_proportion`` method annualises.  No "find one year"
+        # windowing is needed: a sub-year timeline scales up (duration <
+        # 1), a multi-year timeline averages over its years (duration >
+        # 1), and a one-year timeline is unchanged (duration == 1).
+        new_tl = timelines_list[0] if timelines_list else None
+        # Walk back to the truly unmodified (pre-coarsening) timeline.
+        base_tl = new_tl
+        seen_tl: set[str] = set()
+        while base_tl in self.original_timeline and base_tl not in seen_tl:
+            seen_tl.add(base_tl)
+            base_tl = self.original_timeline[base_tl]
+        base_steps = self.timelines.get(base_tl, [])
+        all_step_names: set[str] = {step[0] for step in base_steps}
+        total_hours = sum(float(step[1]) for step in base_steps)
+        duration_in_years = total_hours / HOURS_PER_YEAR
+        if duration_in_years:
+            inflow_path = wf / "input" / "pt_node_inflow.csv"
+            inflow_frame = _provider_get_or_read(
+                provider, _provider_key(inflow_path), inflow_path,
+            )
+            ts_sum: dict[str, float] = {}
+            if inflow_frame is not None and inflow_frame.height > 0:
+                cols = inflow_frame.columns
+                grouped = (
+                    inflow_frame
+                    .filter(pl.col(cols[1]).is_in(all_step_names))
+                    .select(
+                        pl.col(cols[0]).alias("node"),
+                        pl.col(cols[-1]).cast(pl.Float64, strict=False)
+                        .alias("v"),
+                    )
+                    .group_by("node")
+                    .agg(pl.col("v").sum().alias("v"))
+                )
+                for n_name, v in grouped.iter_rows():
+                    if n_name:
+                        ts_sum[str(n_name)] = (
+                            float(v) if v is not None else 0.0
+                        )
+            const_for_node: dict[str, float] = {}
+            for node__value in node__inflow:
+                try:
+                    const_for_node[node__value[0]] = float(node__value[1])
+                except (ValueError, TypeError):
+                    continue
+            flow_rows: list[list] = []
+            for n_name in dict.fromkeys(
+                list(ts_sum) + list(const_for_node)
+            ):
+                energy = (
+                    ts_sum.get(n_name, 0.0)
+                    + const_for_node.get(n_name, 0.0) * total_hours
+                )
+                flow_rows.append([n_name, energy / duration_in_years])
+            flow_path = wf / "solve_data" / "node_full_timeline_flow.csv"
+            provider.put(
+                _provider_key(flow_path),
+                _build_frame_with_headers(["node", "value"], flow_rows),
+            )
+
 
 # ---------------------------------------------------------------------------
 # Helpers (private)

{flextool-4.1.0 → flextool-4.1.1}/flextool/process_outputs/out_node.py

@@ -108,21 +108,31 @@ def node_summary(par, s, v, r, debug):
                         & node_dt.columns.get_level_values('category').isin(['Excess load'])]
     node_dt[downward_slack_cols] = downward_slack_data[downward_slack_cols.get_level_values('node')]
 
-    # Inflow
+    # Inflow — par.node_inflow is energy per step (MWh/step).  Divide it by
+    # step_duration in place so the Inflow column becomes a MW rate like every
+    # other node__dt category (identity at step_duration == 1).  Dividing
+    # node_dt's own inflow columns reuses the exact (period, time) index the
+    # flow path already aligns against, so a stray/misaligned row cannot turn
+    # into NaN and get silently zeroed by the fillna(0.0) below.
     inflow_cols = node_dt.columns[
                     node_dt.columns.get_level_values('node').isin(par.node_inflow.columns.intersection(nodes))
                     & node_dt.columns.get_level_values('category').isin(['Inflow'])]
     node_dt[inflow_cols] = par.node_inflow[inflow_cols.get_level_values('node')]
+    node_dt[inflow_cols] = node_dt[inflow_cols].div(par.step_duration, axis=0)
 
     # Fill any remaining NaN values with 0
     node_dt = node_dt.fillna(0.0)
 
     results.append((node_dt, 'node_dt_ep'))
 
-    # 2. Period-level node summary.  Most categories (flows, slacks, self
-    # discharge) are MW — multiply by step_duration to get MWh per step.
-    # Inflow is already MWh/step (par.node_inflow is energy per step, see
-    # mod comment at flextool.mod:2319), so compute it separately.
+    # 2. Period-level node summary.  Every node__dt category is now a MW rate
+    # (Inflow was divided by step_duration at the inflow block above), so the
+    # table is internally consistent and each (d, t) row balances.  The period
+    # path therefore multiplies all categories — inflow included — by
+    # step_duration uniformly to get MWh per step.  (Algebra: the pre-fix
+    # inflow period sum was Σ_t inflow_MWh_step·weight / share; after the fix
+    # it is Σ_t (inflow_MWh_step / sd)·sd·weight / share — identical, so
+    # node__d is unchanged.)
     energy_categories = [c for c in categories if c != 'Inflow']
     energy_cols = node_dt.columns[node_dt.columns.get_level_values('category').isin(energy_categories)]
     inflow_cols = node_dt.columns[node_dt.columns.get_level_values('category') == 'Inflow']
@@ -135,7 +145,7 @@ def node_summary(par, s, v, r, debug):
         par.complete_period_share_of_year, par.step_duration, div_level=1)
     node_d_inflow = annualize_dt_to_d(
         node_dt[inflow_cols], par.timestep_weight,
-        par.complete_period_share_of_year, div_level=1)
+        par.complete_period_share_of_year, par.step_duration, div_level=1)
     node_d = pd.concat([node_d_energy, node_d_inflow], axis=1).reindex(columns=node_dt.columns)
 
     results.append((node_d, 'node_d_ep'))

{flextool-4.1.0 → flextool-4.1.1}/flextool.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flextool
-Version: 4.1.0
+Version: 4.1.1
 Summary: IRENA FlexTool is an energy and power systems model for understanding the role of variable power generation in future energy systems.
 Author: IRENA FlexTool contributors
 License: © International Renewable Energy Agency 2018-2022

{flextool-4.1.0 → flextool-4.1.1}/flextool.egg-info/SOURCES.txt

@@ -53,6 +53,7 @@ flextool/engine_polars/_benders.py
 flextool/engine_polars/_block_layout.py
 flextool/engine_polars/_blocks.py
 flextool/engine_polars/_commodity_ladder.py
+flextool/engine_polars/_constants.py
 flextool/engine_polars/_cumulative_invest.py
 flextool/engine_polars/_db_loader.py
 flextool/engine_polars/_db_reader.py

{flextool-4.1.0 → flextool-4.1.1}/pyproject.toml

@@ -3,7 +3,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flextool"
-version = "4.1.0"
+version = "4.1.1"
 description = "IRENA FlexTool is an energy and power systems model for understanding the role of variable power generation in future energy systems."
 readme = "README.md"
 license = { file = "LICENSE.txt" }