Landscape Visualisation Submodule

class AnalysisResult[source]

Bases: TypedDict

component_reports: list[ComplementReport]

Per-component analyses

correlations: ndarray

Parameter–score correlations

field_ranking: None

Always None in the flat-parameter analysis mode

global_ranking: list[ParamEntry]

Global parameter importance

influence_maps: InfluenceMap

Parameter influence arrays

raw: RawResult

Raw numerical quantities

scores: ndarray

PCA scores along the trajectory

summary: PCASummary

Global PCA summary

class ComplementReport[source]

Bases: TypedDict

abs_component_map: ndarray
component_id: int
component_map: ndarray
component_vector: ndarray
explained_variance_ratio: float
field_component_scores: None
path_contribution_map: ndarray
score_max: float
score_mean: float
score_min: float
score_std: float
top_abs_parameters: list[ParamEntry]
top_negative_parameters: list[ParamEntry]
top_positive_parameters: list[ParamEntry]
top_training_path_parameters: list[ParamEntry]
class InfluenceMap[source]

Bases: TypedDict

flat: InfluenceMapInstance
class InfluenceMapInstance[source]

Bases: TypedDict

global_abs_influence: ndarray
global_path_influence: ndarray
global_sq_influence: ndarray
parameter_range: ndarray
parameter_std: ndarray
path_length_per_param: ndarray
class PCAPlotResult[source]

Bases: TypedDict

components: Figure
summary: Figure
class PCAResult[source]

Bases: TypedDict

X: ndarray

PCA grid X coordinates

Y: ndarray

PCA grid Y coordinates

Z: ndarray

Loss values on the PCA grid

components: ndarray

PCA component vectors

explained_variance_ratio: ndarray

Variance explained by each PCA component

param0: float

Reference parameter vector used as the center of the scan

param_history: ndarray

Parameter trajectory used to fit the PCA

pca: PCA

Fitted PCA object

traj_xy: ndarray

Trajectory projected onto the PCA plane

traj_z: ndarray | None

Loss values along the trajectory if compute_traj_loss is True, otherwise None

x_range: tuple[float, float]

Scan bounds along the PCA X axis

y_range: tuple[float, float]

Scan bounds along the PCA Y axis

class PCASummary[source]

Bases: TypedDict

cumulative_explained_variance: ndarray
dominant_component: int
effective_rank_90pct: int
effective_rank_95pct: int
explained_variance_ratio: ndarray
field_ranking: None
most_influential_parameters: list[ParamEntry]
n_components_analyzed: int
n_parameters: int
n_steps: int
class ParamEntry[source]

Bases: TypedDict

abs_loading: NotRequired[float]
correlation_with_component_score: NotRequired[float | None]
field: None
global_abs_influence: float
global_path_influence: float
global_sq_influence: float
index: int
label: str
loading: NotRequired[float]
local_index: int
mean: float
path_contribution_in_component: NotRequired[float]
path_length: float
range: float
sq_loading: NotRequired[float]
std: float
class RawResult[source]

Bases: TypedDict

abs_loadings: ndarray
block_slices: None
components: ndarray
flat_parameter_labels: list[str]
global_abs_influence: ndarray
global_path_influence: ndarray
global_sq_influence: ndarray
index_map: None
param_mean: ndarray
param_range: ndarray
param_std: ndarray
parameter_labels: list[str]
path_contrib_per_component: ndarray
path_length_per_param: ndarray
sq_loadings: ndarray
weights: ndarray
analyze_pca(scan_result, n_components=None, top_k=10, weight_mode='variance', eps=1e-12)[source]

Analyze a PCA applied to an optimization parameter trajectory.

Parameters:

  • scan_result (PCAResult) – Mapping containing PCA results and the parameter trajectory.

  • n_components (int | None) – Number of PCA components to analyze.

  • top_k (int) – Number of parameters retained in importance rankings.

  • weight_mode (str) –

    Weighting scheme used to aggregate component influence across PCA components. Supported values are:

    • "variance": weights components according to their explained variance ratio.

    • "uniform": assigns equal weight to all analyzed components.

  • eps (float) – Small constant used for numerical stability.

Returns:

PCA interpretability results.

Return type:

AnalysisResult

loss_scan_1d(params, direction, loss_function, n_steps=200, end_points=None, n_jobs=-1)[source]

Evaluate and plot the loss function along a one-dimensional direction in parameter space.

