bamengine 0.9.1__tar.gz → 0.9.2__tar.gz

{bamengine-0.9.1/src/bamengine.egg-info → bamengine-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bamengine
-Version: 0.9.1
+Version: 0.9.2
 Summary: A modular Python framework for the BAM agent-based macroeconomic model
 Author-email: Kostas Ganitis <ganitiskostas@gmail.com>
 Maintainer-email: Kostas Ganitis <ganitiskostas@gmail.com>
@@ -83,17 +83,10 @@ Dynamic: license-file
 <p align="center">
   A Python implementation of the BAM (Bottom-Up Adaptive Macroeconomics) model
   from <a href="https://doi.org/10.1007/978-88-470-1971-3"><em>Macroeconomics from the Bottom-up</em></a>
-  (Delli Gatti et al., 2011). Simulate households, firms, and banks
-  interacting across labor, credit, and goods markets, where macroeconomic
-  dynamics emerge from individual agent decisions.
-</p>
-
-<p align="center">
-  <em>Traditional economics models economies from the top down, assuming
-  markets automatically reach equilibrium. BAM Engine takes a different approach:
-  it simulates individual workers, firms, and banks making decisions and
-  interacting in markets, letting macroeconomic patterns emerge from the
-  bottom up.</em>
+  (Delli Gatti et al., 2011). It runs simulations of individual workers, firms, and
+  banks making decisions and interacting in labor, credit and goods markets, letting
+  macroeconomic patterns (growth, unemployment, inflation, business cycles) <b>emerge
+  from the bottom up</b>, instead of assuming them with aggregate equations.
 </p>
 
 <p align="center">
@@ -172,17 +165,16 @@ See the [Getting Started guide](https://bam-engine.readthedocs.io/en/latest/quic
 
 ## Features
 
-- **Complete BAM Model:** Full Chapter 3 implementation: firms, households, and banks interacting across labor, credit, and goods markets
-- **ECS Architecture:** Entity-Component-System design separates data (Roles) from behavior (Events) for clean extensibility
-- **Vectorized Performance:** All agent operations use NumPy arrays; no Python loops over agents
-- **Built-in Extensions:** R&D / Growth+, buffer-stock consumption, and taxation modules
-- **Validation Framework:** Three scenario validators with scoring and robustness analysis
-- **Calibration Pipeline:** Morris screening, grid search, and tiered stability testing
-- **Easy Configuration:** All parameters configurable without code changes via YAML files
+- **Complete BAM Implementation:** Baseline model from *Macroeconomics from the Bottom-up*, Chapter 3 (firms, households, and banks across labor, credit, and goods markets), three built-in extensions (R&D / Growth+, buffer-stock consumption, taxation), and a robustness analysis suite (internal validity, sensitivity, structural experiments).
+- **Vectorized Performance:** Agent state lives in parallel NumPy arrays and behavior is expressed as array transformations, not Python loops over agent objects. Simulations scale to large populations and long horizons.
+- **Pluggable Extension System:** Add custom roles, events, and pipeline hooks via decorators without modifying the engine. The same mechanism powers the built-in extensions.
+- **Parameter Calibration:** Automated pipeline for tuning model parameters against validation targets.
 
 ## Architecture
 
-BAM Engine uses an ECS (Entity-Component-System) architecture: agents are lightweight entities, state lives in Role components stored as NumPy arrays, and behavior is defined by Event systems executed via a YAML-configurable pipeline. Custom roles, events, and relationships can be added without modifying core code.
+BAM Engine uses an ECS (Entity-Component-System) architecture: agents are lightweight entities, state lives in **Role** components stored as parallel NumPy arrays, and behavior is defined by **Event** systems composed into a YAML-configurable pipeline. New roles, events, and relationships can be added through decorators, without modifying core code.
+
+The trade-off is a mindset shift: you write agent rules as systems that transform whole arrays of state at once, not as methods on per-agent objects. ECS itself does not demand vectorization, but BAM Engine treats it as the default. Every built-in system processes all agents at once, with the goods market's sequential matching rounds as the deliberate exception where strict per-agent ordering matters.
 
 See the [User Guide](https://bam-engine.readthedocs.io/en/latest/user_guide/index.html) for a full walkthrough of the model and its architecture.
 

{bamengine-0.9.1 → bamengine-0.9.2}/README.md

@@ -13,17 +13,10 @@
 <p align="center">
   A Python implementation of the BAM (Bottom-Up Adaptive Macroeconomics) model
   from <a href="https://doi.org/10.1007/978-88-470-1971-3"><em>Macroeconomics from the Bottom-up</em></a>
-  (Delli Gatti et al., 2011). Simulate households, firms, and banks
-  interacting across labor, credit, and goods markets, where macroeconomic
-  dynamics emerge from individual agent decisions.
-</p>
-
-<p align="center">
-  <em>Traditional economics models economies from the top down, assuming
-  markets automatically reach equilibrium. BAM Engine takes a different approach:
-  it simulates individual workers, firms, and banks making decisions and
-  interacting in markets, letting macroeconomic patterns emerge from the
-  bottom up.</em>
+  (Delli Gatti et al., 2011). It runs simulations of individual workers, firms, and
+  banks making decisions and interacting in labor, credit and goods markets, letting
+  macroeconomic patterns (growth, unemployment, inflation, business cycles) <b>emerge
+  from the bottom up</b>, instead of assuming them with aggregate equations.
 </p>
 
 <p align="center">
@@ -102,17 +95,16 @@ See the [Getting Started guide](https://bam-engine.readthedocs.io/en/latest/quic
 
 ## Features
 
-- **Complete BAM Model:** Full Chapter 3 implementation: firms, households, and banks interacting across labor, credit, and goods markets
-- **ECS Architecture:** Entity-Component-System design separates data (Roles) from behavior (Events) for clean extensibility
-- **Vectorized Performance:** All agent operations use NumPy arrays; no Python loops over agents
-- **Built-in Extensions:** R&D / Growth+, buffer-stock consumption, and taxation modules
-- **Validation Framework:** Three scenario validators with scoring and robustness analysis
-- **Calibration Pipeline:** Morris screening, grid search, and tiered stability testing
-- **Easy Configuration:** All parameters configurable without code changes via YAML files
+- **Complete BAM Implementation:** Baseline model from *Macroeconomics from the Bottom-up*, Chapter 3 (firms, households, and banks across labor, credit, and goods markets), three built-in extensions (R&D / Growth+, buffer-stock consumption, taxation), and a robustness analysis suite (internal validity, sensitivity, structural experiments).
+- **Vectorized Performance:** Agent state lives in parallel NumPy arrays and behavior is expressed as array transformations, not Python loops over agent objects. Simulations scale to large populations and long horizons.
+- **Pluggable Extension System:** Add custom roles, events, and pipeline hooks via decorators without modifying the engine. The same mechanism powers the built-in extensions.
+- **Parameter Calibration:** Automated pipeline for tuning model parameters against validation targets.
 
 ## Architecture
 
-BAM Engine uses an ECS (Entity-Component-System) architecture: agents are lightweight entities, state lives in Role components stored as NumPy arrays, and behavior is defined by Event systems executed via a YAML-configurable pipeline. Custom roles, events, and relationships can be added without modifying core code.
+BAM Engine uses an ECS (Entity-Component-System) architecture: agents are lightweight entities, state lives in **Role** components stored as parallel NumPy arrays, and behavior is defined by **Event** systems composed into a YAML-configurable pipeline. New roles, events, and relationships can be added through decorators, without modifying core code.
+
+The trade-off is a mindset shift: you write agent rules as systems that transform whole arrays of state at once, not as methods on per-agent objects. ECS itself does not demand vectorization, but BAM Engine treats it as the default. Every built-in system processes all agents at once, with the goods market's sequential matching rounds as the deliberate exception where strict per-agent ordering matters.
 
 See the [User Guide](https://bam-engine.readthedocs.io/en/latest/user_guide/index.html) for a full walkthrough of the model and its architecture.
 

{bamengine-0.9.1 → bamengine-0.9.2}/pyproject.toml

@@ -241,7 +241,11 @@ line-ending = "auto"
 docstring-code-format = true
 
 [tool.mypy]
-python_version = "3.11"
+# 3.12 (not the 3.11 floor) so mypy can parse PEP 695 `type` statements that
+# numpy >= 2.5 ships in its stubs; runtime 3.11 support is guarded by the test
+# matrix. The codebase uses `from __future__ import annotations` and no
+# 3.12-only runtime syntax, so this does not weaken our own checks.
+python_version = "3.12"
 strict = true
 files = ["src/"]
 disallow_untyped_decorators = false  # Allow @event, @role decorators

{bamengine-0.9.1 → bamengine-0.9.2}/src/bamengine/__init__.py

@@ -166,7 +166,7 @@ Notes
 
 from __future__ import annotations
 
-__version__: str = "0.9.1"
+__version__: str = "0.9.2"
 
 # ============================================================================
 # Standard library imports

{bamengine-0.9.1 → bamengine-0.9.2}/src/bamengine/core/relationship.py

@@ -212,7 +212,7 @@ class Relationship(
         Idx1D
             Array of edge indices where source_ids == source_id
         """
-        return np.where(self.source_ids[: self.size] == source_id)[0]
+        return np.flatnonzero(self.source_ids[: self.size] == source_id)
 
     def query_targets(self, target_id: int) -> Idx1D:
         """
@@ -228,7 +228,7 @@ class Relationship(
         Idx1D
             Array of edge indices where target_ids == target_id
         """
-        return np.where(self.target_ids[: self.size] == target_id)[0]
+        return np.flatnonzero(self.target_ids[: self.size] == target_id)
 
     def aggregate_by_source(
         self,

{bamengine-0.9.1 → bamengine-0.9.2}/src/bamengine/simulation.py

@@ -62,7 +62,7 @@ from collections.abc import Mapping
 from dataclasses import dataclass, field
 from importlib import resources
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Literal
+from typing import TYPE_CHECKING, Any, Literal, get_args
 
 import numpy as np
 import yaml
@@ -92,7 +92,7 @@ from bamengine.roles import (
 from bamengine.relationships import LoanBook  # Must import after roles
 
 # isort: on
-from bamengine.typing import Float1D
+from bamengine.typing import Bool1D, Float1D, Int1D
 
 __all__ = ["Simulation"]
 
@@ -110,6 +110,36 @@ _ANNOTATION_DTYPE: dict[str, tuple[type[np.generic], int]] = {
     "Idx1D": (np.intp, -1),
 }
 
+# Resolved type-alias objects → (numpy dtype, fill value), used when annotations
+# are real objects (no ``from __future__ import annotations`` in the role's module).
+# Keying on the alias objects is stable across numpy versions, unlike the internal
+# ``__args__`` layout of ``NDArray[...]`` (which changed in numpy 2.5). Idx1D is
+# intentionally absent: it equals Int1D on 64-bit platforms (np.intp is np.int64),
+# so a resolved agent-id field maps to (int, 0); the -1 sentinel is reachable via
+# the Agent class or string annotations.
+_ALIAS_DTYPE: dict[Any, tuple[type[np.generic], int]] = {
+    Float1D: (np.float64, 0),
+    Int1D: (np.int64, 0),
+    Bool1D: (np.bool_, 0),
+}
+
+
+def _np_scalar_from_annotation(ann: Any) -> type[np.generic] | None:
+    """Extract the numpy scalar type from an ``NDArray[...]`` annotation.
+
+    Robust to the numpy 2.5 layout change where ``NDArray[np.int64].__args__``
+    became ``(np.int64,)`` instead of ``(Any, np.dtype[np.int64])``. Returns
+    ``None`` when no numpy scalar can be found.
+    """
+    for arg in get_args(ann):
+        if isinstance(arg, type) and issubclass(arg, np.generic):
+            return arg  # numpy >= 2.5: NDArray[X] -> (X,)
+        for inner in get_args(arg):
+            if isinstance(inner, type) and issubclass(inner, np.generic):
+                return inner  # numpy <= 2.4: NDArray[X] -> (Any, np.dtype[X])
+    return None
+
+
 log = logging.getLogger(__name__)
 
 
@@ -1637,33 +1667,51 @@ class Simulation:
     def _resolve_annotation_dtype(ann: Any) -> tuple[type[np.generic], int]:
         """Resolve a role field annotation to (numpy dtype, fill value).
 
-        Handles string annotations (from ``__future__`` annotations),
-        resolved ``GenericAlias`` / type objects, and the Agent class.
-        Agent/Idx1D annotations use -1 fill (unassigned sentinel);
-        all others use 0.
+        Handles string annotations (from ``__future__`` annotations), the
+        Agent class, the known resolved type aliases, and arbitrary
+        ``NDArray[np.<scalar>]`` objects. Agent (class / string) annotations
+        use -1 fill (unassigned sentinel); all others use 0.
+
+        Raises
+        ------
+        TypeError
+            If the annotation cannot be mapped to a numpy dtype. Failing
+            loudly avoids silently materialising the wrong dtype (e.g. an
+            ``Int`` field becoming float64), which is what a quiet fallback
+            did before numpy 2.5 changed ``NDArray`` introspection.
         """
         # String annotations (e.g., 'Float', 'Int1D')
         if isinstance(ann, str):
-            return _ANNOTATION_DTYPE.get(ann, (np.float64, 0))
+            try:
+                return _ANNOTATION_DTYPE[ann]
+            except KeyError:
+                raise TypeError(
+                    f"Cannot resolve a numpy dtype for role field annotation "
+                    f"{ann!r}. Use Float, Int, Bool, Agent, or an "
+                    f"NDArray[np.<scalar>] annotation."
+                ) from None
 
-        # Agent class (bamengine.core.agent.Agent) — special case
+        # Agent class (bamengine.core.agent.Agent) — unassigned sentinel -1
         from bamengine.core.agent import Agent as AgentCls
 
         if ann is AgentCls:
             return np.intp, -1
 
-        # Resolved GenericAlias: NDArray[np.float64] → extract inner dtype
-        args: tuple[Any, ...] = getattr(ann, "__args__", ())
-        if len(args) >= 2:
-            inner_args: tuple[Any, ...] = getattr(args[1], "__args__", ())
-            if (
-                inner_args
-                and isinstance(inner_args[0], type)
-                and issubclass(inner_args[0], np.generic)
-            ):
-                return inner_args[0], 0
-
-        return np.float64, 0  # pragma: no cover - default fallback
+        # Known resolved type aliases (Float1D/Int1D/Bool1D and their friendly
+        # aliases) — version-independent, no NDArray introspection needed.
+        resolved = _ALIAS_DTYPE.get(ann)
+        if resolved is not None:
+            return resolved
+
+        # Arbitrary NDArray[np.<scalar>] — introspect robustly across numpy.
+        scalar = _np_scalar_from_annotation(ann)
+        if scalar is not None:
+            return scalar, 0
+
+        raise TypeError(
+            f"Cannot resolve a numpy dtype for role field annotation {ann!r}. "
+            f"Use Float, Int, Bool, Agent, or an NDArray[np.<scalar>] annotation."
+        )
 
     def get_event(self, name: str) -> Any:
         """

{bamengine-0.9.1 → bamengine-0.9.2/src/bamengine.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bamengine
-Version: 0.9.1
+Version: 0.9.2
 Summary: A modular Python framework for the BAM agent-based macroeconomic model
 Author-email: Kostas Ganitis <ganitiskostas@gmail.com>
 Maintainer-email: Kostas Ganitis <ganitiskostas@gmail.com>
@@ -83,17 +83,10 @@ Dynamic: license-file
 <p align="center">
   A Python implementation of the BAM (Bottom-Up Adaptive Macroeconomics) model
   from <a href="https://doi.org/10.1007/978-88-470-1971-3"><em>Macroeconomics from the Bottom-up</em></a>
-  (Delli Gatti et al., 2011). Simulate households, firms, and banks
-  interacting across labor, credit, and goods markets, where macroeconomic
-  dynamics emerge from individual agent decisions.
-</p>
-
-<p align="center">
-  <em>Traditional economics models economies from the top down, assuming
-  markets automatically reach equilibrium. BAM Engine takes a different approach:
-  it simulates individual workers, firms, and banks making decisions and
-  interacting in markets, letting macroeconomic patterns emerge from the
-  bottom up.</em>
+  (Delli Gatti et al., 2011). It runs simulations of individual workers, firms, and
+  banks making decisions and interacting in labor, credit and goods markets, letting
+  macroeconomic patterns (growth, unemployment, inflation, business cycles) <b>emerge
+  from the bottom up</b>, instead of assuming them with aggregate equations.
 </p>
 
 <p align="center">
@@ -172,17 +165,16 @@ See the [Getting Started guide](https://bam-engine.readthedocs.io/en/latest/quic
 
 ## Features
 
-- **Complete BAM Model:** Full Chapter 3 implementation: firms, households, and banks interacting across labor, credit, and goods markets
-- **ECS Architecture:** Entity-Component-System design separates data (Roles) from behavior (Events) for clean extensibility
-- **Vectorized Performance:** All agent operations use NumPy arrays; no Python loops over agents
-- **Built-in Extensions:** R&D / Growth+, buffer-stock consumption, and taxation modules
-- **Validation Framework:** Three scenario validators with scoring and robustness analysis
-- **Calibration Pipeline:** Morris screening, grid search, and tiered stability testing
-- **Easy Configuration:** All parameters configurable without code changes via YAML files
+- **Complete BAM Implementation:** Baseline model from *Macroeconomics from the Bottom-up*, Chapter 3 (firms, households, and banks across labor, credit, and goods markets), three built-in extensions (R&D / Growth+, buffer-stock consumption, taxation), and a robustness analysis suite (internal validity, sensitivity, structural experiments).
+- **Vectorized Performance:** Agent state lives in parallel NumPy arrays and behavior is expressed as array transformations, not Python loops over agent objects. Simulations scale to large populations and long horizons.
+- **Pluggable Extension System:** Add custom roles, events, and pipeline hooks via decorators without modifying the engine. The same mechanism powers the built-in extensions.
+- **Parameter Calibration:** Automated pipeline for tuning model parameters against validation targets.
 
 ## Architecture
 
-BAM Engine uses an ECS (Entity-Component-System) architecture: agents are lightweight entities, state lives in Role components stored as NumPy arrays, and behavior is defined by Event systems executed via a YAML-configurable pipeline. Custom roles, events, and relationships can be added without modifying core code.
+BAM Engine uses an ECS (Entity-Component-System) architecture: agents are lightweight entities, state lives in **Role** components stored as parallel NumPy arrays, and behavior is defined by **Event** systems composed into a YAML-configurable pipeline. New roles, events, and relationships can be added through decorators, without modifying core code.
+
+The trade-off is a mindset shift: you write agent rules as systems that transform whole arrays of state at once, not as methods on per-agent objects. ECS itself does not demand vectorization, but BAM Engine treats it as the default. Every built-in system processes all agents at once, with the goods market's sequential matching rounds as the deliberate exception where strict per-agent ordering matters.
 
 See the [User Guide](https://bam-engine.readthedocs.io/en/latest/user_guide/index.html) for a full walkthrough of the model and its architecture.
 

{bamengine-0.9.1 → bamengine-0.9.2}/src/validation/robustness/internal_validity.py

@@ -330,8 +330,34 @@ def _analyze_seed(
 ) -> SeedAnalysis:
     """Compute co-movements, AR fit, and summary stats for one seed."""
     if ts.collapsed:
-        # Return a minimal result for collapsed simulations
+        # Compute basic scalar stats from pre-collapse data when enough
+        # post-burn-in data exists.  This lets entry-experiment figures
+        # show degradation even when most/all seeds collapse.
         n_lags = 2 * max_lag + 1
+        bi = burn_in
+        post_bi_len = len(ts.unemployment) - bi
+
+        if post_bi_len >= 10:
+            unemp_ss = ts.unemployment[bi:]
+            gdp_growth_ss = ts.gdp_growth[max(bi - 1, 0) :]
+            unemployment_mean = float(np.nanmean(unemp_ss))
+            unemployment_std = float(np.nanstd(unemp_ss))
+            inflation_mean = float(np.nanmean(ts.inflation[bi:]))
+            inflation_std = float(np.nanstd(ts.inflation[bi:]))
+            gdp_growth_mean = float(np.nanmean(gdp_growth_ss))
+            gdp_growth_std = float(np.nanstd(gdp_growth_ss))
+            real_wage_mean = float(np.nanmean(ts.real_wage[bi:]))
+            productivity_mean = float(np.nanmean(ts.avg_productivity[bi:]))
+        else:
+            unemployment_mean = np.nan
+            unemployment_std = np.nan
+            inflation_mean = np.nan
+            inflation_std = np.nan
+            gdp_growth_mean = np.nan
+            gdp_growth_std = np.nan
+            real_wage_mean = np.nan
+            productivity_mean = np.nan
+
         return SeedAnalysis(
             seed=ts.seed,
             collapsed=True,
@@ -340,14 +366,14 @@ def _analyze_seed(
             ar_order=ar_order,
             ar_r_squared=0.0,
             irf=np.zeros(irf_periods),
-            unemployment_mean=np.nan,
-            unemployment_std=np.nan,
-            inflation_mean=np.nan,
-            inflation_std=np.nan,
-            gdp_growth_mean=np.nan,
-            gdp_growth_std=np.nan,
-            real_wage_mean=np.nan,
-            productivity_mean=np.nan,
+            unemployment_mean=unemployment_mean,
+            unemployment_std=unemployment_std,
+            inflation_mean=inflation_mean,
+            inflation_std=inflation_std,
+            gdp_growth_mean=gdp_growth_mean,
+            gdp_growth_std=gdp_growth_std,
+            real_wage_mean=real_wage_mean,
+            productivity_mean=productivity_mean,
             phillips_corr=np.nan,
             okun_corr=np.nan,
             beveridge_corr=np.nan,

{bamengine-0.9.1 → bamengine-0.9.2}/src/validation/robustness/sensitivity.py

@@ -174,8 +174,13 @@ def _aggregate_seed_analyses(
 
     stats_dict: dict[str, dict[str, float]] = {}
     for attr_name in stat_fields:
+        # Use all seeds (not just valid) so that collapsed/degenerate
+        # seeds with pre-collapse data contribute to scalar stats.
+        # The NaN filter handles seeds that have no usable data.
         values = [
-            getattr(a, attr_name) for a in valid if not np.isnan(getattr(a, attr_name))
+            getattr(a, attr_name)
+            for a in seed_analyses
+            if not np.isnan(getattr(a, attr_name))
         ]
         if values:
             mean_val = float(np.mean(values))

{bamengine-0.9.1 → bamengine-0.9.2}/src/validation/robustness/viz.py

@@ -345,16 +345,17 @@ def plot_pa_gdp_comparison(
     output_dir.mkdir(parents=True, exist_ok=True)
 
     # Use log_gdp from the PA-off seed analysis and baseline for comparison
-    log_gdp_off = pa_result.pa_off_validity.seed_analyses[seed].log_gdp
+    burn_in = pa_result.pa_off_validity.burn_in
+    log_gdp_off = pa_result.pa_off_validity.seed_analyses[seed].log_gdp[burn_in:]
     if pa_result.baseline_validity is not None:
-        log_gdp_on = pa_result.baseline_validity.seed_analyses[seed].log_gdp
+        log_gdp_on = pa_result.baseline_validity.seed_analyses[seed].log_gdp[burn_in:]
     else:
         raise ValueError(
             "PA GDP comparison requires baseline; re-run with include_baseline=True"
         )
 
-    fig, ax = plt.subplots(1, 1, figsize=(12, 5))
-    periods = np.arange(len(log_gdp_on))
+    fig, ax = plt.subplots(1, 1, figsize=(8, 6))
+    periods = np.arange(burn_in, burn_in + len(log_gdp_on))
     ax.plot(periods, log_gdp_on, "b-", linewidth=1, alpha=0.8, label="PA on")
     ax.plot(
         periods[: len(log_gdp_off)],
@@ -507,7 +508,7 @@ def plot_entry_comparison(
     ]
     collapse_rates = [vr.collapse_rate for vr in vrs]
 
-    fig, axes = plt.subplots(1, 3, figsize=(14, 5))
+    fig, axes = plt.subplots(1, 3, figsize=(10, 7))
     fig.suptitle(
         "Entry Neutrality: Impact of Profit Taxation (Section 3.10.2)",
         fontsize=13,

{bamengine-0.9.1 → bamengine-0.9.2}/src/validation/scenarios/_utils.py

@@ -2,9 +2,53 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 import numpy as np
 from numpy.typing import NDArray
 
+if TYPE_CHECKING:
+    from matplotlib.axes import Axes
+
+
+def shade_beyond_extreme(
+    ax: Axes, extreme_min: float, extreme_max: float, axis: str = "y"
+) -> None:
+    """Shade areas beyond extreme bounds darker than the transition zone.
+
+    Creates a visual hierarchy:
+    - Normal zone (white): within normal bounds
+    - Transition zone (alpha=0.1 red): between extreme and normal bounds
+    - Beyond extreme (alpha=0.25 red): outside extreme bounds
+
+    Must be called AFTER all data is plotted so axis limits are set by the data.
+
+    Parameters
+    ----------
+    ax : Axes
+        Matplotlib axes to shade.
+    extreme_min, extreme_max : float
+        Extreme bound values.
+    axis : str
+        ``"y"`` for horizontal bands, ``"x"`` for vertical bands.
+    """
+    alpha = 0.25
+    color = "red"
+    if axis == "y":
+        ymin, ymax = ax.get_ylim()
+        if ymin < extreme_min:
+            ax.axhspan(ymin, extreme_min, alpha=alpha, color=color, zorder=0)
+        if ymax > extreme_max:
+            ax.axhspan(extreme_max, ymax, alpha=alpha, color=color, zorder=0)
+        ax.set_ylim(ymin, ymax)
+    else:
+        xmin, xmax = ax.get_xlim()
+        if xmin < extreme_min:
+            ax.axvspan(xmin, extreme_min, alpha=alpha, color=color, zorder=0)
+        if xmax > extreme_max:
+            ax.axvspan(extreme_max, xmax, alpha=alpha, color=color, zorder=0)
+        ax.set_xlim(xmin, xmax)
+
 
 def compute_detrended_correlation(
     x: NDArray[np.floating], y: NDArray[np.floating]

{bamengine-0.9.1 → bamengine-0.9.2}/src/validation/scenarios/baseline/targets.yaml

@@ -34,10 +34,10 @@ metadata:
     time_series:
       unemployment_rate:
         targets:
-          normal_min: 0.03
-          normal_max: 0.08
-          extreme_min: 0.02
-          extreme_max: 0.12
+          normal_min: 0.02
+          normal_max: 0.12
+          extreme_min: 0.00
+          extreme_max: 0.15
           mean_target: 0.065     # Book Figure 3.2b extracted
 
       inflation_rate:
@@ -50,10 +50,10 @@ metadata:
 
       log_gdp:
         targets:
-          normal_min: 5.438
-          normal_max: 5.491
-          extreme_min: 5.394
-          extreme_max: 5.501
+          normal_min: 5.394
+          normal_max: 5.501
+          extreme_min: 5.359
+          extreme_max: 5.521
           mean_target: 5.460
 
       real_wage:

{bamengine-0.9.1 → bamengine-0.9.2}/src/validation/scenarios/baseline/viz.py

@@ -22,6 +22,7 @@ import numpy as np
 from scipy.stats import skew
 
 from bamengine import ops
+from validation.scenarios._utils import shade_beyond_extreme
 from validation.scenarios.baseline import BaselineMetrics
 from validation.scoring import STATUS_COLORS, check_range
 
@@ -174,7 +175,6 @@ def visualize_baseline_results(
         bounds["log_gdp"]["normal_min"],
         alpha=0.1,
         color="red",
-        label="Extreme zone",
     )
     ax.axhspan(
         bounds["log_gdp"]["normal_max"],
@@ -207,7 +207,7 @@ def visualize_baseline_results(
     ax.set_ylabel("Log output")
     ax.set_xlabel("t")
     ax.grid(True, linestyle="--", alpha=0.3)
-    ax.legend(loc="upper left", fontsize=7)
+    ax.legend(loc="lower left", fontsize=7)
     # Stats box at lower right to avoid legend overlap
     b = bounds["log_gdp"]
     actual_mean = np.mean(log_gdp)
@@ -225,6 +225,7 @@ def visualize_baseline_results(
         horizontalalignment="right",
         bbox=dict(boxstyle="round", facecolor="wheat", alpha=0.5),
     )
+    shade_beyond_extreme(ax, b["extreme_min"], b["extreme_max"])
 
     # Panel (0,1): Unemployment Rate
     ax = axes[0, 1]
@@ -269,6 +270,11 @@ def visualize_baseline_results(
     ax.grid(True, linestyle="--", alpha=0.3)
     ax.set_ylim(bottom=0)
     add_stats_box(ax, unemployment_pct, "unemployment", is_pct=True)
+    shade_beyond_extreme(
+        ax,
+        bounds["unemployment"]["extreme_min"] * 100,
+        bounds["unemployment"]["extreme_max"] * 100,
+    )
 
     # Panel (1,0): Annual Inflation Rate
     # NOTE: Unlike other panels, inflation shows ALL periods (no burn-in) with x-axis in years,
@@ -319,6 +325,11 @@ def visualize_baseline_results(
     ax.grid(True, linestyle="--", alpha=0.3)
     # Stats box uses full-period data (matching the plot and validation metrics)
     add_stats_box(ax, inflation_full_pct, "inflation", is_pct=True)
+    shade_beyond_extreme(
+        ax,
+        bounds["inflation"]["extreme_min"] * 100,
+        bounds["inflation"]["extreme_max"] * 100,
+    )
 
     # Panel (1,1): Productivity and Real Wage Co-movement (two-line plot)
     ax = axes[1, 1]
@@ -377,6 +388,7 @@ def visualize_baseline_results(
         horizontalalignment="left",
         bbox=dict(boxstyle="round", facecolor="wheat", alpha=0.5),
     )
+    shade_beyond_extreme(ax, b["extreme_min"], b["extreme_max"])
 
     # Bottom 2x2: Macroeconomic curves
     # --------------------------------

{bamengine-0.9.1 → bamengine-0.9.2}/src/validation/scenarios/growth_plus/viz.py

@@ -22,6 +22,7 @@ import numpy as np
 from scipy.stats import skew
 
 from bamengine import ops
+from validation.scenarios._utils import shade_beyond_extreme
 from validation.scenarios.growth_plus import GrowthPlusMetrics
 from validation.scoring import (
     STATUS_COLORS,
@@ -77,34 +78,6 @@ def _save_panels(fig, axes, output_dir, panel_names, dpi=150):
     print(f"Saved {len(panel_names)} panels + combined figure to {output_dir}/")
 
 
-def _shade_beyond_extreme(ax, extreme_min, extreme_max, axis="y"):
-    """Shade areas beyond extreme bounds darker than the transition zone.
-
-    Creates a visual hierarchy:
-    - Normal zone (white): within normal bounds
-    - Transition zone (alpha=0.1 red): between extreme and normal bounds
-    - Beyond extreme (alpha=0.25 red): outside extreme bounds — clearly dangerous
-
-    Must be called AFTER all data is plotted so axis limits are set by the data.
-    """
-    alpha = 0.25
-    color = "red"
-    if axis == "y":
-        ymin, ymax = ax.get_ylim()
-        if ymin < extreme_min:
-            ax.axhspan(ymin, extreme_min, alpha=alpha, color=color, zorder=0)
-        if ymax > extreme_max:
-            ax.axhspan(extreme_max, ymax, alpha=alpha, color=color, zorder=0)
-        ax.set_ylim(ymin, ymax)
-    else:
-        xmin, xmax = ax.get_xlim()
-        if xmin < extreme_min:
-            ax.axvspan(xmin, extreme_min, alpha=alpha, color=color, zorder=0)
-        if xmax > extreme_max:
-            ax.axvspan(extreme_max, xmax, alpha=alpha, color=color, zorder=0)
-        ax.set_xlim(xmin, xmax)
-
-
 def _add_cv_cyclicality_box(ax, mean, cv, cyclicality_corr, label="pro-cyc"):
     """Add stats box showing pre-computed mean, CV, and cyclicality correlation."""
     ax.text(
@@ -308,7 +281,7 @@ def visualize_growth_plus_results(
         horizontalalignment="right",
         bbox=dict(boxstyle="round", facecolor="wheat", alpha=0.5),
     )
-    _shade_beyond_extreme(ax, b["extreme_min"], b["extreme_max"])
+    shade_beyond_extreme(ax, b["extreme_min"], b["extreme_max"])
 
     # Panel (0,1): Unemployment Rate
     ax = axes[0, 1]
@@ -353,7 +326,7 @@ def visualize_growth_plus_results(
     ax.grid(True, linestyle="--", alpha=0.3)
     ax.set_ylim(bottom=0)
     add_stats_box(ax, unemployment_pct, "unemployment", is_pct=True)
-    _shade_beyond_extreme(
+    shade_beyond_extreme(
         ax,
         bounds["unemployment"]["extreme_min"] * 100,
         bounds["unemployment"]["extreme_max"] * 100,
@@ -409,7 +382,7 @@ def visualize_growth_plus_results(
     # Stats box uses post-burn-in data (matching validation metrics)
     inflation_ss_pct = metrics.inflation[burn_in:] * 100
     add_stats_box(ax, inflation_ss_pct, "inflation", is_pct=True)
-    _shade_beyond_extreme(
+    shade_beyond_extreme(
         ax,
         bounds["inflation"]["extreme_min"] * 100,
         bounds["inflation"]["extreme_max"] * 100,
@@ -787,7 +760,7 @@ def visualize_financial_dynamics(
             verticalalignment="top",
             bbox=dict(boxstyle="round", facecolor=box_color, alpha=0.7),
         )
-        _shade_beyond_extreme(ax, extreme_min, extreme_max, axis="x")
+        shade_beyond_extreme(ax, extreme_min, extreme_max, axis="x")
     ax.set_title("Output Growth Rate Distribution", fontsize=12, fontweight="bold")
     ax.set_xlabel("Output growth rate")
     ax.set_ylabel("Log-rank")
@@ -884,7 +857,7 @@ def visualize_financial_dynamics(
             verticalalignment="top",
             bbox=dict(boxstyle="round", facecolor=box_color, alpha=0.7),
         )
-        _shade_beyond_extreme(ax, extreme_min, extreme_max, axis="x")
+        shade_beyond_extreme(ax, extreme_min, extreme_max, axis="x")
     ax.set_title(
         "Firms' Asset Growth Rate Distribution", fontsize=12, fontweight="bold"
     )
@@ -966,7 +939,7 @@ def visualize_financial_dynamics(
         horizontalalignment="left",
         bbox=dict(boxstyle="round", facecolor="wheat", alpha=0.5),
     )
-    _shade_beyond_extreme(ax, extreme_min * 100, extreme_max * 100)
+    shade_beyond_extreme(ax, extreme_min * 100, extreme_max * 100)
 
     # Figure 3.6d: Number of Bankruptcies
     ax = axes[1, 1]
@@ -1064,7 +1037,7 @@ def visualize_financial_dynamics(
         metrics.financial_fragility_cv,
         metrics.fragility_gdp_correlation,
     )
-    _shade_beyond_extreme(ax, extreme_min, extreme_max)
+    shade_beyond_extreme(ax, extreme_min, extreme_max)
 
     # Figure 3.7b: Price Ratio (Market Price / Clearing Price)
     ax = axes[2, 1]
@@ -1114,7 +1087,7 @@ def visualize_financial_dynamics(
         metrics.price_ratio_gdp_correlation,
         label="counter-cyc",
     )
-    _shade_beyond_extreme(ax, pr_extreme_min, pr_extreme_max)
+    shade_beyond_extreme(ax, pr_extreme_min, pr_extreme_max)
 
     # Figure 3.7c: Price Dispersion
     ax = axes[3, 0]
@@ -1168,7 +1141,7 @@ def visualize_financial_dynamics(
         horizontalalignment="left",
         bbox=dict(boxstyle="round", facecolor="wheat", alpha=0.5),
     )
-    _shade_beyond_extreme(ax, pd_extreme_min, pd_extreme_max)
+    shade_beyond_extreme(ax, pd_extreme_min, pd_extreme_max)
 
     # Figure 3.7d: Equity and Sales Dispersion
     ax = axes[3, 1]
@@ -1224,7 +1197,7 @@ def visualize_financial_dynamics(
         horizontalalignment="left",
         bbox=dict(boxstyle="round", facecolor="wheat", alpha=0.5),
     )
-    _shade_beyond_extreme(ax, es_extreme_min, es_extreme_max)
+    shade_beyond_extreme(ax, es_extreme_min, es_extreme_max)
 
     plt.tight_layout()
     _save_panels(fig, axes, _OUTPUT_DIR, _FINANCIAL_PANEL_NAMES)