flextool 4.0.4__tar.gz → 4.1.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flextool
-Version: 4.0.4
+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
@@ -38,11 +38,11 @@ Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
-Requires-Dist: polar-high>=3.7.0
-Requires-Dist: highspy<=1.14.0,>=1.14.0
-Requires-Dist: polars>=1.40
-Requires-Dist: pandas
-Requires-Dist: spinedb-api
+Requires-Dist: polar-high>=3.8.0
+Requires-Dist: highspy<1.15,>=1.14.0
+Requires-Dist: polars<3,>=1.40
+Requires-Dist: pandas<4,>=2.2.3
+Requires-Dist: spinedb-api<0.37,>=0.36.5
 Requires-Dist: openpyxl
 Requires-Dist: odfpy
 Requires-Dist: python-calamine

{flextool-4.0.4 → flextool-4.1.1}/flextool/cli/cmd_open_results_db.py

@@ -33,6 +33,7 @@ from pathlib import Path
 
 from flextool.cli._console import run_tool
 from flextool.cli.cmd_run_flextool import resolve_output_path
+from flextool.gui.platform_utils import spine_db_editor_argv
 
 
 def resolve_results_db_path(project_folder_file, output_location=None):
@@ -100,16 +101,10 @@ def _build_launch_argv(db_urls):
     ``db_urls`` may be a single URL string or a list of URLs (each becomes a
     tab).  The supported standalone entry point is
     ``spinetoolbox.spine_db_editor.main:main``, whose ``main()`` reads
-    positional ``url`` args.
+    positional ``url`` args.  Shared with the GUI launchers
+    (:func:`flextool.gui.platform_utils.spine_db_editor_argv`).
     """
-    if isinstance(db_urls, str):
-        db_urls = [db_urls]
-    return [
-        sys.executable,
-        "-m",
-        "spinetoolbox.spine_db_editor.main",
-        *db_urls,
-    ]
+    return spine_db_editor_argv(db_urls)
 
 
 def launch_db_editor(db_urls, _popen=subprocess.Popen):

{flextool-4.0.4 → flextool-4.1.1}/flextool/engine_polars/_axis_enums.py

@@ -105,6 +105,9 @@ _AXIS_SYNONYMS: dict[str, str] = {
     "b_f": "block",
     # Period history column — holds period tokens (subset of d).
     "d_h": "d",
+    # Scenario-lineage pair column (``dd_same_scenario``, recourse plan
+    # §6b Slice A) — holds period tokens (subset of d).
+    "d_other": "d",
     # ``d_first`` — column holding period tokens of "first" periods
     # (e.g. in ``_lifetime_expired_pairs_lf`` cascade).  Subset of d.
     "d_first": "d",

{flextool-4.0.4 → flextool-4.1.1}/flextool/engine_polars/_benders.py

@@ -114,6 +114,10 @@ from flextool.engine_polars.autoscale import (
     unscale_solution,
 )
 from flextool.engine_polars._region_filter import HalfFlow, RegionSplit
+from flextool.engine_polars._solve_state import FlexToolConfigError
+from flextool.engine_polars._stochastic_detect import (
+    is_genuinely_stochastic as _is_genuinely_stochastic,
+)
 from flextool.engine_polars.input import FlexData
 
 _logger = logging.getLogger(__name__)
@@ -2043,6 +2047,18 @@ def solve_benders(
     -------
     BendersResult
     """
+    # Slice C Guard 2 (defensive): a caller reaching solve_benders while
+    # bypassing _run_benders_solve (the primary guard site) still fails
+    # loudly on a stochastic model.  Same shared detector on the master
+    # ``data``.  Benders x stochastics is not supported (recourse plan §4).
+    if _is_genuinely_stochastic(data):
+        raise FlexToolConfigError(
+            "solve_benders called on a stochastic model "
+            "(period__branch has non-realized branch periods with active "
+            "time); Benders x stochastics is not supported "
+            "(recourse plan §4)."
+        )
+
     if build_problem is None:
         def build_problem(pb, d):
             _build_flextool(pb, d, scale_the_objective=scale_the_objective)

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.0.4 → flextool-4.1.1}/flextool/engine_polars/_cumulative_invest.py