Parameters:

  • params (ndarray[tuple[Any, ...], dtype[float64]]) – Reference parameter vector.

  • direction (ndarray[tuple[Any, ...], dtype[float64]]) – Direction in parameter space used for the scan. It is normalized by its maximum absolute value.

  • loss_function (Callable[[ndarray[tuple[Any, ...], dtype[float64]]], float]) – Callable returning the loss for a given parameter vector.

  • n_steps (int) – Number of scan points.

  • end_points (tuple[float, float] | None) – Bounds of the scan parameter. Default is (-π, π).

  • n_jobs (int) – Number of parallel jobs used to evaluate the loss.

Return type:

None

Side effects:

Saves the figure to figures/landscape1d.pdf and displays it.

loss_scan_2d_3d(params, direction1, direction2, loss_function, n_steps=100, end_points_x=None, end_points_y=None, plot3D=True, n_jobs=-1)[source]

Evaluate and plot the loss function on a two-dimensional parameter plane.

Parameters:

  • params (ndarray[tuple[Any, ...], dtype[float64]]) – Reference parameter vector.

  • direction1 (ndarray[tuple[Any, ...], dtype[float64]]) – First scan direction in parameter space. It is normalized by its maximum absolute value.

  • direction2 (ndarray[tuple[Any, ...], dtype[float64]]) – Second scan direction in parameter space. It is normalized by its maximum absolute value.

  • loss_function (Callable[[ndarray[tuple[Any, ...], dtype[float64]]], float]) – Callable returning the loss for a given parameter vector.

  • n_steps (int) – Number of points per scan direction. Default is 100.

  • end_points_x (tuple[float, float] | None) – Bounds of the scan parameter along the first direction. Default is (-π, π).

  • end_points_y (tuple[float, float] | None) – Bounds of the scan parameter along the second direction. Default is (-π, π).

  • plot3D (bool) – Whether to generate a 3D visualization of the loss surface.

  • n_jobs (int) – Number of parallel jobs used to evaluate the loss.

Return type:

None

Side effects:

Saves the 2D figure to figures/landscape2d.pdf and, if requested, the 3D figure to figures/landscape3d.pdf. Displays the generated figures.

pca_loss_scan(params_history, loss_function, n_steps=200, offset=0.5, compute_traj_loss=True, n_jobs=-1, backend='loky')[source]

Evaluate the loss function in the PCA subspace of an optimization trajectory.

Parameters:

  • params_history (ndarray) – Array containing the successive parameter vectors of the optimization trajectory.

  • loss_function (Callable[[ndarray[tuple[Any, ...], dtype[float64]]], float]) – Callable returning the loss for a given parameter vector.

  • n_steps (int) – Number of grid points per PCA axis.

  • offset (float | tuple[float, float]) – Margin added to the PCA scan bounds. If a scalar is provided, it is converted to (-abs(offset), abs(offset)).

  • compute_traj_loss (bool) – Whether to evaluate the loss along the original trajectory.

  • n_jobs (int) – Number of parallel jobs used to evaluate the loss.

  • backend (str) – Joblib backend used for parallel loss evaluations.

Returns:

The PCA result

Return type:

PCAResult

perform_pca_and_analysis(params_history, loss_function, n_steps, offset, n_top, circuit, n_jobs=-1)[source]

Run the full PCA-based loss landscape and interpretability analysis pipeline.

Parameters:

  • params_history (ndarray) – Parameter trajectory used to fit the PCA.

  • loss_function (Callable[[ndarray[tuple[Any, ...], dtype[float64]]], float]) – Callable returning the loss for a given parameter vector.

  • n_steps (int) – Number of grid points per PCA axis.

  • offset (float | tuple[float, float]) – Margin added to the PCA scan bounds.

  • n_top (int) – Number of top entries shown in analysis plots.

  • circuit (QuantumCircuit) – Quantum circuit used for the PCA influence schematic.

  • n_jobs (int) – Number of parallel jobs used during loss evaluations. Default is -1.

Returns:

Mapping returned by analyze_pca.

Side effects:

Generates and displays several plots, and saves some figures under figures/.

plot_pca_analysis(analysis, n_top=10, decimals=4, summary_figsize=None, component_figsize_per_row=None, max_label_length=28)[source]

Plot summaries of a PCA interpretability analysis.

Parameters:

  • analysis (AnalysisResult) – Mapping returned by analyze_pca.

  • n_top (int) – Number of top entries shown in each plot.

  • decimals (int) – Number of decimals used for axis formatting.

  • summary_figsize (tuple[int, int] | None) – Figure size for the global summary. Default is (14, 10).

  • component_figsize_per_row (tuple[int, int] | None) – Figure size per row for component plots. Default is (18, 4).

  • max_label_length (int) – Maximum length of labels before truncation.

