fix: defer PI computation over window_size

Author: Elwardi

src/foambo/default_config.py

@@ -115,7 +115,9 @@ def _get_doc_models():
         DimensionalityReductionOptions,
     )
     from .metrics import FoamJob, LocalJobMetric
+    from .robustness import RobustOptimizationConfig
     return [
+        (RobustOptimizationConfig,   "robust_optimization"),
         (ExperimentOptions,          "experiment"),
         (TrialGenerationOptions,     "trial_generation"),
         (ModelSpecConfig,            "trial_generation.generation_nodes[].generator_specs[]"),

src/foambo/docs_concepts.py

@@ -504,6 +504,57 @@
 available via ``GET /api/v1/events``.""",
     },
 
+    "concept.robust_optimization": {
+        "category": "Concept",
+        "content": """\
+Robust optimization — designing for performance under context uncertainty.
+
+Instead of optimizing at one nominal operating point, robust mode samples a
+distribution of context values (flowRate, temperature, inlet profile, …) at
+every candidate design and collapses the resulting outcome distribution via a
+risk measure. The optimizer then maximizes the risk-adjusted score, favoring
+designs that stay good across contexts rather than designs that peak at one
+and tank at others.
+
+**YAML:**
+```yaml
+robust_optimization:
+  context_groups: [operating_point]   # parameter groups treated as contexts
+  risk_measure: auto                  # or: cvar, mars
+  robustness: 0.8                     # alpha; higher = more conservative
+  context_samples: 4                  # samples per candidate
+  # context_points: auto-generated via Sobol unless given explicitly
+```
+
+**Risk measures:**
+- ``cvar`` (Conditional Value-at-Risk) — average of the worst ``(1-alpha)``
+  fraction of context outcomes. Single-objective only.
+- ``mars`` (MVaR Approximation via Random Scalarizations) — multi-objective
+  VaR built from random weight vectors; each scalarization reduces the problem
+  to single-objective CVaR, then Ax aggregates. Multi-objective only.
+- ``auto`` — picks CVaR when the optimization has one objective and MARS when
+  it has multiple.
+
+**Mechanism:** foamBO's ``SubstituteContextFeatures`` input transform swaps
+the candidate's context slot for each Sobol-drawn context point at acquisition
+evaluation time. The GP is evaluated once per context sample and the risk
+measure reduces the ``n_contexts`` values to a single score that
+``optimize_acqf`` maximizes.
+
+**Parallelism:** robust trials require ``context_samples`` design evaluations
+each. With ``parallelism: N``, each Ax orchestrator slot still corresponds to
+one design point (the context sweep runs inside the acquisition, not the
+runner), so the runner budget is unchanged.
+
+**Full details, risk-measure math, MOO suitability matrix, and comparisons
+to SAASBO / InputPerturbation:** see ``docs/risk-measures-guide.md``.
+
+**Specialization:** once a robust run converges, pin the context with
+``bootstrap: + specialize: {ctx: value}`` to continue optimizing design
+variables at a concrete operating point. See
+``concept.bootstrap_and_specialize``.""",
+    },
+
     "concept.bootstrap_and_specialize": {
         "category": "Concept",
         "content": """\

src/foambo/optimize.py

@@ -542,16 +542,26 @@ def callback(sched: Orchestrator):
         from .analysis import plot_streaming_metrics
         plot_streaming_metrics(raw_cfg, client)
 
-        # Log convergence estimate (Part A) after BO trials
+        # Log convergence estimate (Part A) — throttled to every `window_size`
+        # completed trials (same cadence the global stopping strategy uses).
         try:
             gs = client._generation_strategy
             if gs is not None and gs.adapter is not None:
-                from .analysis import compute_convergence_pi, format_convergence_log
-                _imp_bar = getattr(orch_cfg, 'global_stopping_strategy', None)
-                _imp_bar = getattr(_imp_bar, 'improvement_bar', 0.1) if _imp_bar else 0.1
-                conv = compute_convergence_pi(client, gs, improvement_bar=_imp_bar)
-                if conv.get("estimates"):
-                    log.info("\n%s", format_convergence_log(conv))
+                from ax.core.base_trial import TrialStatus as _TS
+                n_completed = sum(
+                    1 for t in client._experiment.trials.values()
+                    if t.status in (_TS.COMPLETED, _TS.EARLY_STOPPED)
+                )
+                gss = getattr(orch_cfg, 'global_stopping_strategy', None)
+                window = getattr(gss, 'window_size', None) or 5
+                last = getattr(callback, '_last_conv_n', 0)
+                if n_completed > 0 and n_completed - last >= window:
+                    from .analysis import compute_convergence_pi, format_convergence_log
+                    _imp_bar = getattr(gss, 'improvement_bar', 0.1) if gss else 0.1
+                    conv = compute_convergence_pi(client, gs, improvement_bar=_imp_bar)
+                    if conv.get("estimates"):
+                        log.info("\n%s", format_convergence_log(conv))
+                        callback._last_conv_n = n_completed
         except Exception as e:
             log.debug("Convergence estimate failed: %s", e)