CharacterizationResult¶

class CharacterizationResult(job_id, status, hardness=None, report=None, recommendations=<factory>, created_at=None, completed_at=None, *, html='')[source]¶

Bases: object

Result container for QUBO/HUBO characterization.

Returned by characterize_and_validate() and characterize_and_validate(). Displays a rich HTML report when rendered in a Jupyter notebook.

Note

Credit cost scales with QUBO size.

Attributes Summary

`approximation_ratio`	Achievable upper-bound approximation ratio from the light-cone engine.
`approximation_ratio_error_bound`	`±ε` uncertainty band on `approximation_ratio`.
`ar_vs_depth`	Monotone predicted approximation ratio as a function of QAOA depth.
`best_parameters`	Best QAOA parameters found during parameter sweep (if requested).
`certificate`	Structural certificate backing `regime`/`confidence`.
`classical_baseline`	What cheap classical solvers achieve on the same QUBO.
`completed_at`	ISO timestamp when the characterization job completed.
`concentration_ratio`	Probability mass on reference states relative to the subspace uniform baseline `1/2^k` (k = simulated/variable qubits).
`confidence`	`"proven"`, `"estimated"`, or `"open"`.
`constraint_diagnostics`	Per-constraint feasibility diagnostics (violation rate, redundancy).
`cost_gap`	Energy gap between the best and second-best assignment (cost spectrum).
`cost_gap_normalized`	`cost_gap` divided by the full energy range `E_max - E_min`.
`created_at`	ISO timestamp when the characterization job was created.
`feasibility_rate`	Fraction of sampled states that satisfy all constraints.
`formulation_quality`	Structural amenability score (0–100), reference-independent.
`frustration_index`	Fraction of couplings unsatisfiable at the best solution.
`global_flip_symmetric`	Whether flipping every bit maps the best solution to another optimum.
`ground_state_degeneracy`	Number of optimal assignments (exact for small problems).
`hardness`	Hardness analysis — difficulty rating, spectral gap, condition number.
`html`	Server-rendered HTML report.
`is_psd`	Whether the QUBO matrix is positive semidefinite (`certificate["structural"]["is_psd"]`).
`is_well_tuned`	Whether the penalty parameter is well-tuned based on the analysis.
`job_id`	Unique identifier for the characterization job.
`penalty_lambda_min_feasible`	Empirical smallest penalty at which the optimum becomes feasible.
`penalty_lambda_min_feasible_estimated`	Whether `penalty_lambda_min_feasible` is a subspace estimate.
`penalty_lambda_safe`	Lucas/GKD guaranteed penalty bound (upper end of the recommended range).
`penalty_recommendation`	Recommended penalty multiplier for constrained problems.
`quality_score`	QAOA amenability score (0–100) at the best parameters found.
`quantum_curiosity`	`certificate["quantum_curiosity"]` — probe run when the certificate is `uncertain`.
`rank`	Rank of the QUBO matrix (`certificate["structural"]["rank"]`).
`recommendations`	Actionable suggestions for tuning the QUBO or QAOA setup, derived from the characterization report.
`recommended_layers_basis`	How `recommended_min_layers` was chosen.
`recommended_min_layers`	Recommended minimum QAOA depth p, derived from the AR-vs-depth curve.
`reference_concentration_score`	QAOA quality (0–100) at the best swept parameters (reference-dependent).
`refuse_reason`	Why a `"refuse"` `regime` reported no approximation ratio.
`regime`	Analysis regime the server used to reach its certificate/AR call.
`regime_diagnostics`	Light-cone sizes behind the `regime` call.
`relaxation_bound`	Continuous relaxation bound on the optimum (e.g. LP/SDP), if computed.
`report`	Full characterization report — quality score, state probabilities, etc.
`state_probabilities`	Per-state probability data from the characterization report.
`status`	Job status (`COMPLETED`, `FAILED`, etc.).
`structural_sensitivity`	Per-qubit structural sensitivity analysis (if requested).
`treewidth_estimate`	Upper bound on the interaction-graph treewidth (min-fill heuristic).

Methods Summary

`display`()	Print a rich console report of the characterization result.
`qaoa_initial_params`([layers])	Warm-start angles ready for `QAOA`'s `run`.
`summary`()	Return a rich text summary of the characterization result.

Attributes Documentation

approximation_ratio¶

Achievable upper-bound approximation ratio from the light-cone engine.

r = (⟨C⟩ − C_max) / (C_min − C_max) ∈ [0, 1], evaluated at the uniform |+⟩ state by the light-cone engine — an upper bound on what a real, cold-started QAOA run can reach at the swept depth, not a guarantee any live run gets there. Paired with approximation_ratio_error_bound for the ±ε band around it. Interpret it against classical_baseline (an AR of 0.9 means little if greedy already reaches the optimum).

None in the "refuse" regime — the server declined to estimate rather than ship an unreliable number.

