Public Representation Frontier

Pareto frontier search for public reporting representations.

class updatesupport.frontier.FrontierScenarioResult(scenario, q_name, q_description, min_cell_weight, hidden_columns, public_cells, hidden_cells, lower, upper, ambiguity, observed_value, public_adequate, bound_type='exact', screening_backend=None, screening_status=None, screening_certified=False, screening_exact_solve_run=False, screening_exact_solve_avoided=False, screening_conservative_ambiguity=None, screening_exact_ambiguity=None)[source]

Bases: object

One stress-test result for one public-representation candidate.

Parameters:

  • scenario (str)

  • q_name (str)

  • q_description (str)

  • min_cell_weight (float)

  • hidden_columns (tuple[str, ...])

  • public_cells (int)

  • hidden_cells (int)

  • lower (float)

  • upper (float)

  • ambiguity (float)

  • observed_value (float)

  • public_adequate (bool)

  • bound_type (str)

  • screening_backend (str | None)

  • screening_status (str | None)

  • screening_certified (bool)

  • screening_exact_solve_run (bool)

  • screening_exact_solve_avoided (bool)

  • screening_conservative_ambiguity (float | None)

  • screening_exact_ambiguity (float | None)

scenario: str
q_name: str
q_description: str
min_cell_weight: float
hidden_columns: tuple[str, ...]
public_cells: int
hidden_cells: int
lower: float
upper: float
ambiguity: float
observed_value: float
public_adequate: bool
bound_type: str = 'exact'
screening_backend: str | None = None
screening_status: str | None = None
screening_certified: bool = False
screening_exact_solve_run: bool = False
screening_exact_solve_avoided: bool = False
screening_conservative_ambiguity: float | None = None
screening_exact_ambiguity: float | None = None
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.frontier.FrontierSearchTrace(search, exact, evaluated_candidates, candidate_space_size, scenario_count, max_added_columns, max_evaluations=None, beam_width=None, enforce_bucket_budget=False, skipped_by_budget=0, pruned_by_dominance=0, pruned_by_beam=0, scalarized_weights=None, minimum_objective=None, solver=None, solver_status=None, objective_value=None, optimization_guarantee=None, oracle_iterations=0, oracle_rejections=0, stopping_reason='completed')[source]

Bases: object

Metadata describing how the frontier search was run.

Parameters:

  • search (str)

  • exact (bool)

  • evaluated_candidates (int)

  • candidate_space_size (int)

  • scenario_count (int)

  • max_added_columns (int)

  • max_evaluations (int | None)

  • beam_width (int | None)

  • enforce_bucket_budget (bool)

  • skipped_by_budget (int)

  • pruned_by_dominance (int)

  • pruned_by_beam (int)

  • scalarized_weights (dict[str, float] | None)

  • minimum_objective (str | None)

  • solver (str | None)

  • solver_status (str | None)

  • objective_value (float | None)

  • optimization_guarantee (str | None)

  • oracle_iterations (int)

  • oracle_rejections (int)

  • stopping_reason (str)

search: str
exact: bool
evaluated_candidates: int
candidate_space_size: int
scenario_count: int
max_added_columns: int
max_evaluations: int | None = None
beam_width: int | None = None
enforce_bucket_budget: bool = False
skipped_by_budget: int = 0
pruned_by_dominance: int = 0
pruned_by_beam: int = 0
scalarized_weights: dict[str, float] | None = None
minimum_objective: str | None = None
solver: str | None = None
solver_status: str | None = None
objective_value: float | None = None
optimization_guarantee: str | None = None
oracle_iterations: int = 0
oracle_rejections: int = 0
stopping_reason: str = 'completed'
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.frontier.FrontierScreeningSummary(backend, candidate_count, endpoint_count, scenario_count, certified_count, exact_solve_count, exact_solve_avoided_count, conservative_endpoint_count, exact_endpoint_count, support_solve_count, compiled_template_count, exact_fallback, ambiguity_limit, reason='')[source]

Bases: object

