axbo_extensions 1.4.0__tar.gz

axbo_extensions-1.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

axbo_extensions-1.4.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: axbo_extensions
+Version: 1.4.0
+Summary: Ax/BoTorch GLUE for multi-fidelity + robust optimization.
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ax-platform==1.3.1
+Requires-Dist: botorch==0.18.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: numpy
+Requires-Dist: sympy
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# Bayesian (BOTorch) extensions for the Ax platform
+
+> This is largely an experimental library basically glueing **multi-fidelity** and **robust** optimization
+> into the ax-platform internals. Refactored out of
+> [foamBO](https://github.com/FoamScience/OpenFOAM-Multi-Objective-Optimization) to decouple it from its orchestration capabilities.
+
+Extracts foamBO's self-contained (historic) `robustness.py` (qMultiFidHVKG cost loop,
+`SubstituteContextFeatures`, `RobustAcquisition` CVaR/MARS, `augment_generator_specs` /
+`cycle_context`) into a separate package so more tools can have these capabilities
+without getting foamBO's orchestration if they don't want it.

axbo_extensions-1.4.0/README.md

@@ -0,0 +1,10 @@
+# Bayesian (BOTorch) extensions for the Ax platform
+
+> This is largely an experimental library basically glueing **multi-fidelity** and **robust** optimization
+> into the ax-platform internals. Refactored out of
+> [foamBO](https://github.com/FoamScience/OpenFOAM-Multi-Objective-Optimization) to decouple it from its orchestration capabilities.
+
+Extracts foamBO's self-contained (historic) `robustness.py` (qMultiFidHVKG cost loop,
+`SubstituteContextFeatures`, `RobustAcquisition` CVaR/MARS, `augment_generator_specs` /
+`cycle_context`) into a separate package so more tools can have these capabilities
+without getting foamBO's orchestration if they don't want it.

axbo_extensions-1.4.0/axbo_extensions/__init__.py