approximation_ratio_error_bound¶

±ε uncertainty band on approximation_ratio.

0 for the exact light-cone computation ("exact"/"structured" regime); positive for the truncated Pauli-propagation estimate used in the "estimate" regime.

ar_vs_depth¶

Monotone predicted approximation ratio as a function of QAOA depth.

Each entry has layers, gammas, betas, energy, approximation_ratio, and error_bound; the curve is non-decreasing in layers.

best_parameters¶: Best QAOA parameters found during parameter sweep (if requested).

certificate¶

Structural certificate backing regime/confidence.

A dict with certified_easy, no_lowdepth_advantage_expected, uncertain (bools), easy_witnesses, lowdepth_markers (lists of str), and optional quantum_curiosity / structural sub-dicts — see quantum_curiosity, is_psd, rank.

classical_baseline¶

What cheap classical solvers achieve on the same QUBO.

A dict with greedy_energy, sa_energy, best_energy, distinct_optima, and (for small problems) exact_ground_energy. The reference an approximation_ratio needs to be meaningful.

completed_at: str | None = None¶: ISO timestamp when the characterization job completed.

concentration_ratio¶

Probability mass on reference states relative to the subspace uniform baseline 1/2^k (k = simulated/variable qubits).

1.0 matches a uniform distribution over the simulated subspace; > 1 means the ansatz concentrates mass on references; < 1 means it concentrates away from them. Values near or below 1 at the returned parameters indicate the ansatz at this depth cannot resolve the reference states — increasing circuit depth (more QAOA layers) or running a deeper parameter sweep is the typical remedy.

Note the baseline is the subspace uniform 1/2^k, NOT the full-space 1/2^n used by the “× uniform” cue in the rendered state-probabilities table — so the two can point different directions on the same report (they answer different questions: concentration within the simulated subspace vs. against the full Hilbert space).

Prefers the value at the best sweep parameters (concentration_at_best) when available.

confidence¶

"proven", "estimated", or "open".

Type:: Confidence level behind regime

constraint_diagnostics¶: Per-constraint feasibility diagnostics (violation rate, redundancy).

cost_gap¶: Energy gap between the best and second-best assignment (cost spectrum).

cost_gap_normalized¶

cost_gap divided by the full energy range E_max - E_min.

Scale-invariant (unlike the raw cost_gap), so it’s the version to compare across differently-scaled formulations of the same problem.

created_at: str | None = None¶: ISO timestamp when the characterization job was created.

feasibility_rate¶: Fraction of sampled states that satisfy all constraints.

formulation_quality¶

Structural amenability score (0–100), reference-independent.

Scale-invariant composite of the normalized cost gap, ground-state degeneracy, density, and weight balance. A high score means the QUBO is well-formed for QAOA, not that any depth will solve it.

frustration_index¶: Fraction of couplings unsatisfiable at the best solution.

global_flip_symmetric¶

Whether flipping every bit maps the best solution to another optimum.

When True, a standard X-mixer QAOA state stays in a fixed global-parity eigenspace at any depth, so this degeneracy cannot be resolved by adding layers alone (see ground_state_degeneracy).

ground_state_degeneracy¶: Number of optimal assignments (exact for small problems).

hardness: dict | None = None¶: Hardness analysis — difficulty rating, spectral gap, condition number.

html: str = ''¶: Server-rendered HTML report. Empty when the HTML endpoint was unreachable.

is_psd¶: Whether the QUBO matrix is positive semidefinite (certificate["structural"]["is_psd"]).

is_well_tuned¶: Whether the penalty parameter is well-tuned based on the analysis.

job_id: str = <dataclasses._MISSING_TYPE object>¶: Unique identifier for the characterization job.

penalty_lambda_min_feasible¶

Empirical smallest penalty at which the optimum becomes feasible.

Exact only for small problems; above ~15 variables it is an unreliable subspace-search estimate — check penalty_lambda_min_feasible_estimated and prefer penalty_lambda_safe when it is True.

penalty_lambda_min_feasible_estimated¶

Whether penalty_lambda_min_feasible is a subspace estimate.

True past the exact-search size cap (~15 qubits), where the value is advisory only; rely on penalty_lambda_safe there.

penalty_lambda_safe¶: Lucas/GKD guaranteed penalty bound (upper end of the recommended range).

penalty_recommendation¶: Recommended penalty multiplier for constrained problems.

quality_score¶

QAOA amenability score (0–100) at the best parameters found.

Prefers the reference-dependent reference_concentration_score (how well the QAOA ansatz concentrates probability on the reference states at the swept best parameters); falls back to the structural formulation_quality when no sweep was run.

This is not the solution quality — for the achievable-upper-bound approximation ratio, see approximation_ratio, and for the “is quantum worth it?” structural call see certificate.

quantum_curiosity¶

