scan_2d

scan_2d(program, *, center=None, direction_x=None, direction_y=None, grid_shape=(41, 41), span_x=(-3.141592653589793, 3.141592653589793), span_y=(-3.141592653589793, 3.141592653589793), normalize_directions=True, rng=None, reporter=None)[source]

Two-dimensional loss-landscape scan for a variational program.

The scan is constructed from a center point plus two linearly independent directions in parameter space. A rectangular grid of offsets is generated, converted into concrete parameter sets, and evaluated using the program’s batched cost pipeline.

When either direction is omitted, the missing axis is filled with a random vector orthogonal to the other (same norm as the reference axis when normalize_directions is False, matching the usual orqviz 2D scan construction). Use rng for reproducibility.

Parameters:

  • program (_SupportsVizScan) – Variational program to scan.

  • center (TypeAliasType | None) – Flat parameter vector around which the scan plane is defined. If omitted, the scan centers on program.best_params from a previous optimization run.

  • direction_x (TypeAliasType | None) – First direction spanning the scan plane. If omitted, a random direction is drawn unless direction_y alone is given, in which case direction_x is a random vector orthogonal to direction_y.

  • direction_y (TypeAliasType | None) – Second direction spanning the scan plane. If omitted, a random direction orthogonal to direction_x is used (orqviz-style).

  • grid_shape (tuple[int, int]) – Number of sample points along the x and y scan directions. Both entries must be at least 2.

  • span_x (tuple[float, float]) – Inclusive offset range along direction_x (default \((-\pi, \pi)\)).

  • span_y (tuple[float, float]) – Inclusive offset range along direction_y.

  • normalize_directions (bool) – If True (default), user-supplied directions are unit-normalized; random supplementary directions are unit vectors. If False, coefficients multiply the raw direction vectors; random pairs keep matched norms like orqviz.

  • rng (Generator | int | None) – Optional numpy.random.Generator or integer seed for any randomly generated directions.

  • reporter (ProgressReporter | None) – See scan_1d().

Returns:

Object containing the sampled grid, loss values, evaluated parameter sets, and plotting helpers.

Return type:

Scan2DResult

Raises:

  • TypeError – If program is not a supported variational program.

  • NotImplementedError – If program is an IterativeQAOA instance.

  • ValueError – If the directions have the wrong shape, are zero, are not linearly independent, or if grid_shape is invalid.