@@ -0,0 +1,12 @@
+"""axbo_extensions — shared Ax/BoTorch GLUE for multi-fidelity + robust optimization.
+
+Home for foamBO's ported MultiFid/robust glue (qMultiFidHVKG cost loop, SubstituteContextFeatures,
+RobustAcquisition CVaR/MARS, augment_generator_specs/cycle_context).
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("axbo_extensions")
+except PackageNotFoundError:  # running from source without an install
+    __version__ = "0.0.0"

axbo_extensions-1.4.0/axbo_extensions/dimreduction.py

@@ -0,0 +1,121 @@
+"""Sobol-sensitivity dimensionality reduction (generic port of foamBO
+``_maybe_reduce_dimensions``).
+
+After the GP is fit, fix low-influence parameters at a constant to shrink the search space.
+The latch lives in a caller-owned ``state`` dict so it survives the detached ask/run/tell
+boundary (foamBO used an in-memory ``nonlocal``). Must run AFTER ``get_next_trials`` — Sobol
+needs a fitted model.
+"""
+
+from __future__ import annotations
+
+import logging
+
+log = logging.getLogger("axbo_extensions.dimreduction")
+
+
+def select_params_to_fix(
+    importance: dict[str, float], min_importance: float, max_fix_fraction: float
+) -> list[str]:
+    """Low-influence params to fix: importance < threshold, ascending, capped so >=1 stays
+    active. Pure (no model) — the testable core of the reduction decision."""
+    names = list(importance)
+    cap = min(int(len(names) * max_fix_fraction), len(names) - 1)
+    ordered = sorted(names, key=lambda n: importance[n])
+    return [n for n in ordered if importance[n] < min_importance][:cap]
+
+
+def _cv_fit_ok(gs) -> bool:
+    """False if model fit is too poor to trust Sobol (mean CV error > 50% of error range)."""
+    try:
+        import numpy as np
+        from ax.adapter.cross_validation import cross_validate
+
+        errs = []
+        for r in cross_validate(adapter=gs.adapter):
+            for m, obs in r.observed.data.means_dict.items():
+                errs.append(abs(obs - r.predicted.means_dict.get(m, obs)))
+        if errs:
+            rng = max(errs)
+            if rng > 0 and float(np.mean(errs)) / rng > 0.5:
+                return False
+    except Exception:  # noqa: BLE001 - CV unavailable -> proceed with Sobol
+        pass
+    return True
+
+
+def _sobol_importance(gs, exp) -> dict[str, float]:
+    """Total-order Sobol indices of the fitted GP mean, per range parameter (Ax-private)."""
+    import torch
+    from ax.utils.sensitivity.sobol_measures import SobolSensitivityGPMean
+
+    model = gs.adapter.generator.surrogate.model
+    names = [n for n, p in exp.search_space.parameters.items() if hasattr(p, "lower")]
+    bounds = torch.zeros(2, len(names), dtype=torch.float64)
+    bounds[1] = 1.0  # Ax models operate in normalized [0,1] space
+    total = SobolSensitivityGPMean(
+        model=model, bounds=bounds, num_mc_samples=1000
+    ).total_order_indices()
+    return {n: float(total[i].abs()) for i, n in enumerate(names)}
+
+
+def maybe_reduce_dimensions(client, cfg, state: dict) -> None:
+    """Fix low-influence parameters once enough trials are in. Mutates the experiment search
+    space in place (persists when the Client is saved); idempotent via ``state['done']``.
+
+    cfg: a DimensionalityReductionConfig-like; state: ``{"done": bool, "attempts": int}``
+    (the caller persists it). Wrapped in a 3-strike try/except over the Ax-private paths (§6).
+    """
+    if state.get("done") or not getattr(cfg, "enabled", False):
+        return
+    from ax.core.base_trial import TrialStatus
+
+    exp = client._experiment
+    n_done = sum(1 for t in exp.trials.values() if t.status == TrialStatus.COMPLETED)
+    if n_done < cfg.after_trials:
+        return
+    gs = client._generation_strategy
+    if gs is None or getattr(gs, "adapter", None) is None:
+        return
+
+    try:
+        if not _cv_fit_ok(gs):
+            log.info("dim-reduction deferred: model fit too poor")
+            return
+        importance = _sobol_importance(gs, exp)
+    except Exception as e:  # noqa: BLE001
+        state["attempts"] = state.get("attempts", 0) + 1
+        if state["attempts"] >= 3:
+            state["done"] = True
+            log.warning("dim-reduction disabled after 3 failed attempts: %s", e)
+        return
+
+    to_fix = select_params_to_fix(importance, cfg.min_importance, cfg.max_fix_fraction)
+    if not to_fix:
+        state["done"] = True
+        return
+
+    best: dict = {}
+    if cfg.fix_at == "best":
+        try:
+            best = client.get_best_parameterization(use_model_predictions=False)[0]
+        except Exception:  # noqa: BLE001 - fall back to center
+            best = {}
+
+    from ax.core.parameter import FixedParameter
+
+    for n in to_fix:
+        p = exp.search_space.parameters[n]
+        if cfg.fix_at == "best" and best.get(n) is not None:
+            val = best[n]
+        elif hasattr(p, "lower"):
+            val = (p.lower + p.upper) / 2
+        elif hasattr(p, "values"):
+            val = p.values[0]
+        else:
+            continue
+        exp.search_space.update_parameter(
+            FixedParameter(name=n, parameter_type=p.parameter_type, value=val)
+        )
+        log.info("dim-reduction: fixed %s=%s (importance=%.4f)", n, val, importance[n])
+    state["done"] = True

axbo_extensions-1.4.0/axbo_extensions/multifidelity.py

@@ -0,0 +1,267 @@
+"""Multi-fidelity GLUE for Ax + BoTorch (ported from foamBO ``robustness.py`` /
+``optimize.py``).
+
+- ``MultiFidHVKGAcquisition``: Ax ``Acquisition`` subclass that strips ``X_pending``
+  (qMultiFidHVKG's input constructor rejects it).
+- ``update_cost_state``: recompute ``cost_intercept`` / ``fidelity_weights`` for the
+  ``AffineFidelityCostModel`` qMultiFidHVKG builds, from the observed is_cost metric. The
+  ±0.5 positivity-floor + normalization math is load-bearing — copied verbatim.
+- ``apply_fidelity_parameters``: stamp ``_is_fidelity`` / ``_target_value`` onto Ax
+  search-space parameters after ``configure_experiment``.
+- ``augment_specs_for_multifidelity``: inject ``SingleTaskMultiFidelityGP`` surrogate
+  + qMultiFidHVKG acqf + ``MultiFidHVKGAcquisition`` into a Client's generation-strategy nodes.
+
+Pinned to ax-platform 1.3.x / botorch 0.18.x.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import defaultdict
+from typing import Any, Optional
+
+from ax.generators.torch.botorch_modular.acquisition import Acquisition
+
+log = logging.getLogger("axbo_extensions.multifidelity")
+
+
+class MultiFidHVKGAcquisition(Acquisition):
+    """Acquisition subclass that strips kwargs incompatible with qMultiFidHVKG.
+
+    ``construct_inputs_qMultiFidHVKG`` doesn't accept ``X_pending`` (unlike most other
+    BoTorch input constructors). This subclass clears it before the parent passes
+    acqf_options to the input constructor.
+    """
+
+    def _construct_botorch_acquisition(self, botorch_acqf_class, botorch_acqf_options, model):
+        _saved = self.X_pending
+        self.X_pending = None
+        try:
+            return super()._construct_botorch_acquisition(
+                botorch_acqf_class=botorch_acqf_class,
+                botorch_acqf_options=botorch_acqf_options,
+                model=model,
+            )
+        finally:
+            self.X_pending = _saved
+
+
+def _fidelity_feature_index(client, fid_param_name: str) -> int:
+    """Feature index of the fidelity parameter in the search space."""
+    param_names = list(client._experiment.search_space.parameters.keys())
+    return param_names.index(fid_param_name)
+
+
+def update_cost_state(client, multifid_cost: dict, log=None) -> None:
+    """Recompute cost-model params from observed is_cost metric data.
+
+    Reads observed values of the cost metric, computes per-fidelity means, then derives
+    ``cost_intercept`` and ``fidelity_weights`` for the ``AffineFidelityCostModel`` that
+    qMultiFidHVKG's input constructor builds internally. Writes directly into the acqf_opts
+    dict (``multifid_cost['acqf_opts_ref']``) so the next acquisition construction picks up
+    updated values.
+
+    AffineFidelityCostModel: cost(x) = cost_intercept + Σ(w_i × s_i). With two fidelity
+    levels (s=0 cheap, s=1 expensive): cost_intercept = mean_cost_at_s0,
+    fidelity_weight = mean_cost_at_s1 - mean_cost_at_s0.
+    """
+    from ax.core.base_trial import TrialStatus as _TS
+
+    cost_metric_name = multifid_cost["metric"]
+    fidelity_param_name = multifid_cost["fidelity_param"]
+    # Collect observed costs per fidelity level (keyed by raw fidelity value)
+    sums: dict = defaultdict(float)
+    counts: dict = defaultdict(int)
+    df = client._experiment.lookup_data().df
+    for trial in client._experiment.trials.values():
+        if trial.status not in (_TS.COMPLETED, _TS.EARLY_STOPPED):
+            continue
+        fid_val = trial.arm.parameters.get(fidelity_param_name)
+        if fid_val is None:
+            continue
+        sub = df[(df.trial_index == trial.index) & (df.metric_name == cost_metric_name)]
+        if sub.empty:
+            continue
+        sums[fid_val] += float(sub["mean"].iloc[-1])
+        counts[fid_val] += 1
+    per_f = {fv: sums[fv] / counts[fv] for fv in sums if counts[fv] > 0}
+    if not per_f or per_f == multifid_cost["state"]["per_fidelity"]:
+        return  # no change
+    multifid_cost["state"]["per_fidelity"] = per_f
+
+    # Build numeric mapping for AffineFidelityCostModel.
+    # For numeric fidelity: use values directly.
+    # For categorical (str) fidelity: map to ordinal indices sorted by cost.
+    raw_keys = sorted(per_f.keys(), key=lambda k: per_f[k])
+    is_numeric = all(isinstance(k, (int, float)) for k in raw_keys)
+    if is_numeric:
+        fid_vals = sorted(float(k) for k in raw_keys)
+        costs = [per_f[k] for k in sorted(per_f.keys())]
+    else:
+        # Map categorical levels to 0..N-1 ordered by ascending cost
+        fid_vals = list(range(len(raw_keys)))
+        costs = [per_f[k] for k in raw_keys]
+
+    cost_intercept = min(costs)  # cheapest fidelity floor
+    # Weights: slope per fidelity unit. For discrete {0,1}: w = cost_high - cost_low.
+    # For continuous: linear fit.
+    fid_range = fid_vals[-1] - fid_vals[0] if len(fid_vals) > 1 else 0
+    if fid_range > 0:
+        fid_weight = (max(costs) - min(costs)) / fid_range
+    else:
+        fid_weight = 1.0
+    # Positivity floor: BoTorch's InverseCostWeightedUtility requires cost(X) > 0 over
+    # the entire acqf domain. Ax extends INT-fidelity model-space bounds by ±0.5, so
+    # AffineFidelityCostModel sees fid ∈ [-0.5, 1.5]; cost(X) = intercept + weight × X
+    # must stay > 0 across that range → intercept ≥ 0.5 × weight + ε. Normalize to keep
+    # costs O(1) (qMultiFidHVKG tolerates large absolute values poorly).
+    max_cost = max(costs) if max(costs) > 0 else 1.0
+    cost_intercept_norm = cost_intercept / max_cost
+    fid_weight_norm = fid_weight / max_cost
+    cost_intercept_safe = max(cost_intercept_norm, 0.5 * fid_weight_norm + 1e-3)
+    opts = multifid_cost["acqf_opts_ref"]
+    opts["cost_intercept"] = max(cost_intercept_safe, 1e-6)
+    if log:
+        log.debug(
+            "MultiFid cost normalized: raw intercept=%.3f weight=%.3f max_cost=%.3f → "
+            "intercept=%.3f weight=%.3f",
+            cost_intercept,
+            fid_weight,
+            max_cost,
+            cost_intercept_safe,
+            fid_weight_norm,
+        )
+    fid_feature_idx = _fidelity_feature_index(client, multifid_cost["fidelity_param"])
+    opts["fidelity_weights"] = {fid_feature_idx: fid_weight_norm}
+    if log:
+        log.info(
+            "Multi-fidelity cost updated: intercept=%.2f, weight=%.2f "
+            "(from %d fidelity levels: %s)",
+            cost_intercept,
+            fid_weight,
+            len(per_f),
+            list(per_f.keys()),
+        )
+
+
+def apply_fidelity_parameters(client, fidelity_params: dict, log=None) -> None:
+    """Stamp ``_is_fidelity`` / ``_target_value`` onto Ax search-space parameters.
+
+    ``fidelity_params`` maps parameter name -> fidelity_target. Call after
+    ``configure_experiment`` (Ax's parameter configs don't carry these attrs).
+    """
+    from ax.core.parameter import FixedParameter
+
+    for pname, target_val in fidelity_params.items():
+        p = client._experiment.search_space.parameters.get(pname)
+        if p is None or isinstance(p, FixedParameter):
+            continue
+        p._is_fidelity = True
+        p._target_value = target_val
+        if log:
+            log.info("Fidelity parameter: %s (fidelity_target=%s)", pname, target_val)
+
+
+def augment_specs_for_multifidelity(
+    client, cost_metric_name: Optional[str] = None, log=None
+) -> Optional[dict]:
+    """Inject MultiFid surrogate + qMultiFidHVKG acqf + ``MultiFidHVKGAcquisition`` into the Client's
+    generation-strategy nodes.
+
+    Requires fidelity parameters already stamped (``apply_fidelity_parameters``) and a
+    generation strategy already set. Returns the ``multifid_cost`` state dict (to feed
+    ``update_cost_state`` each batch) when ``cost_metric_name`` is given, else ``None``.
+    """
+    from ax.adapter.registry import Generators
+    from ax.generators.torch.botorch_modular.surrogate import SurrogateSpec
+    from ax.generators.torch.botorch_modular.utils import ModelConfig
+    from botorch.acquisition.multi_objective.hypervolume_knowledge_gradient import (
+        qMultiFidelityHypervolumeKnowledgeGradient,
+    )
+    from botorch.models.gp_regression_fidelity import SingleTaskMultiFidelityGP
+
+    fidelity_params = [
+        p
+        for p in client._experiment.search_space.parameters.values()
+        if getattr(p, "is_fidelity", False)
+    ]
+    if not fidelity_params:
+        return None
+
+    gs = client._generation_strategy
+    multifid_cost: Optional[dict] = None
+    for node in gs._nodes:
+        for spec in node.generator_specs:
+            if spec.generator_enum != Generators.BOTORCH_MODULAR:
+                continue
+            gk = spec.generator_kwargs
+            if "botorch_acqf_class" not in gk:
+                gk["botorch_acqf_class"] = qMultiFidelityHypervolumeKnowledgeGradient
+                if log:
+                    log.info("Multi-fidelity: auto-selected qMultiFidHVKG")
+            # qMultiFidHVKG's fantasy-based acqf optimizer diverges on raw multi-scale bounds
+            # (out-of-bounds candidates / hangs). MBM deliberately DROPS UnitX to keep discrete
+            # params discrete, leaving the acqf in raw parameter space — fine for qLogNEHVI/MARS,
+            # fatal for KG. Force UnitX-inclusive transforms so the acqf optimizes in [0,1].
+            # Idempotent; range-int params get continuous-relaxed + rounded (acceptable for KG).
+            from ax.adapter.registry import Cont_X_trans, Y_trans
+
+            gk["transforms"] = Cont_X_trans + Y_trans
+            # Inject surrogate only if not already set (preserves an explicit one and is
+            # idempotent on a reloaded client whose strategy already carries it).
+            if gk.get("surrogate_spec") is None:
+                # allow_batched_models=False forces a ModelListGP of per-output STMFGPs
+                # (qMultiFidHVKG requirement — load-bearing).
+                gk["surrogate_spec"] = SurrogateSpec(
+                    model_configs=[ModelConfig(botorch_model_class=SingleTaskMultiFidelityGP)],
+                    allow_batched_models=False,
+                )
+                gk["acquisition_class"] = MultiFidHVKGAcquisition
+                if log:
+                    log.info(
+                        "Multi-fidelity: SingleTaskMultiFidelityGP surrogate (fidelity param: %s)",
+                        fidelity_params[0].name,
+                    )
+            # Build cost state regardless of fresh/reloaded surrogate so the batch loop's
+            # update_cost_state has a live acqf_opts_ref after a JSON reload.
+            if cost_metric_name is not None:
+                multifid_cost = {
+                    "state": {"per_fidelity": {}},
+                    "metric": cost_metric_name,
+                    "fidelity_param": fidelity_params[0].name,
+                    "acqf_opts_ref": gk.setdefault("botorch_acqf_options", {}),
+                }
+                multifid_cost["acqf_opts_ref"].setdefault("cost_intercept", 1.0)
+    return multifid_cost
+
+
+# ---------------------------------------------------------------------------
+# Ax JSON serialization registry — run at import so saved MultiFid experiments serialize.
+# MultiFidHVKGAcquisition is an Ax Acquisition wrapper; qMultiFidHVKG/MOMF are BoTorch
+# AcquisitionFunctions not in Ax's default registry. Without this, save_to_json_file
+# raises "Class qMultiFidelityHypervolumeKnowledgeGradient not in registry".
+# ---------------------------------------------------------------------------
+try:
+    from ax.storage.botorch_modular_registry import (
+        CLASS_TO_REGISTRY,
+        CLASS_TO_REVERSE_REGISTRY,
+        register_acquisition,
+    )
+    from botorch.acquisition import AcquisitionFunction as _AcqFn
+
+    register_acquisition(MultiFidHVKGAcquisition)
+    for _mod, _name in [
+        (
+            "botorch.acquisition.multi_objective.hypervolume_knowledge_gradient",
+            "qMultiFidelityHypervolumeKnowledgeGradient",
+        ),
+        ("botorch.acquisition.multi_objective.multi_fidelity", "MOMF"),
+    ]:
+        try:
+            _cls = getattr(__import__(_mod, fromlist=[_name]), _name)
+            CLASS_TO_REGISTRY[_AcqFn][_cls] = _name
+            CLASS_TO_REVERSE_REGISTRY[_AcqFn][_name] = _cls
+        except (ImportError, AttributeError):  # pragma: no cover
+            pass
+except ImportError:  # pragma: no cover - Ax storage registry path drift
+    log.warning("Ax storage registry unavailable; MultiFid JSON (de)serialization skipped")

axbo_extensions-1.4.0/axbo_extensions/regionscreening.py

@@ -0,0 +1,116 @@
+"""Region screening — inactivity decision core (port of foamBO _maybe_screen_regions).
+
+Only the **pure decision** is ported: given a region's per-trial scalars, is its spread
+below the inactivity threshold, and how long has the streak run. That math is durable and
+reusable.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Iterable, Optional
+
+log = logging.getLogger("axbo_extensions.regionscreening")
+
+
+def region_inactive(
+    scalars: Iterable[float],
+    min_delta: Optional[float] = None,
+    min_delta_frac: Optional[float] = None,
+) -> dict:
+    """Is the region's objective-scalar spread below its inactivity threshold?
+
+    ``min_delta`` = absolute threshold; else ``min_delta_frac`` is relative to the largest
+    magnitude observed. Returns ``{samples, spread, threshold, inactive}``.
+    """
+    vals = list(scalars)
+    spread = (max(vals) - min(vals)) if vals else 0.0
+    ref = max((abs(v) for v in vals), default=0.0)
+    threshold = min_delta if min_delta is not None else (min_delta_frac or 0.0) * ref
+    return {
+        "samples": len(vals),
+        "spread": spread,
+        "threshold": threshold,
+        "inactive": bool(vals) and spread < threshold,
+    }
+
+
+def next_streak(streak: int, inactive: bool) -> int:
+    """Consecutive-inactive streak: increment when inactive, reset to 0 otherwise."""
+    return streak + 1 if inactive else 0
+
+
+def shrunk_bounds(lo: float, hi: float, center: float, shrink_factor: float) -> tuple[float, float]:
+    """New ``[lo, hi]`` after a shrink: a ``shrink_factor * range`` window around ``center``,
+    clamped to the original bounds. Pure — the shrink geometry."""
+    half = (shrink_factor * (hi - lo)) / 2.0
+    return max(lo, center - half), min(hi, center + half)
+
+
+def _group_params(parameter_groups: dict, group: str) -> list[str]:
+    return [n for n, gs in (parameter_groups or {}).items() if group in (gs or [])]
+
+
+def maybe_screen_regions(
+    client, cfg, scalars_by_region: dict, parameter_groups: dict, state: dict
+) -> None:
+    """Advise/shrink parameter groups whose objective-scalar spread stays below threshold for
+    ``confirm_passes`` consecutive passes (plan §2.A2). ``scalars_by_region``: ``{group:
+    {trial_idx: scalar}}`` (caller reads these from the executor's results — the generic
+    result-field provider). ``state`` persists streaks / shrunk groups / original bounds /
+    advisories across the detached ask/run/tell boundary. Shrink mutates the search space
+    in place (Ax-private update_parameter, gated)."""
+    if not getattr(cfg, "enabled", False) or not cfg.regions:
+        return
+    streaks = state.setdefault("streaks", {})
+    shrunk = state.setdefault("shrunk_groups", [])
+    advisories = state.setdefault("advisories", [])
+
+    ready = []
+    for region in cfg.regions:
+        vals = list(scalars_by_region.get(region.group, {}).values())
+        if len(vals) < cfg.after_trials:
+            continue
+        inactive = region_inactive(vals, region.min_delta, region.min_delta_frac)["inactive"]
+        streaks[region.group] = next_streak(streaks.get(region.group, 0), inactive)
+        if streaks[region.group] >= cfg.confirm_passes and region.group not in shrunk:
+            ready.append(region.group)
+    if not ready:
+        return
+
+    if cfg.mode == "advise":
+        for g in ready:
+            advisories.append({"group": g, "params": _group_params(parameter_groups, g)})
+            shrunk.append(g)  # recorded so we advise once
+            log.info("region screening (advise): group %s inactive", g)
+        return
+
+    # shrink mode — narrow each group param's range around the best point, once per group.
+    try:
+        from ax.core.parameter import RangeParameter
+
+        exp = client._experiment
+        orig_bounds = state.setdefault("original_bounds", {})
+        try:
+            best = client.get_best_parameterization(use_model_predictions=False)[0]
+        except Exception:  # noqa: BLE001
+            best = {}
+        n_total = len(exp.search_space.parameters)
+        budget = max(min(cfg.max_shrinkable or n_total, n_total - 1) - len(orig_bounds), 0)
+        for g in ready:
+            for pname in _group_params(parameter_groups, g):
+                if budget <= 0:
+                    break
+                p = exp.search_space.parameters.get(pname)
+                if not isinstance(p, RangeParameter):
+                    continue
+                lo, hi = float(p.lower), float(p.upper)
+                orig_bounds.setdefault(pname, (lo, hi))
+                center = best.get(pname, (lo + hi) / 2.0)
+                new_lo, new_hi = shrunk_bounds(lo, hi, center, cfg.shrink_factor)
+                p.update_range(lower=new_lo, upper=new_hi)
+                budget -= 1
+                log.info("region screening: shrank %s -> [%.4g, %.4g]", pname, new_lo, new_hi)
+            shrunk.append(g)
+    except Exception as e:  # noqa: BLE001 - Ax-private mutation path, stay non-fatal
+        log.warning("region screening shrink failed: %s", e)