Opt-in conservative endpoint screening used during frontier evaluation.

Parameters:

  • backend (str)

  • candidate_count (int)

  • endpoint_count (int)

  • scenario_count (int)

  • certified_count (int)

  • exact_solve_count (int)

  • exact_solve_avoided_count (int)

  • conservative_endpoint_count (int)

  • exact_endpoint_count (int)

  • support_solve_count (int)

  • compiled_template_count (int)

  • exact_fallback (bool)

  • ambiguity_limit (float | None)

  • reason (str)

backend: str
candidate_count: int
endpoint_count: int
scenario_count: int
certified_count: int
exact_solve_count: int
exact_solve_avoided_count: int
conservative_endpoint_count: int
exact_endpoint_count: int
support_solve_count: int
compiled_template_count: int
exact_fallback: bool
ambiguity_limit: float | None
reason: str = ''
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.frontier.FrontierScreenedRefinement(column, reason)[source]

Bases: object

A requested refinement column that was not evaluated.

Parameters:
column: str
reason: str
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.frontier.PublicRepresentationCandidate(added_columns, public_columns, public_cells, hidden_cells, min_public_cells, max_public_cells, min_hidden_cells, max_hidden_cells, scenarios, max_ambiguity, mean_ambiguity, passes_ambiguity_limit=None, scalarized_score=None, scalarized_components=<factory>)[source]

Bases: object

A public column set evaluated over a stress-test grid.

Parameters:
added_columns: tuple[str, ...]
public_columns: tuple[str, ...]
public_cells: int
hidden_cells: int
min_public_cells: int
max_public_cells: int
min_hidden_cells: int
max_hidden_cells: int
scenarios: tuple[FrontierScenarioResult, ...]
max_ambiguity: float
mean_ambiguity: float
passes_ambiguity_limit: bool | None = None
scalarized_score: float | None = None
scalarized_components: dict[str, float]
property added_column_count: int
property observed_value: float
property public_adequate: bool
property label: str
ambiguity_by_scenario()[source]
Return type:

dict[str, float]

as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.frontier.FrontierScenarioComparison(scenario, q_name, min_cell_weight, hidden_columns, baseline_ambiguity, selected_ambiguity, reduction, reduction_percent, passes_ambiguity_limit, public_adequate)[source]

Bases: object

Baseline-vs-selected ambiguity comparison for one scenario.

Parameters:

  • scenario (str)

  • q_name (str)

  • min_cell_weight (float)

  • hidden_columns (tuple[str, ...])

  • baseline_ambiguity (float | None)

  • selected_ambiguity (float)

  • reduction (float | None)

  • reduction_percent (float | None)

  • passes_ambiguity_limit (bool | None)

  • public_adequate (bool)

scenario: str
q_name: str
min_cell_weight: float
hidden_columns: tuple[str, ...]
baseline_ambiguity: float | None
selected_ambiguity: float
reduction: float | None
reduction_percent: float | None
passes_ambiguity_limit: bool | None
public_adequate: bool
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.frontier.FrontierCloseAlternative(added_columns, label, public_cells, max_ambiguity, delta_public_cells, delta_max_ambiguity)[source]

Bases: object

Nearby dominated alternative shown in an explanation.

Parameters:

  • added_columns (tuple[str, ...])

  • label (str)

  • public_cells (int)

  • max_ambiguity (float)

  • delta_public_cells (int)

  • delta_max_ambiguity (float)

added_columns: tuple[str, ...]
label: str
public_cells: int
max_ambiguity: float
delta_public_cells: int
delta_max_ambiguity: float
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.frontier.FrontierCandidateExplanation(candidate, baseline, scenario_comparisons, close_dominated_alternatives, screened_refinements, search_trace, ambiguity_limit, bucket_budget)[source]

Bases: ReportArtifactMixin

Review-oriented explanation for one frontier candidate.

