Skip to content

Performance

Limits is one frozen object holding every size cap and tunable threshold the library uses: the largest policy it will compile, the reconstruction margin, the conformal α, and so on. You pass a Limits to Module (and to dispatch) to change them; DEFAULT_LIMITS is what you get otherwise. Open this page for the exact field names; for what each field means, its unit and when to change it, read Defaults and limits.

Public here: Limits, DEFAULT_LIMITS, gw_alpha, k_median_threshold. gw_alpha() (≈ 0.8786) is the best Max-Cut ratio a polynomial algorithm can promise if the Unique Games Conjecture holds; k_median_threshold() (1 + 2/e ≈ 1.736) is a hardness lower bound. Neither is a guarantee of this library's code. Capacity planning: Limits and performance.

performance

Budgets and size limits for the runtime.

These are the size caps the library enforces and the timing targets its tests check. A module that exceeds a size cap abstains or raises rather than running an unbounded exact procedure.

Limits dataclass 

Limits(
    max_star_height: int = 3,
    max_dfa_states: int = 256,
    max_nfa_states: int = 512,
    max_game_vertices: int = 200,
    max_wl_k: int = 2,
    max_table_cells_exact: int = 64,
    max_switch_steps: int = 10000,
    max_parity_depth: int = 64,
    max_karp_vertices: int = 200,
    reconstruction_margin: float = 0.05,
    conformal_alpha: float = 0.1,
    operational_fk_prefactor: float = 2.0,
    friedgut_kalai_prefactor: float = float(2**19),
    decide_ms_budget: float = 50.0,
    compile_ms_budget: float = 200.0,
    require_conformal_calibration: bool = False,
    min_support: float = 0.5,
    require_support: bool = False,
)

Hard caps. Tune per deployment; defaults fit interactive examples.

Exceeding a size cap abstains or raises; it never runs an unbounded exact procedure. Where each cap is enforced:

  • max_star_height, max_nfa_states, max_dfa_states: policy compilation raises StarHeightError or CompileError.
  • max_game_vertices, max_parity_depth: the progress check (game) fails closed, so every decision abstains.
  • max_karp_vertices: the mean-payoff solver raises GameTooLarge; the progress check fails closed.
  • max_wl_k: the router refuses the subgoal.
  • max_table_cells_exact: sample_two_row raises ValueError for a larger table.
  • max_switch_steps: sample_switch raises ValueError when asked for more steps.

decide_ms_budget and compile_ms_budget are not timers: nothing stops a slow call. They are targets that tests/test_performance_budget.py checks on a representative module (median decide time and module build time).

The support check reads EvidenceSnapshot.support: it passes when the share of related cases agreeing with the proposed action is at least min_support. When support was not measured (None) it passes, unless require_support is set.

gw_alpha 

gw_alpha() -> float

Goemans–Williamson ratio, the UGC-optimal Max-Cut target.

Source code in src/grounded_decision/performance.py 
66
67
68
69
def gw_alpha() -> float:
    """Goemans–Williamson ratio, the UGC-optimal Max-Cut target."""

    return 0.8785672058

k_median_threshold 

k_median_threshold() -> float

Infimum polynomial approximation factor for metric k-median (125).

Source code in src/grounded_decision/performance.py 
72
73
74
75
76
77
def k_median_threshold() -> float:
    """Infimum polynomial approximation factor for metric k-median (125)."""

    from math import e

    return 1.0 + 2.0 / e