scan_pca

scan_pca(program, *, samples, center=None, grid_shape=(41, 41), components_ids=(0, 1), offset=(-1.0, 1.0), span_x=None, span_y=None, reporter=None)[source]

Evaluate a 2D scan in PCA score space (orqviz-compatible layout).

Fits sklearn.decomposition.PCA on samples, builds a rectangular grid in the selected principal-component scores (default PC0 vs PC1), maps each grid point through inverse_transform into full parameter space, and evaluates the program’s cost function in one batch.

A typical choice for samples is the optimization trajectory:

samples = np.vstack(program.param_history(mode="best_per_iteration"))

When using program.viz.scan_pca(), samples are collected automatically if omitted.

When span_x and span_y are both omitted, axis limits match orqviz PCAobject._get_endpoints_from_pca: min/max of the projected samples on each selected component, plus offset applied to the low and high ends.

Parameters:

  • program (_SupportsVizScan) – Variational program to scan.

  • samples (TypeAliasType) – Rows are parameter vectors used to fit PCA; shape (n_samples, n_params).

  • center (TypeAliasType | None) – Optional anchor in parameter space. If None, the scan plane is the standard PCA affine subspace through the sample mean (orqviz default). If provided (e.g. program.best_params), each reconstructed point is shifted by (center - sample_mean) so the same PC directions pass through center.

  • grid_shape (tuple[int, int]) – (n_x, n_y) grid resolution in score space; both ≥ 2.

  • components_ids (tuple[int, int]) – Which PCA components form the scan axes (default (0, 1)). n_components is set to max(components_ids) + 1.

  • offset (float | tuple[float, float]) – Extra padding on score-axis limits when using automatic spans. A scalar a becomes (-|a|, |a|) on each end (orqviz rule).

  • span_x (tuple[float, float] | None) – If given together with span_y, fixed PC0 score range (bypasses automatic endpoints).

  • span_y (tuple[float, float] | None) – Fixed PC1 score range; must be set if span_x is set.

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

Returns:

Grid in PCA score coordinates, loss values, full parameter sets, sklearn PC directions for the chosen indices, explained variance ratios, and projected samples scores for plotting.

Return type:

PCAScanResult

Raises:

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

  • NotImplementedError – If program is an IterativeQAOA instance.

  • ValueError – If shapes, ranks, grid_shape, or span arguments are invalid.