d0fus 2.3.0__tar.gz → 2.3.3__tar.gz

{d0fus-2.3.0 → d0fus-2.3.3}/D0FUS.py

@@ -20,7 +20,7 @@ sys.path.insert(0, project_root)
 
 # Import all necessary modules
 from D0FUS_BIB.D0FUS_parameterization import *
-from D0FUS_EXE import D0FUS_scan, D0FUS_run, D0FUS_genetic
+from D0FUS_EXE import D0FUS_scan, D0FUS_run, D0FUS_genetic, D0FUS_uncertainty
 
 #%% Mode detection
 
@@ -41,6 +41,15 @@ def detect_mode_from_input(input_file):
     with open(input_file, 'r', encoding='utf-8') as f:
         content = f.read()
     
+    # UNCERTAINTY mode: an [UNCERTAINTY] section, or any tri()/norm()/unif()/envelope()
+    # marginal. Checked first so that optional map axes (a = [min, max, n]) do not make
+    # the file look like a SCAN.
+    if (re.search(r'^\s*\[\s*uncertainty\s*\]', content, re.MULTILINE | re.IGNORECASE)
+            or re.search(r'=\s*(tri|norm|unif|envelope)\s*\(', content, re.IGNORECASE)):
+        n_uncertain = len(re.findall(r'^\s*\w+\s*=\s*(?:tri|norm|unif|envelope)\s*\(',
+                                     content, re.MULTILINE | re.IGNORECASE))
+        return 'uncertainty', n_uncertain
+    
     # Extract genetic algorithm parameters if present
     genetic_params = {}
     genetic_keywords = {
@@ -239,11 +248,18 @@ Modes (detected automatically from input file format):
                        crossover_rate = 0.7     (default: 0.7)
                        mutation_rate = 0.2      (default: 0.2)
 
+    UNCERTAINTY mode:  Monte-Carlo robustness study around one design point
+                       An [UNCERTAINTY] section listing parameter ranges
+                       Example: H = tri(0.75, 1.5)
+                                betaN_limit = tri(2.8, 3.6)
+                                Scaling_Law = envelope(IPB98(y,2) | ITPA20)
+
 Detection rules:
     • [min, max] format (2 values) → OPTIMIZATION (need 2+ parameters)
     • [min, max, n] format (3 values) → SCAN (need exactly 2 parameters)
-    • No brackets → RUN
-    • Cannot mix formats in same file
+    • [UNCERTAINTY] section or tri()/norm()/unif()/envelope() → UNCERTAINTY
+    • No brackets (and no [UNCERTAINTY] section) → RUN
+    • Cannot mix scan and optimization formats in same file
 
 For help:
     python D0FUS.py --help
@@ -283,6 +299,9 @@ def select_input_file():
                 opt_params, genetic_params = params
                 param_names = list(opt_params.keys())
                 mode_str = f"GENETIC ({len(param_names)} params)"
+            elif mode == 'uncertainty':
+                mode_str = (f"UNCERTAINTY ({params} params)" if params
+                            else "UNCERTAINTY (Monte-Carlo)")
             else:
                 mode_str = "RUN"
             print(f"  {i}. {file.name:<30} [{mode_str}]")
@@ -389,6 +408,15 @@ def execute_with_mode_detection(input_file):
             
             # Run genetic optimization with specified or default parameters
             D0FUS_genetic.run_genetic_optimization(input_file, **ga_params)
+        
+        elif mode == 'uncertainty':
+            # UNCERTAINTY mode detected (Monte-Carlo robustness study)
+            print("\n" + "="*60)
+            print("Mode: UNCERTAINTY (Monte-Carlo robustness study)")
+            print(f"Input: {os.path.basename(input_file)}")
+            print("="*60 + "\n")
+            
+            D0FUS_uncertainty.main(input_file, save_figures=True)
     
     except ValueError as e:
         # Invalid number of brackets or parsing error

{d0fus-2.3.0 → d0fus-2.3.3}/D0FUS_BIB/D0FUS_figures.py

@@ -60,6 +60,7 @@ if __name__ != "__main__":
         f_CS_ACAD, f_CS_refined, f_CS_CIRCE,
         F_CIRCE0D, compute_von_mises_stress,
         calculate_E_mag_TF,
+        Number_TF_coils,
     )
     from .D0FUS_parameterization import DEFAULT_CONFIG, E_ELEM
 
@@ -90,6 +91,7 @@ else:
         f_CS_ACAD, f_CS_refined, f_CS_CIRCE,
         F_CIRCE0D, compute_von_mises_stress,
         calculate_E_mag_TF,
+        Number_TF_coils,
     )
     from D0FUS_BIB.D0FUS_parameterization import DEFAULT_CONFIG, E_ELEM
 
@@ -4016,8 +4018,11 @@ def build_conductor_from_run(run: dict, coil: str = "TF") -> dict:
     f_In    = run.get(f"f_In_{coil}", np.nan)
     sc_type = run.get("Supra_choice", "Nb3Sn")
 
-    # Steel asymmetry parameter: n = δ_S1/δ_S2 (1 = square, 0 = optimal)
-    n_cond = float(run.get(f"n_{coil}", 1.0))
+    # Steel asymmetry parameter: n = δ_S1/δ_S2 (1 = square, 0 = optimal).
+    # The run dict stores this as ``n_shape_TF`` / ``n_shape_CS`` (see
+    # _build_run_dict). The previous key ``n_{coil}`` never matched, so the
+    # aspect ratio silently stayed at 1.0 (square) for every run.
+    n_cond = float(run.get(f"n_shape_{coil}", 1.0))
 
     # Guard: fall back to static dict if any fraction is NaN or unphysical
     fallback = _CONDUCTOR_TF if coil == "TF" else _CONDUCTOR_CS
@@ -4026,8 +4031,16 @@ def build_conductor_from_run(run: dict, coil: str = "TF") -> dict:
         return fallback
     if not all(0.0 <= f <= 1.0 for f in fracs):
         return fallback
-    wost_sum = f_sc + f_cu + f_pipe + f_void + f_In
-    if abs(wost_sum - 1.0) > 0.05:
+
+    # The wost (non-steel) region is split into SIX area fractions that sum to
+    # one:  f_sc + f_cu + f_He_pipe + f_void + f_In + f_gap = 1.  The run dict
+    # only stores the first five; the sixth, f_gap (manufacturing / wrap gaps,
+    # passed to calculate_cable_current_density but not forwarded), is recovered
+    # here as the residual.  Earlier code summed only the five stored fractions
+    # and required the total to equal 1, so any deck with f_gap > 0 (the default
+    # 0.15) failed the check and silently reverted to the static Nb3Sn fallback.
+    f_gap = 1.0 - (f_sc + f_cu + f_pipe + f_void + f_In)
+    if not (-0.05 <= f_gap <= 1.0):
         return fallback
 
     # ── Jacket aspect ratio from δ_S1/δ_S2 geometry ──
@@ -4040,15 +4053,20 @@ def build_conductor_from_run(run: dict, coil: str = "TF") -> dict:
     # f_cable_total = wost_frac - f_insulation_total  (derived)
 
     # ── Level 2: renormalise wost fractions to cable-space ──
-    # cable-space = wost minus insulation → fraction of wost = (1 - f_In)
+    # cable-space = wost minus insulation → fraction of wost = (1 - f_In).
+    # f_gap is empty (non-conducting) area, so it is merged into the He void,
+    # which is rendered as the light-blue cable-space background.  This keeps
+    # the four Level-2 fractions summing to exactly one:
+    #   f_SC + f_Cu + f_He_pipe + f_void = 1
     f_cable_wost = 1.0 - f_In
     if f_cable_wost < 1e-6:
         return fallback
 
-    f_SC_cable      = f_sc   / f_cable_wost
-    f_Cu_cable      = f_cu   / f_cable_wost
-    f_He_pipe_cable = f_pipe / f_cable_wost
-    f_void_cable    = f_void / f_cable_wost
+    f_void_eff      = f_void + max(f_gap, 0.0)
+    f_SC_cable      = f_sc      / f_cable_wost
+    f_Cu_cable      = f_cu      / f_cable_wost
+    f_He_pipe_cable = f_pipe    / f_cable_wost
+    f_void_cable    = f_void_eff / f_cable_wost
 
     # Cu_nonCu = 0: each strand is rendered as either pure SC or pure Cu.
     # The correct visual ratio is already ensured by f_SC_cable / f_Cu_cable
