Core module

This section documents the public entry points exposed by the eb-optimization package.

The core module provides top-level constants, policy helpers, and convenience functions that are commonly used when applying optimization logic within the Electric Barometer ecosystem.

eb_optimization

eb_optimization — optimization and tuning layer for the Electric Barometer ecosystem.

This package contains the optimization layer of Electric Barometer:

• search: generic, reusable search mechanics (grids, tie-breaking kernels)
• tuning: calibration and selection utilities (e.g., cost-ratio tuning, sensitivity sweeps)
• policies: frozen, declarative policy artifacts for downstream execution

It intentionally does not define metric primitives or evaluation math. Those live in eb-metrics (and orchestration lives in eb-evaluation).

RALDeltas dataclass

Two-band additive deltas for a two-band RAL policy.

RALTwoBandPolicy dataclass

Portable policy artifact for two-band additive RAL.

This policy encodes the exact "two-band" additive RAL used in the ISO-NE example notebook:

• If baseline forecast \(\hat{y}\) is in the mid-risk band: $$ \hat{y}^{(r)} = \hat{y} + d_{\text{mid}} $$
• If baseline forecast \(\hat{y}\) is in the high-risk band: $$ \hat{y}^{(r)} = \hat{y} + d_{\text{high}} $$

Deltas can be:

• global (fallback) via global_deltas, and/or
• per-key overrides via per_key_deltas, keyed by a segment key column (e.g., interface).

Notes

This class is intentionally a policy artifact (parameters + deterministic application). It does not learn deltas; it only stores and applies them.

get_deltas(key=None)

Return deltas for a key (or the global deltas if none/unknown).

adjust_forecast(df, forecast_col, *, key_col=None)

Apply the two-band additive RAL policy to a forecast column.

Parameters:

Name	Type	Description	Default
df	DataFrame	Input DataFrame containing the forecast to adjust.	required
forecast_col	str	Column name containing baseline forecast values.	required
key_col	str	Column name containing keys for per-key deltas (e.g., "interface"). If omitted, the global deltas are applied.	None

Returns:

Type	Description
Series	Adjusted forecast values as a series named "readiness_forecast".

transform(df, forecast_col, *, key_col=None)

Transform the input DataFrame by applying the forecast adjustment.

to_dict()

Serialize to a JSON-friendly dict.

from_dict(d) classmethod

Deserialize from a dict produced by to_dict().

EntityCostRatioEstimate dataclass

Entity-level cost ratio calibration artifact.

This container is designed to be persistable and ergonomic:

• table can be saved to Parquet/CSV without DataFrame-in-cell object columns.
• curves retains the full per-entity sensitivity curves for audit/plotting.
• Shared metadata captures the governance context of the run.

Attributes:

Name	Type	Description
entity_col	str	Name of the entity identifier column used in table.
method	str	Method identifier used to produce the estimate (e.g., "cost_balance").
grid	ndarray	The filtered candidate grid actually searched (strictly positive values). The order of this grid defines tie-breaking for each entity.
selection	str	Selection strategy used once each curve is computed ("curve" or "kernel").
tie_break	str	Tie-breaking rule applied when multiple candidates achieve the same objective. For this routine it is always "first".
table	DataFrame	One row per entity with scalar results and summary diagnostics. Columns include: - entity_col - R_star - n - under_cost - over_cost - gap - diagnostics (dict; intended to be JSON-serializable)
curves	dict[Any, DataFrame]	Mapping of entity_id -> sensitivity curve DataFrame for that entity. Each curve has columns: [R, under_cost, over_cost, gap].

apply_ral_policy(df, forecast_col, policy=DEFAULT_RAL_POLICY)

Convenience functional wrapper to apply a RALPolicy.