Parameters:
candidate: PublicRepresentationCandidate
baseline: PublicRepresentationCandidate | None
scenario_comparisons: tuple[FrontierScenarioComparison, ...]
close_dominated_alternatives: tuple[FrontierCloseAlternative, ...]
screened_refinements: tuple[FrontierScreenedRefinement, ...]
search_trace: FrontierSearchTrace | None
ambiguity_limit: float | None
bucket_budget: int | None
property baseline_ambiguity: float | None
property selected_ambiguity: float
property ambiguity_reduction: float | None
property ambiguity_reduction_percent: float | None
property added_public_cells: int | None
property failing_scenarios: tuple[FrontierScenarioComparison, ...]
as_dict()[source]
Return type:

dict[str, Any]

to_markdown(*, heading='## Selected Representation Explanation')[source]
Parameters:

heading (str)

Return type:

str

class updatesupport.frontier.PublicRepresentationFrontier(candidates, frontier, dominated, base_public, hidden_columns, hidden_sets, min_cell_weights, candidate_refinements, requested_refinements=(), screened_refinements=(), ambiguity_limit=None, bucket_budget=None, scalarized_weights=None, title='Public Representation Frontier', row_count=None, search_trace=None, screening=None)[source]

Bases: ReportArtifactMixin

Pareto frontier over public-cell complexity and transport stability.

Parameters:
candidates: tuple[PublicRepresentationCandidate, ...]
frontier: tuple[PublicRepresentationCandidate, ...]
dominated: tuple[PublicRepresentationCandidate, ...]
base_public: tuple[str, ...]
hidden_columns: tuple[str, ...]
hidden_sets: tuple[tuple[str, ...], ...]
min_cell_weights: tuple[float, ...]
candidate_refinements: tuple[str, ...]
requested_refinements: tuple[str, ...] = ()
screened_refinements: tuple[FrontierScreenedRefinement, ...] = ()
ambiguity_limit: float | None = None
bucket_budget: int | None = None
scalarized_weights: dict[str, float] | None = None
title: str = 'Public Representation Frontier'
row_count: int | None = None
search_trace: FrontierSearchTrace | None = None
screening: FrontierScreeningSummary | None = None
property minimal_stable: PublicRepresentationCandidate | None

Smallest public representation satisfying ambiguity_limit.

best_under_bucket_budget(budget=None)[source]

Most stable candidate with no more than budget public cells.

Parameters:

budget (int | None)

Return type:

PublicRepresentationCandidate | None

property best_scalarized: PublicRepresentationCandidate | None

Lowest scalarized-score candidate, if scalarization was requested.

property baseline: PublicRepresentationCandidate | None
explain(candidate, *, top_close=5)[source]

Explain why one representation is or is not attractive.

Parameters:
Return type:

FrontierCandidateExplanation

explain_minimal_stable(*, top_close=5)[source]

Explain the minimal stable representation, if one exists.

Parameters:

top_close (int)

Return type:

FrontierCandidateExplanation | None

as_dict()[source]
Return type:

dict[str, Any]

to_markdown()[source]
Return type:

str

updatesupport.frontier.public_representation_frontier(data, *, base_public=None, public=None, hidden, target, candidate_refinements=None, candidate_columns=None, weight=None, min_cell_weight=1.0, min_cell_weights=None, hidden_sets=None, q_presets=('saturated',), ambiguity_limit=None, bucket_budget=None, max_refinements=None, max_added_columns=None, search='exhaustive', beam_width=12, max_evaluations=None, scalarized_weights=None, minimum_objective='public_cells', mip_solver='SCIP', mip_solver_options=None, must_include=None, must_exclude=None, enforce_bucket_budget=False, include_base=True, screening_backend=None, screening_exact_fallback=True, title='Public Representation Frontier')[source]

Search public-column refinements and return the Pareto frontier.

The search runs over subsets of candidate_refinements. It does not learn arbitrary partitions: every candidate is a concrete public representation formed by adding zero or more hidden columns to base_public. Pareto dominance compares public-cell count, added-column count, and ambiguity under every supplied Q stress test.

Parameters:
Return type:

PublicRepresentationFrontier