@@ -4278,6 +4296,193 @@ def plot_CICC_cross_section(
 # Stand-alone execution — smoke test
 # =============================================================================
 
+
+# =============================================================================
+# 7. TF coil number - ripple and port-access constraints
+# =============================================================================
+
+# D0FUS-consistent palette (matches the hex codes used elsewhere in this file)
+_RIP_C_PLASMA = "#f4a582"   # plasma fill
+_RIP_C_COIL   = "#2166ac"   # TF coil footprint
+_RIP_C_ACCESS = "#4dac26"   # maintenance / heating access sector
+
+
+def plot_tf_ripple(
+    R0: float = 6.2,
+    a: float = 2.0,
+    b: float = 1.2,
+    ripple_adm: float = 0.01,
+    L_min: float = 3.6,
+    grid: int = 460,
+    save_dir: str | None = None,
+) -> None:
+    """
+    Top-view map of the toroidal field magnitude produced by the discrete TF
+    coils, illustrating the field ripple.
+
+    The coil number, ripple and outboard standoff (N_coil, ripple, Delta_ext)
+    are taken from the package routine ``Number_TF_coils`` so the figure stays
+    consistent with the D0FUS sizing.  Each coil is modelled as a pair of
+    infinite straight filaments (inner leg at R0 - a - b carrying +I, outer leg
+    at R0 + a + b + Delta_ext carrying -I, at the same toroidal angle); the field
+    magnitude |B| is evaluated on a Cartesian grid in the toroidal mid-plane.
+    The prefactor mu0*I/(2*pi) is dropped, so |B| is in arbitrary units.  The
+    iso-|B| contours scallop near the coils: that scalloping is the ripple.
+
+    Parameters
+    ----------
+    R0, a    : float   Major and minor radius [m].
+    b        : float   Aggregated inboard build (FW + blanket + shield + gaps) [m].
+    ripple_adm : float Admissible ripple fraction (default 1 %).
+    L_min    : float   Minimum toroidal access per coil [m] (default 3.6 m, the
+                       ITER-reproducing value; the manuscript also uses 3.0 m).
+    grid     : int     Number of grid points per axis for the field map.
+    save_dir : str or None
+
+    References
+    ----------
+    Wesson, Tokamaks, 4th ed., p.169 - ripple model.
+    Goldston & Rutherford, Introduction to Plasma Physics, IOP (1995), ch.14.
+    """
+    n_coil, ripple_sel, Delta_ext = Number_TF_coils(R0, a, b, ripple_adm, L_min)
+    R_in   = R0 - a - b
+    R_out  = R0 + a + b + Delta_ext
+    theta  = 2.0 * np.pi * np.arange(n_coil) / n_coil
+
+    # filament positions (inner + outer legs) and signed currents
+    fx = np.concatenate([R_in * np.cos(theta),  R_out * np.cos(theta)])
+    fy = np.concatenate([R_in * np.sin(theta),  R_out * np.sin(theta)])
+    cur = np.concatenate([np.ones(n_coil),      -np.ones(n_coil)])
+
+    # |B| on a Cartesian grid (loop over filaments to limit memory)
+    L = R_out + 0.7
+    gx = np.linspace(-L, L, grid)
+    X, Y = np.meshgrid(gx, gx)
+    Bx = np.zeros_like(X)
+    By = np.zeros_like(X)
+    dmin = np.full(X.shape, np.inf)
+    for xi, yi, ci in zip(fx, fy, cur):
+        dx = X - xi
+        dy = Y - yi
+        d2 = dx * dx + dy * dy
+        Bx += ci * (-dy) / d2
+        By += ci * (dx) / d2
+        dmin = np.minimum(dmin, np.sqrt(d2))
+    rr = np.sqrt(X ** 2 + Y ** 2)
+    Bmag = np.sqrt(Bx ** 2 + By ** 2)
+    # cap the colour scale to the plasma-region field, then hide near-wire
+    # spikes and the central column for legibility
+    vmax = np.percentile(Bmag[(rr > R0 - a) & (rr < R0 + a) & (dmin > 0.22)], 99)
+    Bmag = np.ma.array(Bmag, mask=(dmin < 0.22) | (rr < R0 - a))
+
+    th = np.linspace(0, 2 * np.pi, 400)
+    fig, ax = plt.subplots(figsize=(6.4, 5.9))
+    ax.set_aspect("equal")
+    pcm = ax.pcolormesh(X, Y, Bmag, shading="auto", cmap="magma", vmin=0, vmax=vmax)
+    ax.contour(X, Y, Bmag, levels=np.linspace(0.35 * vmax, vmax, 7),
+               colors="white", linewidths=0.45, alpha=0.55)
+    ax.add_patch(mpatches.Circle((0, 0), R0 - a, facecolor="0.75",
+                                 edgecolor="0.5", lw=0.8, zorder=4))
+    ax.text(0, 0, "central\ncolumn", ha="center", va="center", fontsize=8,
+            color="0.25", zorder=5)
+    ax.plot((R0 + a) * np.cos(th), (R0 + a) * np.sin(th), color="cyan",
+            lw=1.3, ls="--", alpha=0.9, zorder=4)
+    ax.plot(R_out * np.cos(th), R_out * np.sin(th), color="white", lw=0.7,
+            ls=":", alpha=0.5, zorder=4)
+    ax.plot(R_out * np.cos(theta), R_out * np.sin(theta), "o", color="white",
+            ms=5, mec="k", mew=0.5, zorder=5)
+    ax.text(0, (R0 + a) + 0.15, "plasma edge", color="cyan", fontsize=8,
+            ha="center", va="bottom", zorder=6)
+    ax.text(-L + 0.3, L - 0.5,
+            rf"$\delta_\mathrm{{ripple}} = {ripple_sel * 100:.2f}\,\%$",
+            color="white", fontsize=11, va="top")
+    ax.set_xlim(-L, L)
+    ax.set_ylim(-L, L)
+    ax.set_xlabel("x [m]", fontsize=12)
+    ax.set_ylabel("y [m]", fontsize=12)
+    ax.set_title(rf"Toroidal field magnitude, top view ($N_\mathrm{{coil}} = {n_coil}$)",
+                 fontsize=11)
+    fig.colorbar(pcm, ax=ax, shrink=0.85, label=r"$|B|$ (arb. units)")
+    plt.tight_layout()
+    _save_or_show(fig, save_dir, "tf_ripple")
+
+
+def plot_port_access(
+    R0: float = 6.2,
+    a: float = 2.0,
+    b: float = 1.2,
+    ripple_adm: float = 0.01,
+    L_min: float = 3.6,
+    save_dir: str | None = None,
+) -> None:
+    """
+    Clean top view of the tokamak showing the TF coils and the angular sectors
+    left free between them for maintenance and heating access.
+
+    The coil number and outboard standoff come from ``Number_TF_coils`` (same
+    call as plot_tf_ripple), so the layout matches the D0FUS sizing.
+
+    Parameters
+    ----------
+    R0, a, b   : float   Plasma geometry and aggregated inboard build [m].
+    ripple_adm : float   Admissible ripple fraction (for the N_coil selection).
+    L_min      : float   Minimum toroidal pitch per coil for maintenance [m].
+    save_dir   : str or None
+    """
+    n_coil, ripple_sel, Delta_ext = Number_TF_coils(R0, a, b, ripple_adm, L_min)
+    R_out = R0 + a + b + Delta_ext
+    theta_deg = np.degrees(2.0 * np.pi * np.arange(n_coil) / n_coil)
+    pitch = 360.0 / n_coil
+    coil_hw = 0.30 * pitch                         # illustrative coil half-width
+    band = (R_out + 0.6) - (R0 + a)
+
+    fig, ax = plt.subplots(figsize=(6.2, 6.0))
+    ax.set_aspect("equal")
+
+    # plasma annulus + central column
+    ax.add_patch(mpatches.Wedge((0, 0), R0 + a, 0, 360, width=2 * a,
+                                facecolor=_RIP_C_PLASMA, alpha=0.45, lw=0, zorder=1))
+    ax.add_patch(mpatches.Circle((0, 0), R0 - a, facecolor="0.85",
+                                 edgecolor="0.6", lw=0.8, zorder=2))
+    ax.text(0, 0, "central\ncolumn", ha="center", va="center", fontsize=8.5,
+            color="0.3", zorder=3)
+    ax.text(0, -R0, "plasma", ha="center", va="center", fontsize=9,
+            color="#9c4a2f", zorder=3,
+            bbox=dict(boxstyle="round,pad=0.15", fc="white", ec="none", alpha=0.7))
+
+    # access corridors (gaps) and coil footprints
+    for t in theta_deg:
+        ax.add_patch(mpatches.Wedge((0, 0), R_out + 0.6, t + coil_hw,
+                                    t + pitch - coil_hw, width=band,
+                                    facecolor=_RIP_C_ACCESS, alpha=0.16, lw=0,
+                                    zorder=2))
+        ax.add_patch(mpatches.Wedge((0, 0), R_out + 0.6, t - coil_hw,
+                                    t + coil_hw, width=1.7,
+                                    facecolor=_RIP_C_COIL, edgecolor="none",
+                                    alpha=0.95, zorder=3))
+
+    # single neutral label on one access sector
+    tlab = theta_deg[0] + pitch / 2
+    r_lab = R0 + a + 0.9
+    ax.annotate("maintenance /\nheating access",
+                xy=(r_lab * np.cos(np.radians(tlab)), r_lab * np.sin(np.radians(tlab))),
+                xytext=(1.12 * R_out, 1.02 * R_out), fontsize=9, color="#2f6b16",
+                ha="left", arrowprops=dict(arrowstyle="->", color="#2f6b16", lw=1.0))
+
+    ax.plot([], [], color=_RIP_C_COIL, lw=6, label=rf"TF coils ($N = {n_coil}$)")
+    ax.plot([], [], color=_RIP_C_ACCESS, lw=6, alpha=0.4, label="access sectors")
+    lim = R_out + 1.6
+    ax.set_xlim(-lim, lim)
+    ax.set_ylim(-lim, lim)
+    ax.set_xlabel("x [m]", fontsize=12)
+    ax.set_ylabel("y [m]", fontsize=12)
+    ax.set_title(rf"TF coils and maintenance access, top view ($N_\mathrm{{coil}} = {n_coil}$)",
+                 fontsize=11)
+    ax.legend(fontsize=9, loc="upper left")
+    plt.tight_layout()
+    _save_or_show(fig, save_dir, "port_access")
+
+
 if __name__ == "__main__":
 
     parser = argparse.ArgumentParser(
@@ -4339,4 +4544,304 @@ if __name__ == "__main__":
         "e_shield":    0.50,
     }
 
-    plot_all(ITER_RUN, save_dir=_out)
+    plot_all(ITER_RUN, save_dir=_out)
+# =============================================================================
+# UNCERTAINTY-MODE FIGURES
+# Appended to support the D0FUS UNCERTAINTY (Monte-Carlo) execution mode.
+# =============================================================================
+"""
+D0FUS_uncertainty_figures.py -- decision-oriented plots for the uncertainty study.
+
+Figures, in the D0FUS figure style (matplotlib, tab: palette, 150 dpi, tight box).
+Each figure carries a one-line plain-language reading note so it stands on its own:
+
+  - fig_robustness : single decomposition bar of the whole Monte-Carlo. Green is
+    feasible, coloured shares are infeasible cases split by the binding limit, grey
+    did not converge. P(feasible) is over ALL samples (a non-converging corner counts
+    as a failure).
+  - fig_margins : headroom to each plasma limit (P5/P50/P95 of the normalised margin).
+  - scan_feasibility + fig_scan : one-parameter feasibility scans with a traffic-light
+    background, so a glance places the design value in a safe / marginal / unlikely zone.
+  - fig_models : impact of the model-form choices (confinement scaling, elongation, ...)
+    on feasibility and on a key physics output, one row per model combination.
+"""
+import os
+from collections import Counter
+
+import numpy as np
+import matplotlib
+import matplotlib.pyplot as plt
+from matplotlib.patches import Patch
+
+_GREEN, _AMBER, _RED = 'tab:green', 'tab:orange', 'tab:red'
+_BIND_COLOR = {'greenwald': 'tab:blue', 'troyon': 'tab:red',
+               'kink': 'tab:purple', 'build': 'tab:brown'}
+_BIND_LABEL = {'greenwald': 'Greenwald-limited', 'troyon': 'Troyon-limited',
+               'kink': 'kink-limited', 'build': 'build infeasible'}
+# nice axis names for the scan
+_NICE = {'P_fus': 'fusion power  $P_{fus}$', 'R0': 'major radius  $R_0$',
+         'a': 'minor radius  $a$', 'Tbar': r'temperature  $\langle T \rangle$'}
+_UNIT = {'P_fus': '[MW]', 'R0': '[m]', 'a': '[m]', 'Tbar': '[keV]'}
+
+
+def _save(fig, save_dir, fname):
+    if save_dir:
+        os.makedirs(save_dir, exist_ok=True)
+        fig.savefig(os.path.join(save_dir, f"{fname}.png"), dpi=150, bbox_inches='tight')
+    return fig
+
+
+def _zone_color(p):
+    return _GREEN if p >= 85 else (_AMBER if p >= 60 else _RED)
+
+
+# =============================================================================
+# Figure 1 -- robustness verdict (single decomposition bar)
+# =============================================================================
+def fig_robustness(results, save_dir=None):
+    """Decompose the Monte-Carlo into feasible / per-limit infeasible / non-converged."""
+    all_rows = [r for k in results for r in results[k]]
+    n = max(len(all_rows), 1)
+    conv = [r for r in all_rows if r.get('converged')]
+    feas = [r for r in conv if r.get('feasible')]
+    n_noconv = len(all_rows) - len(conv)
+    binding = Counter(r.get('binding') for r in conv if not r.get('feasible'))
+
+    seg = [('feasible', len(feas), _GREEN)]
+    for c in ['greenwald', 'troyon', 'kink', 'build']:
+        if binding.get(c, 0):
+            seg.append((_BIND_LABEL[c], binding[c], _BIND_COLOR[c]))
+    if n_noconv:
+        seg.append(('did not converge', n_noconv, 'lightgray'))
+
+    fig, ax = plt.subplots(figsize=(11, 3.4))
+    left = 0.0
+    for label, count, col in seg:
+        w = 100.0 * count / n
+        ax.barh(0, w, left=left, color=col, edgecolor='white', height=0.5)
+        if w >= 4:
+            ax.text(left + w / 2, 0, f'{w:.0f}%', ha='center', va='center',
+                    fontsize=11, fontweight='bold',
+                    color='white' if col != 'lightgray' else 'black')
+        left += w
+
+    p_feas = 100.0 * len(feas) / n
+    verdict = ('LARGELY FEASIBLE' if p_feas >= 85 else
+               'MARGINAL' if p_feas >= 60 else 'AT RISK')
+    ax.set_xlim(0, 100)
+    ax.set_ylim(-0.5, 0.55)
+    ax.set_yticks([])
+    ax.set_xlabel('share of Monte-Carlo samples [%]', fontsize=12)
+    ax.set_title(f'Design robustness: {p_feas:.0f}% feasible over N = {n} samples'
+                 f'  --  verdict: {verdict}', fontsize=13, fontweight='bold')
+
+    # plain-language reading note
+    if binding:
+        top = max(binding, key=binding.get)
+        cause = _BIND_LABEL.get(top, top).replace('-limited', ' limit').replace(' infeasible', '')
+        note = f"about {p_feas:.0f} designs out of 100 stay within every limit; " \
+               f"the rest are mostly held back by the {cause}"
+    else:
+        note = f"about {p_feas:.0f} designs out of 100 stay within every limit"
+    if n_noconv:
+        note += "; grey = solver did not converge at extreme corners"
+    ax.annotate(note, xy=(0.5, -0.55), xycoords='axes fraction', ha='center',
+                fontsize=10, color='dimgray')
+
+    ax.legend(handles=[Patch(color=c, label=l) for l, _, c in seg],
+              fontsize=9, ncol=len(seg), loc='upper center',
+              bbox_to_anchor=(0.5, -0.55))
+    plt.tight_layout()
+    return _save(fig, save_dir, 'uq_robustness')
+
+
+# =============================================================================
+# Figure 2 -- headroom to each limit (margin spread)
+# =============================================================================
+def fig_margins(results, save_dir=None):
+    """P5/P50/P95 of the normalised margin to each continuous-margin limit."""
+    rows = [r for k in results for r in results[k] if r.get('converged')]
+    margins = {
+        'Greenwald':  [r.get('gw_margin', np.nan) for r in rows],
+        'Troyon':     [r.get('troyon_margin', np.nan) for r in rows],
+        'Kink (q95)': [r.get('kink_margin', np.nan) for r in rows],
+    }
+    ynames = list(margins)
+    y = np.arange(len(ynames))
+
+    fig, ax = plt.subplots(figsize=(9.5, 4.2))
+    # safe side shading (everything right of the limit)
+    ax.axvspan(0, 1.0, color=_GREEN, alpha=0.05)
+    for yi, name in zip(y, ynames):
+        a = np.array([v for v in margins[name] if np.isfinite(v)])
+        if a.size == 0:
+            continue
+        p5, p50, p95 = np.percentile(a, [5, 50, 95])
+        col = _RED if p5 < 0 else (_AMBER if p5 < 0.05 else _GREEN)
+        ax.plot([p5, p95], [yi, yi], color=col, lw=8, alpha=0.45, solid_capstyle='round')
+        ax.plot(p50, yi, 'o', color=col, ms=11)
+        ax.text(p95 + 0.015, yi, f'P50={p50:+.2f}', va='center', fontsize=9.5)
+    ax.axvline(0, color='k', lw=1.4)
+    ax.annotate('at the limit', xy=(0, len(ynames) - 0.45), fontsize=9,
+                color='k', ha='center', va='bottom')
+    ax.set_yticks(y)
+    ax.set_yticklabels(ynames, fontsize=12)
+    ax.set_ylim(-0.7, len(ynames) - 0.2)
+    ax.set_xlabel('headroom to the limit     (0 = at the limit, further right = safer)',
+                  fontsize=11)
+    ax.set_title('Headroom to each plasma limit under uncertainty',
+                 fontsize=13, fontweight='bold')
+    ax.legend(handles=[Patch(color=_GREEN, label='comfortable margin'),
+                       Patch(color=_AMBER, label='tight margin'),
+                       Patch(color=_RED, label='margin can reach the limit')],
+              fontsize=9, ncol=3, loc='upper center', bbox_to_anchor=(0.5, -0.26))
+    ax.annotate('bar = P5 to P95 over the Monte-Carlo; touching the line on the left '
+                'means that limit can be crossed',
+                xy=(0.5, -0.44), xycoords='axes fraction', ha='center',
+                fontsize=9.5, color='dimgray')
+    plt.tight_layout()
+    return _save(fig, save_dir, 'uq_margins')
+
+
+# =============================================================================
+# Figure 3 -- one-parameter feasibility scan (Monte-Carlo at each value)
+# =============================================================================
+def scan_feasibility(uq_file, scan_specs, n_samples=200, n_jobs=-1, combo=None, seed=0, verbose=10):
+    """
+    Sweep each design parameter and run a Monte-Carlo over all the other uncertain
+    inputs at every value. A common LHS sample is reused across a parameter's scan
+    points (common random numbers) so the curve is smooth. The whole scan is evaluated
+    in ONE parallel pass over all (parameter, point, sample) tasks, which avoids the
+    overhead of opening a separate worker pool at every scan point.
+
+    scan_specs : {param: (lo, hi, n_points)}
+    Returns    : {param: (x_values, P_feasible[%], design_value)}
+    """
+    from joblib import Parallel, delayed
+    from D0FUS_EXE import D0FUS_uncertainty as UQ
+
+    base, spec, envelope, controls, deck_path = UQ.parse_uq_file(uq_file)
+    combo = combo or {}
+
+    grids, tasks = {}, []
+    for p, (lo, hi, npts) in scan_specs.items():
+        reduced = {k: v for k, v in spec.items() if k != p}    # exclude the scanned input
+        names = list(reduced.keys())
+        _, X = UQ.sample_lhs(reduced, n_samples, seed=seed)
+        xs = np.unique(np.concatenate([np.linspace(lo, hi, npts),
+                                       [float(getattr(base, p))]]))   # design value on grid
+        grids[p] = (xs, float(getattr(base, p)))
+        for x in xs:
+            for i in range(n_samples):
+                tasks.append((deck_path, names, X[i], {**combo, p: x}))
+
+    # Single tqdm bar in place of joblib's per-batch log lines. return_as
+    # 'generator' keeps submission order so the per-parameter slicing below holds.
+    _gen = Parallel(n_jobs=n_jobs, return_as="generator")(delayed(UQ._uq_worker)(*t) for t in tasks)
+    rows = list(tqdm(_gen, total=len(tasks), desc="Feasibility scan",
+                     unit="run", disable=(verbose == 0)))
+
+    out, idx = {}, 0
+    for p, (xs, nom) in grids.items():
+        pf = []
+        for _ in xs:
+            chunk = rows[idx:idx + n_samples]
+            idx += n_samples
+            feas = [r for r in chunk if r.get('converged') and r.get('feasible')]
+            pf.append(100.0 * len(feas) / n_samples)           # over all samples
+        out[p] = (xs, np.array(pf), nom)
+    return out
+
+
+def fig_scan(scan_results, save_dir=None):
+    """Four-panel feasibility scan with a traffic-light background; a vertical band
+    marks the design value of each parameter."""
+    params = list(scan_results)
+    ncols = 2
+    nrows = int(np.ceil(len(params) / ncols))
+    fig, axes = plt.subplots(nrows, ncols, figsize=(5.7 * ncols, 3.9 * nrows))
+    axes = np.atleast_1d(axes).ravel()
+
+    for ax, p in zip(axes, params):
+        xs, pf, nom = scan_results[p]
+        # traffic-light zones
+        ax.axhspan(85, 105, color=_GREEN, alpha=0.10)
+        ax.axhspan(60, 85, color=_AMBER, alpha=0.10)
+        ax.axhspan(0, 60, color=_RED, alpha=0.10)
+        ax.plot(xs, pf, '-o', color='black', lw=2, ms=3, zorder=4)
+        # vertical band marking the design value
+        ax.axvline(nom, color='0.15', ls='--', lw=1.6, zorder=5)
+        ax.text(nom, 50, ' design value ', rotation=90, va='center', ha='center',
+                fontsize=8.5, color='0.15', zorder=6,
+                bbox=dict(boxstyle='round,pad=0.15', fc='white', ec='0.6', alpha=0.85))
+        ax.set_xlabel(f"{_NICE.get(p, p)}  {_UNIT.get(p, '')}", fontsize=11)
+        ax.set_ylabel('chance of staying feasible [%]', fontsize=10)
+        ax.set_ylim(0, 105)
+        ax.set_xlim(xs.min(), xs.max())
+
+    for ax in axes[len(params):]:
+        ax.axis('off')
+
+    plt.suptitle('How feasibility responds to each design choice',
+                 fontsize=14, fontweight='bold')
+    fig.legend(handles=[Patch(color=_GREEN, alpha=0.35, label='safe (>= 85%)'),
+                        Patch(color=_AMBER, alpha=0.35, label='marginal (60-85%)'),
+                        Patch(color=_RED, alpha=0.35, label='unlikely (< 60%)')],
+               loc='lower center', ncol=3, fontsize=9, frameon=False,
+               bbox_to_anchor=(0.5, -0.02))
+    plt.tight_layout(rect=[0, 0.04, 1, 0.96])
+    return _save(fig, save_dir, 'uq_scan_feasibility')
+
+
+# =============================================================================
+# Figure 4 -- impact of the physics models (envelope combinations)
+# =============================================================================
+def fig_models(results, qoi='Q', save_dir=None):
+    """
+    How the model-form choices (confinement scaling law, elongation model, ...) move
+    feasibility. One row per model combination: a wide spread between rows means the
+    model assumptions matter, a tight spread means they do not. (qoi kept for backward
+    compatibility; no longer plotted.)
+    """
+    combos = [k for k in results if k != ('nominal',)]
+    if not combos:
+        return None                              # no model envelope in this study
+
+    def _label(key):
+        d = dict(key)
+        order = ['Scaling_Law', 'Option_Kappa', 'Bootstrap_choice']
+        vals = [str(d[k]) for k in order if k in d]
+        vals += [str(v) for k, v in key if k not in order]
+        return '  ·  '.join(vals)
+
+    labels, p_feas = [], []
+    for k in combos:
+        rws = results[k]
+        n = max(len(rws), 1)
+        feas = [r for r in rws if r.get('converged') and r.get('feasible')]
+        labels.append(_label(k))
+        p_feas.append(100.0 * len(feas) / n)
+
+    order = np.argsort(p_feas)                    # worst feasibility at the bottom
+    labels = [labels[i] for i in order]
+    p_feas = [p_feas[i] for i in order]
+    y = np.arange(len(labels))
+
+    fig, ax = plt.subplots(figsize=(10, 0.7 * len(labels) + 2.2))
+    grays = [str(max(0.25, 0.85 - 0.6 * p / 100.0)) for p in p_feas]   # darker = higher
+    ax.barh(y, p_feas, color=grays, edgecolor='black', lw=0.8)
+    for yi, p in zip(y, p_feas):
+        ax.text(min(p + 1.5, 97), yi, f'{p:.0f}%', va='center', fontsize=10)
+    ax.axvline(85, color='0.3', ls=':', lw=1)
+    ax.set_xlim(0, 105)
+    ax.set_yticks(y)
+    ax.set_yticklabels(labels, fontsize=11)
+    ax.set_xlabel('probability of staying feasible [%]', fontsize=11)
+    ax.set_title('Impact of the physics models on feasibility',
+                 fontsize=13, fontweight='bold')
+    ax.annotate('each row is one model combination (confinement scaling · elongation); '
+                'the spread shows how much the model assumptions drive feasibility',
+                xy=(0.5, -0.30 if len(labels) <= 4 else -0.18), xycoords='axes fraction',
+                ha='center', fontsize=9.5, color='dimgray')
+    plt.tight_layout()
+    return _save(fig, save_dir, 'uq_models')