CharacterizationResult

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

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	Approximation ratio achieved by the QAOA ansatz at the returned best_parameters (and depth specified in the sweep options).
best_parameters	Best QAOA parameters found during parameter sweep (if requested).
completed_at	ISO timestamp when the characterization job completed.
concentration_ratio	Probability mass on target states relative to the uniform baseline.
created_at	ISO timestamp when the characterization job was created.
feasibility_rate	Fraction of sampled states that satisfy all constraints.
hardness	Hardness analysis — difficulty rating, spectral gap, condition number.
html	Server-rendered HTML report.
is_well_tuned	Whether the penalty parameter is well-tuned based on the analysis.
job_id	Unique identifier for the characterization job.
penalty_recommendation	Recommended penalty multiplier for constrained problems.
quality_score	Composite metric (0–100) of the QUBO's structural amenability to QAOA.
recommendations	Actionable suggestions for tuning the QUBO or QAOA setup, derived from the characterization report.
report	Full characterization report — quality score, state probabilities, etc.
sensitivity	Per-qubit sensitivity analysis (if requested).
state_probabilities	Per-state probability data from the characterization report.
status	Job status (COMPLETED, FAILED, etc.).

Methods Summary

display()	Print a rich console report of the characterization result.
summary()	Return a rich text summary of the characterization result.

Attributes Documentation

approximation_ratio

Approximation ratio achieved by the QAOA ansatz at the returned best_parameters (and depth specified in the sweep options).

This is the server’s diagnostic estimate, not a measurement from a live QAOA run. Comparing it against your own QAOA’s approximation ratio is only meaningful at the same depth and ansatz configuration.

best_parameters

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

completed_at: str | None = None

ISO timestamp when the characterization job completed.

concentration_ratio

Probability mass on target states relative to the uniform baseline.

1.0 matches a uniform distribution; > 1 means the ansatz concentrates mass on targets; < 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 target — increasing circuit depth (more QAOA layers) or running a deeper parameter sweep is the typical remedy.

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

created_at: str | None = None

ISO timestamp when the characterization job was created.

feasibility_rate

Fraction of sampled states that satisfy all constraints.

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_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_recommendation

Recommended penalty multiplier for constrained problems.

quality_score

Composite metric (0–100) of the QUBO’s structural amenability to QAOA.

Derived server-side from spectral and concentration features of the QUBO matrix. Does not predict approximation ratio at any specific depth — a high score means the QUBO is well-conditioned for QAOA, not that p=1 will solve it.

When a parameter sweep was run, returns the score at the best parameters found (quality_at_best); otherwise the score at the user-supplied or default parameters.

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.

report: dict | None = None

Full characterization report — quality score, state probabilities, etc.

sensitivity

Per-qubit sensitivity analysis (if requested).

state_probabilities

Per-state probability data from the characterization report.

status: str = <dataclasses._MISSING_TYPE object>

Job status (COMPLETED, FAILED, etc.).

Methods Documentation

display()

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

summary()

Return a rich text summary of the characterization result.

Return type:

str