@@ -722,6 +722,57 @@ def _emit_group_invest_period(m, d, vars: dict,
 # ---------------------------------------------------------------------------
 # Group invest / divest — total scope
 
+def _emit_group_total_divest_cap(
+    m, *, legacy_name: str, path_name: str, outer: pl.DataFrame,
+    ge: pl.DataFrame, axis: str, var, unitsize, cap_param,
+    sense: str, d_leaf,
+) -> None:
+    """Per-path divest-group total cap (design §7.2 (G) item 4).
+
+    The divest group total sums ``v_divest * unitsize`` over ALL ``d``
+    (``edd_set`` is None on the divest side) grouped by ``g`` — under
+    recourse that cross-scenario double-counts one cap.  When more than
+    one scenario leaf covers the divest periods (recourse, sense
+    ``"<="``), emit ``path_name`` indexed by ``(g, leaf)`` with the
+    inner sum masked to each leaf's periods.  Single leaf — deterministic
+    / flag-off — or the ``">="`` floor keeps the legacy ``over=g`` shape
+    and NAME (byte-parity; the design registers only the ``max`` path
+    cap).
+    """
+    dl = None
+    if (sense == "<=" and d_leaf is not None
+            and getattr(d_leaf, "height", 0) > 0):
+        inv_periods = var.frame.select("d").unique()
+        _d_dt = var.frame.schema["d"]
+        dlx = d_leaf
+        if dlx.schema["d"] != _d_dt:
+            dlx = dlx.with_columns(pl.col("d").cast(_d_dt, strict=False))
+        dl = dlx.join(inv_periods, on="d", how="semi")
+    n_leaves = (dl["leaf"].n_unique()
+                if dl is not None and dl.height > 0 else 1)
+    if n_leaves <= 1:
+        m.add_cstr(
+            legacy_name,
+            over      = outer,
+            sense     = sense,
+            lhs_terms = {"divest_grp": Sum(Where(var * unitsize, ge),
+                                           over=(axis, "d"))},
+            rhs_terms = {"cap": cap_param},
+        )
+        return
+    mask = ge.join(dl, how="cross")
+    over_path = outer.join(dl.select("leaf").unique().sort("leaf"),
+                           how="cross")
+    m.add_cstr(
+        path_name,
+        over      = over_path,
+        sense     = sense,
+        lhs_terms = {"divest_grp": Sum(Where(var * unitsize, mask),
+                                       over=(axis, "d"))},
+        rhs_terms = {"cap": cap_param},
+    )
+
+
 def _emit_group_invest_total(m, d, vars: dict,
                               kind: str, sense: str) -> None:
     """Mod:
@@ -852,16 +903,18 @@ def _emit_group_invest_total(m, d, vars: dict,
                 pl.col("p").is_in(v_p.frame["p"].unique())) \
                 .filter(pl.col("g").is_in(g_set["g"].unique()))
             if ge_p.height > 0:
-                lhs = Sum(
-                    Where(v_p * d.p_unitsize, ge_p),
-                    over=("p", "d"),
-                )
-                m.add_cstr(
-                    f"{name}_p",
-                    over      = outer,
-                    sense     = sense,
-                    lhs_terms = {"divest_grp": lhs},
-                    rhs_terms = {"cap": cap_param},
+                _emit_group_total_divest_cap(
+                    m,
+                    legacy_name = f"{name}_p",
+                    path_name   = f"{name}_path_p",
+                    outer       = outer,
+                    ge          = ge_p,
+                    axis        = "p",
+                    var         = v_p,
+                    unitsize    = d.p_unitsize,
+                    cap_param   = cap_param,
+                    sense       = sense,
+                    d_leaf      = getattr(d, "d_leaf", None),
                 )
         # Node branch
         if v_n is not None and d.p_state_unitsize is not None:
@@ -876,16 +929,18 @@ def _emit_group_invest_total(m, d, vars: dict,
                 pl.col("n").is_in(v_n.frame["n"].unique())) \
                 .filter(pl.col("g").is_in(g_set["g"].unique()))
             if ge_n.height > 0:
-                lhs = Sum(
-                    Where(v_n * us_n, ge_n),
-                    over=("n", "d"),
-                )
-                m.add_cstr(
-                    f"{name}_n",
-                    over      = outer,
-                    sense     = sense,
-                    lhs_terms = {"divest_grp": lhs},
-                    rhs_terms = {"cap": cap_param},
+                _emit_group_total_divest_cap(
+                    m,
+                    legacy_name = f"{name}_n",
+                    path_name   = f"{name}_path_n",
+                    outer       = outer,
+                    ge          = ge_n,
+                    axis        = "n",
+                    var         = v_n,
+                    unitsize    = us_n,
+                    cap_param   = cap_param,
+                    sense       = sense,
+                    d_leaf      = getattr(d, "d_leaf", None),
                 )
 
 

{flextool-4.0.4 → flextool-4.1.1}/flextool/engine_polars/_delay.py

@@ -98,6 +98,7 @@ from polar_high import Sum, Where, Param
 # Engine imports kept light — we don't introduce new variable types.
 
 from ._axis_enums import cast_dim
+from ._derived_params import process_delayed__duration_from_weight
 from ._emit_provider_io import _provider_key
 
 
@@ -176,11 +177,10 @@ def load_data(inp_dir: str | Path, sd_dir: str | Path, *,
 
     pd_df = pd_df.rename({"process": "p"}) if "process" in pd_df.columns else pd_df
 
-    # Δ.12-drop: ``process_delayed__duration`` (set frame, not Param)
-    # produced authoritatively by
-    # ``apply_direct_params.process_delayed__duration_from_source``.
-    # Seed dropped.
-    pdd_df = None
+    # ``process_delayed__duration`` is derived from the delay-weight
+    # keys below (``_derived_params.process_delayed__duration_from_weight``,
+    # the same producer the DB path uses), so its ``td`` labels match
+    # ``dtt__delay_duration`` and ``p_process_delay_weight`` exactly.
 
     # process_source_(un)delayed: (process, source) frames
     def _read_pse(name: str) -> pl.DataFrame | None:
@@ -255,7 +255,12 @@ def load_data(inp_dir: str | Path, sd_dir: str | Path, *,
             rename_map["time_sink"] = "t_sink"
         if "delay_duration" in raw.columns:
             rename_map["delay_duration"] = "td"
-        dtt_df = raw.rename(rename_map).select("d", "t_source", "t_sink", "td")
+        # ``td`` is a duration in hours: Float64, as on the DB path
+        # (``dtt__delay_duration_from_source``).  The CSV carries it as
+        # text whose formatting may differ between writers ("1" / "1.0").
+        dtt_df = (raw.rename(rename_map)
+                  .select("d", "t_source", "t_sink",
+                          pl.col("td").cast(pl.Float64)))
 
     pw_path = sd / "p_process_delay_weight.csv"
     pw_param = None
@@ -266,8 +271,11 @@ def load_data(inp_dir: str | Path, sd_dir: str | Path, *,
             rename_map["process"] = "p"
         if "delay_duration" in raw.columns:
             rename_map["delay_duration"] = "td"
-        pw_long = raw.rename(rename_map).select("p", "td", "value")
+        pw_long = raw.rename(rename_map).select(
+            "p", pl.col("td").cast(pl.Float64),
+            pl.col("value").cast(pl.Float64))
         pw_param = Param(("p", "td"), pw_long)
+    pdd_df = process_delayed__duration_from_weight(pw_param)
 
     return dict(
         process_delayed              = pd_df.select("p"),
@@ -281,6 +289,106 @@ def load_data(inp_dir: str | Path, sd_dir: str | Path, *,
     )
 
 
+# ---------------------------------------------------------------------------
+# Consistency check
+
+class DelayDataError(RuntimeError):
+    """The delay tables of a delayed unit do not line up.
+
+    An internal wiring error, raised instead of building a conversion
+    equation without the unit's input (which forces its output to zero
+    without any message).
+    """
+
+
+def _p_utf8(df: pl.DataFrame, cols: tuple[str, ...]) -> pl.DataFrame:
+    return df.select(pl.col(c).cast(pl.Utf8) for c in cols).unique()
+
+
+def check_delay_tables(d) -> None:
+    """Raise :class:`DelayDataError` unless every delayed indirect unit can
+    get its delayed input term.
+
+    ``conversion_indirect`` takes a delayed unit's inputs out of the
+    undelayed sum (``process_delayed``), so the delayed term must cover
+    them.  For every unit in ``process_delayed`` that is indirect and has
+    inputs (``process_input_flows``):
+
+    * it has delayed input arcs (``process_source_sink_delayed``);
+    * it has ``process_delayed__duration`` rows;
+    * ``td`` has the same dtype in ``process_delayed__duration``,
+      ``dtt__delay_duration`` and ``p_process_delay_weight``;
+    * every ``(p, td)`` has ``dtt__delay_duration`` rows and a weight.
+
+    Delayed connections are not indirect and are not checked here (no
+    delayed term applies to them).
+    """
+    if not has_feature(d):
+        return
+    indirect = getattr(d, "process_indirect", None)
+    inputs = getattr(d, "process_input_flows", None)
+    if indirect is None or indirect.height == 0 or inputs is None:
+        return
+    units = (_p_utf8(d.process_delayed, ("p",))
+             .join(_p_utf8(indirect, ("p",)), on="p", how="semi")
+             .join(_p_utf8(inputs, ("p",)), on="p", how="semi"))
+    if units.height == 0:
+        return
+    names = sorted(units["p"].to_list())
+
+    def _fail(msg: str, which: list[str]) -> None:
+        raise DelayDataError(
+            f"delayed unit(s) {', '.join(which)}: {msg}. Their inputs are "
+            "excluded from the undelayed conversion, so the unit would "
+            "be forced to zero output.")
+
+    psse = getattr(d, "process_source_sink_delayed", None)
+    if psse is None or psse.height == 0:
+        _fail("no delayed input arcs (process_source_sink_delayed)", names)
+    arcs = (psse.select(pl.col(c).cast(pl.Utf8) for c in ("p", "sink"))
+            .filter(pl.col("sink") == pl.col("p")).select("p").unique())
+    missing = units.join(arcs, on="p", how="anti")
+    if missing.height > 0:
+        _fail("no delayed input arcs (process_source_sink_delayed)",
+              sorted(missing["p"].to_list()))
+
+    pdd = getattr(d, "process_delayed__duration", None)
+    dtt = getattr(d, "dtt__delay_duration", None)
+    pw = getattr(d, "p_process_delay_weight", None)
+    if pdd is None or pdd.height == 0:
+        _fail("no delay durations (process_delayed__duration)", names)
+    missing = units.join(_p_utf8(pdd, ("p",)), on="p", how="anti")
+    if missing.height > 0:
+        _fail("no delay durations (process_delayed__duration)",
+              sorted(missing["p"].to_list()))
+    if dtt is None or dtt.height == 0:
+        _fail("no time-shift rows (dtt__delay_duration)", names)
+    if pw is None or pw.frame.height == 0:
+        _fail("no delay weights (p_process_delay_weight)", names)
+    dtypes = {"process_delayed__duration": pdd.schema["td"],
+              "dtt__delay_duration": dtt.schema["td"],
+              "p_process_delay_weight": pw.frame.schema["td"]}
+    if len(set(dtypes.values())) != 1:
+        _fail("delay duration (td) dtypes differ: "
+              + ", ".join(f"{k} {v}" for k, v in dtypes.items()), names)
+    used = (pdd.with_columns(pl.col("p").cast(pl.Utf8))
+            .join(units, on="p", how="semi"))
+    no_shift = used.join(dtt.select("td").unique(), on="td", how="anti")
+    if no_shift.height > 0:
+        _fail("delay duration(s) without time-shift rows "
+              "(dtt__delay_duration): "
+              + ", ".join(f"{p} {td!r}" for p, td in no_shift.iter_rows()),
+              sorted(set(no_shift["p"].to_list())))
+    no_weight = used.join(
+        pw.frame.select(pl.col("p").cast(pl.Utf8), "td"),
+        on=["p", "td"], how="anti")
+    if no_weight.height > 0:
+        _fail("delay duration(s) without a weight "
+              "(p_process_delay_weight): "
+              + ", ".join(f"{p} {td!r}" for p, td in no_weight.iter_rows()),
+              sorted(set(no_weight["p"].to_list())))
+
+
 # ---------------------------------------------------------------------------
 # Constraint contribution
 
@@ -313,10 +421,12 @@ def delayed_input_expr(d, v_flow):
       * ``Sum`` over (source, td) leaves dims (p, d, t).
 
     Returns ``None`` when there's no delayed-process data (caller should
-    use a no-op).
+    use a no-op).  Raises :class:`DelayDataError` when a delayed indirect
+    unit's tables do not line up (:func:`check_delay_tables`).
     """
     if not has_feature(d):
         return None
+    check_delay_tables(d)
     if d.dtt__delay_duration is None or d.p_process_delay_weight is None:
         return None
     if d.process_source_delayed is None or d.process_delayed__duration is None: