flextool 4.0.0__py3-none-any.whl

flextool/__init__.py

@@ -0,0 +1,41 @@
+"""FlexTool energy system optimization model package."""
+import os as _os
+# jemalloc decay config — set BEFORE the first ``import polars`` (which
+# happens transitively in the imports just below).  polars statically
+# links jemalloc; jemalloc reads ``_RJEM_MALLOC_CONF`` exactly once at
+# .so load.  Its default ``dirty_decay_ms`` (~10 s) is longer than the
+# gap between rolling-solve rolls, so each roll's freed GB-scale
+# coefficient frames stay resident as dirty pages when the next roll
+# starts allocating — the per-roll ``priv_dirty`` floor ratchets up
+# (~+2 GB/roll on the 9-roll DES run).  ``dirty_decay_ms:1000`` purges a
+# roll's freed pages ~1 s after they go idle (well before the next roll,
+# which takes minutes) without eagerly madvise-ing on every transient
+# free inside a hot operation.  ``muzzy_decay_ms:0`` forces MADV_DONTNEED
+# (so Private_Dirty actually drops) rather than leaving pages as
+# reclaimable-but-resident MADV_FREE.  glibc knobs (MALLOC_ARENA_MAX,
+# malloc_trim) do NOT touch polars memory — this is the lever that does.
+# ``setdefault`` so a shell-provided value still wins (A/B profiling).
+_os.environ.setdefault("_RJEM_MALLOC_CONF", "dirty_decay_ms:1000,muzzy_decay_ms:0")
+import warnings as _warnings
+# Silence requests' RequestsDependencyWarning.  The FlexTool venv ships a
+# ``requests`` whose pinned urllib3/charset_normalizer version ranges lag the
+# (working) installed versions, so ``import requests`` warns once at import
+# time.  It is harmless but leaks into Spine Toolbox's Tool console for any
+# path that pulls in requests (e.g. an ``http://`` Spine DB-server URL).
+# Match by message — set BEFORE requests is imported transitively below — so
+# we needn't import requests here just to reference its warning class, and the
+# filter stays robust across the venv's exact version numbers.
+_warnings.filterwarnings(
+    "ignore",
+    message=r"urllib3 .*doesn't match a supported version",
+)
+__all__ = [
+    'write_outputs',
+    'migrate_database',
+    'initialize_database',
+    'update_flextool',
+]
+from flextool.process_outputs import write_outputs  # noqa: E402  (after env/warning config above)
+from flextool.update_flextool import migrate_database, initialize_database, update_flextool  # noqa: E402
+
+name = "flextool"

flextool/_mem_sampler.py

@@ -0,0 +1,193 @@
+"""In-process memory sampler — timestamped, allocator-aware memory trace.
+
+RSS is a poor signal for this workload: it conflates shared, clean, and
+allocator-reserved-but-free pages with genuinely-live private data.  This
+sampler additionally records, per sample:
+
+* ``pss_gb`` / ``priv_dirty_gb`` / ``proc_swap_gb`` — from
+  ``/proc/self/smaps_rollup``.  ``Private_Dirty + Swap`` is the
+  allocator-agnostic "what this process truly owns" number (counts dirty
+  anon pages whether they live in glibc, mimalloc, or the C++ heap, and
+  whether resident or swapped).
+* ``glibc_inuse_gb`` / ``glibc_free_gb`` / ``glibc_mmap_gb`` — from
+  glibc ``mallinfo2()`` (``uordblks`` / ``fordblks`` / ``hblkhd``).  The
+  *live-vs-reserved* discriminator: ``fordblks`` is memory glibc has
+  freed but is holding on its arena free-list rather than returning to
+  the OS (what ``malloc_trim`` would release).  NOTE: only sees the glibc
+  allocator — HiGHS/C++ go through glibc, but polars (Rust) may use its
+  own allocator, so a large ``priv_dirty`` with small ``glibc_inuse``
+  points at the non-glibc (polars) side.
+* ``mem_used_gb`` — system used (``MemTotal - MemAvailable``), the number
+  most desktop system monitors plot.  ``available_gb`` / ``swap_used_gb``
+  kept for back-compat.
+
+Gated by ``FLEXTOOL_MEM_SAMPLER``; interval via
+``FLEXTOOL_MEM_SAMPLER_INTERVAL_MS`` (default 100 ms).
+"""
+from __future__ import annotations
+
+import ctypes
+import datetime
+import os
+import sys
+import threading
+import time
+
+
+class _Mallinfo2(ctypes.Structure):
+    # glibc >= 2.33.  All fields size_t (the legacy ``mallinfo`` used int
+    # and overflows past 2 GB — useless here).
+    _fields_ = [
+        (n, ctypes.c_size_t)
+        for n in (
+            "arena", "ordblks", "smblks", "hblks", "hblkhd", "usmblks",
+            "fsmblks", "uordblks", "fordblks", "keepcost",
+        )
+    ]
+
+
+def _make_mallinfo2():
+    """Return a callable giving (inuse, free, mmap) bytes, or None."""
+    try:
+        libc = ctypes.CDLL("libc.so.6")
+        fn = libc.mallinfo2  # AttributeError on glibc < 2.33
+        fn.restype = _Mallinfo2
+        fn.argtypes = []
+    except (OSError, AttributeError):
+        return None
+
+    def _read():
+        mi = fn()
+        return mi.uordblks, mi.fordblks, mi.hblkhd
+
+    return _read
+
+
+def start_mem_sampler() -> None:
+    """Start a daemon thread that samples memory at a fixed interval if FLEXTOOL_MEM_SAMPLER is set."""
+    if os.environ.get("FLEXTOOL_MEM_SAMPLER", "").strip().lower() in ("", "0", "false"):
+        return
+
+    pid = os.getpid()
+    log_path = os.environ.get("FLEXTOOL_MEM_SAMPLER_LOG", f"/tmp/flextool_mem_sampler_{pid}.log")
+    try:
+        interval_ms = max(20, min(10000, int(os.environ.get("FLEXTOOL_MEM_SAMPLER_INTERVAL_MS", "100"))))
+    except ValueError:
+        interval_ms = 100
+    interval_s = interval_ms / 1000.0
+
+    if not sys.platform.startswith("linux"):
+        with open(log_path, "a", buffering=1) as _f:
+            _f.write(
+                f"# flextool memory sampler pid={pid} WARNING: platform is not "
+                f"linux — sampler disabled\n"
+            )
+        return
+
+    _GB = float(2 ** 30)
+    _mallinfo2 = _make_mallinfo2()
+
+    def _read_kv_bytes(path: str, keys: tuple[str, ...]) -> dict[str, int]:
+        """Parse ``Key:   N kB`` lines from a /proc file → bytes."""
+        out: dict[str, int] = {}
+        want = set(keys)
+        with open(path) as fh:
+            for line in fh:
+                k = line.split(":", 1)[0]
+                if k in want:
+                    out[k] = int(line.split()[1]) * 1024
+                    if len(out) == len(want):
+                        break
+        return out
+
+    def _sample() -> dict[str, float]:
+        # Per-process private cost — allocator-agnostic.
+        rss = pss = priv_dirty = proc_swap = 0
+        try:
+            r = _read_kv_bytes(
+                "/proc/self/smaps_rollup",
+                ("Rss", "Pss", "Private_Dirty", "Swap"),
+            )
+            rss = r.get("Rss", 0)
+            pss = r.get("Pss", 0)
+            priv_dirty = r.get("Private_Dirty", 0)
+            proc_swap = r.get("Swap", 0)
+        except Exception:
+            pass
+        if rss == 0:
+            # smaps_rollup unavailable — fall back to VmRSS.
+            try:
+                rss = _read_kv_bytes("/proc/self/status", ("VmRSS",)).get("VmRSS", 0)
+            except Exception:
+                pass
+
+        # System-wide.
+        mem_total = mem_avail = swap_total = swap_free = 0
+        try:
+            m = _read_kv_bytes(
+                "/proc/meminfo",
+                ("MemTotal", "MemAvailable", "SwapTotal", "SwapFree"),
+            )
+            mem_total = m.get("MemTotal", 0)
+            mem_avail = m.get("MemAvailable", 0)
+            swap_total = m.get("SwapTotal", 0)
+            swap_free = m.get("SwapFree", 0)
+        except Exception:
+            pass
+
+        # glibc allocator breakdown — live vs reserved-free.
+        g_inuse = g_free = g_mmap = -1
+        if _mallinfo2 is not None:
+            try:
+                g_inuse, g_free, g_mmap = _mallinfo2()
+            except Exception:
+                pass
+
+        return {
+            "rss_gb": rss / _GB,
+            "pss_gb": pss / _GB,
+            "priv_dirty_gb": priv_dirty / _GB,
+            "proc_swap_gb": proc_swap / _GB,
+            "available_gb": mem_avail / _GB,
+            "mem_used_gb": (mem_total - mem_avail) / _GB,
+            "swap_used_gb": (swap_total - swap_free) / _GB,
+            "glibc_inuse_gb": g_inuse / _GB if g_inuse >= 0 else -1.0,
+            "glibc_free_gb": g_free / _GB if g_free >= 0 else -1.0,
+            "glibc_mmap_gb": g_mmap / _GB if g_mmap >= 0 else -1.0,
+        }
+
+    started_at = datetime.datetime.now(datetime.UTC).isoformat()
+    # Stable column order so post-hoc parsing is trivial.
+    _cols = (
+        "rss_gb", "pss_gb", "priv_dirty_gb", "proc_swap_gb",
+        "available_gb", "mem_used_gb", "swap_used_gb",
+        "glibc_inuse_gb", "glibc_free_gb", "glibc_mmap_gb",
+    )
+
+    def _loop(log_path: str, interval_s: float) -> None:
+        mono_start = time.monotonic()
+        with open(log_path, "a", buffering=1) as f:
+            f.write(
+                f"# flextool memory sampler pid={pid} started_at={started_at} "
+                f"interval_ms={interval_ms} mallinfo2={'yes' if _mallinfo2 else 'no'}\n"
+            )
+            f.write("# priv_dirty_gb+proc_swap_gb = true private cost; "
+                    "glibc_free_gb = held-free (malloc_trim-able); "
+                    "mem_used_gb = system used (monitor metric)\n")
+            while True:
+                ts = datetime.datetime.now(datetime.UTC).isoformat()
+                mono_s = time.monotonic() - mono_start
+                try:
+                    s = _sample()
+                    parts = "\t".join(f"{c}={s[c]:.4f}" for c in _cols)
+                    line = f"ts={ts}\tmono_s={mono_s:.3f}\tepoch={time.time():.3f}\t{parts}\n"
+                except Exception as exc:
+                    line = f"ts={ts}\tmono_s={mono_s:.3f}\tepoch={time.time():.3f}\terror={repr(exc)}\n"
+                f.write(line)
+                # Explicit flush so the last samples before SIGKILL reach disk;
+                # line-buffered mode alone won't flush until the process exits cleanly.
+                f.flush()
+                time.sleep(interval_s)
+
+    t = threading.Thread(target=_loop, args=(log_path, interval_s), name="flextool-mem-sampler", daemon=True)
+    t.start()