certificate["quantum_curiosity"] — probe run when the certificate is uncertain.

A dict with status, depth_to_escape_locality, and next_step.

rank¶: Rank of the QUBO matrix (certificate["structural"]["rank"]).

recommendations: list[dict] = <dataclasses._MISSING_TYPE object>¶

Actionable suggestions for tuning the QUBO or QAOA setup, derived from the characterization report.

Always a list — empty when no rules fire or the job didn’t complete. Each entry is a dict with these keys:

level — one of "info", "warn", "action". action recommends a concrete change; warn flags a risk; info is contextual.
metric — which report field triggered the rule (e.g. "quality_score", "feasibility_rate").
text — plain-text message, suitable for terminal/log output.
html — the same message with inline <strong> markup, consumed by the notebook _repr_html_ renderer. text and html carry the same content; choose by output medium.

recommended_layers_basis¶

How recommended_min_layers was chosen.

One of "threshold_reached" (AR hit the near-optimal threshold), "saturated" (deeper layers stopped helping), "depth_limited" (AR still climbing at the deepest probed depth), "structural" (no sweep), or "flat_spectrum".

recommended_min_layers¶

Recommended minimum QAOA depth p, derived from the AR-vs-depth curve.

The smallest depth at which the (monotone) predicted approximation ratio reaches near-optimal or stops improving; see recommended_layers_basis for which of those fired. Falls back to a structural estimate when no parameter sweep was run.

This is an achievable-optimal depth: it is the depth at which a well-tuned QAOA (optimal angles) reaches the target ratio. A real run with a finite-budget optimizer typically plateaus a layer or two shallower, so treat this as an upper guide. Warm-starting from the per-layer angles in ar_vs_depth closes much of that gap.

reference_concentration_score¶: QAOA quality (0–100) at the best swept parameters (reference-dependent).

refuse_reason¶

Why a "refuse" regime reported no approximation ratio.

"lightcone_too_wide" — the depth-p interaction light-cone exceeds the feasibility budget a priori (a size limit, not density). "estimate_unreachable" — routed to the truncated estimator, but its ±ε tolerance was unreachable within the term budget. None outside the "refuse" regime. See regime_diagnostics for the sizes.

regime¶

Analysis regime the server used to reach its certificate/AR call.

One of "exact", "structured", "estimate", or "refuse". "refuse" means the interaction light-cone is wider than the feasibility budget at the requested depth, so no cheap-and-correct assessment exists — approximation_ratio is None in that regime. See refuse_reason for which limit was hit. This is set by the light-cone width (which grows with circuit depth and connectivity), not by coupling density.

regime_diagnostics¶

Light-cone sizes behind the regime call.

A dict with max_lightcone_k, n, layers, k_cheap, and k_feasible — the numbers that determined the regime.

relaxation_bound¶

Continuous relaxation bound on the optimum (e.g. LP/SDP), if computed.

A provable lower bound on the true minimum energy, independent of any classical heuristic — when it’s close to classical_baseline’s best_energy, that baseline is already known to be near-optimal.

report: dict | None = None¶: Full characterization report — quality score, state probabilities, etc.

state_probabilities¶: Per-state probability data from the characterization report.

status: str = <dataclasses._MISSING_TYPE object>¶: Job status (COMPLETED, FAILED, etc.).

structural_sensitivity¶: Per-qubit structural sensitivity analysis (if requested).

treewidth_estimate¶: Upper bound on the interaction-graph treewidth (min-fill heuristic).

Methods Documentation

display()[source]¶

Print a rich console report of the characterization result.

Uses the rich library to display styled panels, tables, and gauges in the terminal. In Jupyter notebooks, prefer evaluating the result object directly (which triggers _repr_html_).

Return type:: None

qaoa_initial_params(layers=None)[source]¶

Warm-start angles ready for QAOA’s run.

Returns the swept angles as an initial_params array of shape (1, 2 * layers), ordered per layer as [γ₀, β₀, γ₁, β₁, …] — the exact layout QAOA.run(initial_params=...) expects — so warm-starting a real run from a characterization is one line:

result = characterize_and_validate(problem, service=service,
                                   options=CharacterizationOptions(parameter_sweep=True))
p = result.recommended_min_layers
qaoa = QAOA(problem, n_layers=p)
qaoa.run(initial_params=result.qaoa_initial_params())

Prefers the per-depth ar_vs_depth angles for the requested layers (default: recommended_min_layers, else the deepest available). Falls back to broadcasting the p=1 best_parameters across layers when no depth curve is available. Returns None when no angles were produced — the "refuse" regime, or no parameter_sweep — so guard the result before passing it on.

Parameters:: layers (int | None) – Circuit depth to warm-start. Defaults to recommended_min_layers. Must match the n_layers of the QAOA you feed it into.
Return type:: ndarray | None

summary()[source]¶

Return a rich text summary of the characterization result.

Return type:: str