Returns:

  • summary: Global PCA summary figure

  • components: Component-level analysis figure

Return type:

Mapping containing the generated figures

plot_pca_circuit_schematic_real_circuit(qc, analysis, score_key='global_sq_influence', cmap='viridis', box_width=0.55, box_height=0.5, show_values=False, title=None, show_gamma=True, gamma_label=None, label_mode='label', show_entanglers=True, entangler_linewidth=1.6)[source]

Plot a circuit schematic annotated with PCA-based parameter scores.

Parameters:

  • qc (QuantumCircuit) – Qiskit quantum circuit to visualize, or any compatible object exposing qc.data, qc.parameters, qc.num_qubits, and qc.find_bit.

  • analysis (AnalysisResult) – Mapping returned by analyze_pca.

  • score_key (str) – Influence metric used for coloring.

  • cmap (str) – Colormap used to map scores to colors.

  • box_width (float) – Width of parameter boxes.

  • box_height (float) – Height of parameter boxes.

  • show_values (bool) – Whether to display numerical scores.

  • title (str | None) – Optional figure title.

  • show_gamma (bool) – Whether to display the global scaling parameter. The gamma parameter is shown only if the PCA score vector contains one additional score compared to the number of Qiskit circuit parameters.

  • gamma_label (str | None) – Optional label for the scaling parameter.

  • label_mode (str) –

    Labeling scheme used for parameter boxes. Supported values are:

    • "index"

    • "theta"

    • "full"

    • "gate+index"

    • "gate"

    • "label"

    • "gate+label"

  • show_entanglers (bool) – Whether to render entangling gates.

  • entangler_linewidth (float) – Line width for entangling connections.

Returns:

matplotlib.figure.Figure

Saved Files:

  • figures/circuitpcainfluence.pdf

plot_pca_loss_scan_2d(scan_result, ax=None, cmap='viridis', contour=False, contour_levels=20, show_colorbar=True, trajectory_kwargs=None)[source]

Plot a 2D PCA loss landscape with the optimization trajectory.

Parameters:

  • scan_result (PCAResult) – Mapping returned by pca_loss_scan.

  • ax (Axes | None) – Axis on which to draw the plot.

  • cmap (str) – Colormap used for the loss surface.

  • contour (bool) – Whether to overlay contour lines. Default is False.

  • contour_levels (int) – Number of contour levels. Default is 20.

  • show_colorbar (bool) – Whether to display a colorbar. Default is True.

  • trajectory_kwargs (dict[str, Any] | None) – Optional keyword arguments for trajectory plotting.

Notes

  • The figure is saved to figures/pcaLandscape2d.pdf.

  • If LogNorm() is used for normalization, the values in Z must be strictly positive.

Returns:

Figure containing the plot. ax: Axis on which the plot is drawn.

Return type:

fig

Parameters:

  • scan_result (PCAResult)

  • ax (Axes | None)

  • cmap (str)

  • contour (bool)

  • contour_levels (int)

  • show_colorbar (bool)

  • trajectory_kwargs (dict[str, Any] | None)

plot_pca_loss_scan_3d(scan_result, cmap='viridis', elev=30, azim=-60, alpha_surface=0.85, trajectory_kwargs=None)[source]

Plot a 3D PCA loss landscape.

Parameters:

  • scan_result (PCAResult) – Mapping returned by pca_loss_scan.

  • cmap (str) – Colormap used for the surface.

  • elev (float) – Elevation angle of the view.

  • azim (float) – Azimuth angle of the view.

  • alpha_surface (float) – Surface transparency.

  • trajectory_kwargs (dict[str, Any] | None) – Optional keyword arguments for trajectory plotting.

Notes

  • The figure is saved to figures/pcaLandscape3d.pdf.

  • If LogNorm() is used for normalization, the values in Z must

    be strictly positive.

Returns:

Figure containing the plot and Tuple (ax1, ax2) containing the main PCA landscape axis and the log-scale surface axis.

Parameters:

  • scan_result (PCAResult)

  • cmap (str)

  • elev (float)

  • azim (float)

  • alpha_surface (float)

  • trajectory_kwargs (dict[str, Any] | None)

random_mixed_directions(n)[source]

Generate two random directions in parameter space.

Parameters:

n (int) – Total parameter dimension.

Returns:

Two random direction vectors, with the second orthogonalized with respect to the first.