flextool/_resources.py

@@ -0,0 +1,43 @@
+"""Locate bundled FlexTool package data files.
+
+Static FlexTool resources — schema JSONs, YAML/text templates, and
+canonical-database sources (all under ``flextool/schemas/``), plus the HiGHS
+options template (``flextool/bin/``) — must be reached through
+:mod:`importlib.resources` rather than ``Path(__file__).resolve()``
+walks.  After ``pip install flextool`` the package is the only thing
+on ``sys.path``; the historical layout where these dirs sat at the
+*repo root* alongside the package no longer exists.
+
+Two helpers are exposed:
+
+``package_data_path(relative)``
+    Returns a :class:`pathlib.Path` to a resource inside the
+    ``flextool`` package, e.g.
+    ``package_data_path("schemas/default_plots.yaml")``.
+    Editable installs return the real on-disk path; wheel installs
+    return the unpacked site-packages path (importlib.resources
+    materialises zipped data on demand, but we never ship zipped so
+    in practice this is always a stable filesystem path).
+
+``package_data_text(relative)``
+    Convenience wrapper that returns the file contents as a string —
+    handy when the caller doesn't actually need a path (YAML/JSON
+    parsing).
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+import flextool
+
+
+def package_data_path(relative: str) -> Path:
+    """Path to ``flextool/<relative>`` inside the installed package."""
+    return Path(resources.files(flextool).joinpath(relative))
+
+
+def package_data_text(relative: str) -> str:
+    """Text contents of ``flextool/<relative>``."""
+    return resources.files(flextool).joinpath(relative).read_text(encoding="utf-8")

flextool/calibrate/__init__.py

@@ -0,0 +1,51 @@
+"""FlexTool energy-margin calibrator package.
+
+The calibrator drives an investment+dispatch solve each iteration by
+shelling out to :mod:`flextool.cli.cmd_run_flextool`, then reads the
+per-node unserved-energy slack from the produced outputs to decide how to
+adjust the energy margin.  This package hosts that loop (the ``C1`` CLI,
+``python -m flextool.calibrate``, lands here) and its building blocks.
+
+The first building block is the resilient solve-success detector in
+:mod:`flextool.calibrate._solve_status` — it decides "did this solve
+actually succeed?" from the solve's *output directory* plus the (weak)
+subprocess exit code, tolerating a known model-specific post-solve writer
+crash that can bubble to a nonzero exit even when every output is present.
+"""
+
+from __future__ import annotations
+
+from flextool.calibrate._final_outputs import (
+    FINAL_WRITE_METHOD_CHOICES,
+    write_final_outputs,
+)
+from flextool.calibrate._loop import (
+    CalibConfig,
+    CalibError,
+    CalibResult,
+    IterRecord,
+    run_calibration,
+)
+from flextool.calibrate._report import format_summary, write_report
+from flextool.calibrate._solve_status import (
+    OutputCheck,
+    SolveOutcome,
+    assess_solve,
+    default_required_outputs,
+)
+
+__all__ = [
+    "FINAL_WRITE_METHOD_CHOICES",
+    "CalibConfig",
+    "CalibError",
+    "CalibResult",
+    "IterRecord",
+    "OutputCheck",
+    "SolveOutcome",
+    "assess_solve",
+    "default_required_outputs",
+    "format_summary",
+    "run_calibration",
+    "write_final_outputs",
+    "write_report",
+]

flextool/calibrate/__main__.py

@@ -0,0 +1,11 @@
+"""``python -m flextool.calibrate`` entry point.
+
+Delegates to :func:`flextool.calibrate._cli.main` so the calibrator can be
+launched as a module.
+"""
+
+from __future__ import annotations
+
+from flextool.calibrate._cli import main
+
+raise SystemExit(main())

flextool/calibrate/_cli.py

@@ -0,0 +1,316 @@
+"""Command-line front end for the adequacy-margin calibrator (C2).
+
+Wires the argument surface onto :class:`~flextool.calibrate._loop.CalibConfig`,
+runs :func:`~flextool.calibrate._loop.run_calibration`, then renders the
+report CSVs and prints the human-readable summary.  Exposed as
+``python -m flextool.calibrate`` via :mod:`flextool.calibrate.__main__`.
+
+The calibrator solves ``--iterations + 1`` times (iteration 0 is the
+baseline) and, for every shedding node, sizes an ``energy_margin_adder``
+increment that injects that node's residual unserved energy back as demand,
+damped and guarded against over-build.  This module is the operator's entry
+point to that loop.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from flextool.calibrate._loop import (
+    CalibConfig,
+    CalibError,
+    CalibResult,
+    run_calibration,
+)
+from flextool.calibrate._final_outputs import (
+    FINAL_WRITE_METHOD_CHOICES,
+    write_final_outputs,
+)
+from flextool.calibrate._report import format_summary, write_report
+
+DEFAULT_WORK_DIR = Path("calib_work")
+DEFAULT_OUT_ROOT = Path("calib_out")
+# Small positive default: convergence when total residual unserved energy is
+# at/below this many MWh (a single-MWh floor absorbs solver noise).
+DEFAULT_SLACK_THRESHOLD_MWH = 1.0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser for the calibrator CLI."""
+    parser = argparse.ArgumentParser(
+        prog="flextool.calibrate",
+        description=(
+            "Calibrate per-node energy-margin adders until every node's "
+            "residual unserved energy falls to/under the slack threshold, "
+            "freezing resource-capped nodes rather than over-building demand."
+        ),
+    )
+    parser.add_argument(
+        "db",
+        help="SpineDB URL (or path) of the model to calibrate.",
+    )
+    parser.add_argument(
+        "scenario",
+        help="Name of the scenario (model instance) to calibrate.",
+    )
+    parser.add_argument(
+        "--iterations",
+        type=int,
+        required=True,
+        help=(
+            "Number of ADJUSTMENT iterations after the baseline; the loop "
+            "runs iterations+1 solves (iteration 0 is the baseline)."
+        ),
+    )
+    parser.add_argument(
+        "--slack-threshold",
+        type=float,
+        default=DEFAULT_SLACK_THRESHOLD_MWH,
+        dest="slack_threshold_mwh",
+        help=(
+            "Convergence threshold in MWh: stop once total residual unserved "
+            "energy is at/under this value (default: "
+            f"{DEFAULT_SLACK_THRESHOLD_MWH})."
+        ),
+    )
+    parser.add_argument(
+        "--stall-fraction",
+        type=float,
+        default=0.05,
+        dest="stall_fraction",
+        help=(
+            "Over-build guard STALL fraction [0..1]. A shedding node whose "
+            "residual unserved energy drops by LESS than this fraction of its "
+            "prior gap in response to its own bump is frozen as resource-capped "
+            "(margin buys it no adequacy) and reported as needing firm "
+            "capacity / imports / storage. HIGHER freezes a stalled node "
+            "SOONER; 0.0 disables the guard. Default: 0.05."
+        ),
+    )
+    parser.add_argument(
+        "--over-build-tightness",
+        type=float,
+        default=0.05,
+        dest="over_build_tightness",
+        help=(
+            "DEPRECATED / no-op: retained for compatibility only. The "
+            "over-build guard now freezes on residual STALL (see "
+            "--stall-fraction), not curtailment efficiency, so this value is "
+            "not consulted. Default: 0.05."
+        ),
+    )
+    parser.add_argument(
+        "--damping-first-iteration",
+        type=float,
+        default=1.0,
+        dest="damping_first",
+        help=(
+            "Damping factor lambda applied to the FIRST correction "
+            "(increment = lambda * residual / W). 1.0 = full undamped step. "
+            "Default: 1.0."
+        ),
+    )
+    parser.add_argument(
+        "--damping-remaining-iterations",
+        type=float,
+        default=0.5,
+        dest="damping_remaining",
+        help=(
+            "Damping factor lambda applied to every correction AFTER the "
+            "first; lower damps oscillation as slack nears zero. Default: 0.5."
+        ),
+    )
+    parser.add_argument(
+        "--overshoot",
+        type=float,
+        default=1.0,
+        dest="overshoot",
+        help=(
+            "Planning-margin SAFETY multiplier on the sized margin (default "
+            "1.0 = off). A single-year (or single-year representative-period) "
+            "model under-estimates true multi-year severity, so a value >1 "
+            "deliberately over-provisions: overshoot=1.2 builds ~20%% beyond "
+            "the measured slack. Higher builds more headroom for unmodeled "
+            "multi-year risk; the right value is MODEL-DEPENDENT."
+        ),
+    )
+    parser.add_argument(
+        "--sizing",
+        choices=("uniform", "timed"),
+        default="uniform",
+        dest="sizing",
+        help=(
+            "Adder placement mode. 'uniform' (default): a constant "
+            "per-timestep margin sized lambda*residual/W. 'timed': the SAME "
+            "total energy placed per-cell at the low-VRE stress hours, folded "
+            "from node_slack_up_dt_e onto the representative timeline."
+        ),
+    )
+    parser.add_argument(
+        "--warm-start-cache-dir",
+        type=Path,
+        default=None,
+        dest="warm_start_cache_dir",
+        help=(
+            "Directory for the warm-start basis cache shared across "
+            "iterations (default: <work-dir>/warm_start_cache)."
+        ),
+    )
+    parser.add_argument(
+        "--work-dir",
+        type=Path,
+        default=DEFAULT_WORK_DIR,
+        dest="work_dir",
+        help=(
+            "Subprocess working directory for the per-iteration solves "
+            f"(default: {DEFAULT_WORK_DIR}/)."
+        ),
+    )
+    parser.add_argument(
+        "--output-location",
+        type=Path,
+        default=DEFAULT_OUT_ROOT,
+        dest="out_root",
+        help=(
+            "Output-location root; solve outputs land under "
+            "<output-location>/output_parquet/<scenario>/ and the report "
+            "CSVs under <output-location>/calibration_reports/<scenario>/ "
+            f"(default: {DEFAULT_OUT_ROOT}/)."
+        ),
+    )
+    parser.add_argument(
+        "--final-write-methods",
+        type=str,
+        nargs="+",
+        default=["csv"],
+        choices=list(FINAL_WRITE_METHOD_CHOICES),
+        dest="final_write_methods",
+        help=(
+            "After the loop, regenerate these output formats from the final "
+            "surviving parquet (<output-location>/output_parquet/<scenario>/) "
+            "WITHOUT re-solving — so the calibrated model's results are "
+            "available just like a regular run's. parquet is always present, "
+            "so it is not a choice here; the rest derive from it. "
+            "Default: csv. Use --skip-final-outputs to leave the results "
+            "parquet-only."
+        ),
+    )
+    parser.add_argument(
+        "--skip-final-outputs",
+        action="store_true",
+        dest="skip_final_outputs",
+        help=(
+            "Do not regenerate any non-parquet outputs after the loop; leave "
+            "the results as the parquet tree written by the final solve."
+        ),
+    )
+    parser.add_argument(
+        "--results-db-url",
+        type=str,
+        default=None,
+        dest="results_db_url",
+        help=(
+            "Target SpineDB URL for the 'spinedb' final-write-method (default: "
+            "<output-location>/results.sqlite). Only consulted when 'spinedb' "
+            "is in --final-write-methods."
+        ),
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help=(
+            "Archive each iteration's outputs to out_iter_<k>/ instead of "
+            "clearing them between iterations."
+        ),
+    )
+    return parser
+
+
+def _config_from_args(args: argparse.Namespace) -> CalibConfig:
+    """Translate parsed args into a :class:`CalibConfig`.
+
+    Fills the warm-start cache default relative to the work dir when the
+    operator did not pin one.
+    """
+    warm_start_cache_dir = args.warm_start_cache_dir
+    if warm_start_cache_dir is None:
+        warm_start_cache_dir = Path(args.work_dir) / "warm_start_cache"
+    # --skip-final-outputs wins over any requested formats.
+    final_write_methods = (
+        () if args.skip_final_outputs else tuple(args.final_write_methods)
+    )
+    return CalibConfig(
+        iterations=args.iterations,
+        slack_threshold_mwh=args.slack_threshold_mwh,
+        damping_first=args.damping_first,
+        damping_remaining=args.damping_remaining,
+        over_build_tightness=args.over_build_tightness,
+        warm_start_cache_dir=Path(warm_start_cache_dir),
+        work_dir=Path(args.work_dir),
+        out_root=Path(args.out_root),
+        debug=args.debug,
+        sizing=args.sizing,
+        overshoot=args.overshoot,
+        stall_fraction=args.stall_fraction,
+        final_write_methods=final_write_methods,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the calibrator from the command line.
+
+    Parses *argv* (or ``sys.argv``), runs the calibration, writes the report
+    CSVs under ``<output-location>/calibration_reports/<scenario>/``, prints the
+    summary to stdout, and (unless ``--skip-final-outputs``) regenerates the
+    requested non-parquet output formats from the final surviving parquet
+    without re-solving.  Returns 0 on success; on a fail-closed solve
+    (:class:`CalibError`) prints the reason to stderr and returns 1.
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    config = _config_from_args(args)
+
+    try:
+        result: CalibResult = run_calibration(args.db, args.scenario, config)
+    except CalibError as exc:
+        print(f"calibration failed: {exc}", file=sys.stderr)
+        return 1
+
+    # Namespace the report CSVs by scenario (matching output_parquet/<scenario>/)
+    # so calibrating several scenarios into one shared output-location root does
+    # not overwrite one scenario's report with the next.
+    report_dir = Path(config.out_root) / "calibration_reports" / args.scenario
+    write_report(result, out_dir=report_dir)
+    print(format_summary(result))
+    print(f"\nReport CSVs written under {report_dir}/")
+
+    # Regenerate the requested regular output formats from the final surviving
+    # parquet (no re-solve).  A failure here does NOT fail the calibration — the
+    # solve succeeded and its results are intact as parquet, so this is a
+    # convenience step; warn and still return 0.
+    if config.final_write_methods:
+        try:
+            written = write_final_outputs(
+                config.out_root,
+                args.scenario,
+                config.final_write_methods,
+                results_db_url=args.results_db_url,
+            )
+            print(
+                f"Final outputs ({', '.join(written)}) regenerated from parquet "
+                f"under {config.out_root}/"
+            )
+        except Exception as exc:  # noqa: BLE001 — never fail the run on output regen
+            print(
+                f"warning: could not regenerate final outputs "
+                f"({', '.join(config.final_write_methods)}) from parquet: {exc}. "
+                f"The parquet results under {config.out_root}/output_parquet/"
+                f"{args.scenario}/ are intact.",
+                file=sys.stderr,
+            )
+    return 0
+
+
+__all__ = ["build_parser", "main"]