scan_1d

scan_1d(program, *, center=None, direction=None, n_points=51, span=(-3.141592653589793, 3.141592653589793), normalize_directions=True, rng=None, reporter=None)[source]

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

The scan is constructed by taking a center point in parameter space and a direction vector, then evaluating the program’s cost function at evenly spaced offsets along that line. Internally, the scan uses _evaluate_cost_param_sets() directly, so it reuses the program’s normal batched evaluation path instead of going through run().

Geometry matches the usual orqviz 1D pattern when span uses the default \((-\pi, \pi)\) and normalize_directions is False: each offset \(t\) maps to center + t * direction with the direction norm affecting Euclidean step size. The default normalize_directions=True keeps a unit direction so span is measured along a normalized axis.

Parameters:

  • program (_SupportsVizScan) – Variational program to scan.

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

  • direction (TypeAliasType | None) – Flat direction vector in parameter space. If omitted, a random direction is drawn (reproducible via rng).

  • n_points (int) – Number of sample points along the scan line. Must be at least 2.

  • span (tuple[float, float]) – Inclusive scalar offset range applied along direction (orqviz end_points default is \((-\pi, \pi)\)).

  • normalize_directions (bool) – If True (default), non-zero direction is unit-normalized before building center + t * direction.

  • rng (Generator | int | None) – Optional numpy.random.Generator or integer seed used when direction is None.

  • reporter (ProgressReporter | None) – Optional ProgressReporter. When omitted, uses program.reporter if present, otherwise LoggingProgressReporter. Start/finish messages are emitted around the single batched evaluation (same pattern as run).

Returns:

Object containing offsets, sampled loss values, the concrete parameter sets that were evaluated, and plotting helpers.

Return type:

Scan1DResult

Raises: