characterize_and_validate

characterize_and_validate(problem, reference_states, *, service, options=None)[source]

One-call QUBO/HUBO characterization with rich notebook display.

Converts the problem to wire format, submits it to the Qoro Characterization Service, and returns a CharacterizationResult that renders a styled report in Jupyter.

Parameters:

  • problem (divi.qprog.problems.BinaryOptimizationProblem) – A BinaryOptimizationProblem. Wrap raw inputs (ndarray, sparse, BQM, HUBO dict, etc.) by constructing one — the constructor accepts every shape this function used to take directly.

  • reference_states (list[str]) – Reference solution bitstrings used for reference-dependent diagnostics. They are not constraints, not a warm start, and do not have to be proven optima. Pass [] when you do not have reference solutions; the service may derive a classical reference solution for analyses that require one.

  • service (QoroService) – A QoroService instance to drive the API calls.

  • options (CharacterizationOptions | None) – Optional CharacterizationOptions configuring sub-analyses, fixed parameters, ansatz, and constraints. Defaults to a no-op options object (server-side defaults).

Returns:

Rich result object. Displaying it in Jupyter shows a styled HTML report.

Return type:

CharacterizationResult

Raises:

requests.exceptions.HTTPError – On API errors.

Examples

>>> import numpy as np
>>> from divi.backends import QoroService
>>> from divi.backends.characterization import (
...     CharacterizationOptions,
...     characterize_and_validate,
... )
>>> from divi.qprog.problems import BinaryOptimizationProblem
>>> problem = BinaryOptimizationProblem(np.array([[-1, 2], [0, -1]]))
>>> result = characterize_and_validate(
...     problem,
...     reference_states=["01", "10"],
...     service=QoroService(),
...     options=CharacterizationOptions(parameter_sweep=True),
... )
>>> result.quality_score
78.5

Note

Credit cost scales with QUBO size.